# Project Context

## Purpose
Obsidian plugin that embeds the OpenCode AI assistant via an iframe. The plugin spawns a local OpenCode server process and displays its web UI in the Obsidian sidebar, enabling AI-assisted coding and note-taking within Obsidian.

## Tech Stack
- **TypeScript** - Primary language with strict null checks
- **Obsidian Plugin API** - For UI integration, views, settings, and commands
- **esbuild** - Bundler (ES2018 target, CommonJS output)
- **Node.js child_process** - For spawning the OpenCode server process
- **Bun** - Package manager and runtime

## Project Conventions

### Code Style

**Imports:**
- ES modules with named imports
- Order: Obsidian API → Node.js builtins → local modules
- Use `type` keyword for type-only imports
- Relative paths with `./` prefix

```typescript
import { Plugin, WorkspaceLeaf, Notice } from "obsidian";
import { spawn, ChildProcess } from "child_process";
import type OpenCodePlugin from "./main";
import { OpenCodeSettings, DEFAULT_SETTINGS } from "./types";
```

**Naming Conventions:**
| Type | Convention | Example |
|------|------------|---------|
| Classes | PascalCase | `OpenCodePlugin`, `ProcessManager` |
| Interfaces/Types | PascalCase | `OpenCodeSettings`, `ProcessState` |
| Constants | UPPER_CASE or camelCase | `DEFAULT_SETTINGS`, `OPENCODE_VIEW_TYPE` |
| Variables/functions | camelCase | `getVaultPath`, `startServer` |
| Private members | camelCase (no prefix) | `private processManager` |
| Files | PascalCase for classes | `ProcessManager.ts`, `OpenCodeView.ts` |

**TypeScript Patterns:**
- `strictNullChecks` enabled - always handle null/undefined
- Union types for state: `"stopped" | "starting" | "running" | "error"`
- `async/await` over raw Promises
- Explicit return types on public methods

### Architecture Patterns

**Project Structure:**
```
src/
├── main.ts           # Plugin entry, extends Plugin
├── types.ts          # Types and constants
├── OpenCodeView.ts   # Sidebar view (ItemView) with iframe
├── ProcessManager.ts # Server process lifecycle
├── SettingsTab.ts    # Settings UI (PluginSettingTab)
└── icons.ts          # Custom icon registration
```

**Obsidian Patterns:**
- Extend `Plugin` with `onload()`/`onunload()` lifecycle
- Extend `ItemView` for views: `getViewType()`, `onOpen()`, `onClose()`
- Extend `PluginSettingTab` for settings: `display()`
- DOM helpers: `createEl()`, `createDiv()`, `setIcon()`
- Register in `onload()`, clean up in `onunload()`

**State Management:**
- Callback-based subscriptions for state changes
- Centralized state in manager classes (ProcessManager)
- Immediate notification on state change via callbacks

**Error Handling:**
- try/catch for async operations
- `console.error()` for debugging
- `new Notice()` for user-facing errors
- Boolean returns for success/failure
- Silent catch for non-critical ops (health checks)

### Testing Strategy
Not currently configured. If adding tests:
- Use Vitest for test runner
- Place tests in `src/__tests__/` or `*.test.ts` files
- Add ESLint with `@typescript-eslint/parser` for linting

### Git Workflow
Standard feature branch workflow. Commit messages should be concise and describe the change.

## Domain Context

**OpenCode Server:**
- OpenCode is an AI assistant CLI that can run as a web server
- The plugin spawns `opencode serve` with port/hostname/CORS flags
- Server health is checked via `/global/health` endpoint
- Project directory is encoded as base64 in the URL path

**Obsidian Integration:**
- View is registered with `OPENCODE_VIEW_TYPE` constant
- Opens in right sidebar by default
- Supports lazy start (starts server when view opens)
- Auto-start option available in settings

**Process States:**
- `stopped` - Server not running
- `starting` - Server spawn initiated, waiting for health check
- `running` - Server healthy and responding
- `error` - Server failed to start or crashed

## Important Constraints

**Desktop Only:**
- Uses Node.js APIs (`child_process.spawn()`) unavailable on mobile
- File system access via vault adapter requires desktop
- Check for desktop environment before adding mobile-incompatible features

**Build Output:**
- Must produce single `main.js` file (CommonJS format)
- External: `obsidian`, `electron`, CodeMirror modules, Node.js builtins

**TypeScript Config:**
- Target: ES6
- Module: ESNext (bundled to CJS)
- Strict null checks enabled
- No implicit any

## External Dependencies

**Runtime:**
- OpenCode CLI must be installed on user's system (configurable path)
- Default port: 14096, hostname: 127.0.0.1

**Development:**
- `obsidian` - Obsidian API types and runtime
- `@types/node` - Node.js type definitions
- `esbuild` - Build bundler
- `typescript` - Type checking