codebase-snapshot 0.9.9 → 0.9.12

package/dist/{chunk-HQBEQ67K.js → chunk-5OR3WVPW.js}

@@ -1,4 +1,4 @@
-import { GENERATOR_VERSION, MIN_MAX_PART_BYTES, SCHEMA_VERSION, GENERATOR_NAME, ARTIFACT_NAMES, PRESETS, generateSnapshot, validateSnapshot, explainPath, renderExplainText, describeManifestShapeProblem, loadConfigFileDetailed, parseByteSize, resolveConfig } from './chunk-KUVFTJHK.js';
+import { GENERATOR_VERSION, anchorForPath, displayPath, MIN_MAX_PART_BYTES, SCHEMA_VERSION, GENERATOR_NAME, ARTIFACT_NAMES, PRESETS, generateSnapshot, generateInWorker, validateSnapshot, buildImportResolver, resolveSpecifier, truncateToBytes, explainPath, renderExplainText, describeManifestShapeProblem, loadConfigFileDetailed, parseByteSize, resolveConfig } from './chunk-3H45YMBG.js';
 import * as fs from 'fs';
 import * as path2 from 'path';
 
@@ -520,6 +520,8 @@ function createMcpServer(options) {
 // src/mcp/part.ts
 var FILE_HEADING = "### FILE: ";
 var CONTENT_MARKERS = /* @__PURE__ */ new Set(["#### Content", "#### Bounded Preview"]);
+var ANCHOR_LINE = /^<a id="([^"]+)"><\/a>$/;
+var INCLUSION_MODES = /* @__PURE__ */ new Set(["full", "preview", "signatures"]);
 function parsePartSections(partText) {
   const lines = partText.split("\n");
   const sections = [];
@@ -530,16 +532,26 @@ function parsePartSections(partText) {
       continue;
     }
     const heading = lines[index].slice(FILE_HEADING.length);
+    const anchorMatch = index > 0 ? ANCHOR_LINE.exec(lines[index - 1]) : null;
     let cursor = index + 1;
     let inclusion = null;
-    let sha256 = null;
     let includedLines = null;
     while (cursor < lines.length && !CONTENT_MARKERS.has(lines[cursor])) {
       const line = lines[cursor];
       if (line.startsWith(FILE_HEADING)) break;
-      if (line.startsWith("- Inclusion: ")) inclusion = line.slice("- Inclusion: ".length).trim();
-      else if (line.startsWith("- SHA-256: ")) sha256 = line.slice("- SHA-256: ".length).trim();
-      else if (line.startsWith("- Included Lines: ")) {
+      if (line.startsWith("- Meta: ")) {
+        for (const field of line.slice("- Meta: ".length).split("|")) {
+          const value = field.trim();
+          if (INCLUSION_MODES.has(value)) inclusion = value;
+        }
+        const counts = /(-?\d+) of (-?\d+) lines|(\d+) lines/.exec(line);
+        if (counts) {
+          const emitted = counts[1] ?? counts[3];
+          includedLines = Number.isFinite(Number(emitted)) ? Number(emitted) : null;
+        }
+      } else if (line.startsWith("- Inclusion: ")) {
+        inclusion = line.slice("- Inclusion: ".length).trim();
+      } else if (line.startsWith("- Included Lines: ")) {
         const value = Number(line.slice("- Included Lines: ".length).trim());
         includedLines = Number.isFinite(value) ? value : null;
       }
@@ -563,40 +575,42 @@ function parsePartSections(partText) {
       body.push(lines[bodyLine]);
       bodyLine += 1;
     }
-    sections.push({ path: heading, body: body.join("\n"), inclusion, sha256, includedLines });
+    sections.push({ path: heading, anchor: anchorMatch?.[1] ?? null, body: body.join("\n"), inclusion, includedLines });
     index = bodyLine + 1;
   }
   return sections;
 }
-function findSection(sections, relativePath, sha256) {
-  const exact = sections.find((section) => section.path === relativePath);
+function findSection(sections, relativePath) {
+  const anchor = anchorForPath(relativePath);
+  const byAnchor = sections.find((section) => section.anchor === anchor);
+  if (byAnchor) return byAnchor;
+  const rendered = displayPath(relativePath);
+  const samePath = (section) => section.path === relativePath || section.path === rendered;
+  const exact = sections.find(samePath);
   if (exact) return exact;
-  if (sha256) {
-    const byHash = sections.filter((section) => section.sha256 === sha256);
-    if (byHash.length === 1) return byHash[0];
-    if (byHash.length > 1) {
-      const byPath = byHash.find(
-        (section) => section.path.toLowerCase() === relativePath.toLowerCase()
-      );
-      if (byPath) return byPath;
-    }
-  }
-  const folded = sections.filter((section) => section.path.toLowerCase() === relativePath.toLowerCase());
+  const foldedPath = rendered.toLowerCase();
+  const folded = sections.filter((section) => {
+    const path4 = section.path.toLowerCase();
+    return path4 === relativePath.toLowerCase() || path4 === foldedPath;
+  });
   return folded.length === 1 ? folded[0] : null;
 }
 function windowText(body, fromLine, lineCount) {
   const lines = body.split("\n");
-  const total = lines.length;
-  const start = Math.min(Math.max(1, Math.trunc(fromLine)), Math.max(1, total));
+  const total = body.length === 0 ? 0 : lines.length;
+  const requested = Math.max(1, Math.trunc(fromLine));
+  const pastEnd = total > 0 && requested > total;
+  const start = pastEnd ? requested : Math.min(requested, Math.max(1, total));
   const end = Math.min(total, start + Math.max(1, Math.trunc(lineCount)) - 1);
-  const slice = lines.slice(start - 1, end);
+  const slice = pastEnd ? [] : lines.slice(start - 1, Math.max(start - 1, end));
   return {
     text: slice.join("\n"),
     fromLine: start,
     returnedLines: slice.length,
     totalLines: total,
-    truncated: end < total,
-    nextFromLine: end < total ? end + 1 : null
+    truncated: !pastEnd && end < total,
+    nextFromLine: !pastEnd && end < total ? end + 1 : null,
+    pastEnd
   };
 }
 function foldForComparison(value) {
@@ -667,7 +681,7 @@ async function openWorkspace(root, overrides = {}) {
   }
   try {
     const config = resolveConfig(loaded.config, cliOptions, root);
-    return { ok: true, workspace: { root, config, configFile: loaded.file } };
+    return { ok: true, workspace: { root, config, configFile: loaded.file, cliOptions } };
   } catch (error) {
     return { ok: false, message: error instanceof Error ? error.message : String(error) };
   }
@@ -741,6 +755,11 @@ var ROOT_PROPERTY = {
   type: "string",
   description: "Repository root. Defaults to the directory this server was started in."
 };
+var OUT_DIR_PROPERTY = {
+  type: "string",
+  description: "Snapshot directory, relative to the root. Defaults to the project configuration's outDir."
+};
+var outDirOverride = (args) => ({ outDir: args.outDir });
 function failure(message) {
   return { text: message, isError: true };
 }
@@ -781,9 +800,39 @@ function toRelativePath(root, value) {
 }
 function symbolsOf(entry) {
   const summary = entry.summary;
-  if (!summary || typeof summary !== "object" || !("exports" in summary)) return [];
-  const source = summary;
-  return [...source.exports, ...source.reactComponents, ...source.routeHandlers];
+  if (!summary || typeof summary !== "object") return [];
+  const names = [];
+  const collect = (value) => {
+    if (!Array.isArray(value)) return;
+    for (const item of value) {
+      if (typeof item === "string") names.push(item);
+    }
+  };
+  const record = summary;
+  for (const field of [
+    "exports",
+    "reactComponents",
+    "routeHandlers",
+    "functions",
+    "classes",
+    "interfaces",
+    "types",
+    "enums",
+    "hooks",
+    "headings",
+    // The rest of the same records. `variables` is where a `const`, a Python constant, a Go
+    // `var`, a Rust `mod`, a C `#define` and a Terraform `variable` block all land, so leaving it
+    // out made `snapshot_locate` miss most of what a non-JavaScript file declares; `directives`
+    // carries `"use client"`-style markers, and `frontmatterKeys`/`keys` are the headings and
+    // top-level names of a Markdown or JSON file.
+    "variables",
+    "directives",
+    "frontmatterKeys",
+    "keys"
+  ]) {
+    collect(record[field]);
+  }
+  return names;
 }
 async function prepare(args, context, overrides = {}) {
   const rootOutcome = resolveRoot(args.root, context);
@@ -798,7 +847,7 @@ var statusTool = {
   description: "Report whether a snapshot exists for this repository, when it was built, and what it covers. Reads the manifest rather than the repository, so it is cheap. Call it before deciding whether a snapshot needs to be generated.",
   inputSchema: {
     type: "object",
-    properties: { root: ROOT_PROPERTY },
+    properties: { root: ROOT_PROPERTY, outDir: OUT_DIR_PROPERTY },
     additionalProperties: false
   },
   outputSchema: {
@@ -819,7 +868,7 @@ var statusTool = {
   },
   annotations: READ_ONLY,
   async handler(args, context) {
-    const prepared = await prepare(args, context);
+    const prepared = await prepare(args, context, outDirOverride(args));
     if (!prepared.ok) return prepared.outcome;
     const workspace = prepared.workspace;
     const read = readManifest(workspace);
@@ -878,6 +927,7 @@ var planTool = {
     type: "object",
     properties: {
       root: ROOT_PROPERTY,
+      outDir: OUT_DIR_PROPERTY,
       maxPartBytes: {
         type: "string",
         description: 'Byte budget per part, for example 307200 or "300k". Defaults to the project configuration.'
@@ -898,7 +948,7 @@ var planTool = {
   },
   annotations: READ_ONLY,
   async handler(args, context) {
-    const prepared = await prepare(args, context, { maxPartBytes: args.maxPartBytes });
+    const prepared = await prepare(args, context, { maxPartBytes: args.maxPartBytes, outDir: args.outDir });
     if (!prepared.ok) return prepared.outcome;
     const workspace = prepared.workspace;
     let manifest;
@@ -952,13 +1002,10 @@ var generateTool = {
     type: "object",
     properties: {
       root: ROOT_PROPERTY,
+      outDir: OUT_DIR_PROPERTY,
       maxPartBytes: {
         type: "string",
         description: 'Byte budget per part, for example 307200 or "300k". Defaults to the project configuration.'
-      },
-      outDir: {
-        type: "string",
-        description: "Output directory relative to the root. Defaults to the project configuration."
       }
     },
     additionalProperties: false
@@ -981,35 +1028,32 @@ var generateTool = {
     });
     if (!prepared.ok) return prepared.outcome;
     const workspace = prepared.workspace;
-    let manifest;
-    try {
-      manifest = generateSnapshot(workspace.config);
-    } catch (error) {
-      return failure(error instanceof Error ? error.message : String(error));
-    }
+    const result = await generateInWorker(workspace.root, workspace.cliOptions);
+    if (!result.ok) return failure(result.message);
+    const summary = result.summary;
     forgetManifest(manifestPathFor(workspace));
     const written = relativeFor(workspace, path2.resolve(workspace.root, workspace.config.outDir));
     const lines = [
       `Wrote ${written}/`,
-      `Files: ${manifest.counts.totalFiles} included, ${manifest.counts.skippedCount} skipped, ${plural(manifest.counts.partsCount, "part")}`,
-      `Parts: ${manifest.parts.map((part) => `${part.filename} (${formatBytes(part.byteSize)})`).join(", ")}`,
-      `Fingerprint: ${manifest.fingerprint}`
+      `Files: ${summary.totalFiles} included, ${summary.skippedCount} skipped, ${plural(summary.partsCount, "part")}`,
+      `Parts: ${summary.parts.map((part) => `${part.filename} (${formatBytes(part.byteSize)})`).join(", ")}`,
+      `Fingerprint: ${summary.fingerprint}`
     ];
-    if (manifest.warnings.length > 0) {
-      lines.push(`Warnings (${manifest.warnings.length}):`);
-      for (const warning of manifest.warnings.slice(0, 5)) lines.push(`  - ${warning}`);
+    if (summary.warnings.length > 0) {
+      lines.push(`Warnings (${summary.warnings.length}):`);
+      for (const warning of summary.warnings.slice(0, 5)) lines.push(`  - ${warning}`);
     }
     return {
       text: lines.join("\n"),
       structured: {
-        fingerprint: manifest.fingerprint,
-        files: manifest.counts.totalFiles,
-        skipped: manifest.counts.skippedCount,
-        parts: manifest.counts.partsCount,
-        emittedBytes: manifest.totals.totalContentBytes,
+        fingerprint: summary.fingerprint,
+        files: summary.totalFiles,
+        skipped: summary.skippedCount,
+        parts: summary.partsCount,
+        emittedBytes: summary.totalContentBytes,
         outDir: written,
-        partFiles: manifest.parts.map((part) => part.filename),
-        warningCount: manifest.warnings.length
+        partFiles: summary.parts.map((part) => part.filename),
+        warningCount: summary.warnings.length
       }
     };
   }
@@ -1020,7 +1064,7 @@ var validateTool = {
   description: "Re-read the repository and report whether the snapshot on disk still matches it. Use it before trusting context that came from an earlier session, or after changing the config.",
   inputSchema: {
     type: "object",
-    properties: { root: ROOT_PROPERTY },
+    properties: { root: ROOT_PROPERTY, outDir: OUT_DIR_PROPERTY },
     additionalProperties: false
   },
   outputSchema: {
@@ -1032,7 +1076,7 @@ var validateTool = {
   },
   annotations: READ_ONLY,
   async handler(args, context) {
-    const prepared = await prepare(args, context);
+    const prepared = await prepare(args, context, outDirOverride(args));
     if (!prepared.ok) return prepared.outcome;
     const workspace = prepared.workspace;
     let result;
@@ -1099,7 +1143,8 @@ var locateTool = {
         default: 20,
         description: "Maximum matches to return."
       },
-      root: ROOT_PROPERTY
+      root: ROOT_PROPERTY,
+      outDir: OUT_DIR_PROPERTY
     },
     required: ["query"],
     additionalProperties: false
@@ -1110,7 +1155,7 @@ var locateTool = {
   },
   annotations: READ_ONLY,
   async handler(args, context) {
-    const prepared = await prepare(args, context);
+    const prepared = await prepare(args, context, outDirOverride(args));
     if (!prepared.ok) return prepared.outcome;
     const workspace = prepared.workspace;
     const read = readManifest(workspace);
@@ -1145,12 +1190,13 @@ var locateTool = {
           continue;
         }
       }
-      if (wants("layer") && entry.layer.toLowerCase() === needle) add(entry, "layer");
-      else if (wants("kind") && entry.kind.toLowerCase() === needle) add(entry, "kind");
+      if (wants("layer") && entry.layer.toLowerCase().includes(needle)) add(entry, "layer");
+      else if (wants("kind") && entry.kind.toLowerCase().includes(needle)) add(entry, "kind");
     }
     if (wants("route")) {
       for (const route of manifest.indexes.routes) {
-        if (!route.path.toLowerCase().includes(needle)) continue;
+        const method = route.methods.find((name) => name.toLowerCase().includes(needle));
+        if (!route.path.toLowerCase().includes(needle) && method === void 0) continue;
         if (matches.some((match) => match.path === route.path)) continue;
         matches.push({
           path: route.path,
@@ -1185,6 +1231,127 @@ var locateTool = {
     };
   }
 };
+var dependentsTool = {
+  name: "snapshot_dependents",
+  title: "Follow the import graph",
+  description: 'For one file in the snapshot: what it imports, and which files import it. Answers "what breaks if I change this?" without reading the parts.',
+  inputSchema: {
+    type: "object",
+    properties: {
+      path: {
+        type: "string",
+        description: "Snapshot-relative path, exactly as snapshot_locate or manifest.files[] reports it."
+      },
+      direction: {
+        type: "string",
+        enum: ["both", "imports", "imported-by"],
+        default: "both",
+        description: "Which edges to return."
+      },
+      limit: {
+        type: "integer",
+        minimum: 1,
+        maximum: 200,
+        default: 50,
+        description: "Maximum entries per direction."
+      },
+      root: ROOT_PROPERTY,
+      outDir: OUT_DIR_PROPERTY
+    },
+    required: ["path"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      path: { type: "string" },
+      imports: { type: "array" },
+      importedBy: { type: "array" },
+      unresolved: { type: "array" }
+    }
+  },
+  annotations: READ_ONLY,
+  async handler(args, context) {
+    const prepared = await prepare(args, context, outDirOverride(args));
+    if (!prepared.ok) return prepared.outcome;
+    const read = readManifest(prepared.workspace);
+    if (!read.ok) return failure(read.message);
+    const manifest = read.manifest;
+    const requested = String(args.path ?? "").trim().replace(/\\/g, "/");
+    if (requested.length === 0) return failure('"path" must not be empty.');
+    const filesByPath = new Map(manifest.files.map((file) => [file.relativePath, file]));
+    const entry = filesByPath.get(requested) ?? manifest.files.find((file) => file.relativePath.toLowerCase() === requested.toLowerCase());
+    if (!entry) {
+      return failure(
+        `${requested} is not in the snapshot. Use snapshot_locate to find its path, or snapshot_explain to see whether it was excluded.`
+      );
+    }
+    const direction = args.direction === "imports" || args.direction === "imported-by" ? String(args.direction) : "both";
+    const limit = typeof args.limit === "number" && args.limit > 0 ? Math.floor(args.limit) : 50;
+    const resolver = buildImportResolver(manifest.files);
+    const imports = [];
+    const unresolved = [];
+    if (direction !== "imported-by") {
+      const own = manifest.indexes.imports.byFile.find((file) => file.path === entry.relativePath);
+      for (const specifier of own?.imports ?? []) {
+        const resolved = resolveSpecifier(entry.relativePath, specifier, resolver);
+        if (resolved === null) {
+          unresolved.push(specifier);
+          continue;
+        }
+        const target = filesByPath.get(resolved);
+        if (target) imports.push({ path: resolved, specifier, part: target.part });
+      }
+    }
+    const importedBy = [];
+    if (direction !== "imports") {
+      for (const candidate of manifest.indexes.imports.byFile) {
+        if (candidate.path === entry.relativePath) continue;
+        const edge = candidate.imports.some(
+          (specifier) => resolveSpecifier(candidate.path, specifier, resolver) === entry.relativePath
+        );
+        if (!edge) continue;
+        const source = filesByPath.get(candidate.path);
+        importedBy.push({ path: candidate.path, part: source?.part ?? "" });
+      }
+    }
+    const shownImports = imports.slice(0, limit);
+    const shownImportedBy = importedBy.slice(0, limit);
+    const lines = [
+      `${entry.relativePath} \u2014 ${importedBy.length} importer(s), ${imports.length} import(s), ${unresolved.length} outside the snapshot.`
+    ];
+    if (direction !== "imports") {
+      lines.push("", "Imported by:");
+      if (shownImportedBy.length === 0) lines.push("  (nothing in the snapshot imports it)");
+      for (const item of shownImportedBy) lines.push(`  ${item.path}  [${item.part}]`);
+      if (importedBy.length > shownImportedBy.length) {
+        lines.push(`  \u2026 ${importedBy.length - shownImportedBy.length} more; raise \`limit\`.`);
+      }
+    }
+    if (direction !== "imported-by") {
+      lines.push("", "Imports:");
+      if (shownImports.length === 0) lines.push("  (none recorded for this file)");
+      for (const item of shownImports) {
+        lines.push(`  ${item.path}  (from "${item.specifier}")  [${item.part}]`);
+      }
+      if (imports.length > shownImports.length) {
+        lines.push(`  \u2026 ${imports.length - shownImports.length} more; raise \`limit\`.`);
+      }
+      if (unresolved.length > 0) {
+        lines.push("", `Outside the snapshot (${unresolved.length}): ${unresolved.join(", ")}`);
+      }
+    }
+    return {
+      text: lines.join("\n"),
+      structured: {
+        path: entry.relativePath,
+        imports: shownImports,
+        importedBy: shownImportedBy,
+        unresolved
+      }
+    };
+  }
+};
 var readTool = {
   name: "snapshot_read",
   title: "Read a file from the snapshot",
@@ -1209,7 +1376,8 @@ var readTool = {
         default: 200,
         description: "How many lines to return."
       },
-      root: ROOT_PROPERTY
+      root: ROOT_PROPERTY,
+      outDir: OUT_DIR_PROPERTY
     },
     required: ["path"],
     additionalProperties: false
@@ -1227,7 +1395,7 @@ var readTool = {
   },
   annotations: READ_ONLY,
   async handler(args, context) {
-    const prepared = await prepare(args, context);
+    const prepared = await prepare(args, context, outDirOverride(args));
     if (!prepared.ok) return prepared.outcome;
     const workspace = prepared.workspace;
     if (typeof args.path !== "string") return failure('"path" must be a string.');
@@ -1262,7 +1430,7 @@ var readTool = {
         `${entry.part} could not be read, so the snapshot is damaged. Run snapshot_generate to rebuild it.`
       );
     }
-    const section = findSection(parsePartSections(partText), entry.relativePath, entry.hashSha256);
+    const section = findSection(parsePartSections(partText), entry.relativePath);
     if (!section) {
       return failure(
         `${relativePath} is recorded in ${entry.part} but its section could not be located there. Run snapshot_generate to rebuild the snapshot.`
@@ -1274,16 +1442,28 @@ var readTool = {
     let body = window.text;
     let truncatedByBytes = false;
     if (Buffer.byteLength(body, "utf8") > MAX_RESULT_BYTES) {
-      body = body.slice(0, MAX_RESULT_BYTES);
+      const clipped = truncateToBytes(body, MAX_RESULT_BYTES);
+      body = clipped.content;
       const lastBreak = body.lastIndexOf("\n");
       body = lastBreak > 0 ? body.slice(0, lastBreak) : body;
       truncatedByBytes = true;
     }
     const returnedLines = body.length === 0 ? 0 : body.split("\n").length;
-    const moreRemain = window.truncated || truncatedByBytes;
+    const moreRemain = !window.pastEnd && (window.truncated || truncatedByBytes);
     const header = [
       `${entry.relativePath} \u2014 ${entry.part}, ${entry.layer}/${entry.kind}, ${entry.language}`,
-      section.inclusion === "preview" ? "Bounded preview: this source file is large, so the snapshot holds only its head and tail." : `Lines ${window.fromLine}\u2013${window.fromLine + returnedLines - 1} of ${window.totalLines}.`
+      // The line range is the answer to "where am I in this file", and it is computed from the
+      // body the window was taken from, so it is just as meaningful for a preview as for a full
+      // file. It used to be replaced — not augmented — by the preview note, so a 40-line window
+      // into a 300-line preview came back with no range at all and the caller could not tell
+      // where the window ended. Both facts are stated now, and `signatures` is no longer
+      // silently treated as a full file.
+      ...section.inclusion === "preview" ? [
+        "Bounded preview: the snapshot holds this file's head and tail only, so these line numbers count the preview, not the source."
+      ] : section.inclusion === "signatures" ? [
+        "Signatures: function and method bodies were replaced with `{ /* ... */ }` when the snapshot was generated."
+      ] : [],
+      window.totalLines === 0 ? "This file is empty." : window.pastEnd ? `This file has ${window.totalLines} line(s); fromLine=${window.fromLine} is past its end.` : `Lines ${window.fromLine}\u2013${window.fromLine + returnedLines - 1} of ${window.totalLines}.`
     ];
     const lines = [...header, "", body];
     if (moreRemain) {
@@ -1320,7 +1500,8 @@ var explainTool = {
         type: "string",
         description: "Path relative to the repository root. Directories are explained as a whole."
       },
-      root: ROOT_PROPERTY
+      root: ROOT_PROPERTY,
+      outDir: OUT_DIR_PROPERTY
     },
     required: ["path"],
     additionalProperties: false
@@ -1335,7 +1516,7 @@ var explainTool = {
   },
   annotations: READ_ONLY,
   async handler(args, context) {
-    const prepared = await prepare(args, context);
+    const prepared = await prepare(args, context, outDirOverride(args));
     if (!prepared.ok) return prepared.outcome;
     const workspace = prepared.workspace;
     if (typeof args.path !== "string") return failure('"path" must be a string.');
@@ -1375,6 +1556,7 @@ function buildTools() {
     generateTool,
     validateTool,
     locateTool,
+    dependentsTool,
     readTool,
     explainTool
   ];
@@ -1446,9 +1628,15 @@ var RESOURCE_TEMPLATE_URIS = ["snapshot://parts/{index}"];
 
 // src/agent/option-scope.ts
 var VALIDATE_OPTIONS = [
+  "sarif",
+  "skeleton",
+  "changed-since",
+  "staged",
+  "with-dependents",
   "cwd",
   "out-dir",
   "max-part-bytes",
+  "max-part-tokens",
   "large-file-bytes",
   "max-monolith-bytes",
   "include-monolith",
@@ -1465,9 +1653,15 @@ var VALIDATE_OPTIONS = [
 ];
 var COMMAND_OPTION_SCOPE = {
   generate: [
+    "sarif",
+    "skeleton",
+    "changed-since",
+    "staged",
+    "with-dependents",
     "cwd",
     "out-dir",
     "max-part-bytes",
+    "max-part-tokens",
     "large-file-bytes",
     "max-monolith-bytes",
     "include-monolith",
@@ -1505,6 +1699,12 @@ var COMMAND_OPTION_SCOPE = {
     "version"
   ],
   explain: [
+    // The scope decides what `explain` says about a file, dependents included: without these,
+    // a file that is in the snapshot only because it imports a changed one was explained as
+    // `included: false, reason: "unchanged"`.
+    "changed-since",
+    "staged",
+    "with-dependents",
     "cwd",
     "out-dir",
     "max-part-bytes",
@@ -1525,6 +1725,7 @@ var COMMAND_OPTION_SCOPE = {
   diff: ["format", "mode", "no-config", "no-update-check", "help", "version"],
   describe: ["format", "mode", "help", "version"],
   init: [
+    "install-hook",
     "cwd",
     "out-dir",
     "max-part-bytes",
@@ -1547,13 +1748,29 @@ var COMMAND_OPTION_SCOPE = {
   // `mcp` reads the repository, so it takes --cwd. It has no --format: stdout carries JSON-RPC
   // messages, and there is no second shape to choose, so offering the flag would be a lie.
   mcp: ["cwd", "mode", "help", "version"],
+  // `setup` generates through the `generate` command, so every generation setting it can
+  // honour is in scope. Rejecting them made the one-command path unable to express a walk
+  // scan, a monolith or a different large-file threshold; the alternative was to run
+  // `setup` and then edit the config it had just written.
   setup: [
+    "install-hook",
     "cwd",
     "out-dir",
     "max-part-bytes",
+    // Persisted into the config `setup` writes, then forwarded to the generation it runs — so
+    // the snapshot it produces validates against the config beside it. Accepting a setting here
+    // without writing it down made `setup --large-file-bytes 100k` finish with a snapshot its
+    // own `validate` called drifted, on the first run of a brand-new project.
+    "max-part-tokens",
+    "skeleton",
+    "sarif",
+    "large-file-bytes",
+    "max-monolith-bytes",
+    "include-monolith",
     "include-sensitive-files",
     "skip-artifacts",
     "only-artifacts",
+    "discovery",
     "preset",
     "include",
     "exclude",
@@ -1839,6 +2056,13 @@ function buildAgentContract() {
         appliesTo: optionAppliesTo("max-part-bytes"),
         summary: 'Byte budget per markdown part. Accepts "120k" / "1.5mb". Minimum 4096.'
       },
+      {
+        flag: "--max-part-tokens",
+        type: "string",
+        default: "unset",
+        appliesTo: optionAppliesTo("max-part-tokens"),
+        summary: "Ceiling on a part expressed in tokens. Narrows --max-part-bytes instead of replacing it; the manifest records both units. Minimum 1024."
+      },
       {
         flag: "--large-file-bytes",
         type: "string",
@@ -1888,6 +2112,41 @@ function buildAgentContract() {
         appliesTo: optionAppliesTo("only-artifacts"),
         summary: "Write only these artifacts. Cannot be combined with --skip-artifacts."
       },
+      {
+        flag: "--skeleton",
+        type: "boolean",
+        default: false,
+        appliesTo: optionAppliesTo("skeleton"),
+        summary: 'Replace function and method bodies with `{ /* ... */ }` in TypeScript/TSX files, keeping signatures and comments. The part records inclusionMode "signatures" for each file it touched.'
+      },
+      {
+        flag: "--sarif",
+        type: "boolean",
+        default: false,
+        appliesTo: optionAppliesTo("sarif"),
+        summary: "Also write reports/audit.sarif (SARIF 2.1.0) so a CI security gate can read the redaction findings. The matched value is never included."
+      },
+      {
+        flag: "--changed-since",
+        type: "string",
+        default: "unset",
+        appliesTo: optionAppliesTo("changed-since"),
+        summary: 'Snapshot only the files that differ from this git ref, plus untracked ones. Everything else is recorded in skipped[] with reason "unchanged". Requires a git checkout.'
+      },
+      {
+        flag: "--staged",
+        type: "boolean",
+        default: false,
+        appliesTo: optionAppliesTo("staged"),
+        summary: "Snapshot only the files staged in the index. The pre-commit counterpart of --changed-since."
+      },
+      {
+        flag: "--with-dependents",
+        type: "boolean",
+        default: false,
+        appliesTo: optionAppliesTo("with-dependents"),
+        summary: "Widen a changed-files scope by one hop: files that import a changed file are included too. Only meaningful with --changed-since or --staged."
+      },
       {
         flag: "--format",
         type: "string",
@@ -1995,6 +2254,13 @@ function buildAgentContract() {
         appliesTo: optionAppliesTo("no-install"),
         summary: "Skip installing the dependency before generating: `setup`, or `generate --autopilot` (CI, offline, or a lockfile you do not want a package manager to touch)."
       },
+      {
+        flag: "--install-hook",
+        type: "boolean",
+        default: false,
+        appliesTo: optionAppliesTo("install-hook"),
+        summary: "After writing the config, install a pre-commit hook that runs `validate`. An existing hook this tool did not write is left alone."
+      },
       {
         flag: "--no-update-check",
         type: "boolean",
@@ -2031,6 +2297,12 @@ function buildAgentContract() {
         { key: "branch", type: "string", default: "main", summary: "Branch recorded when git cannot report one." },
         { key: "preset", type: "string", default: "detected", summary: "Force a preset. Unknown names are an error." },
         { key: "maxPartBytes", type: "number | string", default: 307200, summary: "Per-part byte budget." },
+        { key: "maxPartTokens", type: "number | string | null", default: null, summary: "Per-part token ceiling; narrows maxPartBytes. Minimum 1024." },
+        { key: "skeleton", type: "boolean", default: false, summary: "Collapse function bodies to `{ /* ... */ }` in TypeScript files." },
+        { key: "sarif", type: "boolean", default: false, summary: "Also write reports/audit.sarif." },
+        { key: "changedSince", type: "string | null", default: null, summary: "Snapshot only files that differ from this git ref." },
+        { key: "staged", type: "boolean", default: false, summary: "Snapshot only files staged in the index." },
+        { key: "withDependents", type: "boolean", default: false, summary: "With a changed-files scope, also include one hop of importers." },
         { key: "largeFileBytes", type: "number | string", default: 204800, summary: "Preview threshold for large files." },
         { key: "previewHeadLines", type: "number", default: 80, summary: "Lines kept from the head of a large file." },
         { key: "previewTailLines", type: "number", default: 40, summary: "Lines kept from the tail of a large file." },
@@ -2213,14 +2485,19 @@ do not assume the repository is broken.
    matches the files on disk. Exit 1 means drift \u2014 re-run step 5.
 
 7. **Read the output in this order:**
-   - \`snapshot/parts/part-*.md\` \u2014 the code itself, each file tagged with its layer, kind,
-     language and, when it fits the budget, a structural summary (imports, exports,
-     classes, functions). A dropped summary appears as a \`Summary: (omitted \u2026)\` line.
+   - \`snapshot/parts/part-*.md\` \u2014 the code itself. Each file carries one \`- Meta:\` line
+     (layer/kind, language, inclusion, size) and, only when the body is **not** the whole
+     file, a structural summary (imports, exports, classes, functions). A full file has no
+     summary line, because the summary would repeat the code three lines below it \u2014 read
+     \`manifest.json\` for it. A summary dropped to fit the budget appears as a
+     \`Summary: (omitted \u2026)\` line.
    - \`snapshot/manifest.json\` \u2014 the index. \`files[]\` has \`relativePath\`, \`layer\`,
-     \`kind\`, \`language\`, \`part\`, \`inclusionMode\` and \`hashSha256\`, plus \`encoding\`
-     when the file was not plain UTF-8. \`summary\` is **optional**: it is absent for
-     languages with no structural summary, and \`summaryOmitted: true\` marks one dropped
-     to fit the part budget \u2014 never assume it exists.
+     \`kind\`, \`language\`, \`part\`, \`inclusionMode\`, \`hashSha256\` and the structural
+     \`summary\`, plus \`encoding\` when the file was not plain UTF-8. \`summary\` is
+     **optional**: it is absent for languages with no structural summary, and
+     \`summaryOmitted: true\` marks one dropped to fit the part budget \u2014 never assume it
+     exists. The per-file \`hashSha256\` is only here and in the manifest; it is not printed
+     into the parts.
      \`skipped[]\` records every excluded file **and why**. Prefer querying this over
      re-reading the parts.
    - \`snapshot/reports/audit.md\` \u2014 secrets found, large files, parse diagnostics, git
@@ -2274,7 +2551,7 @@ diff, and the commit, are then yours.
 ## When the client speaks MCP
 
 If the agent runs inside an MCP client, \`npx ${PACKAGE_NAME2}@latest mcp\` serves this repository
-as seven tools over stdio instead of shelling out. Its reads come from the snapshot rather than
+as eight tools over stdio instead of shelling out. Its reads come from the snapshot rather than
 the working tree, so excluded files and redacted values never reach the context. Use
 \`snapshot_locate\` before \`snapshot_read\`, and \`snapshot_validate\` before trusting a snapshot
 from an earlier session.
@@ -2431,7 +2708,8 @@ var SERVER_INSTRUCTIONS = [
   "1. snapshot_status \u2014 is there a snapshot here, and has the tree moved since it was built?",
   "2. snapshot_locate \u2014 find which part holds the code you need.",
   "3. snapshot_read \u2014 read a window of one file. Never read a part end to end.",
-  "4. snapshot_validate \u2014 before trusting context that came from an earlier conversation.",
+  "4. snapshot_dependents \u2014 before changing a file, see what imports it.",
+  "5. snapshot_validate \u2014 before trusting context that came from an earlier conversation.",
   "",
   "Rules that matter:",
   "- Parts are budgeted, not small: a 12-part snapshot is hundreds of kilobytes. Use snapshot_locate first.",
@@ -2474,7 +2752,13 @@ function createLineReader(input, options) {
     while (index >= 0) {
       const line = buffer.slice(0, index);
       buffer = buffer.slice(index + 1);
-      deliver(line);
+      if (discarding) {
+        deliver(line);
+      } else if (line.length > MAX_LINE_BYTES) {
+        options.onOverflow?.(line.length);
+      } else {
+        deliver(line);
+      }
       index = buffer.indexOf("\n");
     }
   };
@@ -2491,14 +2775,14 @@ function createLineReader(input, options) {
       return;
     }
     buffer += chunk;
-    if (buffer.length > MAX_LINE_BYTES && buffer.indexOf("\n") < 0) {
+    drain();
+    if (buffer.length > MAX_LINE_BYTES) {
       discarding = true;
       discardedBytes = buffer.length;
       buffer = "";
       options.onOverflow?.(discardedBytes);
       return;
     }
-    drain();
   };
   const onEnd = () => {
     if (buffer.length > 0) {
@@ -2598,6 +2882,4 @@ async function runStdioServer(options) {
   return code;
 }
 
-export { COMMAND_OPTION_SCOPE, ERROR_CODES, LEGACY_PROTOCOL_VERSIONS, MAX_LINE_BYTES, METHOD, MODERN_PROTOCOL_VERSIONS, SERVER_INSTRUCTIONS, SKILL_NAME, SUPPORTED_PROTOCOL_VERSIONS, buildAgentContract, buildPrompts, buildResourceProvider, buildTools, classifyRequest, coerceNumericStrings, commandsForOption, createLineReader, createMcpServer, createServer, createSession, createWriter, inspectModernMeta, negotiateLegacyVersion, renderContractText, renderSkill, runStdioServer, validateArguments };
-//# sourceMappingURL=chunk-HQBEQ67K.js.map
-//# sourceMappingURL=chunk-HQBEQ67K.js.map
+export { COMMAND_OPTION_SCOPE, ERROR_CODES, LEGACY_PROTOCOL_VERSIONS, MAX_LINE_BYTES, METHOD, MODERN_PROTOCOL_VERSIONS, SERVER_INSTRUCTIONS, SKILL_NAME, SUPPORTED_PROTOCOL_VERSIONS, buildAgentContract, buildPrompts, buildResourceProvider, buildTools, classifyRequest, coerceNumericStrings, commandsForOption, createLineReader, createMcpServer, createServer, createSession, createWriter, findSection, inspectModernMeta, negotiateLegacyVersion, parsePartSections, renderContractText, renderSkill, runStdioServer, validateArguments, windowText };