peaks-loop 4.0.53 → 4.1.0

package/dist/services/codegraph/codegraph-autorefresh.js

@@ -55,7 +55,7 @@
 // build), not `init`.
 import { existsSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-import { CODEGRAPH_DIR_NAME, CODEGRAPH_MARKER_NAME, createCodegraphInvocation, executeCodegraphInvocation, isCodegraphInitialized, } from './codegraph-service.js';
+import { CODEGRAPH_DIR_NAME, CODEGRAPH_MARKER_NAME, createCodegraphInvocation, executeCodegraphInvocation, isCodegraphInitialized } from './codegraph-service.js';
 import { repairCodegraphExcludeFromProject } from './codegraph-exclude-repair.js';
 /**
  * The operator-facing line for a refresh that did not happen, or `null` when
@@ -115,6 +115,50 @@ function firstMeaningfulLine(text) {
     const first = trimmed.split(/\r?\n/)[0];
     return first !== undefined ? first.slice(0, 200) : 'no upstream output';
 }
+/**
+ * Self-heal a `.codegraph/` dir that exists without a `codegraph.db`
+ * (extracted verbatim from `refreshCodegraphAfterSlice` to clear the
+ * `max-lines-per-function` arm; behavior unchanged). Returns a terminal
+ * result when the refresh must stop, `null` when the caller may proceed
+ * to the index step.
+ */
+async function selfHealUninitializedCodegraph(projectRoot, runner) {
+    // A `.codegraph/` dir without a `codegraph.db` is uninitialized:
+    //   - NOT peaks-loop-managed → foreign schema, never touch it.
+    //   - peaks-loop-managed → the dangling state left by the pre-fix
+    //     rid-CG-001 auto-stake (marker stamped, no upstream init). Run
+    //     init (fast, offline-safe — no full index) so the subsequent
+    //     index has a schema to write into.
+    if (!isCodegraphInitialized(projectRoot)) {
+        if (!isCodegraphPeaksLoopManaged(projectRoot)) {
+            return {
+                refreshed: false,
+                reason: 'no-codegraph-dir',
+                note: `auto codegraph refresh skipped: ${CODEGRAPH_DIR_NAME}/ exists without a codegraph.db and is not peaks-loop-managed. Run \`peaks codegraph init\` once to enable post-slice auto-refresh.`
+            };
+        }
+        const initResult = await executeCodegraphInvocation(createCodegraphInvocation({ subcommand: 'init', project: projectRoot }), runner);
+        if (initResult.exitCode !== 0) {
+            return {
+                refreshed: false,
+                reason: 'index-failed',
+                note: `auto codegraph refresh self-heal init failed (exit ${String(initResult.exitCode)}): ${firstMeaningfulLine(initResult.stderr || initResult.stdout)}. ${REFRESH_REMEDY}`
+            };
+        }
+        // That init just wrote upstream's 99-rule default `exclude`
+        // template, some of which block tracked source files — the same
+        // self-heal the CLI's `peaks codegraph init` performs, via the
+        // same shared helper. Skipped, this path would stamp the
+        // peaks-loop marker over an incomplete index that no later
+        // `init` (it would no-op) could ever repair.
+        //
+        // Never throws (the helper catches everything), and
+        // `reindex: false` because the index call below covers the
+        // recovered files.
+        await repairCodegraphExcludeFromProject(projectRoot, runner, { reindex: false });
+    }
+    return null;
+}
 /**
  * Run a best-effort `codegraph index` refresh for `projectRoot` after a
  * slice-complete boundary. NEVER throws — every failure path returns a
@@ -128,51 +172,24 @@ export async function refreshCodegraphAfterSlice(projectRoot, runner) {
         return {
             refreshed: false,
             reason: 'no-codegraph-dir',
-            note: `auto codegraph refresh skipped: no ${CODEGRAPH_DIR_NAME} directory at ${join(projectRoot, CODEGRAPH_DIR_NAME)}. Run \`peaks codegraph init\` once to enable post-slice auto-refresh.`,
+            note: `auto codegraph refresh skipped: no ${CODEGRAPH_DIR_NAME} directory at ${join(projectRoot, CODEGRAPH_DIR_NAME)}. Run \`peaks codegraph init\` once to enable post-slice auto-refresh.`
         };
     }
     try {
-        // A `.codegraph/` dir without a `codegraph.db` is uninitialized:
-        //   - NOT peaks-loop-managed → foreign schema, never touch it.
-        //   - peaks-loop-managed → the dangling state left by the pre-fix
-        //     rid-CG-001 auto-stake (marker stamped, no upstream init). Run
-        //     init (fast, offline-safe — no full index) so the subsequent
-        //     index has a schema to write into.
-        if (!isCodegraphInitialized(projectRoot)) {
-            if (!isCodegraphPeaksLoopManaged(projectRoot)) {
-                return {
-                    refreshed: false,
-                    reason: 'no-codegraph-dir',
-                    note: `auto codegraph refresh skipped: ${CODEGRAPH_DIR_NAME}/ exists without a codegraph.db and is not peaks-loop-managed. Run \`peaks codegraph init\` once to enable post-slice auto-refresh.`,
-                };
-            }
-            const initResult = await executeCodegraphInvocation(createCodegraphInvocation({ subcommand: 'init', project: projectRoot }), runner);
-            if (initResult.exitCode !== 0) {
-                return {
-                    refreshed: false,
-                    reason: 'index-failed',
-                    note: `auto codegraph refresh self-heal init failed (exit ${String(initResult.exitCode)}): ${firstMeaningfulLine(initResult.stderr || initResult.stdout)}. ${REFRESH_REMEDY}`,
-                };
-            }
-            // That init just wrote upstream's 99-rule default `exclude`
-            // template, some of which block tracked source files — the same
-            // self-heal the CLI's `peaks codegraph init` performs, via the
-            // same shared helper. Skipped, this path would stamp the
-            // peaks-loop marker over an incomplete index that no later
-            // `init` (it would no-op) could ever repair.
-            //
-            // Never throws (the helper catches everything), and
-            // `reindex: false` because the index call below covers the
-            // recovered files.
-            await repairCodegraphExcludeFromProject(projectRoot, runner, { reindex: false });
-        }
-        const invocation = createCodegraphInvocation({ subcommand: 'index', project: projectRoot, quiet: true });
+        const selfHeal = await selfHealUninitializedCodegraph(projectRoot, runner);
+        if (selfHeal !== null)
+            return selfHeal;
+        const invocation = createCodegraphInvocation({
+            subcommand: 'index',
+            project: projectRoot,
+            quiet: true
+        });
         const result = await executeCodegraphInvocation(invocation, runner);
         if (result.exitCode !== 0) {
             return {
                 refreshed: false,
                 reason: 'index-failed',
-                note: `auto codegraph refresh failed (exit ${String(result.exitCode)}): ${firstMeaningfulLine(result.stderr || result.stdout)}. ${REFRESH_REMEDY}`,
+                note: `auto codegraph refresh failed (exit ${String(result.exitCode)}): ${firstMeaningfulLine(result.stderr || result.stdout)}. ${REFRESH_REMEDY}`
             };
         }
         return { refreshed: true };
@@ -181,7 +198,7 @@ export async function refreshCodegraphAfterSlice(projectRoot, runner) {
         return {
             refreshed: false,
             reason: 'unavailable',
-            note: `auto codegraph refresh unavailable: ${errorMessage(error)}. ${REFRESH_REMEDY}`,
+            note: `auto codegraph refresh unavailable: ${errorMessage(error)}. ${REFRESH_REMEDY}`
         };
     }
 }

package/dist/services/codegraph/codegraph-config-repair-writer.d.ts

@@ -86,3 +86,47 @@ export type CodegraphConfigRepairOutcome = {
  * anything is written, so a throw can never half-apply.
  */
 export declare function applyCodegraphConfigRepair(projectRoot: string, repair: CodegraphConfigRepairPlan): CodegraphConfigRepairOutcome;
+export type CodegraphConfigRollbackResult = {
+    readonly rolledBack: true;
+    readonly configPath: string;
+    readonly backupPath: string;
+} | {
+    readonly rolledBack: false;
+    readonly configPath: string;
+    readonly backupPath: string;
+    /** Why the rollback did not happen. Never `null` on this arm. */
+    readonly error: string;
+};
+/**
+ * Put `configPath` back to the bytes `writeConfigBackup` saved beside it, and
+ * back to the mode those bytes were saved with.
+ *
+ * This is the reverse of `applyCodegraphConfigRepair`'s write half and the only
+ * reason the `.bak` exists: until this function, the backup had no reader
+ * anywhere in the repository, so "byte-exact rollback" described a file nobody
+ * ever restored.
+ *
+ * The guard is `linkOrDirectoryAt` — the SAME predicate that refuses to WRITE
+ * through a link at the backup path refuses to READ through one here. The
+ * attack it closes is the mirror image of the writer's: `config.json.bak` is
+ * fixed and committable, so a repository that ships it as a link would
+ * otherwise have the link's target's bytes published into `.codegraph/config.json`
+ * as if they were the pre-repair config — attacker-chosen content, written
+ * under the operator's own config path, from a file the operator never
+ * reviewed. A refusal is a refusal and not a repair, at both ends.
+ *
+ * The restore runs through `writeConfigAtomic` (same-directory CSPRNG temp +
+ * `renameSync`) for the same reason the backup write does: a crash mid-write
+ * must leave the repaired config intact rather than a prefix of the restored
+ * one, and the mode is applied to the TEMP before the rename so the published
+ * file never exists at the process umask. The mode comes from `statSync` of the
+ * backup, symmetrical with the write end: the copy carries the original
+ * config's mode, so handing that mode back to the config restores what the
+ * project had granted rather than this process's umask.
+ *
+ * A refusal, or a backup that cannot be read, is RETURNED rather than thrown:
+ * the caller reports it as a field and must keep going — the forced rebuild it
+ * was asked for still has to run. `writeConfigAtomic`'s own fs throw is left to
+ * propagate, and the caller catches that too.
+ */
+export declare function rollbackCodegraphConfig(configPath: string): Promise<CodegraphConfigRollbackResult>;

package/dist/services/codegraph/codegraph-config-repair-writer.js

@@ -3,7 +3,10 @@
 // The pure repair plans (`repairCodegraphExclude` for the exclude axis,
 // `repairCodegraphInclude` for the include axis) and the writer that applies
 // them to `<projectRoot>/.codegraph/config.json` in ONE atomic rewrite, plus
-// the byte-exact `config.json.bak` copy it keeps for rollback.
+// the byte-exact `config.json.bak` copy it keeps for rollback and
+// `rollbackCodegraphConfig`, that copy's reader (slice A1 of
+// `2026-09-17-session-607ead`: the reverse write, so the rollback the `.bak`
+// has always promised is reachable).
 //
 // Extracted verbatim from `codegraph-exclude-repair.ts` (rid
 // 2026-09-17-oversize-followup, G1 — the 800-line file-size cap). Every moved
@@ -142,6 +145,40 @@ function writeConfigAtomic(filePath, content, mode) {
         throw error;
     }
 }
+/**
+ * The shared shape of the two refusals this module makes at the FIXED,
+ * therefore guessable, `config.json.bak` path: a symbolic link (bytes land in
+ * whatever it points at), a directory (there is nowhere for them to land), or
+ * a hard link (`nlink > 1` — another name shares this inode). Returns `null`
+ * when the path is absent or is a plain regular file, the only two states both
+ * ends of the rollback contract may act on.
+ *
+ * ONE predicate, two callers, and that is the point: `writeConfigBackup`
+ * WRITES this copy and `rollbackCodegraphConfig` READS it back. A guard that
+ * drifted between the two would leave the rollback trusting a path the writer
+ * would have refused, so the refusal is the same at both ends because the
+ * trust premise is the same at both ends.
+ *
+ * `lstat`, never `stat`: `stat` follows a link and reports the victim's
+ * regular-file type, which is exactly the case both callers must refuse.
+ */
+function linkOrDirectoryAt(path) {
+    const existing = lstatSync(path, { throwIfNoEntry: false });
+    if (existing === undefined ||
+        (!existing.isSymbolicLink() && !existing.isDirectory() && existing.nlink <= 1)) {
+        return null;
+    }
+    return {
+        // "through" for a link (the bytes land in whatever it points at), "at" for
+        // a directory (there is nowhere for them to land).
+        preposition: existing.isDirectory() ? 'at' : 'through',
+        kind: existing.isSymbolicLink()
+            ? 'a symbolic link'
+            : existing.isDirectory()
+                ? 'a directory'
+                : `a hard link (link count ${String(existing.nlink)})`
+    };
+}
 /**
  * Copy the config's ORIGINAL bytes to `config.json.bak`, refusing to write
  * through a link that already occupies that path.
@@ -207,18 +244,9 @@ function writeConfigAtomic(filePath, content, mode) {
  */
 function writeConfigBackup(configPath, originalText) {
     const backupPath = `${configPath}${CODEGRAPH_CONFIG_BACKUP_SUFFIX}`;
-    const existing = lstatSync(backupPath, { throwIfNoEntry: false });
-    if (existing !== undefined &&
-        (existing.isSymbolicLink() || existing.isDirectory() || existing.nlink > 1)) {
-        const kind = existing.isSymbolicLink()
-            ? 'a symbolic link'
-            : existing.isDirectory()
-                ? 'a directory'
-                : `a hard link (link count ${String(existing.nlink)})`;
-        // "through" for a link (the bytes land in whatever it points at), "at" for
-        // a directory (there is nowhere for them to land).
-        const preposition = existing.isDirectory() ? 'at' : 'through';
-        throw new Error(`codegraph config backup ${backupPath}: refusing to write ${preposition} ${kind} occupying ` +
+    const occupied = linkOrDirectoryAt(backupPath);
+    if (occupied !== null) {
+        throw new Error(`codegraph config backup ${backupPath}: refusing to write ${occupied.preposition} ${occupied.kind} occupying ` +
             'this path. Another file or directory shares it, so a backup written here would overwrite ' +
             'that. Remove it (or point `peaks` at a project root whose `.codegraph/` it owns) and re-run.');
     }
@@ -286,7 +314,10 @@ export function applyCodegraphConfigRepair(projectRoot, repair) {
     // is how a wrong `include` would survive a repair that reported success.
     const include = record.include === undefined ? [] : assertStringArray(record.include, 'include', configPath);
     const excludePlan = repairCodegraphExclude({ exclude, rulesToRemove: repair.rulesToRemove });
-    const includePlan = repairCodegraphInclude({ include, patternsToAdd: repair.includePatternsToAdd });
+    const includePlan = repairCodegraphInclude({
+        include,
+        patternsToAdd: repair.includePatternsToAdd
+    });
     if (!excludePlan.changed && !includePlan.changed) {
         return {
             applied: false,
@@ -320,3 +351,74 @@ export function applyCodegraphConfigRepair(projectRoot, repair) {
         includeCountAfter: includePlan.include.length
     };
 }
+// ─────────────────────────────────────────────────────────────────────
+// Rollback — the read side of the `.bak`
+// ─────────────────────────────────────────────────────────────────────
+/** Local, because this module must not import `codegraph-exclude-repair.ts`. */
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Put `configPath` back to the bytes `writeConfigBackup` saved beside it, and
+ * back to the mode those bytes were saved with.
+ *
+ * This is the reverse of `applyCodegraphConfigRepair`'s write half and the only
+ * reason the `.bak` exists: until this function, the backup had no reader
+ * anywhere in the repository, so "byte-exact rollback" described a file nobody
+ * ever restored.
+ *
+ * The guard is `linkOrDirectoryAt` — the SAME predicate that refuses to WRITE
+ * through a link at the backup path refuses to READ through one here. The
+ * attack it closes is the mirror image of the writer's: `config.json.bak` is
+ * fixed and committable, so a repository that ships it as a link would
+ * otherwise have the link's target's bytes published into `.codegraph/config.json`
+ * as if they were the pre-repair config — attacker-chosen content, written
+ * under the operator's own config path, from a file the operator never
+ * reviewed. A refusal is a refusal and not a repair, at both ends.
+ *
+ * The restore runs through `writeConfigAtomic` (same-directory CSPRNG temp +
+ * `renameSync`) for the same reason the backup write does: a crash mid-write
+ * must leave the repaired config intact rather than a prefix of the restored
+ * one, and the mode is applied to the TEMP before the rename so the published
+ * file never exists at the process umask. The mode comes from `statSync` of the
+ * backup, symmetrical with the write end: the copy carries the original
+ * config's mode, so handing that mode back to the config restores what the
+ * project had granted rather than this process's umask.
+ *
+ * A refusal, or a backup that cannot be read, is RETURNED rather than thrown:
+ * the caller reports it as a field and must keep going — the forced rebuild it
+ * was asked for still has to run. `writeConfigAtomic`'s own fs throw is left to
+ * propagate, and the caller catches that too.
+ */
+export async function rollbackCodegraphConfig(configPath) {
+    const backupPath = `${configPath}${CODEGRAPH_CONFIG_BACKUP_SUFFIX}`;
+    const occupied = linkOrDirectoryAt(backupPath);
+    if (occupied !== null) {
+        return {
+            rolledBack: false,
+            configPath,
+            backupPath,
+            error: `codegraph config rollback ${backupPath}: refusing to restore ${occupied.preposition} ${occupied.kind} occupying ` +
+                'this path. A backup this writer did not create is not a rollback point, and restoring through it ' +
+                'would publish bytes nobody reviewed. Restore it by hand and re-run.'
+        };
+    }
+    let originalText;
+    let originalMode;
+    try {
+        originalText = readFileSync(backupPath, 'utf8');
+        // `& 0o777` drops the file-type bits `statSync` packs above the permission
+        // bits — `chmod` takes permission bits only.
+        originalMode = statSync(backupPath).mode & 0o777;
+    }
+    catch (error) {
+        return {
+            rolledBack: false,
+            configPath,
+            backupPath,
+            error: `codegraph config rollback: cannot read ${backupPath}: ${errorMessage(error)}`
+        };
+    }
+    writeConfigAtomic(configPath, originalText, originalMode);
+    return { rolledBack: true, configPath, backupPath };
+}

package/dist/services/codegraph/codegraph-exclude-integrity.js

@@ -84,7 +84,10 @@ export function inspectCodegraphExcludeIntegrity(projectRoot, inputs = {}) {
         excludedTrackedCount: result.excludedTrackedCount,
         violations: result.violations,
         rulesToRemove: result.rulesToRemove,
-        ruleImpacts: result.rulesToRemove.map((rule) => ({ rule, blockedCount: blockedCounts.get(rule) ?? 0 }))
+        ruleImpacts: result.rulesToRemove.map((rule) => ({
+            rule,
+            blockedCount: blockedCounts.get(rule) ?? 0
+        }))
     };
 }
 /**

package/dist/services/codegraph/codegraph-exclude-repair.d.ts

@@ -64,7 +64,15 @@ export type CodegraphExcludeRepairReport = {
      * AND the reads failed (there is no config to name).
      */
     readonly configPath: string;
-    /** Byte-exact rollback copy (null when nothing was written). */
+    /**
+     * Byte-exact rollback copy (null when nothing was written).
+     *
+     * It is a rollback POINT, not a rollback: nothing in this seam reads it back.
+     * Putting the config back is the separate, explicit
+     * `peaks codegraph config-restore` verb, so this field is what that verb
+     * would read — and its presence is the one guarantee that a restore is
+     * possible at all.
+     */
     readonly backupPath: string | null;
     /** True when the post-repair `codegraph index` finished successfully. */
     readonly reindexed: boolean;
@@ -127,6 +135,20 @@ export type CodegraphExcludeRepairOptions = {
      * C) exists so that upgrading peaks-loop cannot change a downstream
      * project's cost profile, and purging dead rows is the caller's explicit
      * request instead.
+     *
+     * `'force'` changes ONLY the rebuild, never the config: it is the same
+     * two-axis repair as `'exclude'`, followed by `cg.clear()` + `indexAll()`
+     * instead of an incremental index. The config repair STAYS — that is what
+     * makes the force mode worth its cost, because `include` has to be widened
+     * before a rebuild can admit the files the config was dropping.
+     *
+     * Not a self-cancelling run, and that is a design decision rather than a
+     * detail: a mode that wrote the repair and then restored the pre-repair bytes
+     * would leave the config exactly as it found it, `peaks codegraph status`
+     * would still report the gap, and exit 75 would never clear. Putting the
+     * config BACK is the explicit `peaks codegraph config-restore` verb, which
+     * reads the `.bak` this run leaves — an operator decision, not a side effect
+     * of asking for a rebuild.
      */
     readonly reindex?: boolean | 'force';
 };

package/dist/services/codegraph/codegraph-exclude-repair.js

@@ -64,6 +64,12 @@
 //     consumer project (`config.json.bak` matches neither the peaks-loop
 //     snippet nor upstream's own `.codegraph/.gitignore`), so both files
 //     are committable.
+//   - `rollbackCodegraphConfig` is that copy's READER, and it is reached by the
+//     EXPLICIT `peaks codegraph config-restore` verb — never from here. A
+//     repair must not undo itself: this seam's job is to close the gap, so a
+//     run that restored its own write would leave the config exactly as it
+//     found it and `peaks codegraph status` still reporting the gap (exit 75
+//     never clearing). Rolling back is an operator decision, not a step.
 //   - The DIRECTORY both paths live in is contained: `assertCodegraphDirContained`
 //     refuses when `<projectRoot>/.codegraph` resolves (junction or symlink)
 //     outside the canonical project root, so neither the read nor either
@@ -204,8 +210,7 @@ export async function repairCodegraphExcludeFromProject(projectRoot, runner, opt
     // pass runs only on the one run per project that actually widens
     // `include`, where a repair is about to spend seconds rebuilding an index.
     const includeFilesRecovered = includePlan.changed
-        ? includeAdmittedAfter -
-            filterAdmittedTrackedFiles(trackedFiles, config.include).length
+        ? includeAdmittedAfter - filterAdmittedTrackedFiles(trackedFiles, config.include).length
         : 0;
     const nothingToRepair = includePlan.addedPatterns.length === 0 && reconcile.rulesToRemove.length === 0;
     const unchanged = {

package/dist/services/codegraph/codegraph-index-integrity.js

@@ -135,7 +135,7 @@ export const CODEGRAPH_REPAIR_INDEX_COMMAND = 'peaks codegraph repair-index --pr
 export const CODEGRAPH_INDEX_STRICT_ENV_VAR = 'PEAKS_CODEGRAPH_INDEX_STRICT';
 /** True when the project opted in to blocking index-gap verdicts. */
 export function isCodegraphIndexStrictMode(env = process.env) {
-    return env[CODEGRAPH_INDEX_STRICT_ENV_VAR] === '1' || env[CODEGRAPH_INDEX_STRICT_ENV_VAR] === 'true';
+    return (env[CODEGRAPH_INDEX_STRICT_ENV_VAR] === '1' || env[CODEGRAPH_INDEX_STRICT_ENV_VAR] === 'true');
 }
 /**
  * Fold the inspected report (null when there is no index to inspect) and

package/dist/services/codegraph/codegraph-preflight-service.d.ts

@@ -1,30 +1,7 @@
 import { type CodegraphProcessRunner } from './codegraph-service.js';
-export type CodegraphPreflightResult = {
-    available: true;
-    block: string;
-    fileCount: number;
-    truncated: boolean;
-} | {
-    available: false;
-    note: string;
-};
-/** Cap for the directory histogram in the rendered structure block. */
-export declare const CODEGRAPH_STRUCTURE_MAX_DIRS = 40;
-/** Cap for bare root files listed in the rendered structure block. */
-export declare const CODEGRAPH_STRUCTURE_MAX_ROOT_FILES = 12;
-export interface CodegraphStructureFileEntry {
-    readonly path: string;
-}
-export interface CodegraphStructureRenderOptions {
-    readonly maxDirs?: number;
-    readonly maxRootFiles?: number;
-}
-export interface CodegraphStructureSummary {
-    /** Full `## Codegraph structure` markdown block, ending on its own paragraph. */
-    block: string;
-    total: number;
-    truncated: boolean;
-}
+import { type CodegraphPreflightResult, type CodegraphStructureFileEntry, type CodegraphStructureRenderOptions, type CodegraphStructureSummary } from './codegraph-preflight-structure.js';
+export { CODEGRAPH_STRUCTURE_MAX_DIRS, CODEGRAPH_STRUCTURE_MAX_ROOT_FILES } from './codegraph-preflight-structure.js';
+export type { CodegraphPreflightResult, CodegraphStructureFileEntry, CodegraphStructureRenderOptions, CodegraphStructureSummary } from './codegraph-preflight-structure.js';
 /**
  * Pure renderer: turn the codegraph `files --json` payload into a bounded
  * `## Codegraph structure` block. Files are aggregated into a directory

package/dist/services/codegraph/codegraph-preflight-service.js

@@ -31,17 +31,11 @@
 //   - CODEGRAPH_STRUCTURE_MAX_DIRS        = 40  directory rows
 //   - CODEGRAPH_STRUCTURE_MAX_ROOT_FILES  = 12  bare root files
 import { mkdirSync } from 'node:fs';
-import { CODEGRAPH_DIR_NAME, createCodegraphInvocation, defaultCodegraphInitGuard, executeCodegraphInvocation, isCodegraphInitialized, writeCodegraphMarker, } from './codegraph-service.js';
+import { CODEGRAPH_DIR_NAME, createCodegraphInvocation, defaultCodegraphInitGuard, executeCodegraphInvocation, isCodegraphInitialized, writeCodegraphMarker } from './codegraph-service.js';
 import { defaultCodegraphProcessRunner } from './codegraph-process-runner.js';
 import { repairCodegraphExcludeFromProject } from './codegraph-exclude-repair.js';
-/** Cap for the directory histogram in the rendered structure block. */
-export const CODEGRAPH_STRUCTURE_MAX_DIRS = 40;
-/** Cap for bare root files listed in the rendered structure block. */
-export const CODEGRAPH_STRUCTURE_MAX_ROOT_FILES = 12;
-/** Strip a leading `./` (upstream codegraph paths may carry it). */
-function normalizeCodegraphPath(path) {
-    return path.startsWith('./') ? path.slice(2) : path;
-}
+import { CODEGRAPH_STRUCTURE_MAX_DIRS, CODEGRAPH_STRUCTURE_MAX_ROOT_FILES, normalizeCodegraphPath, parseFilesPayload } from './codegraph-preflight-structure.js';
+export { CODEGRAPH_STRUCTURE_MAX_DIRS, CODEGRAPH_STRUCTURE_MAX_ROOT_FILES } from './codegraph-preflight-structure.js';
 /**
  * Pure renderer: turn the codegraph `files --json` payload into a bounded
  * `## Codegraph structure` block. Files are aggregated into a directory
@@ -69,8 +63,7 @@ export function renderCodegraphStructureBlock(files, options = {}) {
         const dir = raw.slice(0, slash);
         dirCounts.set(dir, (dirCounts.get(dir) ?? 0) + 1);
     }
-    const sortedDirs = [...dirCounts.entries()]
-        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+    const sortedDirs = [...dirCounts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
     const shownDirs = sortedDirs.slice(0, maxDirs);
     const truncatedDirs = sortedDirs.length > maxDirs;
     const sortedRoot = [...rootFiles].sort((a, b) => a.localeCompare(b));
@@ -102,28 +95,14 @@ function firstMeaningfulLine(text) {
     const first = trimmed.split(/\r?\n/)[0];
     return first !== undefined ? first.slice(0, 200) : 'no upstream output';
 }
-function parseFilesPayload(stdout) {
-    try {
-        const parsed = JSON.parse(stdout);
-        if (Array.isArray(parsed)) {
-            const entries = parsed
-                .filter((entry) => typeof entry === 'object' && entry !== null && 'path' in entry)
-                .map((entry) => ({ path: typeof entry.path === 'string' ? entry.path : '' }))
-                .filter((entry) => entry.path.length > 0);
-            return { ok: true, entries };
-        }
-        // JSON but not an array — not the shape we expect.
-        return { ok: false, entries: [] };
-    }
-    catch {
-        // Not JSON at all — e.g. the upstream text path ("No files indexed…").
-        return { ok: false, entries: [] };
-    }
-}
 async function readStructure(projectRoot, runner) {
     let result;
     try {
-        const invocation = createCodegraphInvocation({ subcommand: 'files', project: projectRoot, json: true });
+        const invocation = createCodegraphInvocation({
+            subcommand: 'files',
+            project: projectRoot,
+            json: true
+        });
         result = await executeCodegraphInvocation(invocation, runner);
     }
     catch (error) {
@@ -132,20 +111,20 @@ async function readStructure(projectRoot, runner) {
     if (result.exitCode !== 0) {
         return {
             available: false,
-            note: `codegraph files failed (exit ${String(result.exitCode)}): ${firstMeaningfulLine(result.stderr || result.stdout)}`,
+            note: `codegraph files failed (exit ${String(result.exitCode)}): ${firstMeaningfulLine(result.stderr || result.stdout)}`
         };
     }
     const { ok, entries } = parseFilesPayload(result.stdout);
     if (!ok) {
         return {
             available: false,
-            note: 'codegraph files returned no parseable structure — run `peaks codegraph index` before dispatch for symbol-accurate structure.',
+            note: 'codegraph files returned no parseable structure — run `peaks codegraph index` before dispatch for symbol-accurate structure.'
         };
     }
     if (entries.length === 0) {
         return {
             available: false,
-            note: 'codegraph index has no files — run `peaks codegraph index` before dispatch for symbol-accurate structure.',
+            note: 'codegraph index has no files — run `peaks codegraph index` before dispatch for symbol-accurate structure.'
         };
     }
     const summary = renderCodegraphStructureBlock(entries);
@@ -153,7 +132,7 @@ async function readStructure(projectRoot, runner) {
         available: true,
         block: summary.block,
         fileCount: summary.total,
-        truncated: summary.truncated,
+        truncated: summary.truncated
     };
 }
 /**
@@ -181,7 +160,7 @@ export async function buildCodegraphPreflightBlock(projectRoot, runner) {
     if (guard.status === 'conflict-foreign-schema') {
         return {
             available: false,
-            note: `codegraph unavailable: ${CODEGRAPH_DIR_NAME}/ exists with a non-peaks-loop schema and was not touched. Move or rename the foreign directory, then re-run \`peaks codegraph init\` to enable pre-dispatch structure reads.`,
+            note: `codegraph unavailable: ${CODEGRAPH_DIR_NAME}/ exists with a non-peaks-loop schema and was not touched. Move or rename the foreign directory, then re-run \`peaks codegraph init\` to enable pre-dispatch structure reads.`
         };
     }
     // 'fresh' (no dir) OR a dangling peaks-loop dir (marker present, no
@@ -196,7 +175,7 @@ export async function buildCodegraphPreflightBlock(projectRoot, runner) {
             if (initResult.exitCode !== 0) {
                 return {
                     available: false,
-                    note: `codegraph init failed (exit ${String(initResult.exitCode)}): ${firstMeaningfulLine(initResult.stderr || initResult.stdout)}`,
+                    note: `codegraph init failed (exit ${String(initResult.exitCode)}): ${firstMeaningfulLine(initResult.stderr || initResult.stdout)}`
                 };
             }
             try {
@@ -230,7 +209,7 @@ export async function buildCodegraphPreflightBlock(projectRoot, runner) {
             if (indexResult.exitCode !== 0) {
                 return {
                     available: false,
-                    note: `codegraph index failed (exit ${String(indexResult.exitCode)}): ${firstMeaningfulLine(indexResult.stderr || indexResult.stdout)}`,
+                    note: `codegraph index failed (exit ${String(indexResult.exitCode)}): ${firstMeaningfulLine(indexResult.stderr || indexResult.stdout)}`
                 };
             }
         }

package/dist/services/codegraph/codegraph-preflight-structure.d.ts

@@ -0,0 +1,32 @@
+export type CodegraphPreflightResult = {
+    available: true;
+    block: string;
+    fileCount: number;
+    truncated: boolean;
+} | {
+    available: false;
+    note: string;
+};
+/** Cap for the directory histogram in the rendered structure block. */
+export declare const CODEGRAPH_STRUCTURE_MAX_DIRS = 40;
+/** Cap for bare root files listed in the rendered structure block. */
+export declare const CODEGRAPH_STRUCTURE_MAX_ROOT_FILES = 12;
+export interface CodegraphStructureFileEntry {
+    readonly path: string;
+}
+export interface CodegraphStructureRenderOptions {
+    readonly maxDirs?: number;
+    readonly maxRootFiles?: number;
+}
+export interface CodegraphStructureSummary {
+    /** Full `## Codegraph structure` markdown block, ending on its own paragraph. */
+    block: string;
+    total: number;
+    truncated: boolean;
+}
+/** Strip a leading `./` (upstream codegraph paths may carry it). */
+export declare function normalizeCodegraphPath(path: string): string;
+export declare function parseFilesPayload(stdout: string): {
+    ok: boolean;
+    entries: CodegraphStructureFileEntry[];
+};

package/dist/services/codegraph/codegraph-preflight-structure.js

@@ -0,0 +1,33 @@
+// src/services/codegraph/codegraph-preflight-structure.ts
+//
+// The declaration + payload-parsing surface of the pre-dispatch codegraph
+// preflight (`codegraph-preflight-service.ts`), extracted so the service
+// module stays under the repo file-size cap. `codegraph-preflight-service.ts`
+// imports these and re-exports the public ones, so importers keep resolving
+// every name from the original path.
+/** Cap for the directory histogram in the rendered structure block. */
+export const CODEGRAPH_STRUCTURE_MAX_DIRS = 40;
+/** Cap for bare root files listed in the rendered structure block. */
+export const CODEGRAPH_STRUCTURE_MAX_ROOT_FILES = 12;
+/** Strip a leading `./` (upstream codegraph paths may carry it). */
+export function normalizeCodegraphPath(path) {
+    return path.startsWith('./') ? path.slice(2) : path;
+}
+export function parseFilesPayload(stdout) {
+    try {
+        const parsed = JSON.parse(stdout);
+        if (Array.isArray(parsed)) {
+            const entries = parsed
+                .filter((entry) => typeof entry === 'object' && entry !== null && 'path' in entry)
+                .map((entry) => ({ path: typeof entry.path === 'string' ? entry.path : '' }))
+                .filter((entry) => entry.path.length > 0);
+            return { ok: true, entries };
+        }
+        // JSON but not an array — not the shape we expect.
+        return { ok: false, entries: [] };
+    }
+    catch {
+        // Not JSON at all — e.g. the upstream text path ("No files indexed…").
+        return { ok: false, entries: [] };
+    }
+}