Add MVP specs

openspec/changes/document-mvp-capabilities/design.md

@@ -0,0 +1,120 @@
+## Context
+
+This plugin embeds the OpenCode AI assistant into Obsidian by spawning a local server process and displaying its web UI in an iframe within the Obsidian sidebar. The design prioritizes simplicity and reliability for the MVP.
+
+**Constraints:**
+- Desktop-only (requires Node.js child_process APIs)
+- Must work within Obsidian's plugin sandbox
+- OpenCode CLI must be installed separately by the user
+
+## Goals / Non-Goals
+
+**Goals:**
+- Seamless embedding of OpenCode UI in Obsidian sidebar
+- Reliable server process lifecycle management
+- Configurable server and project settings
+- Quick access via ribbon icon and keyboard shortcut
+
+**Non-Goals:**
+- Mobile support (not possible due to Node.js dependencies)
+- Native UI rendering (OpenCode provides its own web UI)
+- Multiple simultaneous OpenCode instances
+- Deep Obsidian integration (file linking, note references)
+
+## Decisions
+
+### 1. Iframe Embedding vs Native Rendering
+**Decision:** Embed OpenCode's web UI via iframe rather than building native Obsidian UI.
+
+**Rationale:**
+- OpenCode already provides a full-featured web interface
+- Reduces maintenance burden - UI updates come from OpenCode automatically
+- Allows feature parity with standalone OpenCode web experience
+
+**Trade-offs:**
+- Limited ability to customize UI appearance
+- Requires CORS configuration (`--cors app://obsidian.md`)
+- Iframe isolation limits some interactions
+
+### 2. Process State Machine
+**Decision:** Use a 4-state machine: `stopped` → `starting` → `running` | `error`
+
+**Rationale:**
+- Clear, predictable state transitions
+- Enables reactive UI that shows appropriate content for each state
+- Prevents race conditions (can't start while starting)
+
+**States:**
+- `stopped`: Server not running, show start button
+- `starting`: Spawn initiated, polling health endpoint, show spinner
+- `running`: Health check passed, show iframe
+- `error`: Spawn failed or health check timeout, show retry option
+
+### 3. Lazy Start Strategy
+**Decision:** Start server when view opens, not when plugin loads.
+
+**Rationale:**
+- Faster Obsidian startup (server spawn is ~2-5 seconds)
+- User may not need OpenCode every session
+- Auto-start available as opt-in setting for users who prefer it
+
+**Implementation:** `OpenCodeView.onOpen()` calls `plugin.startServer()` if state is `stopped`.
+
+### 4. Health Check Polling
+**Decision:** Poll `/global/health` endpoint every 500ms during startup, with 15-second timeout.
+
+**Rationale:**
+- Server needs time to initialize before accepting connections
+- Polling is simple and reliable
+- 15 seconds accommodates slow systems without waiting too long
+
+**Trade-offs:**
+- Slight delay before iframe loads (typically 1-3 seconds)
+- Could use server stdout parsing instead, but health endpoint is more reliable
+
+### 5. Graceful Shutdown
+**Decision:** SIGTERM first, SIGKILL after 2-second timeout.
+
+**Rationale:**
+- Allows server to clean up resources gracefully
+- SIGKILL fallback ensures process doesn't hang
+- 2 seconds is sufficient for typical cleanup
+
+### 6. Project Directory Encoding
+**Decision:** Encode project directory as base64 in URL path (e.g., `http://127.0.0.1:14096/{base64-path}`).
+
+**Rationale:**
+- OpenCode server supports multiple projects via URL routing
+- Base64 handles special characters in paths safely
+- Allows future support for switching projects without server restart
+
+### 7. Callback-Based State Subscriptions
+**Decision:** Use callback array pattern for state change notifications.
+
+**Rationale:**
+- Simpler than event emitters or observables for this scale
+- View subscribes to plugin state changes in `onOpen()`
+- Immediate notification ensures UI stays in sync
+
+**Implementation:**
+```typescript
+plugin.onProcessStateChange((state) => {
+  this.currentState = state;
+  this.updateView();
+});
+```
+
+## Risks / Trade-offs
+
+| Risk | Mitigation |
+|------|------------|
+| OpenCode CLI not installed | Clear error message with settings link |
+| Port already in use | Health check detects existing server, reuses it |
+| Server crash during use | View shows error state, user can retry |
+| Slow server startup | 15-second timeout with spinner feedback |
+
+## Open Questions
+
+- Should we support multiple project directories (tabs/switcher)?
+- Should settings changes hot-reload the iframe without full restart?
+- Should we add connection status indicator in header?