clikit-plugin 0.2.28 → 0.2.30

package/memory/handoffs/2026-02-15-runtime-fixes.md

@@ -1,80 +0,0 @@
----
-date: 2026-02-15
-phase: implementing
-branch: main
----
-
-# Handoff: CliKit Runtime Bug Fixes
-
----
-
-## Status Summary
-
-CliKit plugin v0.2.3 published with installer merge fix and type guards in hooks. **NEW ISSUES IDENTIFIED**: 
-1. Backup creation is now unnecessary since merge works correctly - should be removed
-2. Runtime error `todos.filter is not a function` when OpenCode starts
-
----
-
-## Task Status
-
-### ✅ Completed
-- [x] Fix installer to MERGE with existing opencode.json (v0.2.3)
-- [x] Add defensive type checks to hooks (truncator, security-check, compaction)
-- [x] Publish v0.2.1, v0.2.2, v0.2.3 to npm
-
-### 🔄 In Progress
-- [ ] Remove backup creation from cli.ts
-- [ ] Fix `todos.filter is not a function` runtime error
-
-### 📋 Not Started
-- [ ] Publish v0.2.4
-
----
-
-## Files Modified
-
-| File | Status | Notes |
-|------|--------|-------|
-| `.opencode/src/cli.ts` | Needs Fix | Remove backup logic |
-| `.opencode/src/index.ts` | Needs Fix | Add Array.isArray check |
-| `.opencode/src/hooks/todo-enforcer.ts` | Needs Fix | Add array guard |
-
----
-
-## Git State
-
-- **Branch:** `main`
-- **Last commit:** `31b200c` - Update README with simplified installation
-- **Uncommitted changes:** Yes (8 modified files)
-
----
-
-## Next Steps
-
-1. [ ] Remove backup logic from cli.ts (delete `backupConfig`, `cleanupOldBackups` functions)
-2. [ ] Fix `todos.filter` error in `index.ts:172` and `todo-enforcer.ts:20`
-3. [ ] Run typecheck
-4. [ ] Publish v0.2.4
-
----
-
-## Root Cause: `todos.filter` Bug
-
-```typescript
-// Current (broken) - index.ts:166-172
-const todos = props?.todos as Array<{...}> | undefined;
-if (todos && todos.length > 0) {  // Objects with .length pass this!
-  checkTodoCompletion(todos);      // But .filter fails
-}
-
-// Fix
-if (Array.isArray(todos) && todos.length > 0) {
-  checkTodoCompletion(todos);
-}
-```
-
-**Key files:**
-- `.opencode/src/cli.ts:78-107` — Backup functions to delete
-- `.opencode/src/index.ts:165-180` — Todo handling to fix
-- `.opencode/src/hooks/todo-enforcer.ts:20` — Add array guard

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

@@ -1,195 +0,0 @@
-# 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

@@ -1,128 +0,0 @@
----
-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 |