init

specs/003-chatgpt-app-integration/checklists/requirements.md

@@ -0,0 +1,34 @@
+# Specification Quality Checklist: ChatGPT App Integration
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2025-11-26
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Spec is solid. It clearly delineates the scope (Widget vs App) and addresses the key integration points (Auth, Metadata) identified in the investigation.

specs/003-chatgpt-app-integration/data-model.md

@@ -0,0 +1,38 @@
+# Data Model: ChatGPT Integration
+
+## Auth Entities
+
+### ServiceTokenStrategy
+Strategy for validating static service tokens.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `token` | `str` | The static token to match against. |
+| `user_id` | `str` | The user ID to impersonate (e.g. "demo-user"). |
+
+## Configuration
+
+### AppConfig Updates
+New fields added to `AppConfig`.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `chatgpt_service_token` | `Optional[str]` | Static token for Apps SDK auth. |
+| `chatgpt_cors_origin` | `str` | Allowed CORS origin (default: `https://chatgpt.com`). |
+
+## Tool Responses
+
+### WidgetMeta
+Structure of the `_meta` field in `CallToolResult`.
+
+```json
+{
+  "openai": {
+    "outputTemplate": "https://your-space.hf.space/widget",
+    "toolInvocation": {
+      "invoking": "Searching notes...",
+      "invoked": "Found 3 notes."
+    }
+  }
+}
+```

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

@@ -0,0 +1,104 @@
+# Implementation Plan: [FEATURE]
+
+**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
+**Input**: Feature specification from `/specs/[###-feature-name]/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]
+
+## 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]
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+[Gates determined based on constitution file]
+
+## 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)
+```
+
+### 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/
+│   ├── services/
+│   └── api/
+└── tests/
+
+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]
+```
+
+**Structure Decision**: [Document the selected structure and reference the real
+directories captured above]
+
+## 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] |

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

@@ -0,0 +1,54 @@
+# Phase 0: Research & Technical Decisions
+
+## 1. FastMCP Metadata Injection
+
+**Decision**: Return `CallToolResult` with `_meta` for UI tools.
+
+**Strategy**:
+-   We will stop returning pure Pydantic models from tools that need to trigger widgets (`read_note`, `search_notes`).
+-   Instead, these tools will instantiate the Pydantic model, dump it to a dictionary, and wrap it in a `CallToolResult` object.
+-   The `_meta` field will contain `openai: { outputTemplate: "..." }`.
+-   Non-UI tools (e.g., `list_notes`, `delete_note`) will continue to return Pydantic models or simple text to keep them lightweight.
+
+**Rationale**: This aligns with the OpenAI Apps SDK pattern and allows us to trigger widgets without breaking the existing schema validation (since `structuredContent` will still match the Pydantic schema).
+
+## 2. React Widget Strategy
+
+**Decision**: Use a separate Vite entry point (`widget.html` + `widget.tsx`).
+
+**Strategy**:
+-   Create `frontend/widget.html` as a lightweight entry point.
+-   Create `frontend/src/widget.tsx` to render the widget application.
+-   Refactor `NoteViewer.tsx` into a "pure" component (if it isn't already) that can be imported by both `App.tsx` and `widget.tsx`.
+-   Use `vite-plugin-html` or manual rollup config to output multiple HTML files.
+
+**Rationale**:
+-   **Isolation**: Prevents the main app's router, sidebar, and heavy layout styles from leaking into the iframe.
+-   **Performance**: The widget bundle will be smaller.
+-   **Simplicity**: Easier to reason about "widget state" when it's a fresh React mount rather than a route transition in a complex SPA.
+
+## 3. Authentication
+
+**Decision**: Use a configurable "Service Token" strategy.
+
+**Strategy**:
+-   Refactor `AuthService` to support a `TokenValidator` interface or strategy.
+-   Implement `JWTValidator` (existing) and `StaticTokenValidator` (new).
+-   Add `CHATGPT_SERVICE_TOKEN` to `AppConfig`.
+-   If `CHATGPT_SERVICE_TOKEN` is set, the backend will accept it as a valid Bearer token for any user context (or a specific "chatgpt-bot" user).
+
+**Rationale**:
+-   Hugging Face OAuth is not compatible with the Apps SDK OIDC flow.
+-   Implementing a full OIDC provider is out of scope for the hackathon.
+-   A static service token is secure enough for a demo/hackathon submission and easy to configure in the OpenAI Developer Platform.
+
+## 4. Infrastructure & Hosting
+
+**Decision**: Serve `widget.html` via FastAPI static mount with Skybridge MIME type.
+
+**Strategy**:
+-   Update `backend/src/api/main.py` to serve `frontend/dist/widget.html` on a specific route (e.g., `/widget`).
+-   Ensure the Content-Type header is `text/html+skybridge` (or whatever the specific requirement is, usually just serving it is enough, but we will double-check if OpenAI needs specific headers). *Correction: The expert mentioned `text/html+skybridge` media type for `FileResponse`.*
+-   Update CORS to allow `https://chatgpt.com` (and `https://*.chatgpt.com`).
+
+**Rationale**: Required for the widget to load inside the ChatGPT iframe.

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

@@ -0,0 +1,85 @@
+# Feature Specification: ChatGPT App Integration
+
+**Feature**: 003-chatgpt-app-integration
+**Status**: Draft
+**Created**: 2025-11-26
+
+## 1. Summary
+
+Transform the Document-MCP project into a "ChatGPT App" compatible with the OpenAI Apps SDK. This integration enables ChatGPT users to interact with their document vault using native-feeling UI widgets (Note Viewer, Search Results) embedded directly in the chat interface, powered by the existing FastMCP server.
+
+## 2. Problem Statement
+
+**Context**: Currently, the Document-MCP project works as a standalone web app or a standard MCP server.
+**Problem**: ChatGPT users accessing the vault via standard MCP tools receive raw markdown text in the chat stream, which is verbose and lacks interactivity. They cannot easily visualize the vault or navigate links without leaving the chat context.
+**Impact**: Limits the "AI Knowledge Assistant" experience by forcing users to context-switch between ChatGPT and a separate tab, or suffer through poor readability of raw text responses.
+
+## 3. Goals & Non-Goals
+
+### Goals
+-   **Seamless Integration**: Enable users to search, view, and edit notes entirely within the ChatGPT interface.
+-   **Visual Widgets**: Replace raw text responses with interactive UI widgets for:
+    -   Note Viewing (with Markdown rendering and Wikilink support)
+    -   Search Results (clean list with snippets)
+-   **Dual-Mode Operation**: Ensure the application continues to function as a standalone web app and standard MCP server while supporting the ChatGPT App mode.
+-   **Hackathon Readiness**: Prioritize a functional "demo user" or "service token" auth flow to ensure valid submission for the "Best ChatGPT App" category.
+
+### Non-Goals
+-   **Full Obsidian UI in Chat**: We will not iframe the entire application (sidebar, graph view, settings) into ChatGPT.
+-   **Production OAuth**: We will not implement a full OIDC provider for multi-tenant public access at this stage; a simplified auth strategy is sufficient for the hackathon.
+-   **Complex Graph Viz**: The Graph View widget is out of scope for the initial V1 integration.
+
+## 4. User Scenarios
+
+### Scenario 1: The Recall Loop
+**User**: A developer brainstorming in ChatGPT.
+**Action**: User asks, "What did I note about the authentication API?"
+**System**: ChatGPT calls `search_notes("authentication API")`.
+**Result**: Instead of a JSON dump, a **Search Results Widget** appears in the chat, listing matching notes. The user clicks "API Documentation" in the widget.
+**Follow-up**: The widget transitions to a **Note Viewer Widget**, displaying the rendered markdown of "API Documentation".
+
+### Scenario 2: In-Context Editing
+**User**: Reading the "API Documentation" note in the widget.
+**Action**: User tells ChatGPT, "Update the Auth section to mention we use RS256 now."
+**System**: ChatGPT calls `read_note` (invisible to user), generates the diff, calls `write_note`, and confirms.
+**Result**: The Note Viewer widget refreshes (or a status widget appears) showing the updated content directly in the thread.
+
+## 5. Functional Requirements
+
+### 5.1 Backend & MCP
+-   **Metadata Injection**: The `read_note` and `search_notes` tools must return a `CallToolResult` containing the `_meta.openai.outputTemplate` field to trigger widgets.
+-   **CORS**: The API must allow requests from `https://chatgpt.com` to support iframe loading.
+-   **Service Token**: The backend must support a configured `CHATGPT_SERVICE_TOKEN` to allow the OpenAI Apps SDK to authenticate without full user-facing OAuth.
+
+### 5.2 Frontend Widgets
+-   **Widget Entry Point**: A new build target (`widget.html` + `widget.tsx`) must be created to serve simplified UI components.
+-   **Note Viewer Widget**: A lightweight version of the `NoteViewer` component that:
+    -   Renders Markdown.
+    -   Handles Wikilink clicks (by requesting ChatGPT to navigate or loading the new note within the widget).
+    -   Hides the sidebar and app chrome.
+-   **Search Widget**: A simple list view for search results that triggers note navigation on click.
+
+### 5.3 Infrastructure
+-   **Static Serving**: The FastAPI server must serve `widget.html` with the correct `text/html+skybridge` MIME type when requested.
+-   **Build Pipeline**: The Vite configuration must output both the main SPA (`index.html`) and the widget bundle (`widget.html`).
+
+## 6. Success Criteria
+
+1.  **Widget Rendering**: A `read_note` tool call successfully renders the custom HTML widget inside the ChatGPT Developer Mode interface.
+2.  **Navigation**: Clicking a Wikilink in the widget successfully loads the target note (either by refreshing the widget or triggering a new tool call).
+3.  **Zero Regression**: The existing standalone web app (`/`) continues to function normally for local development.
+4.  **Performance**: Widget load time < 500ms (leveraging the lightweight bundle).
+
+## 7. Assumptions & Dependencies
+
+-   **Host**: Hugging Face Spaces or Localhost (tunneled) will be used for hosting.
+-   **Apps SDK**: We rely on the OpenAI Apps SDK beta features; behavior may be subject to platform changes.
+-   **Auth**: We assume a single-tenant or shared-tenant "demo" mode is acceptable for the hackathon submission.
+
+## 8. Questions & Clarifications
+
+1.  **Widget Navigation**: When a user clicks a link in the widget, should it trigger a client-side router push (staying in the same iframe) or ask ChatGPT to "open note X"?
+    *   *Assumption*: Client-side navigation within the widget is smoother for "browsing", while asking ChatGPT is better for "contextualizing". We will prioritize **client-side navigation** for V1 to keep the UI snappy.
+
+2.  **Auth Header**: Will ChatGPT send the service token in the `Authorization` header?
+    *   *Assumption*: Yes, we will configure the Custom API Action or App definition with the static Bearer token.