kenaz 0.0.0-stage → 0.3.2

package/core/dev/pipeline/plans/PLAN_task_cli_refactor.md

@@ -0,0 +1,281 @@
+# Refactoring Plan: task-cli.js
+
+**Target File**: `.collaboration/cli/task-cli.js`
+**Lines**: 447
+**Objective**: Split into read-friendly modules with clean directory structure
+
+---
+
+## 1. Current State Analysis
+
+### File Structure
+```
+task-cli.js (447 lines)
+├── Imports (3 lines)
+├── TaskCLI Class (419 lines)
+│   ├── constructor()
+│   ├── showHelp()          - 60 lines
+│   ├── createTask()        - 35 lines
+│   ├── listTasks()         - 37 lines
+│   ├── getTask()           - 58 lines
+│   ├── claimTask()         - 18 lines
+│   ├── assignTask()        - 26 lines
+│   ├── completeTask()      - 18 lines
+│   ├── lockTask()          - 21 lines
+│   ├── unlockTask()        - 23 lines
+│   ├── rebuildIndex()      - 15 lines
+│   └── run()               - 25 lines (command router)
+└── CLI Entry Point (20 lines)
+```
+
+### Issues
+1. **Monolithic design** - All 10 commands in single file
+2. **Mixed concerns** - Argument parsing + business logic + output formatting interleaved
+3. **Hard to test** - Cannot unit test individual commands
+4. **Hard to extend** - Adding new command requires modifying main file
+5. **Duplicate patterns** - Error handling and git user lookup repeated
+
+---
+
+## 2. Proposed Directory Structure
+
+```
+.collaboration/cli/
+├── task-cli.js              # Entry point (~30 lines)
+├── commands/                # Command handlers
+│   ├── index.js            # Command registry
+│   ├── create.js           # create command
+│   ├── list.js             # list command
+│   ├── get.js              # get command
+│   ├── claim.js            # claim command
+│   ├── assign.js           # assign command
+│   ├── complete.js         # complete command
+│   ├── lock.js             # lock command
+│   ├── unlock.js           # unlock command
+│   └── rebuild.js          # rebuild command
+├── utils/                   # Shared utilities
+│   ├── arg-parser.js       # Argument parsing helpers
+│   ├── git-user.js         # Git user detection
+│   └── output.js           # Console output helpers (success, error, info)
+├── formatters/              # Output formatters
+│   ├── task-formatter.js   # Format task for display
+│   └── help-formatter.js   # Help text generation
+└── config/
+    └── commands.js          # Command metadata (name, description, options)
+```
+
+---
+
+## 3. Module Breakdown
+
+### Entry Point: `task-cli.js` (~30 lines)
+```javascript
+#!/usr/bin/env node
+const { CommandRegistry } = require('./commands');
+const { showHelp } = require('./formatters/help-formatter');
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0 || args.includes('--help')) {
+    showHelp();
+    return 0;
+  }
+  const [command, ...commandArgs] = args;
+  return CommandRegistry.execute(command, commandArgs);
+}
+
+main().then(process.exit).catch(err => {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+});
+```
+
+### Command Registry: `commands/index.js` (~40 lines)
+```javascript
+const commands = {
+  create: require('./create'),
+  list: require('./list'),
+  get: require('./get'),
+  claim: require('./claim'),
+  assign: require('./assign'),
+  complete: require('./complete'),
+  lock: require('./lock'),
+  unlock: require('./unlock'),
+  rebuild: require('./rebuild'),
+};
+
+module.exports = {
+  CommandRegistry: {
+    execute: async (name, args) => {
+      const cmd = commands[name];
+      if (!cmd) throw new Error(`Unknown command: ${name}`);
+      return cmd.execute(args);
+    },
+    list: () => Object.keys(commands),
+  }
+};
+```
+
+### Example Command: `commands/create.js` (~40 lines)
+```javascript
+const { TaskAPI } = require('../../core/task-api.js');
+const { parseArgs } = require('../utils/arg-parser');
+const { success, error } = require('../utils/output');
+
+module.exports = {
+  name: 'create',
+  description: 'Create a new task',
+  options: ['--title', '--description', '--priority'],
+
+  async execute(args) {
+    const { title, description, priority = 'P2' } = parseArgs(args, ['title', 'description', 'priority']);
+
+    if (!title) {
+      error('Missing --title parameter');
+      return 1;
+    }
+
+    const api = new TaskAPI();
+    const task = await api.createTask({ title, description, priority });
+
+    success(`Task created: ${task.id}`);
+    console.log(`Title: ${task.title}`);
+    console.log(`Priority: ${task.priority}`);
+    return 0;
+  }
+};
+```
+
+### Utils: `utils/arg-parser.js` (~25 lines)
+```javascript
+function parseArgs(args, keys) {
+  const result = {};
+  keys.forEach(key => {
+    const index = args.indexOf(`--${key}`);
+    if (index >= 0 && args[index + 1]) {
+      result[key] = args[index + 1];
+    }
+  });
+  return result;
+}
+
+function getPositional(args, index = 0) {
+  return args.filter(a => !a.startsWith('--'))[index];
+}
+
+module.exports = { parseArgs, getPositional };
+```
+
+### Utils: `utils/git-user.js` (~15 lines)
+```javascript
+const { execSync } = require('child_process');
+
+function getGitUser() {
+  try {
+    return execSync('git config user.email', { encoding: 'utf8' })
+      .trim()
+      .split('@')[0];
+  } catch {
+    return 'unknown';
+  }
+}
+
+module.exports = { getGitUser };
+```
+
+### Utils: `utils/output.js` (~20 lines)
+```javascript
+module.exports = {
+  success: (msg) => console.log(`\u2705 ${msg}`),
+  error: (msg) => console.error(`\u274c ${msg}`),
+  warn: (msg) => console.log(`\u26a0\ufe0f  ${msg}`),
+  info: (msg) => console.log(msg),
+};
+```
+
+---
+
+## 4. Migration Steps
+
+### Phase 1: Create Infrastructure
+1. Create directory structure (`commands/`, `utils/`, `formatters/`, `config/`)
+2. Create `utils/arg-parser.js`
+3. Create `utils/git-user.js`
+4. Create `utils/output.js`
+
+### Phase 2: Extract Commands
+5. Create `commands/create.js`
+6. Create `commands/list.js`
+7. Create `commands/get.js`
+8. Create `commands/claim.js`
+9. Create `commands/assign.js`
+10. Create `commands/complete.js`
+11. Create `commands/lock.js`
+12. Create `commands/unlock.js`
+13. Create `commands/rebuild.js`
+14. Create `commands/index.js` (registry)
+
+### Phase 3: Create Formatters
+15. Create `formatters/task-formatter.js`
+16. Create `formatters/help-formatter.js`
+
+### Phase 4: Refactor Entry Point
+17. Simplify `task-cli.js` to use new modules
+18. Remove old monolithic code
+
+### Phase 5: Testing
+19. Manual test all commands
+20. Verify backward compatibility
+
+---
+
+## 5. Testing Strategy
+
+### Manual Test Checklist
+```bash
+# Test all commands work after refactoring
+node .collaboration/cli/task-cli.js --help
+node .collaboration/cli/task-cli.js create --title "Test" --priority P1
+node .collaboration/cli/task-cli.js list
+node .collaboration/cli/task-cli.js list --status pending
+node .collaboration/cli/task-cli.js get TASK_XXX
+node .collaboration/cli/task-cli.js claim TASK_XXX
+node .collaboration/cli/task-cli.js assign TASK_XXX --to testuser
+node .collaboration/cli/task-cli.js complete TASK_XXX
+node .collaboration/cli/task-cli.js lock TASK_XXX
+node .collaboration/cli/task-cli.js unlock TASK_XXX
+node .collaboration/cli/task-cli.js rebuild
+```
+
+### Backward Compatibility
+- All existing command syntax must work unchanged
+- Exit codes must remain consistent (0 = success, 1 = error)
+- Output format should remain similar
+
+---
+
+## 6. Expected Outcome
+
+| Metric | Before | After |
+|--------|--------|-------|
+| Main file lines | 447 | ~30 |
+| Max file size | 447 | ~60 |
+| Number of files | 1 | 14 |
+| Testability | Low | High |
+| Adding new command | Modify main | Add new file |
+
+---
+
+## 7. Risks and Mitigations
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| Require paths break | CLI fails | Test require paths carefully |
+| Missing export | Command not found | Registry validates on load |
+| Behavior change | User confusion | Follow test checklist |
+
+---
+
+**Status**: Awaiting Approval
+
+*Plan created by Architect Agent | 2026-02-14*

package/core/dev/pipeline/tasks/.gitkeep

@@ -0,0 +1 @@
+# Keep this folder in git

package/core/dev/pipeline/test_results/TASK_TEST_PARALLEL_002_result.txt

@@ -0,0 +1,27 @@
+TASK_TEST_PARALLEL_002 執行結果
+================================
+
+執行時間: 2026-02-11 18:35:00
+Team: developer
+Worker Session: developer_TASK_TEST_PARALLEL_002_2026-02-11_18-34-57-463
+
+測試目的:
+驗證並行處理檔案鎖機制
+
+執行結果:
+✅ 任務成功執行 - Team Worker 正常啟動
+✅ 日誌記錄完整 - 記錄到執行日誌目錄
+✅ 無錯誤發生 - 執行流程順暢
+
+驗收標準:
+- AC-002-1: ✅ 任務成功執行
+- AC-002-2: ✅ 日誌記錄完整
+- AC-002-3: ✅ 無錯誤發生
+
+測試結論:
+並行處理檔案鎖機制運作正常。developer team 可以透過 run-team.js
+成功啟動 Team Worker，並正確記錄執行日誌到專案內。符合 GEN-007
+專案自包含原則。
+
+執行時間: 約 2 分鐘
+實際複雜度: trivial（符合預期）

package/core/dev/plans/CLI_FIRST_INSTALL_FLOW.md

@@ -0,0 +1,128 @@
+# CLI-first install and first-run flow (TASK_2367)
+
+Status: DRAFT for user review. Target flow: install once -> `claude` in the project folder -> `/kenaz init` -> `/Ansuz`.
+Yggdrasil via `/kenaz ygg join`, Alaya via `k-cli alaya register` (device code), Dashboard only for viewing.
+
+## 1. Pieces and where they live
+
+| Piece | What | Location |
+|---|---|---|
+| kenaz-server | headless backend (loopback, port 18080 with fallback), MCP + HTTP | binary `kenaz-server[.exe]` (cargo `--no-default-features --features server`) |
+| kenaz-core | plugins, hooks, scripts, rules the plugin and server read | dir holding `plugins/kenaz`; the server reads tasks via `KENAZ_SOURCE_DIR=<kenaz-core>` |
+| kenaz plugin | `/kenaz` command + hooks | `<kenaz-core>/plugins/kenaz` |
+| installer | `node dashboard/scripts/install-kenaz-cli.js install\|uninstall\|status` | this card |
+| user state | service launcher, logs, `~/.kenaz/` | per-user home |
+| project state | `.kenaz/` in each project | never touched by uninstall |
+
+kenaz-core location: the repo root in dev/mother installs; otherwise the bundled `kenaz-core` next to the binary (same candidates the Rust `peer_mod::resolve_plugin_dir` uses). Installer: `--core-dir`, else `KENAZ_CORE_DIR`, else the repo root of the script. Binary: `--server-bin`, else `<core>/../kenaz-server`, `<core>/bin/`, `dashboard/src-tauri/target/release/`, `~/.kenaz/bin/`.
+
+## 2. What runs as a service
+
+Only `kenaz-server`, per user (no admin, no system service), started at logon, loopback only. The installer writes a launcher/unit and starts it.
+
+| OS | Mechanism | Files |
+|---|---|---|
+| Windows (implemented, real) | per-user Scheduled Task `KenazServer`, trigger at logon, runs `wscript.exe ~\.kenaz\kenaz-server.vbs` (hidden window, sets `KENAZ_SOURCE_DIR`). If `schtasks /Create` is refused (ONLOGON may need elevation) falls back to a `KenazServer.vbs` in the user Startup folder and starts it now | `~\.kenaz\kenaz-server.vbs` |
+| macOS (template written, untested) | launchd user agent `ai.kenaz.server`, RunAtLoad + KeepAlive, `launchctl load -w` | `~/Library/LaunchAgents/ai.kenaz.server.plist` |
+| Linux (template written, untested) | `systemd --user` unit `kenaz-server.service`, `enable --now`; headless boxes need `loginctl enable-linger $USER` | `~/.config/systemd/user/kenaz-server.service` |
+
+Templates are generated by `install-kenaz-cli.js` (`launchdPlist`, `systemdUnit`, `winVbs`) and unit-tested as strings; only Windows is exercised for real.
+
+mcp.json: the server follows the owner rule in `server_boot.rs` (it does not rewrite `~/.claude/mcp.json` when the Dashboard owns it).
+
+## 3. Plugin registration
+
+Chosen path: `CLAUDE_CODE_PLUGIN_DIRS` in `~/.claude/settings.json` `env`, same as kenaz-peer (proven 2026-10-03). The installer appends `<kenaz-core>/plugins/kenaz`:
+- merge, never replace; idempotent; slash/case-insensitive identity (Windows `;`, else `:` separator)
+- one-time backup `settings.json.bak-kenaz-peer` (same name as Rust, so there is one pristine backup), atomic tmp+rename
+- malformed JSON or odd shape is reported and left untouched
+- gates: `claude --version` >= 2.1.287 (else skipped with a "run `claude update`" message, rerun install afterwards), `KENAZ_SKIP_CLAUDE_PROVISION=1` opt-out, plugin dir must contain `hooks/hooks.json`
+
+Alternative considered: a Claude Code plugin marketplace. Better update story and no settings edit, but needs a published marketplace repo and consent flow; revisit when kenaz-core is distributed publicly. The env-var path needs nothing external.
+
+Unification debt: this duplicates the Rust `features/project/peer_mod.rs` logic in Node (installer must work before any Rust binary runs). Later: have the Rust path register `plugins/kenaz` too (or call a shared CLI subcommand) and drop the Node copy. Both write the same env var and backup, so they coexist.
+
+## 4. First run
+
+1. `claude` in any folder (plugin auto-loaded, no `--plugin-dir`).
+2. `/kenaz init` creates `.kenaz/project.yaml`, probes `/api/health`, and prints the optional steps and the next step. It does not force them:
+   - Yggdrasil: `/kenaz ygg join <key>` (also `status`, `leave`)
+   - Alaya: `k-cli alaya register` (device code, approve in any browser)
+   - Next: `/Ansuz`
+3. If the backend is down, init says so and points at `install-kenaz-cli.js install`.
+
+## 5. Upgrade and uninstall
+
+- Upgrade: replace kenaz-core and the binary, rerun `install` (idempotent: registration stays "already", launcher is rewritten, task recreated with /F). Stop the old server first on Windows (`schtasks /End /TN KenazServer`) if the binary is locked.
+- Uninstall: `install-kenaz-cli.js uninstall` removes only our entry from `CLAUDE_CODE_PLUGIN_DIRS`, deletes the scheduled task / Startup launcher / plist / unit and the launcher file. Project `.kenaz/` data and `~/.kenaz/` memory data stay. The settings backup stays.
+- `status` reports plugin registration and service state. `--dry-run` prints the plan for any command and changes nothing.
+
+## 6. Verification
+
+Automated (done): `node --test dashboard/scripts/install-kenaz-cli.test.js plugins/kenaz/scripts/kenaz.test.js` (temp home only).
+
+Acceptance "clean Windows user profile" is PENDING and must be run by the user:
+1. New Windows user (or VM), install Node and `claude` >= 2.1.287; copy kenaz-core and `kenaz-server.exe`.
+2. `node dashboard\scripts\install-kenaz-cli.js install --dry-run --core-dir <core> --server-bin <exe>` and read the plan.
+3. Rerun without `--dry-run`. Expect: `plugin: added`, scheduled task `KenazServer` (or Startup launcher), server answering `http://127.0.0.1:18080/api/health`.
+4. `mkdir test-proj; cd test-proj; claude` then `/kenaz init`, then `/Ansuz`. Expect Ansuz boots with no `--plugin-dir`.
+5. `... uninstall`. Expect `plugin: removed`, task gone (`schtasks /Query /TN KenazServer` fails), `test-proj\.kenaz` still present.
+
+## 7. Open points
+
+- macOS/Linux paths are untested; ONLOGON elevation behaviour on Windows needs the clean-profile run to confirm which branch is taken.
+- Packaging: who ships kenaz-core + binary to `~/.kenaz/bin` (release pipeline, not this card).
+- `k-cli` itself is not yet installed by this script; Alaya registration assumes it is on PATH.
+
+## 8. Decisions (user, 2026-10-09)
+- **Distribution: npm package** - `npx kenaz install` (name `kenaz` is free on npm as of 2026-10-09; publishing needs the user's npm account and explicit OK). Per-platform `kenaz-server` binaries ship as optional platform packages (esbuild pattern: `@kenazai/server-win32-x64`, `-darwin-arm64`, `-darwin-x64`, `-linux-x64`, `-linux-arm64`).
+- **Both harnesses:** the installer detects Claude Code and/or Codex. Claude Code -> plugin registration (this doc, section 3). Codex -> `.formation/bifrost/setup-codex.js` (MCP in ~/.codex/config.toml, native hooks, AGENTS.md).
+- **Platforms: Windows, macOS and Linux in the first release.**
+- **Node.js is a prerequisite** (both harnesses already need it); the installer checks the version and explains how to get it.
+- **Updates: kenaz-server self-updates** (binary + kenaz-core + plugin) from the release feed, with signature verification.
+- **Codex parity with Claude Code:** MCP tools, Yggdrasil commands, Ansuz flow and Codex-native subagent dispatch (TASK_2315).
+
+## 9. npm package `kenaz` (TASK_2377)
+
+Layout: `packages/kenaz` (CLI + staged kenaz-core), `packages/server-{win32-x64,darwin-arm64,darwin-x64,linux-x64,linux-arm64}` (`@kenazai/server-*`, `bin/` filled by CI, gitignored). All versions move in lockstep with `dashboard/src-tauri/Cargo.toml`.
+
+- `kenaz install|uninstall|status|doctor [--dry-run] [--home d] [--no-service] [--no-claude] [--no-codex] [--server-bin p]`.
+- install: Node >= 18 check; copy packaged kenaz-core to `~/.kenaz/core` and the platform binary dir to `~/.kenaz/bin`; record `~/.kenaz/install.json`; Claude Code (if `claude` on PATH) via `install-kenaz-cli.js` (both plugins + service); Codex (if `codex` on PATH) via `setup-codex.js` (MCP, native hooks, `/prompts:kenaz`). Neither is reimplemented.
+- uninstall reverses both (`setup-codex.js uninstall()` removes only the MCP entry, shim hook blocks and prompt it added) and deletes core/bin/install.json; project `.kenaz/` is never touched.
+- doctor: node version, core version, server binary, `/api/health` reachable, Claude plugins registered, Codex MCP + hooks. Exit 1 on any FAIL.
+- `prepack` runs `scripts/stage.js`: stages core with the same git-tracked whitelist as the Dashboard bundle (`kenaz-core-staging.js`, ~19 MB) and vendors `install-kenaz-cli.js`.
+- Release: `.gitlab-ci.yml` cross-builds the 5 targets (native runners; darwin-x64 cross-compiled on the M1 runner), packs tarballs as artifacts, `publish` is manual and does not call npm.
+- Local check: `npm pack ./packages/kenaz` etc., install into a prefix, run with `--home <tmp>` (never the real home).
+- Open: the server loads `libonnxruntime` via `ORT_DYLIB_PATH`; CI ships it next to the binary in `bin/`, but the service launchers do not set `ORT_DYLIB_PATH` yet. macOS/Linux service steps and all 5 CI build jobs are unverified until a pipeline/Mac run.
+
+## 10. 從 Dashboard 遷移 (TASK_2389)
+
+範圍：只偵測並提示。CLI 不會結束 Dashboard 行程、不改登錄檔或 Startup 資料夾。原因：`kenaz-server` 與 Dashboard 都綁 port 18080，不能同時執行。
+
+### 給使用者的步驟（可直接貼進公告）
+
+1. 在系統匣（右下角）對 Kenaz Dashboard（BLOCK ACTION）按右鍵，選「結束 / Quit」，確認程式完全關閉。
+2. 開啟 Dashboard 設定，關閉「開機時啟動 / Launch at startup」，避免登入後它又佔回 port 18080。
+3. 在終端機執行：`npx kenaz install`
+4. 到專案資料夾執行 `claude`，再輸入 `/kenaz init`。
+5. 驗證：`npx kenaz doctor`，每一列應為 ok 或 skip。
+
+若 Dashboard 還在執行，`npx kenaz install` 會印出上面的步驟並以非零碼結束，不會啟動服務。只想先裝 plugin 與 core、暫不啟動服務：加 `--keep-dashboard`。
+要改回 Dashboard：從開始選單啟動它，並在設定中重新開啟「開機時啟動」。`kenaz uninstall` 結束時會印出同樣的提示。
+
+### 資料共用，不需搬移（已讀程式確認）
+
+| 資料 | 位置 |
+|---|---|
+| 專案清單 | `~/.kenaz/projects.json` |
+| 憑證 / relay key / 各專案 Yggdrasil key | `~/.kenaz/credentials.yaml` |
+| 偏好設定 | `~/.kenaz/config.json` |
+| Synapse 記憶 | `<專案>/.synapse/db/memory.db` |
+| 任務、日誌 | `<專案>/.kenaz/` |
+| Peer 收件匣 | `peer_dir(project_root)/inbox.sqlite` |
+
+只有 Dashboard 自己的 webview、LSP 快取與 `.env.local` 放在 `%LOCALAPPDATA%\Kenaz Dashboard`，CLI 不使用。Dashboard 不寫使用者層級的 hooks，只在啟動時補各專案的 post-commit hook（`hook_installer.rs`），所以不需要 marker 檔。
+
+### doctor 為什麼檢查 plugin 路徑
+
+Dashboard 執行時（`peer_mod.rs`）會重新登錄自己 kenaz-core 內的 `kenaz-peer`；自 TASK_2384 起登錄會取代舊副本，所以重新啟動 Dashboard 會把 `CLAUDE_CODE_PLUGIN_DIRS` 的 `kenaz-peer` 改回它的路徑。`kenaz doctor` 會列出：Dashboard 是否執行 / 已安裝、18080 的持有者、`CLAUDE_CODE_PLUGIN_DIRS` 是否指向 Dashboard 的 core。