peaks-cli 1.2.7 → 1.2.9

package/README.md

@@ -13,6 +13,18 @@ npm install -g peaks-cli
 
 安装后，Peaks 会把内置的 8 个 `peaks-*` 技能注册到 Claude Code，会话里直接通过技能名调用即可。
 
+## 本地开发（从源码跑 CLI）
+
+仓库自带 `peaks` CLI 源码。开发模式用 `tsx` 直接跑 `src/cli/index.ts`，所以**首次克隆后 `node_modules/` 里不会有 `chalk` / `ora` / `terminal-kit` 等运行时依赖**——直接 `tsx src/cli/index.ts` 会报 `ERR_MODULE_NOT_FOUND: chalk`。先执行一次 `pnpm install` 把依赖补齐，再验证：
+
+```bash
+pnpm install
+pnpm exec tsx src/cli/index.ts --version   # 应打印 1.2.9
+pnpm exec tsx src/cli/index.ts <cmd>       # 与全局 `peaks <cmd>` 行为一致
+```
+
+热重载开发循环可用 `pnpm dev:watch`。
+
 ## 5 分钟上手
 
 在 Claude Code 对话里，**直接对 Claude 说「用 X 技能做 Y」** 即可，技能会接管剩下的所有流程：

package/dist/src/cli/commands/core-artifact-commands.js

@@ -8,7 +8,8 @@ import { runDoctor } from '../../services/doctor/doctor-service.js';
 import { listSkills } from '../../services/skills/skill-registry.js';
 import { inspectSkillRunbook } from '../../services/skills/skill-runbook-service.js';
 import { setSkillPresence, clearSkillPresence, getSkillPresence, isSkillPresenceMode, touchSkillHeartbeat } from '../../services/skills/skill-presence-service.js';
-import { ensureSession, getSessionMeta, setSessionMeta, setSessionTitle, listSessionMetas } from '../../services/session/session-manager.js';
+import { ensureSession, getSessionMeta, rotateSessionBinding, setSessionMeta, setSessionTitle, listSessionMetas } from '../../services/session/session-manager.js';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { generateProjectContext } from '../../services/memory/project-context-service.js';
 import { fail, ok } from '../../shared/result.js';
@@ -214,6 +215,40 @@ export function registerCoreAndArtifactCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    addJsonOption(session
+        .command('rotate')
+        .description('Drop the project-level session binding so the next peaks call auto-generates a fresh session id. The on-disk session directory is left intact — only .peaks/.session.json is removed.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')
+        .option('--reason <text>', 'human-readable reason for the rotation, recorded in the response data')).action(async (options) => {
+        try {
+            // Canonicalise the project root before touching the binding.
+            // `peaks workspace init` writes the binding with the
+            // realpath-resolved projectRoot; if the caller passes a path
+            // through a symlink (notably /tmp on macOS, which is a
+            // symlink to /private/tmp) without canonicalising here,
+            // readSessionFile's strict projectRoot equality check fails
+            // and the rotate call reports "no prior binding" even
+            // though one exists. The same fix as `workspace init`
+            // (b193714): promote the path to the git root, falling back
+            // to the heuristic, falling back to cwd verbatim.
+            const projectRoot = options.project !== undefined
+                ? options.project
+                : (findProjectRoot(process.cwd()) ?? process.cwd());
+            const canonical = resolveCanonicalProjectRoot(projectRoot);
+            const previousSessionId = rotateSessionBinding(canonical);
+            printResult(io, ok('session.rotate', {
+                previousSessionId,
+                ...(options.reason !== undefined ? { reason: options.reason } : {}),
+                note: previousSessionId === null
+                    ? 'No prior binding was present; the project is already unbound.'
+                    : 'Next ensureSession() call will auto-generate a fresh id. The previous session directory is still on disk at .peaks/<previousSessionId>/.'
+            }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('session.rotate', 'SESSION_ROTATE_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path exists and is writable']), options.json);
+            process.exitCode = 1;
+        }
+    });
     const profile = program.command('profile').description('Manage runtime profiles');
     addJsonOption(profile.command('list').description('List available profiles')).action((options) => {
         printResult(io, ok('profile.list', { profiles: listProfiles() }), options.json);

package/dist/src/cli/commands/perf-commands.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerPerfCommands(program: Command, io: ProgramIO): void;

package/dist/src/cli/commands/perf-commands.js

@@ -0,0 +1,41 @@
+import { executePerfBaselineInit, resolveProjectRootFromCwd } from '../../services/perf/perf-baseline-service.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+export function registerPerfCommands(program, io) {
+    const perf = program.command('perf').description('Manage performance baseline scaffolding for the RD stage');
+    addJsonOption(perf
+        .command('baseline')
+        .description('Scaffold .peaks/<sid>/rd/perf-baseline.md so the RD can record the slice\'s perf numbers in a stable place that QA Gate A4 can diff against. Default dry-run; pass --apply to write.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')
+        .option('--apply', 'write the scaffold into the target project', false)
+        .option('--reason <text>', 'human-readable reason for the baseline (recorded in the response data)')).action(async (options) => {
+        try {
+            const projectRoot = options.project !== undefined
+                ? options.project
+                : resolveProjectRootFromCwd(process.cwd());
+            const result = await executePerfBaselineInit({
+                projectRoot,
+                apply: options.apply === true,
+                ...(options.reason !== undefined ? { reason: options.reason } : {})
+            });
+            const nextActions = [];
+            if (result.sessionId === null) {
+                nextActions.push('No peaks session is bound for this project yet. Run `peaks workspace init` (or any peaks skill) first so a session directory exists.');
+            }
+            else if (result.alreadyInitialized) {
+                nextActions.push(`perf-baseline.md already exists; no files were written. Re-run only after a re-measurement if you intend to overwrite.`);
+            }
+            else if (!result.apply) {
+                nextActions.push('Re-run with --apply to write the scaffold.');
+            }
+            else {
+                nextActions.push('Open the file and fill in the Results table — that is the input QA Gate A4 will diff against.');
+            }
+            printResult(io, ok('perf.baseline', result, [], nextActions), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('perf.baseline', 'PERF_BASELINE_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path exists and is writable']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/src/cli/commands/progress-close-kill.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Best-effort close of a spawned `peaks progress watch`
+ * window. Used by `peaks progress close` (manual escape
+ * hatch) and by the watch-side auto-exit when the sub-agent
+ * hits a terminal phase.
+ *
+ * The close is best-effort by design: we never throw from
+ * individual signals. One failed close primitive is a UX
+ * paper cut, not a correctness bug — the caller still clears
+ * the spawn record after this returns.
+ *
+ * Cross-platform strategy:
+ *
+ *   - macOS: pkill the watch process by command pattern
+ *     (matches the project path, so we never close the
+ *     wrong window), then send AppleScript to Terminal.app
+ *     to close the window by `custom title`. Terminal.app
+ *     is the dominant macOS terminal, and `custom title` is
+ *     the only stable identifier we can target from outside
+ *     the running shell.
+ *   - Linux: pkill the watch process, then try `wmctrl -c
+ *     peaks-cli-progress` to close the terminal window by
+ *     WM class (set in `progress start` for alacritty /
+ *     kitty; gnome-terminal / konsole / xfce4-terminal
+ *     close on their own when the child exits). wmctrl is
+ *     not always installed; we silently no-op on
+ *     "command not found" (exit 127) and surface other
+ *     errors as warnings.
+ *   - Windows: `taskkill /F /FI "WINDOWTITLE eq
+ *     peaks-cli:*"` to kill the cmd.exe wrapper. We use
+ *     the title prefix because the exact title includes the
+ *     `--reason` suffix which we do not know here.
+ *
+ * The kill is intentionally not a single primitive (e.g.
+ * `process.kill(-pid, 'SIGTERM')` on the process group).
+ * The launcher's PID is the spawn-time PID (osascript on
+ * macOS, gnome-terminal on Linux), not the long-lived
+ * watch process — and the long-lived process is the one we
+ * actually need to terminate to make the terminal close.
+ * Targeting by command pattern (pkill) + window title
+ * (AppleScript / wmctrl / taskkill) is more reliable than
+ * PID chasing across detached children.
+ */
+import type { ProgressSpawnRecord } from '../../services/progress/progress-service.js';
+export type KillSpawnedTerminalResult = {
+    /** Each signal that was successfully sent. */
+    signals: string[];
+    /** Soft failures (e.g. pkill matched no process, wmctrl missing). */
+    warnings: string[];
+};
+export declare function killSpawnedTerminal(record: ProgressSpawnRecord, canonicalProjectRoot: string, currentPlatform: NodeJS.Platform): Promise<KillSpawnedTerminalResult>;

package/dist/src/cli/commands/progress-close-kill.js

@@ -0,0 +1,152 @@
+/**
+ * Best-effort close of a spawned `peaks progress watch`
+ * window. Used by `peaks progress close` (manual escape
+ * hatch) and by the watch-side auto-exit when the sub-agent
+ * hits a terminal phase.
+ *
+ * The close is best-effort by design: we never throw from
+ * individual signals. One failed close primitive is a UX
+ * paper cut, not a correctness bug — the caller still clears
+ * the spawn record after this returns.
+ *
+ * Cross-platform strategy:
+ *
+ *   - macOS: pkill the watch process by command pattern
+ *     (matches the project path, so we never close the
+ *     wrong window), then send AppleScript to Terminal.app
+ *     to close the window by `custom title`. Terminal.app
+ *     is the dominant macOS terminal, and `custom title` is
+ *     the only stable identifier we can target from outside
+ *     the running shell.
+ *   - Linux: pkill the watch process, then try `wmctrl -c
+ *     peaks-cli-progress` to close the terminal window by
+ *     WM class (set in `progress start` for alacritty /
+ *     kitty; gnome-terminal / konsole / xfce4-terminal
+ *     close on their own when the child exits). wmctrl is
+ *     not always installed; we silently no-op on
+ *     "command not found" (exit 127) and surface other
+ *     errors as warnings.
+ *   - Windows: `taskkill /F /FI "WINDOWTITLE eq
+ *     peaks-cli:*"` to kill the cmd.exe wrapper. We use
+ *     the title prefix because the exact title includes the
+ *     `--reason` suffix which we do not know here.
+ *
+ * The kill is intentionally not a single primitive (e.g.
+ * `process.kill(-pid, 'SIGTERM')` on the process group).
+ * The launcher's PID is the spawn-time PID (osascript on
+ * macOS, gnome-terminal on Linux), not the long-lived
+ * watch process — and the long-lived process is the one we
+ * actually need to terminate to make the terminal close.
+ * Targeting by command pattern (pkill) + window title
+ * (AppleScript / wmctrl / taskkill) is more reliable than
+ * PID chasing across detached children.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { getErrorMessage } from '../cli-helpers.js';
+const execFileAsync = promisify(execFile);
+export async function killSpawnedTerminal(record, canonicalProjectRoot, currentPlatform) {
+    const signals = [];
+    const warnings = [];
+    // The watch command we spawned, escaped for use as a pkill
+    // pattern. We anchor on `progress watch` (NOT `peaks progress
+    // watch`) because the actual cmdline is `.../peaks.js progress
+    // watch --project /path` — the literal substring
+    // `peaks progress watch` does NOT appear in the cmdline
+    // (there is a `.js` between `peaks` and `progress`).
+    // Anchoring on the verb + the project path is specific
+    // enough to not hit any user-owned `progress watch` process
+    // for a different project.
+    const watchPattern = `progress watch.*--project ${canonicalProjectRoot.replace(/[\\"\s]/g, '\\$&')}`;
+    if (currentPlatform === 'darwin') {
+        // pkill exit codes: 0 = matched & signalled, 1 = no processes
+        // matched (silent miss), 2 = syntax error (warning), 3 = fatal
+        // (warning). macOS pkill writes nothing to stderr on a clean
+        // miss, so the exit code is the only signal we have.
+        await trySignal('pkill', ['-f', watchPattern], signals, 'pkill-watch', warnings, /no.*process/i, new Set([1]));
+        // AppleScript to close the Terminal.app window by
+        // custom title. We use `every window whose custom title
+        // is` so we only close the right tab. AppleScript returns
+        // a non-zero exit when the window is already gone, the
+        // app is not running, or the title does not match — all
+        // of which are silent misses from the user's perspective
+        // (the user-facing outcome is identical to the success
+        // case: the window is no longer visible). Treat any
+        // non-zero exit as silent.
+        try {
+            const escapedTitle = record.windowTitle.replaceAll('\\', '\\\\').replaceAll('"', '\\"');
+            await execFileAsync('osascript', [
+                '-e',
+                `tell application "Terminal" to close (every window whose custom title is "${escapedTitle}")`
+            ]);
+            signals.push('osascript-close-window');
+        }
+        catch {
+            // Silent miss. See comment above.
+        }
+    }
+    else if (currentPlatform === 'linux') {
+        // Same pkill exit code semantics as macOS.
+        await trySignal('pkill', ['-f', watchPattern], signals, 'pkill-watch', warnings, /no.*process/i, new Set([1]));
+        // wmctrl by WM class (set in `progress start`). Missing
+        // wmctrl is silent (exit 127) — most distros ship it but
+        // headless / minimal installs do not.
+        await trySignal('wmctrl', ['-c', 'peaks-cli-progress'], signals, 'wmctrl-close-class', warnings, /not found|No such file/i, new Set([127]));
+    }
+    else if (currentPlatform === 'win32') {
+        // Title prefix is set in `progress start` to `peaks-cli:`.
+        // We match the prefix because the full title includes
+        // the `--reason` suffix which we do not know here.
+        // taskkill exit codes: 0 = success, 1 = no tasks matched
+        // (silent miss — the window is already gone), 128 = error.
+        const titlePrefix = 'peaks-cli:';
+        await trySignal('taskkill', ['/F', '/FI', `WINDOWTITLE eq ${titlePrefix}*`], signals, 'taskkill-window-title', warnings, /no.*task/i, new Set([1]));
+    }
+    else {
+        warnings.push(`unsupported platform: ${currentPlatform}`);
+    }
+    return { signals, warnings };
+}
+/**
+ * Run a single close primitive. If it throws AND either
+ *   (a) the error matches the "expected" stderr pattern
+ *       (e.g. "no process matched" for pkill, "command not
+ *       found" for wmctrl) — most platforms print this on
+ *       stderr; or
+ *   (b) the exit code is in `silentMissExitCodes` (pkill 1,
+ *       wmctrl 127, taskkill 1) — the primitive ran, found
+ *       nothing, and is not telling us via stderr,
+ * we silently no-op — that is the success case for the
+ * primitive. Other errors are appended to `warnings` for
+ * the caller to surface. On a clean resolve, the named
+ * signal is appended to `signals`.
+ */
+async function trySignal(command, args, signals, signal, warnings, expectedFailurePattern, silentMissExitCodes) {
+    try {
+        await execFileAsync(command, args);
+    }
+    catch (error) {
+        // execFile's error object exposes `code` as either a
+        // numeric exit code (when the process ran) or a string
+        // system code like 'ENOENT' (when the binary itself
+        // is missing). Only numeric exit codes are candidates
+        // for silent-miss.
+        const execError = error;
+        if (typeof execError.code === 'number' && silentMissExitCodes.has(execError.code)) {
+            // Exit code says "ran, but found nothing to act on".
+            // The user-facing outcome is identical to the success
+            // case, so do not surface a warning.
+            return;
+        }
+        const message = getErrorMessage(error);
+        if (expectedFailurePattern.test(message)) {
+            return;
+        }
+        warnings.push(`${command}: ${message}`);
+        return;
+    }
+    // Reached only if execFile resolves (exit 0). All three
+    // primitives exit non-zero on a miss, so a clean resolve
+    // means the signal landed.
+    signals.push(signal);
+}

package/dist/src/cli/commands/progress-commands.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerProgressCommands(program: Command, io: ProgramIO): void;