init

GEMINI.md

@@ -3,6 +3,8 @@
 Auto-generated from all feature plans. Last updated: 2025-11-25
 
 ## Active Technologies
+- Python 3.11+, TypeScript/React 18 + `fastmcp`, `fastapi`, `vite` (003-chatgpt-app-integration)
+- No schema changes; relies on existing vault. (003-chatgpt-app-integration)
 
 - Python 3.11+ (Backend), TypeScript/React 18 (Frontend) + `react-force-graph-2d` (New), `FastAPI`, `sqlite3` (002-add-graph-view)
 
@@ -22,6 +24,7 @@ cd src [ONLY COMMANDS FOR ACTIVE TECHNOLOGIES][ONLY COMMANDS FOR ACTIVE TECHNOLO
 Python 3.11+ (Backend), TypeScript/React 18 (Frontend): Follow standard conventions
 
 ## Recent Changes
+- 003-chatgpt-app-integration: Added Python 3.11+, TypeScript/React 18 + `fastmcp`, `fastapi`, `vite`
 
 - 002-add-graph-view: Added Python 3.11+ (Backend), TypeScript/React 18 (Frontend) + `react-force-graph-2d` (New), `FastAPI`, `sqlite3`
 

specs/003-chatgpt-app-integration/plan.md

@@ -1,104 +1,76 @@
-# Implementation Plan: [FEATURE]
+# Implementation Plan: ChatGPT App Integration
 
-**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
-**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
+**Branch**: `003-chatgpt-app-integration` | **Date**: 2025-11-26 | **Spec**: [spec.md](spec.md)
+**Input**: Feature specification from `/specs/003-chatgpt-app-integration/spec.md`
 
 **Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
 
 ## Summary
 
-[Extract from feature spec: primary requirement + technical approach from research]
+Adapt the backend to support ChatGPT Apps SDK by adding a static service token auth strategy, configuring CORS for ChatGPT, and updating MCP tools to return metadata for widget rendering. Create a standalone `widget.html` entry point in the frontend.
 
 ## Technical Context
 
-<!--
-  ACTION REQUIRED: Replace the content in this section with the technical details
-  for the project. The structure here is presented in advisory capacity to guide
-  the iteration process.
--->
-
-**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]  
-**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]  
-**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]  
-**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]  
-**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
-**Project Type**: [single/web/mobile - determines source structure]  
-**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]  
-**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]  
-**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
+**Language/Version**: Python 3.11+, TypeScript/React 18
+**Primary Dependencies**: `fastmcp`, `fastapi`, `vite`
+**Storage**: No schema changes; relies on existing vault.
+**Testing**: `pytest` for auth/tools; manual verification for widgets.
+**Target Platform**: Hugging Face Spaces (Docker) + ChatGPT UI.
+**Project Type**: Full Stack (Backend API + Frontend Widget).
+**Performance Goals**: Widget load < 500ms.
+**Constraints**: Must work alongside existing "local dev" and "HF OAuth" modes.
+**Scale/Scope**: Demo scale (single tenant impersonation via service token).
 
 ## Constitution Check
 
 *GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
 
-[Gates determined based on constitution file]
+-   **Brownfield Integration**: Respects existing auth structure (adding a strategy, not rewriting). Reuses `NoteViewer` component.
+-   **Test-Backed**: New auth strategy will be unit tested.
+-   **Simplicity**: Using static token instead of full OIDC.
 
 ## Project Structure
 
 ### Documentation (this feature)
 
 ```text
-specs/[###-feature]/
-├── plan.md              # This file (/speckit.plan command output)
-├── research.md          # Phase 0 output (/speckit.plan command)
-├── data-model.md        # Phase 1 output (/speckit.plan command)
-├── quickstart.md        # Phase 1 output (/speckit.plan command)
-├── contracts/           # Phase 1 output (/speckit.plan command)
-└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
+specs/003-chatgpt-app-integration/
+├── plan.md              # This file
+├── research.md          # Phase 0 output
+├── data-model.md        # Phase 1 output
+├── quickstart.md        # Phase 1 output
+└── tasks.md             # Phase 2 output
 ```
 
 ### Source Code (repository root)
-<!--
-  ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
-  for this feature. Delete unused options and expand the chosen structure with
-  real paths (e.g., apps/admin, packages/something). The delivered plan must
-  not include Option labels.
--->
 
 ```text
-# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
-src/
-├── models/
-├── services/
-├── cli/
-└── lib/
-
-tests/
-├── contract/
-├── integration/
-└── unit/
-
-# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected)
 backend/
 ├── src/
-│   ├── models/
+│   ├── api/
+│   │   ├── main.py            # Update: CORS, widget route
+│   │   └── middleware/
+│   │       └── auth_middleware.py # Update: Strategy usage
 │   ├── services/
-│   └── api/
+│   │   ├── auth.py            # Update: Refactor to Strategy pattern
+│   │   └── config.py          # Update: New config fields
+│   └── mcp/
+│       └── server.py          # Update: Tool return types
 └── tests/
+    └── unit/
+        └── test_auth_strategy.py # New test
 
 frontend/
-├── src/
-│   ├── components/
-│   ├── pages/
-│   └── services/
-└── tests/
-
-# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected)
-api/
-└── [same as backend above]
-
-ios/ or android/
-└── [platform-specific structure: feature modules, UI flows, platform tests]
+├── vite.config.ts             # Update: Multi-page build
+├── widget.html                # New: Widget entry point
+└── src/
+    └── widget.tsx             # New: Widget root component
 ```
 
-**Structure Decision**: [Document the selected structure and reference the real
-directories captured above]
+**Structure Decision**: Multi-page build for Frontend; Strategy pattern for Backend Auth.
 
 ## Complexity Tracking
 
-> **Fill ONLY if Constitution Check has violations that must be justified**
-
 | Violation | Why Needed | Simpler Alternative Rejected Because |
 |-----------|------------|-------------------------------------|
-| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
-| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |
+| Multi-page Vite | To isolate widget styles/scripts from main app | Iframing the full app is too heavy and leaky for ChatGPT widgets. |

specs/003-chatgpt-app-integration/quickstart.md

@@ -0,0 +1,38 @@
+# Quickstart: ChatGPT App Integration
+
+## Prerequisites
+-   Existing backend running.
+-   `CHATGPT_SERVICE_TOKEN` set in environment.
+
+## Testing the Integration
+
+### 1. Authentication
+```bash
+# Test service token access
+curl -H "Authorization: Bearer <your-service-token>" http://localhost:8000/api/notes
+```
+
+### 2. Widget Serving
+```bash
+# Test widget endpoint
+curl -v http://localhost:8000/widget/note
+# Expect: Content-Type: text/html+skybridge (or similar)
+```
+
+### 3. Tool Metadata
+```bash
+# Test tool call via /mcp endpoint
+curl -X POST http://localhost:8000/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "tools/call",
+    "params": {
+      "name": "read_note",
+      "arguments": {"note_path": "Welcome.md"}
+    },
+    "id": 1
+  }'
+# Expect response to contain _meta.openai.outputTemplate
+```
+

specs/003-chatgpt-app-integration/tasks.md

@@ -0,0 +1,67 @@
+# Tasks: ChatGPT App Integration
+
+**Feature**: 003-chatgpt-app-integration
+**Status**: Pending
+**Spec**: [spec.md](spec.md)
+
+## Phase 1: Setup (Project Initialization)
+
+*Goal: Configure build pipelines and backend settings to support the new widget and auth modes.*
+
+- [ ] T001 Update `backend/src/services/config.py` to include `chatgpt_service_token` and `chatgpt_cors_origin` fields
+- [ ] T002 Update `frontend/vite.config.ts` to support multi-page build (`index.html` and `widget.html`)
+- [ ] T003 Create `frontend/widget.html` as the entry point for the ChatGPT widget
+- [ ] T004 Create `frontend/src/widget.tsx` as the root React component for the widget
+
+## Phase 2: Foundational Tasks
+
+*Goal: Establish authentication and infrastructure required for the integration.*
+
+- [ ] T005 Refactor `backend/src/services/auth.py` to implement Strategy pattern (`JWTValidator` and `StaticTokenValidator`)
+- [ ] T006 [P] Create unit tests for new Auth Strategy in `backend/tests/unit/test_auth_strategy.py`
+- [ ] T007 Update `backend/src/api/middleware/auth_middleware.py` to use the new Auth Service strategies
+- [ ] T008 Update `backend/src/api/main.py` to configure CORS for `https://chatgpt.com`
+- [ ] T009 [P] Update `backend/src/api/main.py` to serve `widget.html` on `/widget` route with `text/html+skybridge` MIME type
+
+## Phase 3: User Story 1 - The Recall Loop
+
+*Goal: Enable searching and viewing notes within ChatGPT.*
+
+- [ ] T010 [US1] Extract `NoteViewer` component logic into a reusable pure component (if not already) in `frontend/src/components/NoteViewer.tsx`
+- [ ] T011 [P] [US1] Create `SearchWidget` component in `frontend/src/components/SearchWidget.tsx` for the widget view
+- [ ] T012 [US1] Implement `WidgetApp` component in `frontend/src/widget.tsx` to handle routing between Note and Search views based on props/URL
+- [ ] T013 [US1] Update `backend/src/mcp/server.py` `read_note` tool to return `CallToolResult` with `_meta.openai.outputTemplate`
+- [ ] T014 [US1] Update `backend/src/mcp/server.py` `search_notes` tool to return `CallToolResult` with `_meta.openai.outputTemplate`
+
+## Phase 4: User Story 2 - In-Context Editing
+
+*Goal: Enable editing notes from ChatGPT interactions.*
+
+- [ ] T015 [US2] Verify `write_note` tool functionality with Service Token auth (no code change expected if T007 is correct, but validation needed)
+- [ ] T016 [US2] Implement auto-refresh or status indication in `WidgetApp` when a note is updated externally (by ChatGPT)
+
+## Final Phase: Polish
+
+*Goal: Ensure seamless experience and robustness.*
+
+- [ ] T017 Verify widget load performance and optimize bundle size if needed
+- [ ] T018 Add error boundary to `WidgetApp` to handle load failures gracefully inside the iframe
+
+## Dependencies
+
+1.  **Setup (T001-T004)**: Must be done first to enable widget development.
+2.  **Foundational (T005-T009)**: Auth and serving infrastructure required before widgets can be loaded by ChatGPT.
+3.  **US1 (T010-T014)**: Depends on Foundational. T013/T014 depend on T009 (widget serving).
+4.  **US2 (T015-T016)**: Depends on US1.
+
+## Parallel Execution Strategy
+
+-   **Frontend vs Backend**: T002-T004 (Frontend Setup) can run parallel to T001 & T005-T008 (Backend Auth).
+-   **Within US1**: T011 (Search Widget UI) and T013/T014 (MCP Tool Updates) can be done in parallel.
+
+## Implementation Strategy
+
+1.  **Infrastructure First**: Get the backend serving the widget HTML and accepting the service token.
+2.  **Widget Shell**: Build the minimal widget shell that can display *something*.
+3.  **Tool Connection**: Wire up the MCP tools to point to the widget.
+4.  **Features**: Flesh out the Viewer and Search capabilities.