# packages/opencode/

OpenCode editor integration for FamiliarOS.

## Responsibility

Provides comprehensive OpenCode editor integration including: MCP server configuration, plugin runtime with event hooks, project/global setup management/removal, and instruction file generation.

## Design

**Plugin Architecture** (`plugin.ts`):
- Default export: `{ id, server }` object
- Server factory: `createFamiliarOSOpenCodeHooks(options)`
- Plugin ID: `familiaros-opencode`

**Plugin Runtime** (`opencode-plugin-runtime.ts`):
- Event hooks: `event`, `chat.message`, `tool.execute.before`, `tool.execute.after`
- Event classification: Maps OpenCode bus events to reactions/speech
- Tool classification: Edit → "editing", Bash test commands → "testing"
- Lease management: Acquires on first use, 2s buffer before expiry
- Throttling: 20s speech cooldown, 3s permission cooldown, 10s reaction cooldown
- Async scheduling via `queueMicrotask`

**Config Management** (`opencode-config.ts`):
- JSONC parsing with `jsonc-parser` (comments, trailing commas)
- Config path resolution (project: `.opencode/`, global: `~/.config/opencode/`)
- Safe file operations: atomic writes, backups, permission checks (0o600/0o700)
- Path traversal prevention (relative path validation)
- Symlink detection and rejection

**Project Setup** (`opencode-project-setup.ts`):
- Status classification: `not_installed`, `installed`, `needs_update`, `custom`, `conflict`, `error`
- Managed block detection in instruction files (`<!-- FAMILIAROS:START/END -->`)
- Config field updates: `mcp`, `instructions`, `plugin` arrays
- Instruction file: `.opencode/familiaros.md` with usage guidelines

**Global Setup** (`opencode-global-setup.ts`):
- Similar to project setup but for `~/.config/opencode/`
- Setup cleanup writes: Removes managed duplicate entries from other config files
- Remove support: `prepareOpenCodeGlobalRemove()` / `writePreparedOpenCodeGlobalRemove()` remove managed MCP, instruction, and plugin entries plus the managed instruction block
- Doctor command: `doctorOpenCodeGlobalSetup()` for status checking
- Config precedence handling: chooses the effective config file across `config.json`, `opencode.json`, and `opencode.jsonc`, preserving existing user arrays when safe

**Status Classification** (`opencode-status.ts`):
- MCP entry detection: `isManagedFamiliarOSMcpEntry()`
- Plugin entry detection: `isManagedFamiliarOSPluginEntry()`
- Command pattern matching (npx, node, local paths)
- Version comparison for update detection

**Previews** (`opencode-previews.ts`):
- MCP entry builder: `buildOpenCodeMcpEntry()` (published/local/bundled modes)
- Plugin spec builder: `buildOpenCodePluginPreview()`
- Instruction path builder: `buildOpenCodeInstructionPath()`
- Familiar ID validation: `validateFamiliarOSPetArg()`
- MCP config formatter: `formatOpenCodeMcpConfig()`

## Flow

```
prepareOpenCodeProjectSetup({ projectDir, petId, cliVersion })
    ↓
readExistingConfigs() → Parse all candidate config files
    ↓
classifyOpenCodeMcpStatus() → Check if installed/needs update/conflict
    ↓
classifyOpenCodeInstructionsStatus() → Check instruction file
    ↓
classifyOpenCodePluginStatus() → Check plugin array
    ↓
buildNextConfig() → Merge mcp/instructions/plugin updates
    ↓
planOpenCodeConfigWrite() → Atomic write plan with backup
    ↓
planInstructionWrite() → Upsert managed instruction block
    ↓
writePreparedOpenCodeProjectSetup() → Execute writes atomically
```

## Integration Points

**Dependencies**:
- `@familiaros/client` - IPC for plugin runtime
- `@familiaros/agent-events` - Speech pools and validation
- `jsonc-parser` - JSONC config parsing and editing

**Package Surface**:
- Package version: `2.1.1`
- Main export (`.`): setup, config, preview, status, and runtime APIs from `dist/index.js`
- Server export (`./server`): OpenCode plugin default export from `dist/plugin.js`

**Consumers**:
- `@familiaros/cli` - `configure` command for OpenCode projects

**Exports**:
- `plugin.ts` - Default plugin export for OpenCode
- `prepareOpenCodeProjectSetup()`, `writePreparedOpenCodeProjectSetup()`
- `prepareOpenCodeGlobalSetup()`, `writePreparedOpenCodeGlobalSetup()`
- `prepareOpenCodeGlobalRemove()`, `writePreparedOpenCodeGlobalRemove()`
- Config management utilities