peaks-loop 4.1.2 → 4.1.4

package/dist/cli/commands/codegraph-config-restore-command.js

@@ -0,0 +1,200 @@
+// src/cli/commands/codegraph-config-restore-command.ts
+//
+// `peaks codegraph config-restore` — the explicit undo of a repair. Split out
+// of `codegraph-commands.ts`; the verb name, options and envelopes are
+// unchanged.
+import { assertCodegraphDirContained, resolveProjectRoot } from '../../services/codegraph/codegraph-service.js';
+import { resolveCodegraphConfigSource } from '../../services/codegraph/codegraph-project-config.js';
+import { rollbackCodegraphConfig } from '../../services/codegraph/codegraph-config-repair-writer.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { getErrorMessage, printResult, redactSensitiveErrorMessage } from '../cli-helpers.js';
+import { addProjectOption } from './codegraph-command-options.js';
+/**
+ * Exit code for a `config-restore` run that never reached the restore point:
+ * `--project` is missing or not a directory, or the containment guard refused
+ * the `.codegraph/` directory.
+ *
+ * Deliberately NOT `CODEGRAPH_CONFIG_RESTORE_EXIT_CODE` (77). The two codes
+ * answer different questions, and a CI job has to be able to tell them apart:
+ *
+ *   - 1  — the command was never aimed at a usable project. Nothing looked at a
+ *          rollback point, so "your backup is unusable" would be a verdict
+ *          nothing reached, and the remedy is a different one (fix the path, or
+ *          remove the link). The VALUE is 1 because that is what every other
+ *          codegraph verb already exits with for this same input failure —
+ *          `repair-exclude --project <bad>` and `status --project <bad>` both
+ *          exit 1 (measured), so a caller that handles one handles this one.
+ *   - 77 — the restore point WAS examined and the restore did not happen.
+ *
+ * Named rather than left as `printCodegraphFailure`'s default `1` so both
+ * classes are visible in one place, side by side, instead of one of them living
+ * only in another module's parameter default.
+ */
+const CODEGRAPH_CONFIG_RESTORE_PRECONDITION_EXIT_CODE = 1;
+/**
+ * Exit code for `peaks codegraph config-restore` when the restore did not
+ * happen: the backup is absent, unreadable, or REFUSED (a symbolic link, a
+ * hard link or a directory occupies the fixed, guessable `.bak` path), or the
+ * reverse write itself failed.
+ *
+ * Its own code rather than the precondition `1`, for the same reason 73/74/75/76
+ * have theirs: it is an operator-actionable verdict about the RESTORE POINT, and
+ * a CI job has to be able to tell it apart from "the command was aimed wrong".
+ * The cause lives in `data.reason`, which names the path and the shape that was
+ * refused — a per-cause CODE would need the rollback helper to return a
+ * discriminated reason rather than a message, which is a change to that helper's
+ * contract for no operator-visible gain while the message already carries the
+ * details.
+ */
+const CODEGRAPH_CONFIG_RESTORE_EXIT_CODE = 77;
+/**
+ * The failure envelope for EVERY `config-restore` failure, so all four `data`
+ * keys are present whatever went wrong.
+ *
+ * A JSON consumer reads `data.restored` and `data.reason` unconditionally, so a
+ * failure envelope that omits them leaves it guessing — and this verb reports a
+ * `reason` instead of an exit code alone precisely so a failure is never silent.
+ * Built here rather than delegated to `printCodegraphFailure`, whose `data` is
+ * always `{}` and therefore cannot satisfy that.
+ *
+ * `code` names the VERB's failure for all three cases; the exit code names the
+ * CLASS (precondition vs restore) and `reason` names the cause. That split is
+ * deliberate: one `code` a consumer can match on, plus the two facts it needs
+ * to decide what to do next.
+ *
+ * The verb-specific `code` is an INTENTIONAL DIVERGENCE from every other
+ * codegraph verb, not a consistency with them — `repair-exclude`,
+ * `repair-index` and `status` all report `CODEGRAPH_COMMAND_FAILED` out of
+ * `printCodegraphFailure` with `data: {}` (measured, 2026-09-17). Two reasons
+ * to diverge here anyway:
+ *
+ *   1. A generic `code` cannot be paired with a verb-specific `reason`
+ *      contract: this verb's failure ALWAYS carries `restored`/`reason`, which
+ *      `printCodegraphFailure` cannot express at all (`fail()` hard-codes the
+ *      other verbs' `data` to `{}`).
+ *   2. `CODEGRAPH_CONFIG_RESTORE_FAILED` says WHICH restore failed, and a
+ *      consumer matching on `code` gets that from the envelope rather than from
+ *      the exit code alone.
+ *
+ * FOLLOW-UP (recorded, not done here — it is out of this slice's scope):
+ * `code` naming across the codegraph verb family is now inconsistent, and the
+ * rest of the family should either adopt verb-specific codes or this one should
+ * return to the generic one. See this slice's RD artifact,
+ * `## A1 QA 修复循环 2`.
+ */
+function printConfigRestoreFailure(io, failure) {
+    const redacted = redactSensitiveErrorMessage(failure.reason);
+    printResult(io, fail('codegraph.config-restore', 'CODEGRAPH_CONFIG_RESTORE_FAILED', redacted, { restored: false, from: null, to: null, reason: redacted }, [...failure.nextActions]), failure.asJson);
+    process.exitCode = failure.exitCode;
+}
+/** The precondition class: nothing below the resolve ran. */
+function printRestorePreconditionFailure(io, asJson, error) {
+    printConfigRestoreFailure(io, {
+        asJson,
+        reason: getErrorMessage(error),
+        exitCode: CODEGRAPH_CONFIG_RESTORE_PRECONDITION_EXIT_CODE,
+        nextActions: [
+            'Check that `--project` names an existing directory whose `.codegraph/` resolves inside it.',
+            'Run `peaks codegraph config-restore --project <root>` again once the path is right.'
+        ]
+    });
+}
+/** The restore class: the reverse write itself threw. */
+function printRestoreWriteFailure(io, asJson, error) {
+    printConfigRestoreFailure(io, {
+        asJson,
+        reason: getErrorMessage(error),
+        exitCode: CODEGRAPH_CONFIG_RESTORE_EXIT_CODE,
+        nextActions: [
+            'Check that the `.codegraph/` directory is writable, then re-run.',
+            'The config was NOT restored; its bytes are unchanged.'
+        ]
+    });
+}
+/** The restore class: the rollback point was examined and refused. */
+function printRestoreRefusedFailure(io, asJson, result) {
+    printConfigRestoreFailure(io, {
+        asJson,
+        reason: result.error,
+        exitCode: CODEGRAPH_CONFIG_RESTORE_EXIT_CODE,
+        nextActions: [
+            `There is no usable rollback point at ${result.backupPath}.`,
+            'A restore needs the `.bak` that a previous `peaks codegraph repair-exclude` or `repair-index` left next to the config.'
+        ]
+    });
+}
+function printRestoreSuccess(io, result, asJson) {
+    printResult(io, ok('codegraph.config-restore', {
+        restored: true,
+        from: result.backupPath,
+        to: result.configPath,
+        reason: null
+    }, [], [
+        'Run `peaks codegraph status --project <root>` to see the restored config reflected in the integrity gate.',
+        'Run `peaks codegraph index` if the index should reflect the restored config too — this verb does not rebuild it.'
+    ]), asJson);
+}
+/**
+ * `peaks codegraph config-restore` — put `.codegraph/config.json` back to the
+ * bytes the last repair backed up to `.codegraph/config.json.bak`.
+ *
+ * The EXPLICIT undo of a repair, and the only way the `.bak` is ever read: the
+ * repair seams leave the copy behind and never consume it, because a repair
+ * that restored its own write would cancel itself out (the config would be
+ * exactly as it was found, `status` would still report the gap, and exit 75
+ * would never clear).
+ *
+ * Touches the CONFIG FILE ONLY — no `codegraph` subprocess is spawned, so this
+ * is safe to run while nothing else is rebuilding. The index still reflects
+ * whatever config the last rebuild used; the envelope's `nextActions` says so
+ * rather than silently reindexing.
+ */
+async function runCodegraphConfigRestoreCommand(io, options, asJson) {
+    let configPath;
+    try {
+        // `resolveProjectRoot` for the same reason the repair verbs use it: the
+        // paths reported here must be the canonical ones, or a `--project` alias
+        // reports a restore that happened somewhere the operator cannot find.
+        const projectRoot = resolveProjectRoot(options.project);
+        // The containment refusal the repair seam makes before IT writes here. A
+        // `.codegraph/` that resolves outside the canonical project root (a junction
+        // or a symlink) would otherwise let this verb publish one project's bytes
+        // into another. Called for its refusal only — the paths below stay derived
+        // from the caller's canonical `projectRoot`.
+        assertCodegraphDirContained(projectRoot);
+        // The same resolver the repair WRITES through, so a restore puts back the
+        // file the repair replaced — not a same-named file upstream never reads.
+        configPath = resolveCodegraphConfigSource(projectRoot).configPath;
+    }
+    catch (error) {
+        printRestorePreconditionFailure(io, asJson, error);
+        return;
+    }
+    let result;
+    try {
+        result = await rollbackCodegraphConfig(configPath);
+    }
+    catch (error) {
+        // Only the reverse write's own fs failure reaches here (the refusals are
+        // returned, not thrown). The RESTORE class, and the same code as a refusal:
+        // the restore was attempted and did not happen, and a script that can read
+        // one can read the other. What differs is the `reason`, which is this
+        // error's own message.
+        printRestoreWriteFailure(io, asJson, error);
+        return;
+    }
+    if (!result.rolledBack) {
+        // LOUD, never silent: the reason reaches the envelope's `message` (which
+        // `fail()` redacts) AND `data.reason`, and the exit code is this verb's
+        // own. A restore that quietly reported success over a `.bak` it refused to
+        // read is exactly the fail-silent family this release closed.
+        printRestoreRefusedFailure(io, asJson, result);
+        return;
+    }
+    printRestoreSuccess(io, result, asJson);
+}
+export function registerCodegraphConfigRestoreCommand(codegraph, io) {
+    addProjectOption(codegraph
+        .command('config-restore')
+        .description('Restore .codegraph/config.json from the byte-exact .bak a repair left — the explicit undo of a repair')).action((options) => runCodegraphConfigRestoreCommand(io, options, options.peaksJson));
+}

package/dist/cli/commands/codegraph-proxy-commands.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from 'commander';
+import type { ProgramIO } from '../cli-helpers.js';
+export declare function registerCodegraphIndexCommands(codegraph: Command, io: ProgramIO): void;
+export declare function registerCodegraphFileCommands(codegraph: Command, io: ProgramIO): void;
+export declare function registerCodegraphAffectedCommand(codegraph: Command, io: ProgramIO): void;
+/**
+ * The proxy verbs in registration order. `index` / `query` and `files` /
+ * `context` are paired because each pair shares a module-level helper set.
+ */
+export declare function registerCodegraphProxyCommands(codegraph: Command, io: ProgramIO): void;

package/dist/cli/commands/codegraph-proxy-commands.js

@@ -0,0 +1,159 @@
+// src/cli/commands/codegraph-proxy-commands.ts
+//
+// The `peaks codegraph` verbs that proxy one upstream invocation: `index`,
+// `query`, `files`, `context` and `affected`. Split out of
+// `codegraph-commands.ts`; the verb names, options and envelopes are
+// unchanged.
+import { resolve } from 'node:path';
+import { writeCodegraphAffectedContext } from '../../services/codegraph/codegraph-service.js';
+import { runCodegraphCommand } from './codegraph-command-runtime.js';
+import { addProjectOption, parsePositiveInteger } from './codegraph-command-options.js';
+/**
+ * The payload written into the codegraph-context envelope: the captured
+ * upstream stdout, parsed as JSON when `--json` asked for JSON and the text
+ * is parseable. A parse failure keeps the raw string, which the envelope
+ * renderer handles cleanly.
+ */
+function resolveAffectedPayload(json, rawStdout) {
+    if (json !== true || rawStdout.length === 0) {
+        return rawStdout;
+    }
+    try {
+        return JSON.parse(rawStdout);
+    }
+    catch {
+        return rawStdout;
+    }
+}
+/** Report the envelope write on stdout, unless `--json` owns stdout. */
+function reportAffectedEnvelope(io, envelope, asJson) {
+    if (asJson === true)
+        return;
+    io.stdout(envelope.written
+        ? `[codegraph-context] wrote ${envelope.path}\n`
+        : `[codegraph-context] skipped: ${envelope.warning}\n`);
+}
+/**
+ * Probes `.codegraph/` for the peaks-loop marker before invoking the
+ * upstream binary.
+ *
+ *   - fresh                          → proceed to upstream init
+ *   - noop-already-peaks-loop        → skip upstream, emit warning
+ *   - conflict-foreign-schema        → exit 73 + CODEGRAPH_INIT_CONFLICT envelope
+ *
+ * On a successful upstream init, write the marker so the next run
+ * hits the noop branch instead of the conflict branch.
+ *
+ * Wraps the generic `runCodegraphCommand` and, after a successful
+ * upstream invocation, calls `writeCodegraphAffectedContext` so the
+ * RD / QA handoff can pick up `.peaks/_runtime/<sid>/rd/codegraph-context.md`
+ * without re-running the (5-30 s) codegraph query.
+ *
+ * The envelope write is gated by `--write-envelope` (default off) so
+ * ad-hoc CLI invocations don't silently mutate the user's session
+ * directory. peaks-code's RD dispatch hook flips the flag on.
+ *
+ * On no-session-binding, we surface a `warning` field instead of
+ * throwing — the upstream result is still printed so the caller
+ * always sees the affected list.
+ */
+async function runCodegraphAffectedCommand(io, files, options, asJson) {
+    // Capture stdout so we can re-emit it into the envelope payload.
+    // We still forward every line to the original `io.stdout` so the
+    // user sees the affected list as if the wrapper were transparent.
+    const capturedLines = [];
+    const captureIo = {
+        stdout: (chunk) => {
+            capturedLines.push(chunk);
+            io.stdout(chunk);
+        },
+        stderr: (chunk) => io.stderr(chunk)
+    };
+    await runCodegraphCommand(captureIo, 'codegraph.affected', {
+        subcommand: 'affected',
+        project: options.project,
+        files,
+        ...(options.json === true ? { json: true } : {})
+    }, asJson);
+    if (!options.writeEnvelope) {
+        return;
+    }
+    // The user opted in via --write-envelope. Run the envelope writer
+    // unconditionally (graceful fallback when no session binding).
+    const envelope = writeCodegraphAffectedContext({
+        projectRoot: resolve(options.project),
+        rid: options.rid ?? process.env.PEAKS_RD_RID ?? 'unknown-rid',
+        files,
+        affectedPayload: resolveAffectedPayload(options.json, capturedLines.join('\n'))
+    });
+    reportAffectedEnvelope(io, envelope, asJson);
+}
+export function registerCodegraphIndexCommands(codegraph, io) {
+    addProjectOption(codegraph
+        .command('index')
+        .description('Index a project with codegraph')
+        .option('--force', 'force reindexing')
+        .option('--quiet', 'reduce upstream output')).action(async (options) => {
+        // `runCodegraphCommand` returns "upstream failed" for the one caller
+        // that ranks exit-code precedence (`status`); every other command just
+        // awaits it, so it is discarded here rather than leaked to commander.
+        await runCodegraphCommand(io, 'codegraph.index', {
+            subcommand: 'index',
+            project: options.project,
+            ...(options.force === true ? { force: true } : {}),
+            ...(options.quiet === true ? { quiet: true } : {})
+        }, options.peaksJson);
+    });
+    addProjectOption(codegraph
+        .command('query')
+        .description('Query codegraph')
+        .argument('<search>', 'search text')
+        .option('--json', 'forward JSON output flag to upstream codegraph')
+        .option('--limit <n>', 'maximum result count', parsePositiveInteger)).action(async (search, options) => {
+        await runCodegraphCommand(io, 'codegraph.query', {
+            subcommand: 'query',
+            project: options.project,
+            search,
+            ...(options.json === true ? { json: true } : {}),
+            ...(options.limit !== undefined ? { limit: options.limit } : {})
+        }, options.peaksJson);
+    });
+}
+export function registerCodegraphFileCommands(codegraph, io) {
+    addProjectOption(codegraph
+        .command('files')
+        .description('List codegraph files')
+        .option('--json', 'forward JSON output flag to upstream codegraph')
+        .option('--max-depth <n>', 'maximum traversal depth', parsePositiveInteger)).action(async (options) => {
+        await runCodegraphCommand(io, 'codegraph.files', {
+            subcommand: 'files',
+            project: options.project,
+            ...(options.json === true ? { json: true } : {}),
+            ...(options.maxDepth !== undefined ? { maxDepth: options.maxDepth } : {})
+        }, options.peaksJson);
+    });
+    addProjectOption(codegraph
+        .command('context')
+        .description('Build task context with codegraph')
+        .argument('<task>', 'task text')).action(async (task, options) => {
+        await runCodegraphCommand(io, 'codegraph.context', { subcommand: 'context', project: options.project, task }, options.peaksJson);
+    });
+}
+export function registerCodegraphAffectedCommand(codegraph, io) {
+    addProjectOption(codegraph
+        .command('affected')
+        .description('Find code affected by files')
+        .argument('<files...>', 'project-relative file paths')
+        .option('--json', 'forward JSON output flag to upstream codegraph')
+        .option('--rid <rid>', 'request id for the codegraph-context envelope (default: env PEAKS_RD_RID or "unknown-rid")')
+        .option('--write-envelope', 'write codegraph-context.md into the active session')).action((files, options) => runCodegraphAffectedCommand(io, files, options, options.peaksJson));
+}
+/**
+ * The proxy verbs in registration order. `index` / `query` and `files` /
+ * `context` are paired because each pair shares a module-level helper set.
+ */
+export function registerCodegraphProxyCommands(codegraph, io) {
+    registerCodegraphIndexCommands(codegraph, io);
+    registerCodegraphFileCommands(codegraph, io);
+    registerCodegraphAffectedCommand(codegraph, io);
+}

package/dist/cli/commands/codegraph-repair-commands.d.ts

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

package/dist/cli/commands/codegraph-repair-commands.js

@@ -0,0 +1,94 @@
+// src/cli/commands/codegraph-repair-commands.ts
+//
+// `peaks codegraph repair-exclude` and `peaks codegraph repair-index` — the
+// explicit repair path, plus the registration of both verbs. Split out of
+// `codegraph-commands.ts`; names, options and envelopes are unchanged.
+import { repairCodegraphExcludeFromProject } from '../../services/codegraph/codegraph-exclude-repair.js';
+import { resolveProjectRoot } from '../../services/codegraph/codegraph-service.js';
+import { ok } from 'peaks-loop-shared/result';
+import { printResult } from '../cli-helpers.js';
+import { printCodegraphFailure } from './codegraph-command-runtime.js';
+import { addProjectOption } from './codegraph-command-options.js';
+const REPAIR_MODES = {
+    exclude: {
+        commandId: 'codegraph.repair-exclude',
+        reindex: true,
+        noopNote: 'Nothing to repair in the codegraph config; nothing was written.'
+    },
+    index: {
+        commandId: 'codegraph.repair-index',
+        // 'force' is upstream's `clear()` + full re-index — the only documented
+        // way to drop rows for files deleted in an earlier commit.
+        reindex: 'force',
+        noopNote: 'The codegraph config already admits every supported tracked file and blocks none; the index was still rebuilt from scratch.'
+    }
+};
+// One sentence, the same shape in both modes, because both modes run the
+// same repair — only the rebuild differs.
+//
+// The include clause this sentence used to carry is gone with the include
+// axis (see `codegraph-exclude-repair.ts`), which also removed the reason the
+// sentence was once split in two: there is a single axis left, and its own
+// counter cannot be read as a verdict on another one.
+function appliedRepairNote(report) {
+    return (`Removed ${report.rulesRemoved.length} exclude rule(s), recovering ${report.filesRecovered} tracked source file(s) that a rule had been hiding.` +
+        ` Config backed up to ${report.backupPath ?? ''}.`);
+}
+/**
+ * Explicit repair path: reconcile the config's `exclude` rules → back it up →
+ * rewrite it → rebuild the index. Mirrors the automatic step `init` runs
+ * after a fresh upstream init, for workspaces that were already
+ * initialized before the integrity gate existed.
+ */
+async function runCodegraphRepairCommand(io, options, asJson, mode) {
+    const spec = REPAIR_MODES[mode];
+    let projectRoot;
+    try {
+        // `resolveProjectRoot`, not a hand-rolled `resolve` + `statSync`: it is
+        // the canonicalizer every codegraph invocation already goes through
+        // (`createCodegraphInvocation`), so the config path this verb reports
+        // and writes names the SAME directory the spawn and the other verbs use
+        // even when `--project` is a symlink, a short name or a differently
+        // cased alias. The error path is unchanged.
+        projectRoot = resolveProjectRoot(options.project);
+    }
+    catch (error) {
+        printCodegraphFailure(io, spec.commandId, error, asJson);
+        return;
+    }
+    const report = await repairCodegraphExcludeFromProject(projectRoot, undefined, {
+        reindex: spec.reindex
+    });
+    // Where the notes go matters: `printResult` renders every `warnings`
+    // entry to stderr with a `warning: ` prefix, so a confirmation parked
+    // in the third slot reads as a problem — and a real warning parked
+    // there double-prefixes. Confirmations go to `nextActions`; only a
+    // genuine `report.warning` reaches `warnings`, verbatim.
+    const confirmations = [report.applied ? appliedRepairNote(report) : spec.noopNote];
+    if (report.applied || mode === 'index') {
+        confirmations.push('Re-run `peaks codegraph status --project <root>` to confirm the gap is closed.');
+    }
+    printResult(io, ok(spec.commandId, {
+        applied: report.applied,
+        rulesRemoved: report.rulesRemoved,
+        filesRecovered: report.filesRecovered,
+        configPath: report.configPath,
+        backupPath: report.backupPath,
+        reindexed: report.reindexed,
+        forcedRebuild: report.forcedRebuild,
+        warning: report.warning
+    }, report.warning === null ? [] : [report.warning], confirmations), asJson);
+    // A repair that could not run to completion (or could not reindex)
+    // must not report success to a shell.
+    if (report.warning !== null) {
+        process.exitCode = 1;
+    }
+}
+export function registerCodegraphRepairCommands(codegraph, io) {
+    addProjectOption(codegraph
+        .command('repair-exclude')
+        .description('Drop config exclude rules that block tracked source files, then rebuild the index')).action((options) => runCodegraphRepairCommand(io, options, options.peaksJson, 'exclude'));
+    addProjectOption(codegraph
+        .command('repair-index')
+        .description('Drop config exclude rules that block tracked source files, then rebuild the index from scratch (drops rows for deleted files)')).action((options) => runCodegraphRepairCommand(io, options, options.peaksJson, 'index'));
+}

package/dist/cli/commands/codegraph-status-command.d.ts

@@ -1,5 +1,5 @@
-import { type ProgramIO } from '../cli-helpers.js';
 import { type CommonCodegraphOptions } from './codegraph-command-runtime.js';
+import type { ProgramIO } from '../cli-helpers.js';
 export declare function attributeUpstreamUpToDateLine(stdout: string): string;
 /**
  * `peaks codegraph status` with an integrity gate.