peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/cli/commands/hooks-commands.js

@@ -0,0 +1,272 @@
+import { existsSync, copyFileSync, mkdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult, getErrorMessage } from '../cli-helpers.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { applyHookInstall, planHookInstall, readHookStatus, readInstalledEntriesFromSettings, removeHookInstall, listSuperpowersDenyEntries } from '../../services/skills/hooks-settings-service.js';
+import { readJsonObjectFile } from '../../services/ide/shared/atomic-json.js';
+import { detectIdeFromContext } from '../../services/ide/hook-translator.js';
+import { getAdapter } from '../../services/ide/ide-registry.js';
+function resolveScope(options) {
+    return options.global ? 'global' : 'project';
+}
+function resolveProjectRoot(scope, project) {
+    return scope === 'project' ? (project ?? findProjectRoot(process.cwd()) ?? process.cwd()) : undefined;
+}
+/**
+ * Resolve the IDE the install should target. The CLI user can override with
+ * `--ide <id>`. Otherwise we delegate to `detectIdeFromContext` which checks
+ * `process.env[adapter.envVar]` → stdin shape → cwd `.trae`/`.claude` →
+ * fallback `'claude-code'`. Pass `parsedStdin: null` since `peaks hooks
+ * install` is not invoked from inside an IDE hook — there's no stdin payload.
+ */
+function resolveIdeForCommand(options, projectRoot) {
+    if (options.ide !== undefined && options.ide.length > 0) {
+        return options.ide;
+    }
+    return detectIdeFromContext({ env: process.env, cwd: projectRoot ?? process.cwd(), parsedStdin: null });
+}
+/**
+ * Slice #014: compute the per-IDE peaks hook entries for the install /
+ * dry-run RESPONSE SUMMARY. This is the *desired* shape (what the install
+ * WOULD write), not what is on disk. The status command uses a different
+ * helper (`readInstalledEntriesFromSettings`) that reads the actual
+ * settings.json.
+ *
+ * After slice #014 only the gate-enforce entry is ever installed
+ * (the legacy progress-start surface is gone). The summary mirrors
+ * the install shape so the JSON envelope doesn't claim a hook the
+ * service did not write.
+ */
+function listExpectedEntriesForIde(ide, _skipProgress = false) {
+    const adapter = getAdapter(ide);
+    if (ide === 'trae') {
+        return [{ matcher: adapter.toolMatcher, sentinel: 'peaks hook handle' }];
+    }
+    return [{ matcher: adapter.toolMatcher, sentinel: 'peaks gate enforce' }];
+}
+/**
+ * Slice 2026-07-24-peaks-code-bridge-002-rootcause (G6b / G10): copy the
+ * superpowers-bridge hook source from the peaks-loop repo
+ * (src/services/hooks/pre-tool-superpowers-bridge.sh) into the user-global
+ * `<userHome>/.claude/skills/peaks-code/hooks/` directory. The user-global
+ * copy is treated as a build artifact: it MUST be byte-identical to the
+ * repo source after install, and the source of truth is the repo file.
+ *
+ * Why this lives in the install command: the install is the single
+ * declared surface where the user-global directory is touched. Adding it
+ * here keeps the "hooks only ship from src/services/hooks/" invariant
+ * (G10 / AC10) — no other code path writes to `~/.claude/skills/peaks-code/hooks/`.
+ *
+ * Failure modes:
+ *   - Source file missing (build not run yet) → silently skip and emit a
+ *     warning. The settings.json install still succeeds; only the script
+ *     distribution is skipped. Matches the "release-pack silent skip
+ *     when tarball lacks dist/version.js" pattern from commit 08d93353.
+ *   - Target directory unwritable → throw so the user knows.
+ *   - Target file already exists with identical bytes → no-op.
+ *   - Target file exists with different bytes → overwrite (the repo
+ *     source is authoritative).
+ *
+ * Returns `{ copied, source, target }` so the install envelope can report
+ * it without forcing the caller to inspect the filesystem.
+ */
+/**
+ * Slice 2026-07-29-worktree-layer3-deny: read the on-disk
+ * `permissions.deny` block from a settings.json object and return
+ * every peaks-managed entry currently present. Used by `hooks status`
+ * to surface Layer 3 governance state without forcing the caller to
+ * re-read the file. Tolerant of missing / malformed `permissions` —
+ * a missing field returns an empty array, never throws.
+ */
+function readOnDiskDenyEntries(settings) {
+    const permissions = settings.permissions;
+    if (!permissions || typeof permissions !== 'object' || Array.isArray(permissions))
+        return [];
+    const deny = permissions.deny;
+    if (!Array.isArray(deny))
+        return [];
+    return deny.filter((d) => typeof d === 'string');
+}
+function copyBridgeHookIfPresent(userHome) {
+    const source = resolve(__dirname, '..', '..', 'services', 'hooks', 'pre-tool-superpowers-bridge.sh');
+    const target = resolve(userHome, '.claude', 'skills', 'peaks-code', 'hooks', 'pre-tool-superpowers-bridge.sh');
+    if (!existsSync(source)) {
+        return { copied: false, source, target };
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    copyFileSync(source, target);
+    return { copied: true, source, target };
+}
+export function registerHooksCommands(program, io) {
+    const hooks = program
+        .command('hooks')
+        .description("Manage the Peaks-managed hook entry in the adapter's settings.json (default: .claude/settings.json for Claude, .trae/settings.json for Trae). Slice #014: the only installed entry is the gate-enforce hook (SOP gate). The legacy progress-start hook (auto-spawn sub-agent progress terminal) is no longer installed — sub-agent progress is now surfaced via the dispatch + heartbeat flow (`peaks sub-agent dispatch` / `peaks sub-agent heartbeat`). The IDE is auto-detected from env / cwd; override with --ide <id>.");
+    addJsonOption(hooks
+        .command('install')
+        .description(`Install the peaks-managed gate-enforce hook entry into the adapter's settings.json. Slice #014: only the gate-enforce entry is installed; the legacy progress-start entry is no longer installed. Idempotent: re-runs are no-ops. Project scope by default.`)
+        .option('--global', 'install into the user-level ~/.claude/settings.json instead of the project')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
+        .option('--ide <id>', "target adapter id (claude-code | trae); default: auto-detect from env/cwd")
+        .option('--dry-run', 'show what would change without writing')
+        .option('--no-progress', 'skip the progress-start PreToolUse hook entry; install ONLY the gate-enforce entry')).action((options) => {
+        const scope = resolveScope(options);
+        const projectRoot = resolveProjectRoot(scope, options.project);
+        const ide = resolveIdeForCommand(options, projectRoot);
+        const skipProgress = options.progress === false;
+        try {
+            if (options.dryRun === true) {
+                const plan = planHookInstall(scope, projectRoot, { ide, skipProgress });
+                const dryRunEntries = listExpectedEntriesForIde(ide, skipProgress);
+                const bridgeCopy = scope === 'global'
+                    ? copyBridgeHookIfPresent(process.env.USERPROFILE ?? process.env.HOME ?? '')
+                    : { copied: false, source: '', target: '' };
+                printResult(io, ok('hooks.install', {
+                    ...plan,
+                    ide,
+                    applied: false,
+                    dryRun: true,
+                    skipProgress,
+                    entries: dryRunEntries,
+                    bridgeHookCopy: bridgeCopy,
+                    // Slice 2026-07-29-worktree-layer3-deny: surface the
+                    // Layer 3 deny entries the install WOULD write. The
+                    // dry-run branch never actually invokes
+                    // `applyHookInstall`, so the on-disk snapshot is not
+                    // consulted here — the list is the desired-state
+                    // constant for clarity in the JSON envelope.
+                    permissionsDenyEntries: listSuperpowersDenyEntries()
+                }, [], [
+                    `would install ${dryRunEntries.length} peaks-managed hook entries`,
+                    `would write ${listSuperpowersDenyEntries().length} permissions.deny entries (Layer 3 worktree governance)`,
+                    bridgeCopy.copied
+                        ? `would copy bridge hook from ${bridgeCopy.source} to ${bridgeCopy.target}`
+                        : 'would not copy bridge hook (source missing or non-global scope)'
+                ]), options.json);
+                return;
+            }
+            const result = applyHookInstall(scope, projectRoot, { ide, skipProgress });
+            // Slice #3: build the per-IDE entries summary from the actual installed
+            // entries, not the slice #1 PEAKS_HOOK_ENTRIES constant (which is the
+            // claude-code default). The user's JSON envelope must reflect the IDE
+            // they targeted. Slice #014: the install only emits the gate-enforce
+            // entry; the summary mirrors the install shape, NOT a hardcoded
+            // expected list.
+            const installedEntries = listExpectedEntriesForIde(ide, skipProgress);
+            // Slice 2026-07-24-peaks-code-bridge-002-rootcause (G6b / G10): when
+            // the install targets global scope, also copy the superpowers-bridge
+            // hook script from src/services/hooks/ to the user-global hooks
+            // directory. Project scope does not need this — project's
+            // .claude/skills/peaks-code is already a junction into the npm source.
+            const bridgeCopy = scope === 'global'
+                ? copyBridgeHookIfPresent(process.env.USERPROFILE ?? process.env.HOME ?? '')
+                : { copied: false, source: '', target: '' };
+            const nextActions = result.applied
+                ? [
+                    'Restart the IDE (or reload the workspace) so the hook entries take effect',
+                    `Installed: ${installedEntries.map((e) => `${e.matcher}→${e.sentinel}`).join(', ')}`,
+                    // Slice 2026-07-29-worktree-layer3-deny: surface L3 deny
+                    // write alongside the hook install — single atomic write.
+                    `Layer 3 deny: wrote ${listSuperpowersDenyEntries().length} permissions.deny entries (worktree governance)`,
+                    bridgeCopy.copied
+                        ? `Copied bridge hook: ${bridgeCopy.target}`
+                        : 'Bridge hook not copied (source missing or non-global scope)'
+                ]
+                : (bridgeCopy.copied
+                    ? [`Bridge hook copied: ${bridgeCopy.target}`]
+                    : []);
+            // Slice 2026-07-29-worktree-layer3-deny: emit L3 deny bookkeeping
+            // in the JSON envelope so downstream automation (audit / sc) can
+            // confirm Layer 3 was applied without re-reading the file. When
+            // the install is a no-op (`applied: false`) the deny block was
+            // already on disk from a prior install; we still emit the
+            // current desired list for symmetry with the dry-run envelope.
+            const denyEntries = listSuperpowersDenyEntries();
+            printResult(io, ok('hooks.install', {
+                ...result,
+                ide,
+                dryRun: false,
+                skipProgress,
+                entries: installedEntries.map((e) => ({ matcher: e.matcher, sentinel: e.sentinel })),
+                bridgeHookCopy: bridgeCopy,
+                permissionsDenyApplied: result.applied,
+                permissionsDenyEntries: denyEntries
+            }, [], nextActions), options.json);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('hooks.install', 'HOOKS_INSTALL_FAILED', message, { scope, ide, applied: false, skipProgress }, [message]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(hooks
+        .command('uninstall')
+        .description("Remove the peaks-managed gate-enforce hook entry from the target settings.json. Any legacy progress-start entry that a pre-#014 install left behind is also removed (sentinel-based scan). Third-party hooks are preserved.")
+        .option('--global', 'remove from the user-level ~/.claude/settings.json instead of the project')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
+        .option('--ide <id>', 'target adapter id (claude-code | trae); default: auto-detect from env/cwd')).action((options) => {
+        const scope = resolveScope(options);
+        const projectRoot = resolveProjectRoot(scope, options.project);
+        const ide = resolveIdeForCommand(options, projectRoot);
+        try {
+            const result = removeHookInstall(scope, projectRoot, { ide });
+            // Slice 2026-07-29-worktree-layer3-deny: surface L3 deny removal
+            // bookkeeping. `permissionsDenyRemoved` mirrors `removed` (the
+            // service strips deny entries on the same atomic write that
+            // strips the hook entries; they share the same boolean).
+            printResult(io, ok('hooks.uninstall', {
+                ...result,
+                ide,
+                permissionsDenyRemoved: result.removed,
+                permissionsDenyEntries: listSuperpowersDenyEntries()
+            }), options.json);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('hooks.uninstall', 'HOOKS_UNINSTALL_FAILED', message, { scope, ide, removed: false }, [message]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(hooks
+        .command('status')
+        .description('Report which peaks-managed hook entries are installed.')
+        .option('--global', 'inspect the user-level ~/.claude/settings.json instead of the project')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
+        .option('--ide <id>', 'target adapter id (claude-code | trae); default: auto-detect from env/cwd')).action((options) => {
+        const scope = resolveScope(options);
+        const projectRoot = resolveProjectRoot(scope, options.project);
+        const ide = resolveIdeForCommand(options, projectRoot);
+        try {
+            const status = readHookStatus(scope, projectRoot, { ide });
+            // Slice #014: read the ACTUAL on-disk entries (post-install shape),
+            // not the IDE-EXPECTED list. Pre-#014 `listInstalledEntriesForIde`
+            // returned the expected list and reported `entries: [Bash, Task]`
+            // even when the file only had `Bash`. The new helper reads the
+            // file and reports whatever peaks-managed entries are present,
+            // including any legacy progress-start entry that a pre-#014
+            // install left behind.
+            const settingsPath = status.settingsPath;
+            const settings = existsSync(settingsPath) ? readJsonObjectFile(settingsPath) : {};
+            // Slice 2026-07-29-worktree-layer3-deny: report the Layer 3 deny
+            // entries actually on disk. We read the existing settings.json
+            // (above) and surface its `permissions.deny` block. Any entry
+            // that matches the current `SUPERPOWERS_DENIED_SKILLS` set is
+            // considered "peaks-managed"; user-written entries are passed
+            // through verbatim so the envelope reflects reality. The desired
+            // list is also included for parity with install / uninstall.
+            const onDiskDeny = readOnDiskDenyEntries(settings);
+            printResult(io, ok('hooks.status', {
+                ...status,
+                ide,
+                entries: readInstalledEntriesFromSettings(settings, ide),
+                permissionsDenyEntries: listSuperpowersDenyEntries(),
+                permissionsDenyOnDisk: onDiskDeny
+            }), options.json);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('hooks.status', 'HOOKS_STATUS_FAILED', message, { scope, ide }, [message]), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/ide-commands.d.ts

@@ -0,0 +1,25 @@
+/**
+ * peaks ide * CLI (Slice 2026-07-09 add-zcode-adapter, Slice C).
+ *
+ * Slice C adds ONE verb:
+ *
+ *   peaks ide model --current
+ *
+ * Outputs the currently-active model id detected from the host
+ * environment (so far: only the `zcode` adapter opts in via
+ * `IdeAdapter.detectCurrentModel?`). The CLI is the read-only
+ * debugging surface for runtime model probing. It does NOT set any
+ * state — `peaks config set model` remains the canonical write path.
+ *
+ * Future slices will extend this surface with `peaks ide list`,
+ * `peaks ide detect`, etc. — this slice keeps the surface minimal
+ * (per Karpathy guideline #2 — Simplicity First).
+ *
+ * Vendor-neutrality: this file delegates to
+ * `src/services/ide/current-model-detector.ts` which walks every
+ * registered adapter. This file does NOT import any specific
+ * adapter.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerIdeCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/ide-commands.js

@@ -0,0 +1,42 @@
+import { detectCurrentIdeModel } from '../../services/ide/current-model-detector.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { listAdapterIds } from '../../services/ide/ide-registry.js';
+export function registerIdeCommands(program, io) {
+    const ide = program.command('ide').description('Read-only introspection helpers for the registered IDE adapter layer (slice 2026-07-09 add-zcode-adapter, Slice C)');
+    addJsonOption(ide
+        .command('model')
+        .description('Inspect the IDE adapter model surface. Slice C supports `--current` only.')
+        .option('--current', 'Print the model id the active IDE adapter reports as currently configured')
+        .action(async (options) => {
+        if (options.current) {
+            await runIdeModelCurrent(io, options);
+            return;
+        }
+        // No verb supplied — Commander would normally show help; we
+        // emit a structured error instead so the JSON envelope stays
+        // consistent for LLM callers.
+        printResult(io, fail('ide.model', 'MISSING_VERB', 'Specify a verb: --current. Future slices may add --configured / --default.', { registeredAdapters: listAdapterIds() }, ['Rerun with --current to read the runtime-detected model id.']), options.json);
+    }));
+}
+async function runIdeModelCurrent(io, options) {
+    try {
+        const modelId = await detectCurrentIdeModel();
+        if (modelId === undefined) {
+            printResult(io, ok('ide.model.current', {
+                modelId: null,
+                detected: false,
+                registeredAdapters: listAdapterIds(),
+            }), options.json);
+            return;
+        }
+        printResult(io, ok('ide.model.current', {
+            modelId,
+            detected: true,
+            registeredAdapters: listAdapterIds(),
+        }), options.json);
+    }
+    catch (error) {
+        printResult(io, fail('ide.model.current', 'DETECTION_FAILED', 'Runtime model detection failed; falling back to configured model. See logs.', { error: error instanceof Error ? error.message : String(error) }, ['Check `PEAKS_LOG_LEVEL=debug peaks ide model --current` for the underlying error.']), options.json);
+    }
+}

package/dist/cli/commands/impact-commands.d.ts

@@ -0,0 +1,15 @@
+/**
+ * v2.15.0 follow-up — G13: impact scan CLI.
+ *
+ *   - `peaks impact scan`        — full impact report (changed files +
+ *                                  affected flows + must-check list)
+ *   - `peaks impact must-check`  — return just the must-check list
+ *                                  (for piping into smoke / release)
+ *
+ * Lightweight glob-based implementation (no AST, no type checking).
+ * Suitable for the "we don't have UT, give me a quick risk list"
+ * use case from the 12 Gaps memory.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerImpactCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/impact-commands.js

@@ -0,0 +1,62 @@
+/**
+ * v2.15.0 follow-up — G13: impact scan CLI.
+ *
+ *   - `peaks impact scan`        — full impact report (changed files +
+ *                                  affected flows + must-check list)
+ *   - `peaks impact must-check`  — return just the must-check list
+ *                                  (for piping into smoke / release)
+ *
+ * Lightweight glob-based implementation (no AST, no type checking).
+ * Suitable for the "we don't have UT, give me a quick risk list"
+ * use case from the 12 Gaps memory.
+ */
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { mustCheckFromReport, runImpactScan } from '../../services/impact/impact-scan-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+export function registerImpactCommands(program, io) {
+    const impact = program
+        .command('impact')
+        .description('v2.15.0 follow-up G13: lightweight impact scan (no AST, glob-based) for存量老项目无 UT 兜底.');
+    addJsonOption(impact
+        .command('scan')
+        .description('Scan the given changed files for impact: impacted files (siblings of changed), ' +
+        'affected business flows (configurable), and the must-check list (concrete ' +
+        'scenarios the user must verify before shipping). Pure local computation, no I/O.')
+        .requiredOption('--files <list>', 'comma-separated list of changed file paths (relative to project root)')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const files = opts.files.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+        if (files.length === 0) {
+            printResult(io, fail('impact.scan', 'INVALID_INPUT', 'no files provided (--files)', { projectRoot }, [
+                'Pass --files with at least one file path.'
+            ]), opts.json ?? false);
+            return;
+        }
+        const report = runImpactScan({ changedFiles: files });
+        printResult(io, ok('impact.scan', { projectRoot, report }, [], [...report.warnings]), opts.json ?? false);
+    });
+    addJsonOption(impact
+        .command('must-check')
+        .description('Return just the must-check list for a set of changed files. ' +
+        'Useful for piping into smoke / release verification flows. ' +
+        'Accepts the same --files flag as `peaks impact scan`.')
+        .requiredOption('--files <list>', 'comma-separated list of changed file paths')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const files = opts.files.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+        if (files.length === 0) {
+            printResult(io, fail('impact.must-check', 'INVALID_INPUT', 'no files provided (--files)', { projectRoot }, [
+                'Pass --files with at least one file path.'
+            ]), opts.json ?? false);
+            return;
+        }
+        const report = runImpactScan({ changedFiles: files });
+        const items = mustCheckFromReport(report);
+        printResult(io, ok('impact.must-check', { projectRoot, count: items.length, items }, [], [
+            items.length === 0
+                ? 'No must-check items generated for the given changes.'
+                : 'Pipe into `peaks smoke add-path` to register these as regression paths.'
+        ]), opts.json ?? false);
+    });
+}

package/dist/cli/commands/job-commands.d.ts

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