clikit-plugin 0.2.20 → 0.2.22

package/dist/cli.d.ts

@@ -1,3 +1,11 @@
 #!/usr/bin/env bun
+interface ScaffoldStats {
+    copied: number;
+    skipped: number;
+    missingSources: string[];
+}
+export declare function resolveProjectDir(env?: NodeJS.ProcessEnv, cwd?: string): string;
+export declare function upsertPluginEntry(existingPlugins: string[], pluginName: string, version: string): string[];
+export declare function scaffoldProjectOpencode(projectDir: string, packageRoot?: string): ScaffoldStats;
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AASA,UAAU,aAAa;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AA4BD,wBAAgB,iBAAiB,CAC/B,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,GAAG,GAAE,MAAsB,GAC1B,MAAM,CAiBR;AAED,wBAAgB,iBAAiB,CAAC,eAAe,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAM1G;AA0CD,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,SAAmB,GAAG,aAAa,CAoDzG"}

package/dist/cli.js

@@ -1,12 +1,126 @@
 #!/usr/bin/env bun
 // @bun
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __require = import.meta.require;
 
 // src/cli.ts
 import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
+import { fileURLToPath } from "url";
 var PLUGIN_NAME = "clikit-plugin";
-var VERSION = "0.2.12";
+var VERSION = "0.2.20";
+function getPackageRoot() {
+  const currentFile = fileURLToPath(import.meta.url);
+  const currentDir = path.dirname(currentFile);
+  if (path.basename(currentDir) === "dist") {
+    return path.dirname(currentDir);
+  }
+  return path.dirname(currentDir);
+}
+function getPackageVersion() {
+  const packageJsonPath = path.join(getPackageRoot(), "package.json");
+  try {
+    const raw = fs.readFileSync(packageJsonPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    return parsed.version || VERSION;
+  } catch {
+    return VERSION;
+  }
+}
+function getPluginEntry() {
+  return `${PLUGIN_NAME}@${getPackageVersion()}`;
+}
+function resolveProjectDir(env = process.env, cwd = process.cwd()) {
+  const candidates = [env.INIT_CWD, env.PWD, cwd].filter((value) => typeof value === "string" && value.trim().length > 0);
+  for (const candidate of candidates) {
+    const resolved = path.resolve(candidate);
+    try {
+      if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
+        return resolved;
+      }
+    } catch {}
+  }
+  return cwd;
+}
+function upsertPluginEntry(existingPlugins, pluginName, version) {
+  const filteredPlugins = existingPlugins.filter((p) => p !== pluginName && !p.startsWith(`${pluginName}@`));
+  filteredPlugins.push(`${pluginName}@${version}`);
+  return filteredPlugins;
+}
+function copyFileIfMissing(sourcePath, targetPath, stats) {
+  if (!fs.existsSync(sourcePath)) {
+    stats.missingSources.push(sourcePath);
+    return;
+  }
+  if (fs.existsSync(targetPath)) {
+    stats.skipped += 1;
+    return;
+  }
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.copyFileSync(sourcePath, targetPath);
+  stats.copied += 1;
+}
+function copyDirectoryFilesIfMissing(sourceDir, targetDir, stats) {
+  if (!fs.existsSync(sourceDir)) {
+    stats.missingSources.push(sourceDir);
+    return;
+  }
+  fs.mkdirSync(targetDir, { recursive: true });
+  const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const targetPath = path.join(targetDir, entry.name);
+    if (entry.isDirectory()) {
+      copyDirectoryFilesIfMissing(sourcePath, targetPath, stats);
+      continue;
+    }
+    if (entry.isFile()) {
+      copyFileIfMissing(sourcePath, targetPath, stats);
+    }
+  }
+}
+function scaffoldProjectOpencode(projectDir, packageRoot = getPackageRoot()) {
+  const projectOpencodeDir = path.join(projectDir, ".opencode");
+  const stats = {
+    copied: 0,
+    skipped: 0,
+    missingSources: []
+  };
+  fs.mkdirSync(projectOpencodeDir, { recursive: true });
+  copyFileIfMissing(path.join(packageRoot, "AGENTS.md"), path.join(projectOpencodeDir, "AGENTS.md"), stats);
+  copyDirectoryFilesIfMissing(path.join(packageRoot, "command"), path.join(projectOpencodeDir, "command"), stats);
+  copyDirectoryFilesIfMissing(path.join(packageRoot, "skill"), path.join(projectOpencodeDir, "skill"), stats);
+  copyDirectoryFilesIfMissing(path.join(packageRoot, "memory", "_templates"), path.join(projectOpencodeDir, "memory", "_templates"), stats);
+  copyFileIfMissing(path.join(packageRoot, "README.md"), path.join(projectOpencodeDir, "README-clikit.md"), stats);
+  const indexPath = path.join(projectOpencodeDir, "index.ts");
+  if (!fs.existsSync(indexPath)) {
+    fs.writeFileSync(indexPath, `import CliKitPlugin from "${PLUGIN_NAME}";
+
+export default CliKitPlugin;
+`);
+    stats.copied += 1;
+  } else {
+    stats.skipped += 1;
+  }
+  return stats;
+}
 function getRealHome() {
   if (process.env.SNAP_REAL_HOME) {
     return process.env.SNAP_REAL_HOME;
@@ -74,7 +188,8 @@ async function install() {
   CliKit Installer
   ================
 `);
-  console.log("[1/3] Adding CliKit plugin to OpenCode config...");
+  const pluginVersion = getPackageVersion();
+  console.log("[1/4] Adding CliKit plugin to OpenCode config...");
   try {
     ensureConfigDir();
   } catch (err) {
@@ -91,22 +206,38 @@ async function install() {
       return 1;
     }
     const config = result.config;
-    const existingPlugins = Array.isArray(config.plugin) ? config.plugin : [];
+    const existingPlugins = Array.isArray(config.plugin) ? config.plugin.filter((p) => typeof p === "string") : [];
     const preservedKeys = Object.keys(config).filter((k) => k !== "plugin");
     if (preservedKeys.length > 0) {
       console.log(`  Preserving existing config: ${preservedKeys.join(", ")}`);
     }
-    const filteredPlugins = existingPlugins.filter((p) => p !== PLUGIN_NAME && !p.startsWith(`${PLUGIN_NAME}@`));
-    filteredPlugins.push(PLUGIN_NAME);
+    const filteredPlugins = upsertPluginEntry(existingPlugins, PLUGIN_NAME, pluginVersion);
     const newConfig = { ...config, plugin: filteredPlugins };
     writeConfig(configPath, newConfig);
-    console.log(`\u2713 Plugin added to ${configPath}`);
+    console.log(`\u2713 Plugin added to ${configPath} as ${getPluginEntry()}`);
   } catch (err) {
     console.error(`\u2717 Failed to update OpenCode config: ${err}`);
     return 1;
   }
   console.log(`
-[2/3] Creating memory directories...`);
+[2/4] Scaffolding project .opencode assets...`);
+  try {
+    const projectDir = resolveProjectDir();
+    const stats = scaffoldProjectOpencode(projectDir);
+    console.log(`\u2713 Project assets ready in ${path.join(projectDir, ".opencode")}`);
+    console.log(`  Copied: ${stats.copied}, Skipped existing: ${stats.skipped}`);
+    if (stats.missingSources.length > 0) {
+      console.log("  Missing bundled sources (skipped):");
+      for (const missing of stats.missingSources) {
+        console.log(`    - ${missing}`);
+      }
+    }
+  } catch (err) {
+    console.error(`\u2717 Failed to scaffold project assets: ${err}`);
+    return 1;
+  }
+  console.log(`
+[3/4] Creating memory directories...`);
   const memoryDir = path.join(getConfigDir(), "memory");
   const memorySubdirs = ["specs", "plans", "research", "reviews", "handoffs", "beads", "prds"];
   for (const subdir of memorySubdirs) {
@@ -117,7 +248,7 @@ async function install() {
   }
   console.log(`\u2713 Memory directories created in ${memoryDir}`);
   console.log(`
-[3/3] Creating CliKit config...`);
+[4/4] Creating CliKit config...`);
   const clikitConfigPath = path.join(getConfigDir(), "clikit.config.json");
   if (!fs.existsSync(clikitConfigPath)) {
     const defaultConfig = {
@@ -165,7 +296,7 @@ Examples:
 `);
 }
 function version() {
-  console.log(`clikit-plugin v${VERSION}`);
+  console.log(`clikit-plugin v${getPackageVersion()}`);
 }
 async function main() {
   const args = process.argv.slice(2);
@@ -193,7 +324,14 @@ async function main() {
   }
   process.exit(exitCode);
 }
-main().catch((err) => {
-  console.error(err);
-  process.exit(1);
-});
+if (import.meta.main) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}
+export {
+  upsertPluginEntry,
+  scaffoldProjectOpencode,
+  resolveProjectDir
+};

package/dist/cli.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli.test.d.ts.map

package/dist/cli.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.test.d.ts","sourceRoot":"","sources":["../src/cli.test.ts"],"names":[],"mappings":""}

package/dist/hooks/session-notification.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-notification.d.ts","sourceRoot":"","sources":["../../src/hooks/session-notification.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,WAAW,yBAAyB;IACxC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,UAAU,CAAC;CACzC;AA0BD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAsBtE;AAED,wBAAgB,qBAAqB,CACnC,SAAS,CAAC,EAAE,OAAO,EACnB,MAAM,CAAC,EAAE,MAAM,GACd,mBAAmB,CAUrB;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,SAAS,CAAC,EAAE,OAAO,EACnB,MAAM,CAAC,EAAE,MAAM,GACd,mBAAmB,CAerB;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,mBAAmB,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CAIzF"}
+{"version":3,"file":"session-notification.d.ts","sourceRoot":"","sources":["../../src/hooks/session-notification.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,WAAW,yBAAyB;IACxC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,UAAU,CAAC;CACzC;AA4BD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAsBtE;AAED,wBAAgB,qBAAqB,CACnC,SAAS,CAAC,EAAE,OAAO,EACnB,MAAM,CAAC,EAAE,MAAM,GACd,mBAAmB,CAUrB;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,SAAS,CAAC,EAAE,OAAO,EACnB,MAAM,CAAC,EAAE,MAAM,GACd,mBAAmB,CAerB;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,mBAAmB,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CAIzF"}

package/dist/hooks/session-notification.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=session-notification.test.d.ts.map

package/dist/hooks/session-notification.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-notification.test.d.ts","sourceRoot":"","sources":["../../src/hooks/session-notification.test.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -4499,15 +4499,17 @@ function escapeSingleQuotes(str2) {
 }
 function getNotifyCommand(payload) {
   const { title, body, urgency } = payload;
-  const escapedTitle = title.replace(/"/g, "\\\"");
-  const escapedBody = body.replace(/"/g, "\\\"");
+  const safeTitle = typeof title === "string" ? title : "Notification";
+  const safeBody = typeof body === "string" ? body : "";
+  const escapedTitle = safeTitle.replace(/"/g, "\\\"");
+  const escapedBody = safeBody.replace(/"/g, "\\\"");
   switch (process.platform) {
     case "linux":
       return `notify-send "${escapedTitle}" "${escapedBody}" --urgency=${urgency || "normal"}`;
     case "darwin":
       return `osascript -e 'display notification "${escapedBody}" with title "${escapedTitle}"'`;
     case "win32":
-      return `powershell -command "[void] [System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); $n = New-Object System.Windows.Forms.NotifyIcon; $n.Icon = [System.Drawing.SystemIcons]::Information; $n.Visible = $true; $n.ShowBalloonTip(5000, '${escapeSingleQuotes(title)}', '${escapeSingleQuotes(body)}', [System.Windows.Forms.ToolTipIcon]::Info)"`;
+      return `powershell -command "[void] [System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); $n = New-Object System.Windows.Forms.NotifyIcon; $n.Icon = [System.Drawing.SystemIcons]::Information; $n.Visible = $true; $n.ShowBalloonTip(5000, '${escapeSingleQuotes(safeTitle)}', '${escapeSingleQuotes(safeBody)}', [System.Windows.Forms.ToolTipIcon]::Info)"`;
     default:
       return null;
   }
@@ -4522,8 +4524,8 @@ function sendNotification(payload) {
   } catch {
     if (process.platform === "linux") {
       try {
-        const wslTitle = escapeSingleQuotes(payload.title);
-        const wslBody = escapeSingleQuotes(payload.body);
+        const wslTitle = escapeSingleQuotes(typeof payload.title === "string" ? payload.title : "Notification");
+        const wslBody = escapeSingleQuotes(typeof payload.body === "string" ? payload.body : "");
         const wslCmd = `powershell.exe -command "[void] [System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); $n = New-Object System.Windows.Forms.NotifyIcon; $n.Icon = [System.Drawing.SystemIcons]::Information; $n.Visible = $true; $n.ShowBalloonTip(5000, '${wslTitle}', '${wslBody}', [System.Windows.Forms.ToolTipIcon]::Info)"`;
         execSync4(wslCmd, { timeout: 5000, stdio: ["pipe", "pipe", "pipe"] });
         return true;

package/memory/handoffs/2026-02-15-importmeta-fix.md

@@ -62,6 +62,7 @@ dist/index.js                    ← import.meta.dir points here
 | 0.2.10 | `__dirname` → `import.meta.dir` (paths still wrong) |
 | 0.2.11 | Correct relative paths from `dist/` directory |
 | 0.2.19 | Retry `getObservationsByType` when SQLite reports datatype mismatch |
+| 0.2.20 | Guard `memoryRead` against non-string paths |
 
 ---
 

package/memory/plans/2026-02-16-plugin-install.md

@@ -0,0 +1,195 @@
+# Implementation Plan: Align CliKit Plugin Installation with OpenCode
+
+**Date:** 2026-02-16
+**Author:** Plan Agent
+**Status:** Draft
+**bead_id:** clikit-plugin
+
+---
+
+## Overview
+
+Define and implement an installation and configuration workflow for CliKit that mirrors Oh My OpenCode’s opinionated setup. This includes documenting the desired behavior, creating a CLI installer that automates plugin registration and config scaffolding, and updating guidance so users can reliably install via npm/local files following OpenCode’s documented plugin system.
+
+## References
+
+- **Spec:** *(not provided)*
+- **PRD:** *(not provided)*
+- **Research:** `.opencode/memory/research/2026-02-16-opencode-plugin-alignment.md` *(planned; current knowledge from repo/docs review)*
+
+---
+
+## Tasks
+
+### Task 1: Capture Target Installation Workflow
+
+| Field | Value |
+|-------|-------|
+| **task_id** | T-001 |
+| **type** | task |
+| **assignee** | build |
+| **effort** | S |
+| **priority** | P1 |
+| **status** | not_started |
+| **dependencies** | none |
+
+**Description:**
+Summarize Oh My OpenCode’s installation behavior (CLI prompts, subscription flags, config injection) and map each requirement to CliKit. Produce a short design note describing which steps we will replicate and which remain optional.
+
+**Input:**
+- README + docs from `code-yeongyu/oh-my-opencode`
+- OpenCode plugin docs (`opencode.ai/docs/plugins`)
+
+**Output:**
+- Design note (e.g., `.opencode/memory/research/2026-02-16-opencode-plugin-alignment.md`)
+- Checklist of actions installer must perform
+
+**Acceptance Criteria:**
+- [ ] AC-01: Clearly list each step Oh My OpenCode installer performs.
+- [ ] AC-02: Define corresponding CliKit behavior (adopt/skip) with rationale.
+
+**Boundaries:**
+- Do not implement code changes here—documentation/research only.
+
+---
+
+### Task 2: Implement CliKit Installer CLI
+
+| Field | Value |
+|-------|-------|
+| **task_id** | T-002 |
+| **type** | feature |
+| **assignee** | build |
+| **effort** | M |
+| **priority** | P0 |
+| **status** | not_started |
+| **dependencies** | [T-001] |
+
+**Description:**
+Create a `bunx clikit-plugin install` command paralleling Oh My OpenCode: accept provider flags, update `opencode.json` plugin array, scaffold `.opencode/clikit.config.json`, and emit post-install instructions. Include validation (prevent duplicates) and support non-interactive defaults.
+
+**Input:**
+- Output of Task 1 design note
+- Existing `.opencode/plugin.ts`, `.opencode/src/config.ts`
+
+**Output:**
+- CLI script (likely under `.opencode/script/install.ts` or package bin entry)
+- Updated package metadata so command is published
+- Tests or manual verification steps documenting expected behavior
+
+**Acceptance Criteria:**
+- [ ] AC-01: Running installer registers CliKit in `plugin` array when absent and is idempotent.
+- [ ] AC-02: Installer writes/merges config template without overwriting user overrides.
+- [ ] AC-03: Help text documents supported flags modeled after Oh My OpenCode.
+
+**Boundaries:**
+- Do not modify runtime hook logic; focus on installer.
+
+---
+
+### Task 3: Update Documentation and Verification Guide
+
+| Field | Value |
+|-------|-------|
+| **task_id** | T-003 |
+| **type** | chore |
+| **assignee** | build |
+| **effort** | S |
+| **priority** | P1 |
+| **status** | not_started |
+| **dependencies** | [T-002] |
+
+**Description:**
+Revise `.opencode/README.md` and root `README.md` to outline installation paths (npm + installer, manual config). Include verification steps (opencode version check, config inspection) and troubleshooting tips inspired by Oh My OpenCode docs.
+
+**Input:**
+- Completed installer features
+- Task 1 research checklist
+
+**Output:**
+- Updated documentation referencing new CLI command, load order, and auth reminders
+
+**Acceptance Criteria:**
+- [ ] AC-01: README contains explicit step-by-step instructions mirroring OpenCode plugin docs.
+- [ ] AC-02: Adds warning about not disabling core features unless required.
+- [ ] AC-03: Describes verification commands post-install.
+
+**Boundaries:**
+- Do not duplicate entire Oh My OpenCode README—only relevant sections.
+
+---
+
+## File Impact
+
+**Files to CREATE:**
+- `.opencode/memory/research/2026-02-16-opencode-plugin-alignment.md` — research note from Task 1
+- `script/install.ts` (or equivalent CLI entry) — new installer command logic
+
+**Files to MODIFY:**
+- `package.json` — add bin entry & dependencies for installer
+- `.opencode/README.md` — refreshed installation instructions
+- `README.md` — high-level install overview referencing CLI
+- `.opencode/src/config.ts` — ensure config loader supports templates/merging if needed by installer
+- `.opencode/script/` helpers (if reused) — support CLI utilities
+
+**Files to DELETE:**
+- (none)
+
+---
+
+## Dependencies
+
+```mermaid
+graph TD
+    T001[T-001: Capture Target Installation Workflow] --> T002[T-002: Implement CliKit Installer CLI]
+    T002 --> T003[T-003: Update Documentation and Verification Guide]
+```
+
+---
+
+## Effort Summary
+
+| Task | Effort | Priority |
+|------|--------|----------|
+| T-001 | S | P1 |
+| T-002 | M | P0 |
+| T-003 | S | P1 |
+
+**Total Estimated Effort:** ~3-4 days (including testing & docs)
+
+---
+
+## Risk Assessment
+
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| Installer overwrites user config | M | M | Implement merge logic with backups + prompts |
+| CLI divergence from OpenCode expectations | M | H | Validate against official plugin docs; add tests for load order |
+| Users skip auth steps leading to failures | H | M | Add prominent warnings & post-install checklist |
+
+---
+
+## Quick Mode Eligibility
+
+Tasks eligible for Quick Mode (no full plan needed):
+- [ ] T-001 (requires research + documentation > 3 files)
+- [ ] T-002 (installer touches multiple files, so not eligible)
+- [ ] T-003 (docs updates only but depends on T-002 completion)
+
+---
+
+## Rollout Plan
+
+| Phase | Tasks | Milestone |
+|-------|-------|-----------|
+| Phase 1 | T-001 | Approved installation blueprint |
+| Phase 2 | T-002 | Installer CLI ready & manually verified |
+| Phase 3 | T-003 | Documentation updated & user walkthrough published |
+
+---
+
+## Approval
+
+- [ ] Plan reviewed
+- [ ] User approved
+- [ ] Ready for implementation

package/memory/research/2026-02-16-opencode-plugin-alignment.md

@@ -0,0 +1,128 @@
+---
+topic: "Oh My OpenCode Installer Behavior"
+date: 2026-02-16
+confidence: high
+depth: deep
+versions:
+  - library: "oh-my-opencode"
+    version: "3.5.5"
+bead_id: clikit-plugin
+---
+
+# Research: Oh My OpenCode Installer
+
+**Question:** How does oh-my-opencode's installer configure OpenCode and what pieces should CliKit replicate?
+
+---
+
+## Summary
+
+Oh My OpenCode's CLI installer (`bunx oh-my-opencode install`) performs a six-step workflow: it validates CLI args, checks for the OpenCode binary/version, ensures the plugin entry exists in `opencode.json`, optionally installs auth/provider configs (Gemini et al.), writes/merges a dedicated `oh-my-opencode` config file, and prints guidance/warnings. Config files live under both the global config dir (`~/.config/opencode`) and per-project `.opencode`. CliKit's installer should mirror the config detection/merge logic and idempotent plugin registration.
+
+---
+
+## Key Findings
+
+### Finding 1: Installer Flow Mirrors Documented Steps
+- `runCliInstaller` (dist/cli/index.js) orchestrates 6 numbered steps: detect OpenCode binary/version, add plugin entry, add auth plugins (conditional), add provider config (conditional), and write final `oh-my-opencode` config before printing summary boxes.
+- Non-interactive mode requires explicit provider flags (`--claude`, `--gemini`, `--copilot`, etc.); otherwise TUI handles prompts.
+- Failure at any sub-step aborts with contextual error text (`formatErrorWithSuggestion`).
+
+### Finding 2: Plugin Registration Logic is Idempotent
+- `addPluginToOpenCodeConfig(version)` ensures `~/.config/opencode/opencode.json[c]` exists, parses JSON/JSONC, removes prior `oh-my-opencode` entries, and writes the latest pinned version string (e.g., `oh-my-opencode@3.5.5`).
+- JSONC files are updated by regex replacement to preserve comments/formatting; JSON files are re-serialized.
+- This mirrors what CliKit's installer must do for `clikit-plugin`, including detection of config dir via `getOpenCodeConfigDir` semantics.
+
+### Finding 3: Config Merge Targets Global + Project Paths
+- `writeOmoConfig` writes `oh-my-opencode.json` (or `.jsonc`) inside `~/.config/opencode/oh-my-opencode.*`, using `deepMergeRecord` against existing JSONC.
+- Loader functions (e.g., `loadPluginConfig`) look at both global config dir and per-project `.opencode/oh-my-opencode.*`, merging project overrides atop global defaults.
+- Ensuring CliKit's installer writes `~/.config/opencode/clikit.config.json` (global) while respecting `.opencode/clikit.config.json` matches OpenCode expectations.
+
+### Finding 4: Ancillary Setup (Auth, Providers, bun install)
+- When Gemini support is requested, installer calls `addAuthPlugins` and `addProviderConfig` to inject additional packages/config references.
+- After plugin or binary updates, oh-my-opencode optionally runs `bun install` inside the config dir to ensure dependencies exist (`runBunInstall`).
+- CliKit may not need auth/provider hooks yet but should adopt the same structure for future flags, and consider invoking `bun install` when copying template files that introduce dependencies.
+
+---
+
+## Comparison
+
+| Aspect | Oh My OpenCode | Current CliKit | Gap |
+|--------|----------------|----------------|-----|
+| Plugin registration | Adds/updates versioned entry in `plugin` array with JSONC-safe merge | Adds bare `clikit-plugin` without version, no JSONC handling | Need versioned entry + JSONC-safe edits |
+| Config scaffolding | Writes `oh-my-opencode.json` w/ deep merge fallback | Writes `clikit.config.json` only if missing, no merge | Implement deep merge + JSONC parse guard |
+| Provider/auth flags | Supports `--claude`, `--gemini`, `--copilot`, `--opencode-zen`, etc. | No flags | Evaluate minimal flag set / defaults |
+| Dependency setup | Runs `bun install` when necessary | None | Optional follow-up |
+| Project overrides | Loader merges global + `.opencode/oh-my-opencode.*` | Loader already merges `~/.config` + project `.opencode` | Already aligned |
+
+---
+
+## Code Examples
+
+### Example 1: Adding Plugin Entry (pseudo-extracted)
+```ts
+const pluginEntry = await getPluginNameWithVersion(currentVersion);
+const parseResult = parseOpenCodeConfigFileWithError(path);
+const plugins = (parseResult.config.plugin ?? []).filter(
+  (p) => !p.startsWith("oh-my-opencode")
+);
+plugins.push(pluginEntry);
+writeConfigPreservingFormat(path, plugins);
+```
+
+### Example 2: Writing Config with Deep Merge
+```ts
+const omoConfigPath = getOmoConfigPath();
+const newConfig = generateOmoConfig(installConfig);
+if (existsSync(omoConfigPath)) {
+  const existing = parseJsonc(readFileSync(omoConfigPath, "utf8"));
+  const merged = deepMergeRecord(existing, newConfig);
+  writeFileSync(omoConfigPath, JSON.stringify(merged, null, 2));
+} else {
+  writeFileSync(omoConfigPath, JSON.stringify(newConfig, null, 2));
+}
+```
+
+---
+
+## Recommendation
+
+**Recommended approach:** Reimplement CliKit's installer to follow Oh My OpenCode's structure.
+
+**Rationale:**
+1. Users already expect the oh-my-opencode workflow; mirroring it reduces friction.
+2. JSONC-safe merging and versioned plugin entries prevent config corruption and enable updates.
+3. Aligning directories and merge logic ensures compatibility with OpenCode's plugin loader (global + project overrides).
+
+---
+
+## Verification Steps
+
+- [ ] Validate installer on machines with `opencode.json` and `opencode.jsonc` variants.
+- [ ] Confirm repeated `bun x clikit-plugin install` leaves config unchanged and updates version.
+- [ ] Ensure `.opencode/clikit.config.json` overrides global values after install.
+
+---
+
+## Open Questions
+
+- [ ] Which provider flags should CliKit expose initially (Claude-only vs. multi-provider)?
+- [ ] Do we need to run `bun install` inside `~/.config/opencode` after copying CliKit assets?
+
+---
+
+## Sources
+
+| Source | Type | Reliability |
+|--------|------|-------------|
+| `oh-my-opencode@3.5.5` package (`dist/cli/index.js`, `postinstall.mjs`) | Source | High |
+| OpenCode config conventions from oh-my-opencode loader | Source | High |
+
+---
+
+## Version Notes
+
+| Library/Tool | Version Researched | Current Latest | Notes |
+|--------------|-------------------|----------------|-------|
+| oh-my-opencode | 3.5.5 | 3.5.5 | Latest on npm during research |
+| clikit-plugin | 0.2.20 | 0.2.20 | Installer work in progress |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clikit-plugin",
-  "version": "0.2.20",
+  "version": "0.2.22",
   "description": "OpenCode plugin with 10 agents, 19 commands, 48 skills, 14 hooks",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,7 +25,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "bun build src/index.ts src/cli.ts --outdir dist --target bun --format esm && tsc --emitDeclarationOnly && cp src/clikit.schema.json dist/",
+    "build": "bun build src/index.ts src/cli.ts --outdir dist --target bun --format esm && tsc --emitDeclarationOnly && cp src/clikit.schema.json dist/ 2>/dev/null || true",
     "clean": "rm -rf dist",
     "prepublishOnly": "bun run clean && bun run build",
     "typecheck": "tsc --noEmit",

package/dist/clikit.schema.json

@@ -1,423 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "CliKit Plugin Configuration",
-  "description": "Configuration for CliKit OpenCode plugin",
-  "type": "object",
-  "properties": {
-    "disabled_agents": {
-      "type": "array",
-      "items": { "type": "string" },
-      "description": "List of agent names to disable",
-      "examples": [["scout"]]
-    },
-    "disabled_commands": {
-      "type": "array",
-      "items": { "type": "string" },
-      "description": "List of command names to disable",
-      "examples": [["debug", "import-plan"]]
-    },
-    "agents": {
-      "type": "object",
-      "description": "Override settings for specific agents",
-      "additionalProperties": {
-        "type": "object",
-        "properties": {
-          "model": { "type": "string", "description": "Override model for this agent" },
-          "temperature": { "type": "number", "minimum": 0, "maximum": 2 },
-          "top_p": { "type": "number", "minimum": 0, "maximum": 1 },
-          "mode": { "enum": ["subagent", "primary", "all"] },
-          "disabled": { "type": "boolean", "description": "Disable this agent" },
-          "color": { "type": "string", "description": "Agent color in UI" },
-          "maxSteps": { "type": "integer", "minimum": 1, "description": "Maximum steps for agent" },
-          "tools": {
-            "type": "object",
-            "additionalProperties": { "type": "boolean" }
-          },
-          "permission": {
-            "type": "object",
-            "description": "Permission overrides for this agent",
-            "properties": {
-              "edit": { "enum": ["ask", "allow", "deny"] },
-              "bash": {
-                "oneOf": [
-                  { "enum": ["ask", "allow", "deny"] },
-                  { "type": "object", "additionalProperties": { "enum": ["ask", "allow", "deny"] } }
-                ]
-              },
-              "webfetch": { "enum": ["ask", "allow", "deny"] },
-              "doom_loop": { "enum": ["ask", "allow", "deny"] },
-              "external_directory": { "enum": ["ask", "allow", "deny"] }
-            }
-          }
-        }
-      }
-    },
-    "commands": {
-      "type": "object",
-      "description": "Override settings for specific commands",
-      "additionalProperties": {
-        "type": "object",
-        "properties": {
-          "agent": { "type": "string", "description": "Agent to use for this command" },
-          "model": { "type": "string", "description": "Model to use for this command" },
-          "subtask": { "type": "boolean", "description": "Run as subtask" },
-          "description": { "type": "string", "description": "Command description" },
-          "template": { "type": "string", "description": "Command template/prompt" }
-        }
-      }
-    },
-    "lsp": {
-      "type": "object",
-      "description": "LSP server configurations to inject into OpenCode",
-      "additionalProperties": {
-        "type": "object",
-        "required": ["command"],
-        "properties": {
-          "command": {
-            "type": "array",
-            "items": { "type": "string" },
-            "description": "Command and arguments to start the LSP server"
-          },
-          "extensions": {
-            "type": "array",
-            "items": { "type": "string" },
-            "description": "File extensions this LSP handles (e.g., ['.ts', '.tsx'])"
-          },
-          "priority": { "type": "integer", "description": "Priority when multiple LSPs match (higher = preferred)" },
-          "disabled": { "type": "boolean", "description": "Disable this LSP server" },
-          "env": {
-            "type": "object",
-            "additionalProperties": { "type": "string" },
-            "description": "Environment variables for the LSP process"
-          },
-          "initialization": {
-            "type": "object",
-            "description": "LSP initialization options"
-          }
-        }
-      },
-      "examples": [{
-        "typescript": {
-          "command": ["typescript-language-server", "--stdio"],
-          "extensions": [".ts", ".tsx", ".js", ".jsx"]
-        }
-      }]
-    },
-    "hooks": {
-      "type": "object",
-      "properties": {
-        "session_logging": {
-          "type": "boolean",
-          "default": true,
-          "description": "Enable session lifecycle logging"
-        },
-        "tool_logging": {
-          "type": "boolean",
-          "default": false,
-          "description": "Enable tool execution logging"
-        },
-        "todo_enforcer": {
-          "type": "object",
-          "description": "Todo continuation enforcer - warns when todos are incomplete",
-          "properties": {
-            "enabled": {
-              "type": "boolean",
-              "default": true,
-              "description": "Enable todo completion checking"
-            },
-            "warn_on_incomplete": {
-              "type": "boolean",
-              "default": true,
-              "description": "Log warning when todos are incomplete"
-            }
-          }
-        },
-        "empty_message_sanitizer": {
-          "type": "object",
-          "description": "Empty message sanitizer - prevents API errors from empty outputs",
-          "properties": {
-            "enabled": {
-              "type": "boolean",
-              "default": true,
-              "description": "Enable empty message sanitization"
-            },
-            "log_empty": {
-              "type": "boolean",
-              "default": true,
-              "description": "Log when empty messages are detected"
-            },
-            "placeholder": {
-              "type": "string",
-              "default": "(No output)",
-              "description": "Placeholder text for empty outputs"
-            }
-          }
-        },
-        "git_guard": {
-          "type": "object",
-          "description": "Blocks dangerous git commands (force push, hard reset, rm -rf)",
-          "properties": {
-            "enabled": {
-              "type": "boolean",
-              "default": true,
-              "description": "Enable git command guard"
-            },
-            "allow_force_with_lease": {
-              "type": "boolean",
-              "default": true,
-              "description": "Allow --force-with-lease as a safer alternative"
-            }
-          }
-        },
-        "security_check": {
-          "type": "object",
-          "description": "Scans for secrets and credentials before git commits",
-          "properties": {
-            "enabled": {
-              "type": "boolean",
-              "default": true,
-              "description": "Enable secret scanning"
-            },
-            "block_commits": {
-              "type": "boolean",
-              "default": false,
-              "description": "Block commits when secrets are detected (vs. warn only)"
-            }
-          }
-        },
-        "subagent_question_blocker": {
-          "type": "object",
-          "description": "Prevents subagents from asking clarifying questions",
-          "properties": {
-            "enabled": {
-              "type": "boolean",
-              "default": true,
-              "description": "Enable subagent question blocking"
-            }
-          }
-        },
-        "comment_checker": {
-          "type": "object",
-          "description": "Detects excessive AI-generated comments in code",
-          "properties": {
-            "enabled": {
-              "type": "boolean",
-              "default": true,
-              "description": "Enable comment density checking"
-            },
-            "threshold": {
-              "type": "number",
-              "default": 0.3,
-              "minimum": 0,
-              "maximum": 1,
-              "description": "Comment-to-code ratio threshold (0.3 = 30%)"
-            }
-          }
-        },
-        "env_context": {
-          "type": "object",
-          "description": "Injects project structure, git branch, and build system info",
-          "properties": {
-            "enabled": {
-              "type": "boolean",
-              "default": true,
-              "description": "Enable environment context injection"
-            },
-            "include_git": {
-              "type": "boolean",
-              "default": true,
-              "description": "Include git branch and status"
-            },
-            "include_package": {
-              "type": "boolean",
-              "default": true,
-              "description": "Include package.json info"
-            },
-            "include_structure": {
-              "type": "boolean",
-              "default": true,
-              "description": "Include project directory structure"
-            },
-            "max_depth": {
-              "type": "integer",
-              "default": 2,
-              "minimum": 1,
-              "maximum": 5,
-              "description": "Max depth for directory structure scan"
-            }
-          }
-        },
-        "auto_format": {
-          "type": "object",
-          "description": "Runs project formatter after file edits (prettier, biome, dprint)",
-          "properties": {
-            "enabled": {
-              "type": "boolean",
-              "default": false,
-              "description": "Enable auto-formatting (off by default)"
-            },
-            "formatter": {
-              "type": "string",
-              "enum": ["prettier", "biome", "dprint"],
-              "description": "Override formatter (auto-detected if not set)"
-            },
-            "extensions": {
-              "type": "array",
-              "items": { "type": "string" },
-              "description": "File extensions to format (e.g., ['.ts', '.tsx'])"
-            },
-            "log": {
-              "type": "boolean",
-              "default": true,
-              "description": "Log format operations"
-            }
-          }
-        },
-        "typecheck_gate": {
-          "type": "object",
-          "description": "Runs TypeScript type checking after .ts/.tsx file edits",
-          "properties": {
-            "enabled": {
-              "type": "boolean",
-              "default": false,
-              "description": "Enable typecheck gate (off by default)"
-            },
-            "tsconfig": {
-              "type": "string",
-              "description": "Path to tsconfig.json (auto-detected if not set)"
-            },
-            "log": {
-              "type": "boolean",
-              "default": true,
-              "description": "Log typecheck results"
-            },
-            "block_on_error": {
-              "type": "boolean",
-              "default": false,
-              "description": "Block file writes when type errors are found"
-            }
-          }
-        },
-        "session_notification": {
-          "type": "object",
-          "description": "Desktop notifications when sessions complete or error",
-          "properties": {
-            "enabled": {
-              "type": "boolean",
-              "default": true,
-              "description": "Enable desktop notifications"
-            },
-            "on_idle": {
-              "type": "boolean",
-              "default": true,
-              "description": "Notify when session goes idle"
-            },
-            "on_error": {
-              "type": "boolean",
-              "default": true,
-              "description": "Notify on session errors"
-            },
-            "title_prefix": {
-              "type": "string",
-              "default": "OpenCode",
-              "description": "Prefix for notification titles"
-            }
-          }
-        },
-        "truncator": {
-          "type": "object",
-          "description": "Dynamic output truncation to prevent context overflow",
-          "properties": {
-            "enabled": {
-              "type": "boolean",
-              "default": true,
-              "description": "Enable output truncation"
-            },
-            "max_output_chars": {
-              "type": "integer",
-              "default": 30000,
-              "description": "Maximum output characters before truncation"
-            },
-            "max_output_lines": {
-              "type": "integer",
-              "default": 500,
-              "description": "Maximum output lines before truncation"
-            },
-            "preserve_head_lines": {
-              "type": "integer",
-              "default": 50,
-              "description": "Lines to preserve from the start"
-            },
-            "preserve_tail_lines": {
-              "type": "integer",
-              "default": 50,
-              "description": "Lines to preserve from the end"
-            },
-            "log": {
-              "type": "boolean",
-              "default": true,
-              "description": "Log truncation events"
-            }
-          }
-        },
-        "compaction": {
-          "type": "object",
-          "description": "Preserves beads state and memory during context compaction",
-          "properties": {
-            "enabled": {
-              "type": "boolean",
-              "default": true,
-              "description": "Enable compaction state preservation"
-            },
-            "include_beads_state": {
-              "type": "boolean",
-              "default": true,
-              "description": "Include beads-village task state"
-            },
-            "include_memory_refs": {
-              "type": "boolean",
-              "default": true,
-              "description": "Include recent memory references"
-            },
-            "include_todo_state": {
-              "type": "boolean",
-              "default": true,
-              "description": "Include current todo list state"
-            },
-            "max_state_chars": {
-              "type": "integer",
-              "default": 5000,
-              "description": "Maximum characters for compaction context"
-            }
-          }
-        },
-        "swarm_enforcer": {
-          "type": "object",
-          "description": "Enforces task isolation for multi-agent swarms",
-          "properties": {
-            "enabled": {
-              "type": "boolean",
-              "default": false,
-              "description": "Enable swarm enforcement (off by default)"
-            },
-            "strict_file_locking": {
-              "type": "boolean",
-              "default": true,
-              "description": "Only allow edits to reserved files"
-            },
-            "block_unreserved_edits": {
-              "type": "boolean",
-              "default": false,
-              "description": "Block edits to unreserved files (vs. warn)"
-            },
-            "log": {
-              "type": "boolean",
-              "default": true,
-              "description": "Log enforcement decisions"
-            }
-          }
-        }
-      }
-    }
-  }
-}