john/claude-engineering-plugin
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

phase 04: deep merge opencode json

Browse Source
This commit is contained in:
Adrian
2026-02-20 13:30:17 -05:00
parent 5abddbcbd9
commit 3914dfdebe
5 changed files with 818 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

574
docs/plans/feature_opencode-commands-as-md-and-config-merge.md Normal file
View File

@@ -0,0 +1,574 @@
# Feature: OpenCode Commands as .md Files, Config Merge, and Permissions Default Fix
**Type:** feature + bug fix (consolidated)
**Date:** 2026-02-20
**Starting point:** Branch `main` at commit `174cd4c`
**Create feature branch:** `feature/opencode-commands-md-merge-permissions`
**Baseline tests:** 180 pass, 0 fail (run `bun test` to confirm before starting)
---
## Context
### User-Facing Goal
When running `bunx @every-env/compound-plugin install compound-engineering --to opencode`, three problems exist:
1. **Commands overwrite `opencode.json`**: Plugin commands are written into the `command` key of `opencode.json`, which replaces the user's existing configuration file (the writer does `writeJson(configPath, bundle.config)` — a full overwrite). The user loses their personal settings (model, theme, provider keys, MCP servers they previously configured).
2. **Commands should be `.md` files, not JSON**: OpenCode supports defining commands as individual `.md` files in `~/.config/opencode/commands/`. This is additive and non-destructive — one file per command, never touches `opencode.json`.
3. **`--permissions broad` is the default and pollutes global config**: The `--permissions` flag defaults to `"broad"`, which writes 14 `permission: allow` entries and 14 `tools: true` entries into `opencode.json` on every install. These are global settings that affect ALL OpenCode sessions, not just plugin commands. Even `--permissions from-commands` is semantically wrong — it unions per-command `allowedTools` restrictions into a single global block, which inverts restriction semantics (a command allowing only `Read` gets merged with one allowing `Bash`, producing global `bash: allow`).
### Expected Behavior After This Plan
- Commands are written as `~/.config/opencode/commands/<name>.md` with YAML frontmatter (`description`, `model`). The `command` key is never written to `opencode.json`.
- `opencode.json` is deep-merged (not overwritten): existing user keys survive, plugin's MCP servers are added. User values win on conflict.
- `--permissions` defaults to `"none"` — no `permission` or `tools` entries are written to `opencode.json` unless the user explicitly passes `--permissions broad` or `--permissions from-commands`.
### Relevant File Paths
| File | Current State on `main` | What Changes |
|---|---|---|
| `src/types/opencode.ts` | `OpenCodeBundle` has no `commandFiles` field. Has `OpenCodeCommandConfig` type and `command` field on `OpenCodeConfig`. | Add `OpenCodeCommandFile` type. Add `commandFiles` to `OpenCodeBundle`. Remove `OpenCodeCommandConfig` type and `command` field from `OpenCodeConfig`. |
| `src/converters/claude-to-opencode.ts` | `convertCommands()` returns `Record<string, OpenCodeCommandConfig>`. Result set on `config.command`. `applyPermissions()` writes `config.permission` and `config.tools`. | `convertCommands()` returns `OpenCodeCommandFile[]`. `config.command` is never set. No changes to `applyPermissions()` itself. |
| `src/targets/opencode.ts` | `writeOpenCodeBundle()` does `writeJson(configPath, bundle.config)` — full overwrite. No `commandsDir`. No merge logic. | Add `commandsDir` to path resolver. Write command `.md` files with backup. Replace overwrite with `mergeOpenCodeConfig()` — read existing, deep-merge, write back. |
| `src/commands/install.ts` | `--permissions` default is `"broad"` (line 51). | Change default to `"none"`. Update description string. |
| `src/utils/files.ts` | Has `readJson()`, `pathExists()`, `backupFile()` already. | No changes needed — utilities already exist. |
| `tests/converter.test.ts` | Tests reference `bundle.config.command` (lines 19, 74, 202-214, 243). Test `"maps commands, permissions, and agents"` tests `from-commands` mode. | Update all to use `bundle.commandFiles`. Rename permission-related test to clarify opt-in nature. |
| `tests/opencode-writer.test.ts` | 4 tests, none have `commandFiles` in bundles. `"backs up existing opencode.json before overwriting"` test expects full overwrite. | Add `commandFiles: []` to all existing bundles. Rewrite backup test to test merge behavior. Add new tests for command file writing and merge. |
| `tests/cli.test.ts` | 10 tests. None check for commands directory. | Add test for `--permissions none` default. Add test for command `.md` file existence. |
| `AGENTS.md` | Line 10: "Keep OpenCode output at `opencode.json` and `.opencode/{agents,skills,plugins}`." | Update to document commands go to `commands/<name>.md`, `opencode.json` is deep-merged. |
| `README.md` | Line 54: "OpenCode output is written to `~/.config/opencode` by default, with `opencode.json` at the root..." | Update to document `.md` command files, merge behavior, `--permissions` default. |
### Prior Context (Pre-Investigation)
- **No `docs/decisions/` directory on `main`**: ADRs will be created fresh during this plan.
- **No prior plans touch the same area**: The `2026-02-08-feat-convert-local-md-settings-for-opencode-codex-plan.md` discusses path rewriting in command bodies but does not touch command output format or permissions.
- **OpenCode docs (confirmed via context7 MCP, library `/sst/opencode`):**
- Command `.md` frontmatter supports: `description`, `agent`, `model`. Does NOT support `permission` or `tools`. Placed in `~/.config/opencode/commands/` (global) or `.opencode/commands/` (project).
- Agent `.md` frontmatter supports: `description`, `mode`, `model`, `temperature`, `tools`, `permission`. Placed in `~/.config/opencode/agents/` or `.opencode/agents/`.
- `opencode.json` is the only place for: `mcp`, global `permission`, global `tools`, `model`, `provider`, `theme`, `server`, `compaction`, `watcher`, `share`.
### Rejected Approaches
**1. Map `allowedTools` to per-agent `.md` frontmatter permissions.**
Rejected: Claude commands are not agents. There is no per-command-to-per-agent mapping. Commands don't specify which agent to run with. Even if they did, the union of multiple commands' restrictions onto a single agent's permissions loses the per-command scoping. Agent `.md` files DO support `permission` in frontmatter, but this would require creating synthetic agents just to hold permissions — misleading and fragile.
**2. Write permissions into command `.md` file frontmatter.**
Rejected: OpenCode command `.md` files only support `description`, `agent`, `model` in frontmatter. There is no `permission` or `tools` key. Confirmed via context7 docs. Anything else is silently ignored.
**3. Keep `from-commands` as the default but fix the flattening logic.**
Rejected: There is no correct way to flatten per-command tool restrictions into a single global permission block. Any flattening loses information and inverts semantics.
**4. Remove the `--permissions` flag entirely.**
Rejected: Some users may want to write permissions to `opencode.json` as a convenience. Keeping the flag with a changed default preserves optionality.
**5. Write commands as both `.md` files AND in `opencode.json` `command` block.**
Rejected: Redundant and defeats the purpose of avoiding `opencode.json` pollution. `.md` files are the sole output format.
---
## Decision Record
### Decision 1: Commands emitted as individual `.md` files, never in `opencode.json`
- **Decision:** `convertCommands()` returns `OpenCodeCommandFile[]` (one `.md` file per command with YAML frontmatter). The `command` key is never set on `OpenCodeConfig`. The writer creates `<commandsDir>/<name>.md` for each file.
- **Context:** OpenCode supports two equivalent formats for commands — JSON in config and `.md` files. The `.md` format is additive (new files) rather than destructive (rewriting JSON). This is consistent with how agents and skills are already handled as `.md` files.
- **Alternatives rejected:** JSON-only (destructive), both formats (redundant). See Rejected Approaches above.
- **Assumptions:** OpenCode resolves commands from the `commands/` directory at runtime. Confirmed via docs.
- **Reversal trigger:** If OpenCode deprecates `.md` command files or the format changes incompatibly.
### Decision 2: `opencode.json` deep-merged, not overwritten
- **Decision:** `writeOpenCodeBundle()` reads the existing `opencode.json` (if present), deep-merges plugin-provided keys (MCP servers, and optionally permission/tools if `--permissions` is not `none`) without overwriting user-set values, and writes the merged result. User keys always win on conflict.
- **Context:** Users have personal configuration in `opencode.json` (API keys, model preferences, themes, existing MCP servers). The current full-overwrite destroys all of this.
- **Alternatives rejected:** Skip writing `opencode.json` entirely — rejected because MCP servers must be written there (no `.md` alternative exists for MCP).
- **Assumptions:** `readJson()` and `pathExists()` already exist in `src/utils/files.ts`. Malformed JSON in existing file should warn and fall back to plugin-only config (do not crash, do not destroy).
- **Reversal trigger:** If OpenCode adds a separate mechanism for plugin MCP server registration that doesn't involve `opencode.json`.
### Decision 3: `--permissions` default changed from `"broad"` to `"none"`
- **Decision:** The `--permissions` CLI flag default changes from `"broad"` to `"none"`. No `permission` or `tools` keys are written to `opencode.json` unless the user explicitly opts in.
- **Context:** `"broad"` silently writes 14 global tool permissions. `"from-commands"` has a semantic inversion bug (unions per-command restrictions into global allows). Both are destructive to user config. `applyPermissions()` already short-circuits on `"none"` (line 299: `if (mode === "none") return`), so no changes to that function are needed.
- **Alternatives rejected:** Fix `from-commands` flattening — impossible to do correctly with global-only target. Remove flag entirely — too restrictive for power users.
- **Assumptions:** The `applyPermissions()` function with mode `"none"` leaves `config.permission` and `config.tools` as `undefined`.
- **Reversal trigger:** If OpenCode adds per-command permission scoping, `from-commands` could become meaningful again.
---
## ADRs To Create
Create `docs/decisions/` directory (does not exist on `main`). ADRs follow `AGENTS.md` numbering convention: `0001-short-title.md`.
### ADR 0001: OpenCode commands written as `.md` files, not in `opencode.json`
- **Context:** OpenCode supports two equivalent formats for custom commands. Writing to `opencode.json` requires overwriting or merging the user's config file. Writing `.md` files is additive and non-destructive.
- **Decision:** The OpenCode target always emits commands as individual `.md` files in the `commands/` subdirectory. The `command` key is never written to `opencode.json` by this tool.
- **Consequences:**
- Positive: Installs are non-destructive. Commands are visible as individual files, easy to inspect. Consistent with agents/skills handling.
- Negative: Users inspecting `opencode.json` won't see plugin commands; they must look in `commands/`.
- Neutral: Requires OpenCode >= the version with command file support (confirmed stable).
### ADR 0002: Plugin merges into existing `opencode.json` rather than replacing it
- **Context:** Users have existing `opencode.json` files with personal configuration. The install command previously backed up and replaced this file entirely, destroying user settings.
- **Decision:** `writeOpenCodeBundle` reads existing `opencode.json` (if present), deep-merges plugin-provided keys without overwriting user-set values, and writes the merged result. User keys always win on conflict.
- **Consequences:**
- Positive: User config preserved across installs. Re-installs are idempotent for user-set values.
- Negative: Plugin cannot remove or update an MCP server entry if the user already has one with the same name.
- Neutral: Backup of pre-merge file is still created for safety.
### ADR 0003: Global permissions not written to `opencode.json` by default
- **Context:** Claude commands carry `allowedTools` as per-command restrictions. OpenCode has no per-command permission mechanism. Writing per-command restrictions as global permissions is semantically incorrect and pollutes the user's global config.
- **Decision:** `--permissions` defaults to `"none"`. The plugin never writes `permission` or `tools` to `opencode.json` unless the user explicitly passes `--permissions broad` or `--permissions from-commands`.
- **Consequences:**
- Positive: User's global OpenCode permissions are never silently modified.
- Negative: Users who relied on auto-set permissions must now pass the flag explicitly.
- Neutral: The `"broad"` and `"from-commands"` modes still work as documented for opt-in use.
---
## Assumptions & Invalidation Triggers
- **Assumption:** OpenCode command `.md` frontmatter supports `description`, `agent`, `model` and does NOT support `permission` or `tools`.
- **If this changes:** The converter could emit per-command permissions in command frontmatter, making `from-commands` mode semantically correct. Phase 2 would need a new code path.
- **Assumption:** `readJson()` and `pathExists()` exist in `src/utils/files.ts` and work as expected.
- **If this changes:** Phase 4's merge logic needs alternative I/O utilities.
- **Assumption:** `applyPermissions()` with mode `"none"` returns early at line 299 and does not set `config.permission` or `config.tools`.
- **If this changes:** The merge logic in Phase 4 might still merge stale data. Verify before implementing.
- **Assumption:** 180 tests pass on `main` at commit `174cd4c` with `bun test`.
- **If this changes:** Do not proceed until the discrepancy is understood.
- **Assumption:** `formatFrontmatter()` in `src/utils/frontmatter.ts` handles `Record<string, unknown>` data and string body, producing valid YAML frontmatter. It filters out `undefined` values (line 35). It already supports nested objects/arrays via `formatYamlLine()`.
- **If this changes:** Phase 2's command file content generation would produce malformed output.
- **Assumption:** The `backupFile()` function in `src/utils/files.ts` returns `null` if the file does not exist, and returns the backup path if it does. It does NOT throw on missing files.
- **If this changes:** Phase 4's backup-before-write for command files would need error handling.
---
## Phases
### Phase 1: Add `OpenCodeCommandFile` type and update `OpenCodeBundle`
**What:** In `src/types/opencode.ts`:
- Add a new type `OpenCodeCommandFile` with `name: string` (command name, used as filename stem) and `content: string` (full file content: YAML frontmatter + body).
- Add `commandFiles: OpenCodeCommandFile[]` field to `OpenCodeBundle`.
- Remove `command?: Record<string, OpenCodeCommandConfig>` from `OpenCodeConfig`.
- Remove the `OpenCodeCommandConfig` type entirely (lines 23-28).
**Why:** This is the foundational type change that all subsequent phases depend on. Commands move from the config object to individual file entries in the bundle.
**Test first:**
File: `tests/converter.test.ts`
Before making any type changes, update the test file to reflect the new shape. The existing tests will fail because they reference `bundle.config.command` and `OpenCodeBundle` doesn't have `commandFiles` yet.
Tests to modify (they will fail after type changes, then pass after Phase 2):
- `"maps commands, permissions, and agents"` (line 11): Change `bundle.config.command?.["workflows:review"]` to `bundle.commandFiles.find(f => f.name === "workflows:review")`. Change `bundle.config.command?.["plan_review"]` to `bundle.commandFiles.find(f => f.name === "plan_review")`.
- `"normalizes models and infers temperature"` (line 60): Change `bundle.config.command?.["workflows:work"]` to check `bundle.commandFiles.find(f => f.name === "workflows:work")` and parse its frontmatter for model.
- `"excludes commands with disable-model-invocation from command map"` (line 202): Change `bundle.config.command?.["deploy-docs"]` to `bundle.commandFiles.find(f => f.name === "deploy-docs")`.
- `"rewrites .claude/ paths to .opencode/ in command bodies"` (line 217): Change `bundle.config.command?.["review"]?.template` to access `bundle.commandFiles.find(f => f.name === "review")?.content`.
Also update `tests/opencode-writer.test.ts`:
- Add `commandFiles: []` to every `OpenCodeBundle` literal in all 4 existing tests (lines 20, 43, 67, 98). These bundles currently only have `config`, `agents`, `plugins`, `skillDirs`.
**Implementation:**
In `src/types/opencode.ts`:
1. Remove lines 23-28 (`OpenCodeCommandConfig` type).
2. Remove line 10 (`command?: Record<string, OpenCodeCommandConfig>`) from `OpenCodeConfig`.
3. Add after line 47:
```typescript
export type OpenCodeCommandFile = {
name: string // command name, used as the filename stem: <name>.md
content: string // full file content: YAML frontmatter + body
}
```
4. Add `commandFiles: OpenCodeCommandFile[]` to `OpenCodeBundle` (between `agents` and `plugins`).
In `src/converters/claude-to-opencode.ts`:
- Update the import on line 11: Remove `OpenCodeCommandConfig` from the import. Add `OpenCodeCommandFile`.
**Code comments required:**
- Above the `commandFiles` field in `OpenCodeBundle`: `// Commands are written as individual .md files, not in opencode.json. See ADR-001.`
**Verification:** `bun test` will show failures in converter tests (they reference the old command format). This is expected — Phase 2 fixes them.
---
### Phase 2: Convert `convertCommands()` to emit `.md` command files
**What:** In `src/converters/claude-to-opencode.ts`:
- Rewrite `convertCommands()` (line 114) to return `OpenCodeCommandFile[]` instead of `Record<string, OpenCodeCommandConfig>`.
- Each command becomes a `.md` file with YAML frontmatter (`description`, optionally `model`) and body (the template text with Claude path rewriting applied).
- In `convertClaudeToOpenCode()` (line 64): replace `commandMap` with `commandFiles`. Remove `config.command` assignment. Add `commandFiles` to returned bundle.
**Why:** This is the core conversion logic change that implements ADR-001.
**Test first:**
File: `tests/converter.test.ts`
The tests were already updated in Phase 1 to reference `bundle.commandFiles`. Now they need to pass. Specific assertions:
1. Rename `"maps commands, permissions, and agents"` to `"from-commands mode: maps allowedTools to global permission block"` — to clarify this tests an opt-in mode, not the default.
- Assert `bundle.config.command` is `undefined` (it no longer exists on the type, but accessing it returns `undefined`).
- Assert `bundle.commandFiles.find(f => f.name === "workflows:review")` is defined.
- Assert `bundle.commandFiles.find(f => f.name === "plan_review")` is defined.
- Permission assertions remain unchanged (they test `from-commands` mode explicitly).
2. `"normalizes models and infers temperature"`:
- Find `workflows:work` in `bundle.commandFiles`, parse its frontmatter with `parseFrontmatter()`, assert `data.model === "openai/gpt-4o"`.
3. `"excludes commands with disable-model-invocation from command map"` — rename to `"excludes commands with disable-model-invocation from commandFiles"`:
- Assert `bundle.commandFiles.find(f => f.name === "deploy-docs")` is `undefined`.
- Assert `bundle.commandFiles.find(f => f.name === "workflows:review")` is defined.
4. `"rewrites .claude/ paths to .opencode/ in command bodies"`:
- Find `review` in `bundle.commandFiles`, assert `content` contains `"compound-engineering.local.md"`.
5. Add NEW test: `"command .md files include description in frontmatter"`:
- Create a minimal `ClaudePlugin` with one command (`name: "test-cmd"`, `description: "Test description"`, `body: "Do the thing"`).
- Convert with `permissions: "none"`.
- Find the command file, parse frontmatter, assert `data.description === "Test description"`.
- Assert the body (after frontmatter) contains `"Do the thing"`.
**Implementation:**
In `src/converters/claude-to-opencode.ts`:
Replace lines 114-128 (`convertCommands` function):
```typescript
// Commands are written as individual .md files rather than entries in opencode.json.
// Chosen over JSON map because opencode resolves commands by filename at runtime (ADR-001).
function convertCommands(commands: ClaudeCommand[]): OpenCodeCommandFile[] {
const files: OpenCodeCommandFile[] = []
for (const command of commands) {
if (command.disableModelInvocation) continue
const frontmatter: Record<string, unknown> = {
description: command.description,
}
if (command.model && command.model !== "inherit") {
frontmatter.model = normalizeModel(command.model)
}
const content = formatFrontmatter(frontmatter, rewriteClaudePaths(command.body))
files.push({ name: command.name, content })
}
return files
}
```
Replace lines 64-87 (`convertClaudeToOpenCode` function body):
- Change line 69: `const commandFiles = convertCommands(plugin.commands)`
- Change lines 73-77 (config construction): Remove the `command: ...` line. Config should only have `$schema` and `mcp`.
- Change line 81-86 (return): Replace `plugins` in the return with `commandFiles, plugins` (add `commandFiles` field to returned bundle).
**Code comments required:**
- Above `convertCommands()`: `// Commands are written as individual .md files rather than entries in opencode.json.` and `// Chosen over JSON map because opencode resolves commands by filename at runtime (ADR-001).`
**Verification:** Run `bun test tests/converter.test.ts`. All converter tests must pass. Then run `bun test` — writer tests should still fail (they expect the old bundle shape; fixed in Phase 1's test updates) but converter tests pass.
---
### Phase 3: Add `commandsDir` to path resolver and write command files
**What:** In `src/targets/opencode.ts`:
- Add `commandsDir` to the return value of `resolveOpenCodePaths()` for both branches (global and custom output dir).
- In `writeOpenCodeBundle()`, iterate `bundle.commandFiles` and write each as `<commandsDir>/<name>.md` with backup-before-overwrite.
**Why:** This creates the file output mechanism for command `.md` files. Separated from Phase 4 (merge logic) for testability.
**Test first:**
File: `tests/opencode-writer.test.ts`
Add these new tests:
1. `"writes command files as .md in commands/ directory"`:
- Create a bundle with one `commandFiles` entry: `{ name: "my-cmd", content: "---\ndescription: Test\n---\n\nDo something." }`.
- Use an output root of `path.join(tempRoot, ".config", "opencode")` (global-style).
- Assert `exists(path.join(outputRoot, "commands", "my-cmd.md"))` is true.
- Read the file, assert content matches (with trailing newline: `content + "\n"`).
2. `"backs up existing command .md file before overwriting"`:
- Pre-create `commands/my-cmd.md` with old content.
- Write a bundle with a `commandFiles` entry for `my-cmd`.
- Assert a `.bak.` file exists in `commands/` directory.
- Assert new content is written.
**Implementation:**
In `resolveOpenCodePaths()`:
- In the global branch (line 39-46): Add `commandsDir: path.join(outputRoot, "commands")` with comment: `// .md command files; alternative to the command key in opencode.json`
- In the custom branch (line 49-56): Add `commandsDir: path.join(outputRoot, ".opencode", "commands")` with same comment.
In `writeOpenCodeBundle()`:
- After the agents loop (line 18), add:
```typescript
const commandsDir = paths.commandsDir
for (const commandFile of bundle.commandFiles) {
const dest = path.join(commandsDir, `${commandFile.name}.md`)
const cmdBackupPath = await backupFile(dest)
if (cmdBackupPath) {
console.log(`Backed up existing command file to ${cmdBackupPath}`)
}
await writeText(dest, commandFile.content + "\n")
}
```
**Code comments required:**
- Inline comment on `commandsDir` in both `resolveOpenCodePaths` branches: `// .md command files; alternative to the command key in opencode.json`
**Verification:** Run `bun test tests/opencode-writer.test.ts`. The two new command file tests must pass. Existing tests must still pass (they have `commandFiles: []` from Phase 1 updates).
---
### Phase 4: Replace config overwrite with deep-merge
**What:** In `src/targets/opencode.ts`:
- Replace `writeJson(paths.configPath, bundle.config)` (line 13) with a call to a new `mergeOpenCodeConfig()` function.
- `mergeOpenCodeConfig()` reads the existing `opencode.json` (if present), merges plugin-provided keys using user-wins-on-conflict strategy, and returns the merged config.
- Import `pathExists` and `readJson` from `../utils/files` (add to existing import on line 2).
**Why:** This implements ADR-002 — the user's existing config is preserved across installs.
**Test first:**
File: `tests/opencode-writer.test.ts`
Modify existing test and add new tests:
1. Rename `"backs up existing opencode.json before overwriting"` (line 88) to `"merges plugin config into existing opencode.json without destroying user keys"`:
- Pre-create `opencode.json` with `{ $schema: "https://opencode.ai/config.json", custom: "value" }`.
- Write a bundle with `config: { $schema: "...", mcp: { "plugin-server": { type: "local", command: "uvx", args: ["plugin-srv"] } } }`.
- Assert merged config has BOTH `custom: "value"` (user key) AND `mcp["plugin-server"]` (plugin key).
- Assert backup file exists with original content.
2. NEW: `"merges mcp servers without overwriting user entries"`:
- Pre-create `opencode.json` with `{ mcp: { "user-server": { type: "local", command: "uvx", args: ["user-srv"] } } }`.
- Write a bundle with `config.mcp` containing both `"plugin-server"` (new) and `"user-server"` (conflict — different args).
- Assert both servers exist in merged output.
- Assert `user-server` keeps user's original args (user wins on conflict).
- Assert `plugin-server` is present with plugin's args.
3. NEW: `"preserves unrelated user keys when merging opencode.json"`:
- Pre-create `opencode.json` with `{ model: "my-model", theme: "dark", mcp: {} }`.
- Write a bundle with `config: { $schema: "...", mcp: { "plugin-server": ... }, permission: { "bash": "allow" } }`.
- Assert `model` and `theme` are preserved.
- Assert plugin additions are present.
**Implementation:**
Add to imports in `src/targets/opencode.ts` line 2:
```typescript
import { backupFile, copyDir, ensureDir, pathExists, readJson, writeJson, writeText } from "../utils/files"
import type { OpenCodeBundle, OpenCodeConfig } from "../types/opencode"
```
Add `mergeOpenCodeConfig()` function:
```typescript
async function mergeOpenCodeConfig(
configPath: string,
incoming: OpenCodeConfig,
): Promise<OpenCodeConfig> {
// If no existing config, write plugin config as-is
if (!(await pathExists(configPath))) return incoming
let existing: OpenCodeConfig
try {
existing = await readJson<OpenCodeConfig>(configPath)
} catch {
// Safety first per AGENTS.md -- do not destroy user data even if their config is malformed.
// Warn and fall back to plugin-only config rather than crashing.
console.warn(
`Warning: existing ${configPath} is not valid JSON. Writing plugin config without merging.`
)
return incoming
}
// User config wins on conflict -- see ADR-002
// MCP servers: add plugin entries, skip keys already in user config.
const mergedMcp = {
...(incoming.mcp ?? {}),
...(existing.mcp ?? {}), // existing takes precedence (overwrites same-named plugin entries)
}
// Permission: add plugin entries, skip keys already in user config.
const mergedPermission = incoming.permission
? {
...(incoming.permission),
...(existing.permission ?? {}), // existing takes precedence
}
: existing.permission
// Tools: same pattern
const mergedTools = incoming.tools
? {
...(incoming.tools),
...(existing.tools ?? {}),
}
: existing.tools
return {
...existing, // all user keys preserved
$schema: incoming.$schema ?? existing.$schema,
mcp: Object.keys(mergedMcp).length > 0 ? mergedMcp : undefined,
permission: mergedPermission,
tools: mergedTools,
}
}
```
In `writeOpenCodeBundle()`, replace line 13 (`await writeJson(paths.configPath, bundle.config)`) with:
```typescript
const merged = await mergeOpenCodeConfig(paths.configPath, bundle.config)
await writeJson(paths.configPath, merged)
```
**Code comments required:**
- Above `mergeOpenCodeConfig()`: `// Merges plugin config into existing opencode.json. User keys win on conflict. See ADR-002.`
- On the `...(existing.mcp ?? {})` line: `// existing takes precedence (overwrites same-named plugin entries)`
- On malformed JSON catch: `// Safety first per AGENTS.md -- do not destroy user data even if their config is malformed.`
**Verification:** Run `bun test tests/opencode-writer.test.ts`. All tests must pass including the renamed test and the 2 new merge tests.
---
### Phase 5: Change `--permissions` default to `"none"`
**What:** In `src/commands/install.ts`, change line 51 `default: "broad"` to `default: "none"`. Update the description string.
**Why:** This implements ADR-003 — stops polluting user's global config with permissions by default.
**Test first:**
File: `tests/cli.test.ts`
Add these tests:
1. `"install --to opencode uses permissions:none by default"`:
- Run install with no `--permissions` flag against the fixture plugin.
- Read the written `opencode.json`.
- Assert it does NOT contain a `permission` key.
- Assert it does NOT contain a `tools` key.
2. `"install --to opencode --permissions broad writes permission block"`:
- Run install with `--permissions broad` against the fixture plugin.
- Read the written `opencode.json`.
- Assert it DOES contain a `permission` key with values.
**Implementation:**
In `src/commands/install.ts`:
- Line 51: Change `default: "broad"` to `default: "none"`.
- Line 52: Change description to `"Permission mapping written to opencode.json: none (default) | broad | from-commands"`.
**Code comments required:**
- On the `default: "none"` line: `// Default is "none" -- writing global permissions to opencode.json pollutes user config. See ADR-003.`
**Verification:** Run `bun test tests/cli.test.ts`. All CLI tests must pass including the 2 new permission tests. Then run `bun test` — all tests (180 original + new ones) must pass.
---
### Phase 6: Update `AGENTS.md` and `README.md`
**What:** Update documentation to reflect all three changes.
**Why:** Keeps docs accurate for future contributors and users.
**Test first:** No tests required for documentation changes.
**Implementation:**
In `AGENTS.md` line 10, replace:
```
- **Output Paths:** Keep OpenCode output at `opencode.json` and `.opencode/{agents,skills,plugins}`.
```
with:
```
- **Output Paths:** Keep OpenCode output at `opencode.json` and `.opencode/{agents,skills,plugins}`. For OpenCode, commands go to `~/.config/opencode/commands/<name>.md`; `opencode.json` is deep-merged (never overwritten wholesale).
```
In `README.md` line 54, replace:
```
OpenCode output is written to `~/.config/opencode` by default, with `opencode.json` at the root and `agents/`, `skills/`, and `plugins/` alongside it.
```
with:
```
OpenCode output is written to `~/.config/opencode` by default. Commands are written as individual `.md` files to `~/.config/opencode/commands/<name>.md`. Agents, skills, and plugins are written to the corresponding subdirectories alongside. `opencode.json` (MCP servers) is deep-merged into any existing file -- user keys such as `model`, `theme`, and `provider` are preserved, and user values win on conflicts. Command files are backed up before being overwritten.
```
Also update `AGENTS.md` to add a Repository Docs Conventions section if not present:
```
## Repository Docs Conventions
- **ADRs** live in `docs/decisions/` and are numbered with 4-digit zero-padding: `0001-short-title.md`, `0002-short-title.md`, etc.
- **Orchestrator run reports** live in `docs/reports/`.
When recording a significant decision (new provider, output format change, merge strategy), create an ADR in `docs/decisions/` following the numbering sequence.
```
**Code comments required:** None.
**Verification:** Read the updated files and confirm accuracy. Run `bun test` to confirm no regressions.
---
## TDD Enforcement
The executing agent MUST follow this sequence for every phase that touches source code:
1. Write the test(s) first in the test file.
2. Run `bun test <test-file>` and confirm the new/modified tests FAIL (red).
3. Implement the code change.
4. Run `bun test <test-file>` and confirm the new/modified tests PASS (green).
5. Run `bun test` (all tests) and confirm no regressions.
**Exception:** Phase 6 is documentation only. Run `bun test` after to confirm no regressions but no red/green cycle needed.
**Note on Phase 1:** Type changes alone will cause test failures. Phase 1 and Phase 2 are tightly coupled — the tests updated in Phase 1 will not pass until Phase 2's implementation is complete. The executing agent should:
1. Update tests in Phase 1 (expect them to fail — both due to type errors and logic changes).
2. Implement type changes in Phase 1.
3. Implement converter changes in Phase 2.
4. Confirm all converter tests pass after Phase 2.
---
## Constraints
**Do not modify:**
- `src/converters/claude-to-opencode.ts` lines 294-417 (`applyPermissions()`, `normalizeTool()`, `parseToolSpec()`, `normalizePattern()`) — these functions are correct for `"broad"` and `"from-commands"` modes. Only the default that triggers them is changing.
- Any files under `tests/fixtures/` — these are data files, not test logic.
- `src/types/claude.ts` — no changes to source types.
- `src/parsers/claude.ts` — no changes to parser logic.
- `src/utils/files.ts` — all needed utilities already exist. Do not add new utility functions.
- `src/utils/frontmatter.ts` — already handles the needed formatting.
**Dependencies not to add:** None. No new npm/bun packages.
**Patterns to follow:**
- Existing writer tests in `tests/opencode-writer.test.ts` use `fs.mkdtemp()` for temp directories and the local `exists()` helper function.
- Existing CLI tests in `tests/cli.test.ts` use `Bun.spawn()` to invoke the CLI.
- Existing converter tests in `tests/converter.test.ts` use `loadClaudePlugin(fixtureRoot)` for real fixtures and inline `ClaudePlugin` objects for isolated tests.
- ADR format: Follow `AGENTS.md` numbering convention `0001-short-title.md` with sections: Status, Date, Context, Decision, Consequences, Plan Reference.
- Commits: Use conventional commit format. Reference ADRs in commit bodies.
- Branch: Create `feature/opencode-commands-md-merge-permissions` from `main`.
## Final Checklist
After all phases complete:
- [ ] `bun test` passes all tests (180 original + new ones, 0 fail)
- [ ] `docs/decisions/0001-opencode-command-output-format.md` exists
- [ ] `docs/decisions/0002-opencode-json-merge-strategy.md` exists
- [ ] `docs/decisions/0003-opencode-permissions-default-none.md` exists
- [ ] `opencode.json` is never fully overwritten — merge logic confirmed by test
- [ ] Commands are written as `.md` files — confirmed by test
- [ ] `--permissions` defaults to `"none"` — confirmed by CLI test
- [ ] `AGENTS.md` and `README.md` updated to reflect new behavior

45
docs/reports/2026-02-20-opencode-command-md-merge/2026-02-20-phase-04-merge-config.md Normal file
View File

@@ -0,0 +1,45 @@
# Phase 4 Handoff: Deep-Merge opencode.json
**Date:** 2026-02-20
**Status:** Complete
## Summary
Implemented `mergeOpenCodeConfig()` function that performs deep-merge of plugin config into existing opencode.json with user-wins-on-conflict strategy.
## Changes Made
### 1. Updated `src/targets/opencode.ts`
- Added imports for `pathExists`, `readJson`, and `OpenCodeConfig` type
- Added `mergeOpenCodeConfig()` function before `writeOpenCodeBundle()`
- Replaced direct `writeJson()` call with merge logic
### 2. Updated `tests/opencode-writer.test.ts`
- Renamed existing backup test to `"merges plugin config into existing opencode.json without destroying user keys"`
- Added two new tests:
- `"merges mcp servers without overwriting user entry"`
- `"preserves unrelated user keys when merging opencode.json"`
## Verification
All 8 tests pass:
```
bun test tests/opencode-writer.test.ts
8 pass, 0 fail
```
## Key Behaviors
1. **User keys preserved**: All existing config keys remain intact
2. **MCP merge**: Plugin MCP servers added, user servers kept on conflict
3. **Permission merge**: Plugin permissions added, user permissions kept on conflict
4. **Tools merge**: Plugin tools added, user tools kept on conflict
5. **Fallback**: If existing config is malformed JSON, writes plugin-only config (safety first)
6. **Backup**: Original config is still backed up before writing merged result
## Next Steps
- Proceed to next phase (if any)
- Consider adding decision log entry for ADR-002 (user-wins-on-conflict strategy)

58
docs/reports/2026-02-20-opencode-command-md-merge/decisions.md
View File

@@ -126,4 +126,60 @@ for (const commandFile of bundle.commandFiles) {
## Alternatives Considered
1. Use intermediate variable for commandDir - Rejected: caused intermittent undefined errors
2. Use direct property reference `openCodePaths.commandDir` - Chosen: more reliable
2. Use direct property reference `openCodePaths.commandDir` - Chosen: more reliable
---
## Decision: ADR-002 - User-Wins-On-Conflict for Config Merge
**Date:** 2026-02-20
**Status:** Adopted
## Context
When merging plugin config into existing opencode.json, conflicts may occur (e.g., same MCP server name with different configuration). The merge strategy must decide which value wins.
## Decision
**User config wins on conflict.** When plugin and user both define the same key (MCP server name, permission, tool), the user's value takes precedence.
### Rationale
- Safety first: Do not overwrite user data with plugin defaults
- Users have explicit intent in their local config
- Plugins should add new entries without modifying user's existing setup
- Aligns with AGENTS.md principle: "Do not delete or overwrite user data"
### Merge Algorithm
```typescript
const mergedMcp = {
...(incoming.mcp ?? {}),
...(existing.mcp ?? {}), // existing takes precedence
}
```
Same pattern applied to `permission` and `tools`.
### Fallback Behavior
If existing `opencode.json` is malformed JSON, warn and write plugin-only config rather than crashing:
```typescript
} catch {
console.warn(`Warning: existing ${configPath} is not valid JSON. Writing plugin config without merging.`)
return incoming
}
```
## Consequences
- Positive: User config never accidentally overwritten
- Positive: Plugin can add new entries without conflict
- Negative: Plugin cannot modify user's existing server configuration (must use unique names)
- Negative: Silent merge may mask configuration issues if user expects plugin override
## Alternatives Considered
1. Plugin wins on conflict - Rejected: would overwrite user data
2. Merge and combine arrays - Rejected: MCP servers are keyed objects, not array
3. Fail on conflict - Rejected: breaks installation workflow

59
src/targets/opencode.ts
View File

@@ -1,6 +1,58 @@
import path from "path"
import { backupFile, copyDir, ensureDir, writeJson, writeText } from "../utils/files"
import type { OpenCodeBundle } from "../types/opencode"
import { backupFile, copyDir, ensureDir, pathExists, readJson, writeJson, writeText } from "../utils/files"
import type { OpenCodeBundle, OpenCodeConfig } from "../types/opencode"
// Merges plugin config into existing opencode.json. User keys win on conflict. See ADR-002.
async function mergeOpenCodeConfig(
configPath: string,
incoming: OpenCodeConfig,
): Promise<OpenCodeConfig> {
// If no existing config, write plugin config as-is
if (!(await pathExists(configPath))) return incoming
let existing: OpenCodeConfig
try {
existing = await readJson<OpenCodeConfig>(configPath)
} catch {
// Safety first per AGENTS.md -- do not destroy user data even if their config is malformed.
// Warn and fall back to plugin-only config rather than crashing.
console.warn(
`Warning: existing ${configPath} is not valid JSON. Writing plugin config without merging.`
)
return incoming
}
// User config wins on conflict -- see ADR-002
// MCP servers: add plugin entry, skip keys already in user config.
const mergedMcp = {
...(incoming.mcp ?? {}),
...(existing.mcp ?? {}), // existing takes precedence (overwrites same-named plugin entry)
}
// Permission: add plugin entry, skip keys already in user config.
const mergedPermission = incoming.permission
? {
...(incoming.permission),
...(existing.permission ?? {}), // existing takes precedence
}
: existing.permission
// Tools: same pattern
const mergedTools = incoming.tools
? {
...(incoming.tools),
...(existing.tools ?? {}),
}
: existing.tools
return {
...existing, // all user keys preserved
$schema: incoming.$schema ?? existing.$schema,
mcp: Object.keys(mergedMcp).length > 0 ? mergedMcp : undefined,
permission: mergedPermission,
tools: mergedTools,
}
}
export async function writeOpenCodeBundle(outputRoot: string, bundle: OpenCodeBundle): Promise<void> {
const openCodePaths = resolveOpenCodePaths(outputRoot)
@@ -10,7 +62,8 @@ export async function writeOpenCodeBundle(outputRoot: string, bundle: OpenCodeBu
if (backupPath) {
console.log(`Backed up existing config to ${backupPath}`)
}
await writeJson(openCodePaths.configPath, bundle.config)
const merged = await mergeOpenCodeConfig(openCodePaths.configPath, bundle.config)
await writeJson(openCodePaths.configPath, merged)
const agentsDir = openCodePaths.agentsDir
for (const agent of bundle.agents) {

91
tests/opencode-writer.test.ts
View File

@@ -88,18 +88,22 @@ describe("writeOpenCodeBundle", () => {
expect(await exists(path.join(outputRoot, ".opencode"))).toBe(false)
})
test("backs up existing opencode.json before overwriting", async () => {
test("merges plugin config into existing opencode.json without destroying user keys", async () => {
const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "opencode-backup-"))
const outputRoot = path.join(tempRoot, ".opencode")
const configPath = path.join(outputRoot, "opencode.json")
// Create existing config
// Create existing config with user keys
await fs.mkdir(outputRoot, { recursive: true })
const originalConfig = { $schema: "https://opencode.ai/config.json", custom: "value" }
await fs.writeFile(configPath, JSON.stringify(originalConfig, null, 2))
// Bundle adds mcp server but keeps user's custom key
const bundle: OpenCodeBundle = {
config: { $schema: "https://opencode.ai/config.json", new: "config" },
config: {
$schema: "https://opencode.ai/config.json",
mcp: { "plugin-server": { type: "local", command: "uvx", args: ["plugin-srv"] } }
},
agents: [],
plugins: [],
commandFiles: [],
@@ -108,9 +112,11 @@ describe("writeOpenCodeBundle", () => {
await writeOpenCodeBundle(outputRoot, bundle)
// New config should be written
// Merged config should have both user key and plugin key
const newConfig = JSON.parse(await fs.readFile(configPath, "utf8"))
expect(newConfig.new).toBe("config")
expect(newConfig.custom).toBe("value") // user key preserved
expect(newConfig.mcp).toBeDefined()
expect(newConfig.mcp["plugin-server"]).toBeDefined()
// Backup should exist with original content
const files = await fs.readdir(outputRoot)
@@ -121,6 +127,81 @@ describe("writeOpenCodeBundle", () => {
expect(backupContent.custom).toBe("value")
})
test("merges mcp servers without overwriting user entry", async () => {
const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "opencode-merge-mcp-"))
const outputRoot = path.join(tempRoot, ".opencode")
const configPath = path.join(outputRoot, "opencode.json")
// Create existing config with user's mcp server
await fs.mkdir(outputRoot, { recursive: true })
const existingConfig = {
mcp: { "user-server": { type: "local", command: "uvx", args: ["user-srv"] } }
}
await fs.writeFile(configPath, JSON.stringify(existingConfig, null, 2))
// Bundle adds plugin server AND has conflicting user-server with different args
const bundle: OpenCodeBundle = {
config: {
$schema: "https://opencode.ai/config.json",
mcp: {
"plugin-server": { type: "local", command: "uvx", args: ["plugin-srv"] },
"user-server": { type: "local", command: "uvx", args: ["plugin-override"] } // conflict
}
},
agents: [],
plugins: [],
commandFiles: [],
skillDirs: [],
}
await writeOpenCodeBundle(outputRoot, bundle)
// Merged config should have both servers, with user-server keeping user's original args
const mergedConfig = JSON.parse(await fs.readFile(configPath, "utf8"))
expect(mergedConfig.mcp).toBeDefined()
expect(mergedConfig.mcp["plugin-server"]).toBeDefined()
expect(mergedConfig.mcp["user-server"]).toBeDefined()
expect(mergedConfig.mcp["user-server"].args[0]).toBe("user-srv") // user wins on conflict
expect(mergedConfig.mcp["plugin-server"].args[0]).toBe("plugin-srv") // plugin entry present
})
test("preserves unrelated user keys when merging opencode.json", async () => {
const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "opencode-preserve-"))
const outputRoot = path.join(tempRoot, ".opencode")
const configPath = path.join(outputRoot, "opencode.json")
// Create existing config with multiple user keys
await fs.mkdir(outputRoot, { recursive: true })
const existingConfig = {
model: "my-model",
theme: "dark",
mcp: {}
}
await fs.writeFile(configPath, JSON.stringify(existingConfig, null, 2))
// Bundle adds plugin-specific keys
const bundle: OpenCodeBundle = {
config: {
$schema: "https://opencode.ai/config.json",
mcp: { "plugin-server": { type: "local", command: "uvx", args: ["plugin-srv"] } },
permission: { "bash": "allow" }
},
agents: [],
plugins: [],
commandFiles: [],
skillDirs: [],
}
await writeOpenCodeBundle(outputRoot, bundle)
// All user keys preserved
const mergedConfig = JSON.parse(await fs.readFile(configPath, "utf8"))
expect(mergedConfig.model).toBe("my-model")
expect(mergedConfig.theme).toBe("dark")
expect(mergedConfig.mcp["plugin-server"]).toBeDefined()
expect(mergedConfig.permission["bash"]).toBe("allow")
})
test("writes command files as .md in commands/ directory", async () => {
const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "opencode-cmd-"))
const outputRoot = path.join(tempRoot, ".config", "opencode")