@lzehrung/codegraph 2.2.3 → 2.3.1

package/dist/bin/cli.js

@@ -432,6 +432,13 @@ function graphCommandSchema(positionals) {
     "--symbols-detailed-scope"
   ], positionals);
 }
+function getCliCommandUsage(command) {
+  const usage = CLI_COMMAND_SCHEMAS.get(command)?.positionals.usage;
+  if (!usage) {
+    throw new Error(`No validation usage is defined for ${command}.`);
+  }
+  return usage;
+}
 function allowedFlagsForSchema(schema) {
   return /* @__PURE__ */ new Set(["--help", "-h", "--version", "-v", "--debug", ...schema.flags ?? []]);
 }
@@ -692,7 +699,8 @@ var init_options = __esm({
       [
         "affected",
         commandSchema([...SHARED_BUILD_FLAGS, "--json", "--quiet", "--stdin"], [...SHARED_BUILD_OPTIONS, "--base", "--depth", "--filter", "--head"], {
-          kind: "any"
+          kind: "any",
+          usage: "Usage: codegraph affected <file...> [--stdin] [--base <ref> --head <ref>] [--root <path>] [--depth <n>] [--filter <glob>] [--json | --quiet]"
         })
       ],
       [
@@ -716,7 +724,7 @@ var init_options = __esm({
         commandSchema([...JSON_OUTPUT_FLAGS, "--text"], ["--language", "--max-tokens", "--min-tokens"], {
           kind: "max",
           max: 1,
-          usage: "Usage: codegraph chunk <file-path> [options]"
+          usage: "Usage: codegraph chunk <file-path> [--language <language>] [--min-tokens <n>] [--max-tokens <n>] [--text] [--json | --pretty]"
         })
       ],
       [
@@ -727,10 +735,10 @@ var init_options = __esm({
       ],
       [
         "deps",
-        commandSchema([...SHARED_BUILD_FLAGS, ...JSON_OUTPUT_FLAGS], [...SHARED_BUILD_OPTIONS, "--depth"], {
+        commandSchema([...SHARED_BUILD_FLAGS, ...JSON_OUTPUT_FLAGS, "--all"], [...SHARED_BUILD_OPTIONS, "--depth"], {
           kind: "max",
           max: 1,
-          usage: "Usage: codegraph deps <file> [--root <path>] [--depth <n>] [--json | --pretty]"
+          usage: "Usage: codegraph deps <file|file::symbol|symbol:...> [--root <path>] [--depth <n> | --all] [--json | --pretty]"
         })
       ],
       [
@@ -813,7 +821,7 @@ var init_options = __esm({
         commandSchema([...SHARED_BUILD_FLAGS, ...JSON_OUTPUT_FLAGS], SHARED_BUILD_OPTIONS, {
           kind: "max",
           max: 3,
-          usage: "Usage: codegraph goto <file>[:line[:column]] [line] [column] [--root <path>] [--json | --pretty]"
+          usage: "Usage: codegraph goto <file|file::symbol|symbol:...> [--root <path>] [--json | --pretty]\n       codegraph goto <file>[:line[:column]] [line] [column] [--root <path>] [--json | --pretty]"
         })
       ],
       ["graph", graphCommandSchema({ kind: "any" })],
@@ -832,7 +840,16 @@ var init_options = __esm({
       [
         "grep",
         commandSchema(["--ignore-case", "--json", "--pretty", "-i", "--no-gitignore"], ["--glob", "--ignore-glob", "--include-glob", "--max-hits", "--pattern", "--query", "--regex", "--root"], {
-          kind: "any"
+          kind: "max",
+          max: 1,
+          // `handleGrepCommand` takes the pattern from --pattern, then --regex, then the
+          // positional, and --query is a separate syntax-tree mode. Present all three forms
+          // so a parse failure does not imply the positional regex is mandatory.
+          usage: [
+            "Usage: codegraph grep <regex> [--root <dir>] [--glob|--include-glob|--ignore-glob <glob>] [--ignore-case|-i] [--no-gitignore] [--max-hits <n>] [--json | --pretty]",
+            "       codegraph grep --pattern|--regex <expr> [--root <dir>] [--glob|--include-glob|--ignore-glob <glob>] [--ignore-case|-i] [--no-gitignore] [--max-hits <n>] [--json | --pretty]",
+            "       codegraph grep --query <tree-sitter-query> [--root <dir>] [--json | --pretty]"
+          ].join("\n")
         })
       ],
       [
@@ -872,7 +889,7 @@ var init_options = __esm({
         ], {
           kind: "max",
           max: 1,
-          usage: "Usage: codegraph impact [project-root] [--provider git|github|raw] [options]"
+          usage: "Usage: codegraph impact [project-root] [--provider git|github|raw] [--depth <n>] [options] [--json | --pretty]"
         })
       ],
       [
@@ -947,7 +964,7 @@ var init_options = __esm({
         ], {
           kind: "max",
           max: 1,
-          usage: "Usage: codegraph server <start|status|stop> [--root <path>]"
+          usage: "Usage: codegraph server <start|status|stop> [--root <path>] [--json | --pretty]"
         })
       ],
       [
@@ -974,10 +991,10 @@ var init_options = __esm({
       ],
       [
         "rdeps",
-        commandSchema([...SHARED_BUILD_FLAGS, ...JSON_OUTPUT_FLAGS], [...SHARED_BUILD_OPTIONS, "--depth"], {
+        commandSchema([...SHARED_BUILD_FLAGS, ...JSON_OUTPUT_FLAGS, "--all"], [...SHARED_BUILD_OPTIONS, "--depth"], {
           kind: "max",
           max: 1,
-          usage: "Usage: codegraph rdeps <file> [--root <path>] [--depth <n>] [--json | --pretty]"
+          usage: "Usage: codegraph rdeps <file|file::symbol|symbol:...> [--root <path>] [--depth <n> | --all] [--json | --pretty]"
         })
       ],
       [
@@ -985,7 +1002,7 @@ var init_options = __esm({
         commandSchema([...SHARED_BUILD_FLAGS, ...JSON_OUTPUT_FLAGS], [...SHARED_BUILD_OPTIONS, "--col", "--column", "--file", "--line"], {
           kind: "max",
           max: 3,
-          usage: "Usage: codegraph refs <file>[:line[:column]] [line] [column] [--root <path>] [--json | --pretty]"
+          usage: "Usage: codegraph refs <file|file::symbol|symbol:...> [--root <path>] [--json | --pretty]\n       codegraph refs <file>[:line[:column]] [line] [column] [--root <path>] [--json | --pretty]\n       codegraph refs --file <file> [--line <line> --col <column>] [--root <path>] [--json | --pretty]"
         })
       ],
       [
@@ -1095,7 +1112,7 @@ var init_options = __esm({
         commandSchema(["--json", "--pretty"], ["--db", "--query", "--sqlite"], {
           kind: "max",
           max: 2,
-          usage: 'Usage: codegraph sql <sqlite-path> "SELECT ..." [--json | --pretty] OR codegraph sql --db <sqlite path> --query "SELECT ..." [--json | --pretty]'
+          usage: 'Usage: codegraph sql <sqlite-path> "SELECT ..." [--json | --pretty] OR codegraph sql --db <sqlite-path> --query "SELECT ..." [--json | --pretty]'
         })
       ],
       [
@@ -1148,16 +1165,14 @@ function resolveCliProgressPresentation(input) {
   if (input.stderrIsTTY) {
     return input.terminalSupportsControlSequences ? "interactive" : "log";
   }
-  if (input.policy === "always")
-    return "log";
-  return "off";
+  return "log";
 }
 function createCliProgressDisplay(options) {
   if (options.presentation === "log")
-    return createLogProgressDisplay(options.write);
-  return createInteractiveProgressDisplay(options.write);
+    return createLogProgressDisplay(options.write, options.delayMs);
+  return createInteractiveProgressDisplay(options.write, options.delayMs);
 }
-function createInteractiveProgressDisplay(write) {
+function createInteractiveProgressDisplay(write, delayMs = 0) {
   let active = false;
   let rendered = false;
   let frameIndex = 0;
@@ -1165,6 +1180,7 @@ function createInteractiveProgressDisplay(write) {
   let total = 0;
   let mode = "build";
   let interval;
+  let delay;
   const clear = () => {
     if (!rendered)
       return;
@@ -1177,39 +1193,55 @@ function createInteractiveProgressDisplay(write) {
     const action = progressAction(mode);
     const frame = SPINNER_FRAMES[frameIndex % SPINNER_FRAMES.length];
     frameIndex += 1;
-    const count = total > 0 ? ` ${current}/${total} files` : "";
+    const count = formatProgressCount(current, total);
     write(`${CLEAR_LINE}${action} project index... ${frame}${count}`);
     rendered = true;
   };
   const stopInterval = () => {
-    if (interval === void 0)
-      return;
-    clearInterval(interval);
-    interval = void 0;
+    if (interval !== void 0) {
+      clearInterval(interval);
+      interval = void 0;
+    }
+    if (delay !== void 0) {
+      clearTimeout(delay);
+      delay = void 0;
+    }
   };
   const start = (update) => {
     stopInterval();
     clear();
     active = true;
+    rendered = false;
     frameIndex = 0;
     current = update.current;
     total = update.total;
     mode = update.mode ?? "build";
-    render();
-    interval = setInterval(render, REFRESH_INTERVAL_MS);
-    interval.unref();
+    const beginRendering = () => {
+      if (!active)
+        return;
+      render();
+      interval = setInterval(render, REFRESH_INTERVAL_MS);
+      interval.unref();
+    };
+    if (delayMs) {
+      delay = setTimeout(beginRendering, delayMs);
+      delay.unref();
+    } else {
+      beginRendering();
+    }
   };
   const complete = (update) => {
     if (!active)
       return;
     active = false;
     stopInterval();
+    if (!rendered)
+      return;
     clear();
     const verb = progressCompleteVerb(mode);
-    const fileCount = update.total;
-    const files = fileCount === 1 ? "file" : "files";
+    const fileCount = formatFileCount(update.total, "words");
     const elapsed = update.elapsedMs === void 0 ? "" : ` in ${formatDuration(update.elapsedMs)}`;
-    write(`${verb} project index: ${fileCount} ${files}${elapsed}.
+    write(`${verb} project index: ${fileCount}${elapsed}.
 `);
   };
   return {
@@ -1239,37 +1271,92 @@ function createInteractiveProgressDisplay(write) {
     }
   };
 }
-function createLogProgressDisplay(write) {
+function formatFileCount(count, zeroFormat = "numeric") {
+  if (!count && zeroFormat === "words")
+    return "no files";
+  return `${count} file${count === 1 ? "" : "s"}`;
+}
+function formatProgressCount(current, total) {
+  if (total > 0)
+    return ` ${current}/${formatFileCount(total)}`;
+  return ` ${formatFileCount(current)} processed`;
+}
+function createLogProgressDisplay(write, delayMs = 0) {
   let active = false;
+  let rendered = false;
+  let current = 0;
+  let total = 0;
   let mode = "build";
+  let delay;
+  let heartbeat;
+  const stopTimers = () => {
+    if (delay !== void 0) {
+      clearTimeout(delay);
+      delay = void 0;
+    }
+    if (heartbeat !== void 0) {
+      clearInterval(heartbeat);
+      heartbeat = void 0;
+    }
+  };
+  const renderStart = () => {
+    if (!active || rendered)
+      return;
+    rendered = true;
+    write(`[Progress] ${progressAction(mode)} project index.
+`);
+    heartbeat = setInterval(() => {
+      if (!active)
+        return;
+      write(`[Progress] ${progressAction(mode)} project index:${formatProgressCount(current, total)}.
+`);
+    }, 1e3);
+    heartbeat.unref();
+  };
+  const start = (update) => {
+    stopTimers();
+    active = true;
+    rendered = false;
+    current = update.current;
+    total = update.total;
+    mode = update.mode ?? "build";
+    if (delayMs) {
+      delay = setTimeout(renderStart, delayMs);
+      delay.unref();
+    } else {
+      renderStart();
+    }
+  };
   return {
     update: (update) => {
       if (update.phase === "start") {
-        active = true;
-        mode = update.mode ?? "build";
-        const action = progressAction(mode);
-        write(`[Progress] ${action} project index.
-`);
+        start(update);
         return;
       }
       if (update.phase === "complete") {
         if (!active)
           return;
         active = false;
+        stopTimers();
+        if (!rendered)
+          return;
         const verb = progressCompleteVerb(mode);
         const elapsed = update.elapsedMs === void 0 ? "" : ` in ${formatDuration(update.elapsedMs)}`;
-        write(`[Progress] ${verb} project index: ${update.total} files${elapsed}.
+        write(`[Progress] ${verb} project index: ${formatFileCount(update.total, "words")}${elapsed}.
 `);
         return;
       }
       if (!active) {
         if (update.phase === "update")
           return;
-        active = true;
+        start(update);
       }
-      const isComplete = update.current >= update.total;
-      if (update.current === 1 || isComplete || update.current % 100 === 0) {
-        write(`[Progress] ${update.current}/${update.total} files processed.
+      current = update.current;
+      total = update.total;
+      mode = update.mode ?? mode;
+      const isComplete = update.total > 0 && update.current >= update.total;
+      if (rendered && (update.current === 1 || isComplete || update.current % 100 === 0)) {
+        write(`[Progress] ${formatFileCount(update.current)} processed.
 `);
       }
     },
@@ -1277,6 +1364,7 @@ function createLogProgressDisplay(write) {
     },
     dispose: () => {
       active = false;
+      stopTimers();
     }
   };
 }
@@ -1295,9 +1383,10 @@ function progressCompleteVerb(mode) {
   return "Checked";
 }
 function formatDuration(elapsedMs2) {
-  if (elapsedMs2 < 1e3)
-    return `${Math.max(0, Math.round(elapsedMs2))}ms`;
-  return `${(elapsedMs2 / 1e3).toFixed(1)}s`;
+  const durationMs = Math.max(0, elapsedMs2);
+  if (durationMs < 1e3)
+    return `${Math.round(durationMs)}ms`;
+  return `${(durationMs / 1e3).toFixed(1)}s`;
 }
 var REFRESH_INTERVAL_MS, CLEAR_LINE, SPINNER_FRAMES;
 var init_progress = __esm({
@@ -1519,7 +1608,8 @@ function createCliProgressHandler(policy) {
   context.progressDisplay?.dispose();
   const display = createCliProgressDisplay({
     presentation,
-    write: context.runtime.stderr
+    write: context.runtime.stderr,
+    ...policy === "auto" ? { delayMs: 1e3 } : {}
   });
   context.progressDisplay = display;
   return display.update;
@@ -50669,11 +50759,11 @@ function sameSymbolEdgeMultiset(expected, actual) {
     return false;
   const counts = /* @__PURE__ */ new Map();
   for (const edge of expected) {
-    const key = serializedSymbolEdge(edge);
+    const key = symbolEdgeKey(edge);
     counts.set(key, (counts.get(key) ?? 0) + 1);
   }
   for (const edge of actual) {
-    const key = serializedSymbolEdge(edge);
+    const key = symbolEdgeKey(edge);
     const remaining = counts.get(key);
     if (remaining === void 0)
       return false;
@@ -50684,27 +50774,30 @@ function sameSymbolEdgeMultiset(expected, actual) {
   }
   return !counts.size;
 }
-function serializedSymbolEdge(edge) {
-  return JSON.stringify({
-    from: edge.from,
-    to: edge.to,
-    label: edge.label,
-    site: edge.site ? {
-      file: edge.site.file,
-      range: {
-        start: {
-          line: edge.site.range.start.line,
-          column: edge.site.range.start.column,
-          ...edge.site.range.start.index !== void 0 ? { index: edge.site.range.start.index } : {}
-        },
-        end: {
-          line: edge.site.range.end.line,
-          column: edge.site.range.end.column,
-          ...edge.site.range.end.index !== void 0 ? { index: edge.site.range.end.index } : {}
-        }
-      }
-    } : void 0
-  });
+function symbolEdgeKey(edge) {
+  const from = lengthPrefixedSymbolEdgeField(edge.from);
+  const to = lengthPrefixedSymbolEdgeField(edge.to);
+  const label = edge.label === void 0 ? "u" : `s${lengthPrefixedSymbolEdgeField(edge.label)}`;
+  if (!edge.site)
+    return `f${from}t${to}l${label}s`;
+  const { file: file2, range } = edge.site;
+  const startIndex = range.start.index === void 0 ? "u" : `n${range.start.index}`;
+  const endIndex = range.end.index === void 0 ? "u" : `n${range.end.index}`;
+  return [
+    `f${from}`,
+    `t${to}`,
+    `l${label}`,
+    `s${lengthPrefixedSymbolEdgeField(file2)}`,
+    `sl${range.start.line}`,
+    `sc${range.start.column}`,
+    `si${startIndex}`,
+    `el${range.end.line}`,
+    `ec${range.end.column}`,
+    `ei${endIndex}`
+  ].join("");
+}
+function lengthPrefixedSymbolEdgeField(value) {
+  return `${value.length}:${value}`;
 }
 function normalizedSnapshotNativeMode(nativeMode) {
   if (nativeMode === void 0 || nativeMode === "auto")
@@ -55743,6 +55836,17 @@ function toolFollowUp(tool, arguments_ = {}, label) {
     ...label !== void 0 ? { label } : {}
   };
 }
+function dedupeAgentFollowUps(followUps) {
+  const seen = /* @__PURE__ */ new Set();
+  return followUps.filter((followUp) => {
+    const serializedArguments = JSON.stringify(followUp.arguments);
+    const key = `${followUp.tool.length}|${followUp.tool}${serializedArguments}`;
+    if (seen.has(key))
+      return false;
+    seen.add(key);
+    return true;
+  });
+}
 function formatAgentFollowUpAsCli(followUp) {
   const args = followUp.arguments;
   switch (followUp.tool) {
@@ -60762,7 +60866,7 @@ async function handleSqlCommand(context) {
   const dbOpt = context.getOpt("--db") ?? context.getOpt("--sqlite") ?? context.positionals[0];
   const queryText = context.getOpt("--query") ?? context.positionals[1];
   if (!dbOpt || !queryText) {
-    context.writeStderrLine('Usage: sql <sqlite-path> "SELECT ..." OR sql --db <sqlite-path> --query "SELECT ..."');
+    context.writeStderrLine(getCliCommandUsage("sql"));
     context.exit(2);
   }
   const dbPath = path60.isAbsolute(dbOpt) ? normalizePath(dbOpt) : normalizePath(resolveFilePathFromRoot(context.cwd(), dbOpt));
@@ -60775,6 +60879,7 @@ var init_sql2 = __esm({
     init_sqlite();
     init_paths();
     init_pretty();
+    init_options();
   }
 });
 
@@ -60968,7 +61073,7 @@ function formatChunkSummary(chunks) {
 async function handleChunkCommand(context) {
   const inputFilePath = context.positionals[0];
   if (!inputFilePath) {
-    context.writeStderrLine("Usage: chunk <file-path> [options]");
+    context.writeStderrLine(getCliCommandUsage("chunk"));
     context.writeStderrLine("Options:");
     context.writeStderrLine("  --min-tokens N    Minimum tokens per chunk (default: 150)");
     context.writeStderrLine("  --max-tokens N    Maximum tokens per chunk (default: 400)");
@@ -60976,16 +61081,25 @@ async function handleChunkCommand(context) {
     context.writeStderrLine("  --text            Force text chunking mode");
     context.exit(2);
   }
+  const languageOverride = context.getOpt("--language");
+  if (languageOverride) {
+    const languageId = normalizeChunkLanguageId(languageOverride);
+    const isSupported = supportedChunkLanguageIds.has(languageId);
+    if (!isSupported) {
+      context.writeStderrLine(`Unsupported --language value "${languageId}". Supported languages: ${chunkLanguageHelp}.`);
+      context.exit(2);
+    }
+  }
   try {
     const filePath = path61.resolve(context.cwd(), parseSourceLocationInput(inputFilePath).file);
     const source = await fsp33.readFile(filePath, "utf8");
     const ext = path61.extname(filePath).toLowerCase();
-    let languageId = context.getOpt("--language");
-    if (!languageId) {
+    let languageId;
+    if (!languageOverride) {
       const support = supportForFile(filePath);
       languageId = support ? normalizeChunkLanguageId(support.id) : chunkTextLanguageByExtension[ext] || "text";
     } else {
-      languageId = normalizeChunkLanguageId(languageId);
+      languageId = normalizeChunkLanguageId(languageOverride);
     }
     const forceText = context.hasFlag("--text");
     const minTokensRaw = context.getOpt("--min-tokens");
@@ -61032,7 +61146,7 @@ async function handleChunkCommand(context) {
     exitWithError(context, error51, 1, "Chunking failed");
   }
 }
-var chunkLanguageAliases2, chunkTextLanguageByExtension, chunkLanguageHelp;
+var chunkLanguageAliases2, chunkTextLanguageByExtension, supportedChunkLanguageIds, chunkLanguageHelp;
 var init_chunk = __esm({
   "dist/cli/chunk.js"() {
     "use strict";
@@ -61054,7 +61168,8 @@ var init_chunk = __esm({
       ".yaml": "yaml",
       ".yml": "yaml"
     };
-    chunkLanguageHelp = Array.from(/* @__PURE__ */ new Set([...Object.keys(LANG_CONFIGS).sort(), "vue", "svelte", "json", "yaml", "text"])).join(", ");
+    supportedChunkLanguageIds = /* @__PURE__ */ new Set([...Object.keys(LANG_CONFIGS), "vue", "svelte", "json", "yaml", "text"]);
+    chunkLanguageHelp = [...supportedChunkLanguageIds].sort().join(", ");
   }
 });
 
@@ -74864,11 +74979,12 @@ function suggestCliCommands(input, limit = 3) {
 function routeForCliIntent(input) {
   return INTENT_ROUTES.find((route) => route.pattern.test(input))?.command;
 }
-function renderCliCommandList() {
-  const width = Math.max(...CLI_COMMAND_CATALOG.map((command) => command.name.length));
-  return CLI_COMMAND_CATALOG.map((command) => `  ${command.name.padEnd(width)}  ${command.summary}`).join("\n");
+function renderCliCommandList(advanced = false) {
+  const commands = advanced ? CLI_COMMAND_CATALOG : CLI_COMMAND_CATALOG.filter((command) => CORE_COMMAND_NAMES[command.name]);
+  const width = Math.max(...commands.map((command) => command.name.length));
+  return commands.map((command) => `  ${command.name.padEnd(width)}  ${command.summary}`).join("\n");
 }
-var CLI_COMMAND_CATALOG, commandByName, aliasToCommand, INTENT_ROUTES;
+var CLI_COMMAND_CATALOG, commandByName, aliasToCommand, INTENT_ROUTES, CORE_COMMAND_NAMES;
 var init_commandCatalog = __esm({
   "dist/cli/commandCatalog.js"() {
     "use strict";
@@ -74940,6 +75056,15 @@ var init_commandCatalog = __esm({
       { pattern: /^(configure|setup|agent)$/i, command: "codegraph install" },
       { pattern: /^(health|diagnose|check)$/i, command: "codegraph doctor" }
     ];
+    CORE_COMMAND_NAMES = {
+      doctor: true,
+      orient: true,
+      explore: true,
+      search: true,
+      file: true,
+      deps: true,
+      review: true
+    };
   }
 });
 
@@ -75042,7 +75167,7 @@ function helpTextForCommand(command, positionals) {
   }
   return void 0;
 }
-var CLI_TASK_HELP_TEXT, CLI_HELP_TEXT, LIFECYCLE_HELP_TEXT, AFFECTED_HELP_TEXT, INSTALL_HELP_TEXT, UNINSTALL_HELP_TEXT, SHARED_INDEX_OPTIONS_HELP, EXPLORE_HELP_TEXT, FILE_HELP_TEXT, SEARCH_HELP_TEXT, GOTO_HELP_TEXT, REFS_HELP_TEXT, GREP_HELP_TEXT, SQL_HELP_TEXT, SYMBOLS_HELP_TEXT, CALLERS_HELP_TEXT, CALLEES_HELP_TEXT, SUPERTYPES_HELP_TEXT, SUBTYPES_HELP_TEXT, IMPLEMENTATIONS_HELP_TEXT, RENAME_PREVIEW_HELP_TEXT, REFACTOR_PLAN_HELP_TEXT, ORIENT_HELP_TEXT, PACKET_HELP_TEXT, EXPLAIN_HELP_TEXT, ARTIFACT_HELP_TEXT, SERVER_HELP_TEXT, MCP_HELP_TEXT, MCP_SERVE_HELP_TEXT, DUPLICATES_HELP_TEXT, DRIFT_HELP_TEXT, VIEWER_HELP_TEXT, INDEX_HELP_TEXT, GRAPH_HELP_TEXT, REVIEW_HELP_TEXT, IMPACT_HELP_TEXT, INSPECT_HELP_TEXT, DEPS_HELP_TEXT, RDEPS_HELP_TEXT, PATH_HELP_TEXT, CYCLES_HELP_TEXT, HOTSPOTS_HELP_TEXT, UNRESOLVED_HELP_TEXT, LINKS_HELP_TEXT, APISURFACE_HELP_TEXT, GRAPH_DELTA_HELP_TEXT, DOCTOR_HELP_TEXT, CHUNK_HELP_TEXT, SKILL_HELP_TEXT, DUMPMOD_HELP_TEXT, VERSION_HELP_TEXT;
+var CLI_TASK_HELP_TEXT, CLI_HELP_TEXT, ADVANCED_HELP_TEXT, LIFECYCLE_HELP_TEXT, AFFECTED_HELP_TEXT, INSTALL_HELP_TEXT, UNINSTALL_HELP_TEXT, SHARED_INDEX_OPTIONS_HELP, EXPLORE_HELP_TEXT, FILE_HELP_TEXT, SEARCH_HELP_TEXT, GOTO_HELP_TEXT, REFS_HELP_TEXT, GREP_HELP_TEXT, SQL_HELP_TEXT, SYMBOLS_HELP_TEXT, CALLERS_HELP_TEXT, CALLEES_HELP_TEXT, SUPERTYPES_HELP_TEXT, SUBTYPES_HELP_TEXT, IMPLEMENTATIONS_HELP_TEXT, RENAME_PREVIEW_HELP_TEXT, REFACTOR_PLAN_HELP_TEXT, ORIENT_HELP_TEXT, PACKET_HELP_TEXT, EXPLAIN_HELP_TEXT, ARTIFACT_HELP_TEXT, SERVER_HELP_TEXT, MCP_HELP_TEXT, MCP_SERVE_HELP_TEXT, DUPLICATES_HELP_TEXT, DRIFT_HELP_TEXT, VIEWER_HELP_TEXT, INDEX_HELP_TEXT, GRAPH_HELP_TEXT, REVIEW_HELP_TEXT, IMPACT_HELP_TEXT, INSPECT_HELP_TEXT, DEPS_HELP_TEXT, RDEPS_HELP_TEXT, PATH_HELP_TEXT, CYCLES_HELP_TEXT, HOTSPOTS_HELP_TEXT, UNRESOLVED_HELP_TEXT, LINKS_HELP_TEXT, APISURFACE_HELP_TEXT, GRAPH_DELTA_HELP_TEXT, DOCTOR_HELP_TEXT, CHUNK_HELP_TEXT, SKILL_HELP_TEXT, DUMPMOD_HELP_TEXT, VERSION_HELP_TEXT;
 var init_help = __esm({
   "dist/cli/help.js"() {
     "use strict";
@@ -75069,9 +75194,11 @@ Start here:
 
 Usage: codegraph <command> [options] [path]
 
-Commands:
+Core commands:
 ${renderCliCommandList()}
 
+For the complete catalog, run: codegraph help advanced
+
 Graph Options:
   --fast-graph                Use text import extraction for plain .js and .ts
                               files. May miss multiline or complex patterns;
@@ -75170,6 +75297,11 @@ Examples:
   codegraph refactor-plan Service --rename RenamedService
   codegraph version
   codegraph -v
+`;
+    ADVANCED_HELP_TEXT = `codegraph - Complete command catalog
+
+Commands:
+${renderCliCommandList(true)}
 `;
     LIFECYCLE_HELP_TEXT = `codegraph init/status/sync/uninit - Initialize, inspect, refresh, or remove project-local Codegraph state
 
@@ -75266,20 +75398,20 @@ ${SHARED_INDEX_OPTIONS_HELP}
 `;
     GOTO_HELP_TEXT = `codegraph goto - Go to a definition
 
-Usage: codegraph goto <file>::<symbol> [--root <path>] [--json | --pretty]
+Usage: codegraph goto <file|file::symbol|symbol:...> [--root <path>] [--json | --pretty]
        codegraph goto <file>[:line[:column]] [line] [column] [--root <path>] [--json | --pretty]
 
-A qualified symbol path resolves one definition without a location. A file-only target succeeds when the file defines one symbol; otherwise JSON returns bounded candidates. Search-result locations and portable symbol handles can be pasted directly.
+A qualified symbol path or portable symbol handle resolves one definition without a location. A file-only target succeeds when the file defines one symbol; otherwise JSON returns bounded candidates. Search-result locations and portable symbol handles can be pasted directly.
 
 ${SHARED_INDEX_OPTIONS_HELP}
 `;
     REFS_HELP_TEXT = `codegraph refs - Find semantic references
 
-Usage: codegraph refs <file>::<symbol> [--root <path>] [--json | --pretty]
+Usage: codegraph refs <file|file::symbol|symbol:...> [--root <path>] [--json | --pretty]
        codegraph refs <file>[:line[:column]] [line] [column] [--root <path>] [--json | --pretty]
        codegraph refs --file <file> [--line <line> --col <column>] [--root <path>] [--json | --pretty]
 
-A qualified symbol path finds references for one declaration without a location. A file-only target finds references for every symbol defined in that file. Search-result locations and portable symbol handles can be pasted directly.
+A qualified symbol path or portable symbol handle resolves one definition and reports references to it without a location. A file-only target finds references for every definition in the file.
 
 ${SHARED_INDEX_OPTIONS_HELP}
 `;
@@ -75635,7 +75767,9 @@ ${SHARED_INDEX_OPTIONS_HELP}
 `;
     DEPS_HELP_TEXT = `codegraph deps - List file dependencies
 
-Usage: codegraph deps <file|file::symbol|symbol:...> [--root <path>] [--depth <n>] [--json | --pretty]
+Usage: codegraph deps <file|file::symbol|symbol:...> [--root <path>] [--depth <n> | --all] [--json | --pretty]
+
+By default, outputs dependencies through depth 1. Use --depth for another finite output depth, or --all to include every depth.
 
 A qualified symbol path or portable symbol handle uses its declaring file for file-graph traversal. Use callees for symbol-level call relationships.
 
@@ -75643,7 +75777,9 @@ ${SHARED_INDEX_OPTIONS_HELP}
 `;
     RDEPS_HELP_TEXT = `codegraph rdeps - List reverse file dependencies
 
-Usage: codegraph rdeps <file|file::symbol|symbol:...> [--root <path>] [--depth <n>] [--json | --pretty]
+Usage: codegraph rdeps <file|file::symbol|symbol:...> [--root <path>] [--depth <n> | --all] [--json | --pretty]
+
+By default, outputs reverse dependencies through depth 1. Use --depth for another finite output depth, or --all to include every depth.
 
 A qualified symbol path or portable symbol handle uses its declaring file for file-graph traversal. Use callers for symbol-level call relationships.
 
@@ -81735,8 +81871,17 @@ async function handleTypeHierarchyCommand(command, context) {
     context.writeStderrLine(helpText2(command).trimEnd());
     context.exit(2);
   }
+  let limit;
+  let depth;
+  try {
+    limit = parseBoundedIntegerOption(context.getOpt("--limit"), "--limit", DEFAULT_HIERARCHY_LIMIT2, 0, MAX_HIERARCHY_LIMIT2);
+    if (command !== "implementations") {
+      depth = parseBoundedIntegerOption(context.getOpt("--depth"), "--depth", DEFAULT_HIERARCHY_DEPTH, 1, MAX_HIERARCHY_DEPTH2);
+    }
+  } catch (error51) {
+    exitWithError(context, error51, 2);
+  }
   try {
-    const limit = parseBoundedIntegerOption(context.getOpt("--limit"), "--limit", DEFAULT_HIERARCHY_LIMIT2, 0, MAX_HIERARCHY_LIMIT2);
     if (command === "implementations") {
       const response2 = await findImplementations2({
         root: context.root,
@@ -81747,7 +81892,6 @@ async function handleTypeHierarchyCommand(command, context) {
       writeResponse(context, response2, formatImplementationsResponse);
       return;
     }
-    const depth = parseBoundedIntegerOption(context.getOpt("--depth"), "--depth", DEFAULT_HIERARCHY_DEPTH, 1, MAX_HIERARCHY_DEPTH2);
     const request = {
       root: context.root,
       handle,
@@ -81853,6 +81997,9 @@ async function handleExplainCommand(context) {
   } else {
     context.writeStdoutLine(formatAgentExplanation(response));
   }
+  if (response.target.kind === "not_found") {
+    context.exit(1);
+  }
 }
 var init_explain2 = __esm({
   "dist/cli/explain.js"() {
@@ -82140,10 +82287,10 @@ function buildFocusTargets(modules, packets, review) {
         kind: "hotspot",
         file: module2.file,
         why: `graph-central module: fan-in ${module2.fanIn}, fan-out ${module2.fanOut}, score ${module2.score}`,
-        followUps: [
+        followUps: dedupeAgentFollowUps([
           toolFollowUp("packet_get", { target: packet.file }),
           toolFollowUp("packet_get", { target: module2.file })
-        ]
+        ])
       });
       continue;
     }
@@ -98492,7 +98639,7 @@ var init_tools = __esm({
           limit: { type: "integer", minimum: 0, maximum: 50, default: 5 },
           maxPackets: { type: "integer", minimum: 0, maximum: 10, default: 3 },
           maxPaths: { type: "integer", minimum: 0, maximum: 10, default: 3 },
-          includeSource: { type: "boolean", default: true }
+          includeSource: { type: "boolean", default: false }
         }, ["query"]),
         dispatch: { handler: "explore" }
       },
@@ -99107,7 +99254,7 @@ function createCodegraphMcpHandlersForSession(options, session) {
       ...request.limit !== void 0 ? { limit: request.limit } : {},
       ...request.maxPackets !== void 0 ? { maxPackets: request.maxPackets } : {},
       ...request.maxPaths !== void 0 ? { maxPaths: request.maxPaths } : {},
-      ...request.includeSource !== void 0 ? { includeSource: request.includeSource } : {}
+      includeSource: request.includeSource ?? false
     })),
     orient: async (request) => await withFreshness(async () => await orientCodegraphWithSession(session, {
       root,
@@ -102676,11 +102823,82 @@ function toToolResult(value) {
     content: [
       {
         type: "text",
-        text: JSON.stringify(value, null, 2)
+        text: JSON.stringify(translateMcpFollowUps(value))
       }
     ]
   };
 }
+function translateMcpFollowUps(value) {
+  if (Array.isArray(value))
+    return translateFollowUpCollection(value);
+  if (typeof value !== "object" || value === null)
+    return value;
+  const source = value;
+  let translated;
+  for (const [key, nestedValue] of Object.entries(source)) {
+    const nestedTranslation = translateMcpFollowUps(nestedValue);
+    if (nestedTranslation === nestedValue)
+      continue;
+    translated ??= { ...source };
+    translated[key] = nestedTranslation;
+  }
+  return translateFollowUps(translated ?? source);
+}
+function translateFollowUpCollection(value) {
+  let translated;
+  for (const [index, entry] of value.entries()) {
+    const entryTranslation = translateMcpFollowUps(entry);
+    if (entryTranslation === entry) {
+      if (translated !== void 0)
+        translated.push(entry);
+      continue;
+    }
+    translated ??= [...value.slice(0, index)];
+    translated.push(entryTranslation);
+  }
+  return translated ?? value;
+}
+function translateFollowUps(value) {
+  const followUps = value.followUps;
+  if (!Array.isArray(followUps) || !followUps.every(isAgentFollowUp))
+    return value;
+  const translatedFollowUps = followUps.map(translateMcpFollowUp);
+  if (translatedFollowUps.every((followUp, index) => followUp === followUps[index]))
+    return value;
+  return { ...value, followUps: translatedFollowUps };
+}
+function isAgentFollowUp(value) {
+  return typeof value === "object" && value !== null && "tool" in value && typeof value.tool === "string" && "arguments" in value && typeof value.arguments === "object" && value.arguments !== null && !Array.isArray(value.arguments);
+}
+function translateMcpFollowUp(followUp) {
+  if (followUp.tool === "chunk")
+    return { ...followUp, tool: "get_file" };
+  if (followUp.tool === "duplicates") {
+    return {
+      ...followUp,
+      tool: "packet_get",
+      arguments: { target: firstDuplicateFile(followUp.arguments) }
+    };
+  }
+  if (followUp.tool === "explore" && followUp.arguments.includeSource === void 0) {
+    return {
+      ...followUp,
+      arguments: { ...followUp.arguments, includeSource: true }
+    };
+  }
+  if (followUp.tool === "impact" && followUp.arguments.provider === "git") {
+    const arguments_ = { ...followUp.arguments };
+    delete arguments_.provider;
+    return { ...followUp, arguments: arguments_ };
+  }
+  return followUp;
+}
+function firstDuplicateFile(arguments_) {
+  const files = arguments_.files;
+  if (!Array.isArray(files))
+    return ".";
+  return files.find((file2) => typeof file2 === "string") ?? ".";
+}
 function toToolErrorResult(error51) {
   const message = errorMessage(error51).replace(/(?:[A-Za-z]:)?[/\\][^'"\n]*?(?=(?:[/\\][^'"\n]*)?['"]|$)/g, "<path>");
   return { isError: true, content: [{ type: "text", text: message }] };
@@ -103344,7 +103562,7 @@ import path86 from "node:path";
 async function handleServerCommand(context) {
   const command = context.positionals[0];
   if (!isServerCommand(command)) {
-    context.writeStderrLine("Usage: codegraph server <start|status|stop> [--root <path>]");
+    context.writeStderrLine(getCliCommandUsage("server"));
     context.exit(2);
   }
   try {
@@ -104174,7 +104392,8 @@ var init_server2 = __esm({
         "--warmup",
         "--warmup-symbols",
         "--workers",
-        "--json"
+        "--json",
+        "--pretty"
       ],
       status: ["--json", "--pretty"],
       stop: []
@@ -104922,7 +105141,7 @@ async function handleGraphCommand(context) {
     ...cacheDir ? { cacheDir } : {},
     ...context.cacheLocation ? { cacheLocation: context.cacheLocation } : {}
   };
-  const stable = context.hasFlag("--stable");
+  const stable = true;
   let format = "mermaid";
   if (context.hasFlag("--json")) {
     format = "json";
@@ -106844,7 +107063,7 @@ function formatGotoOutput(projectRootFs, output) {
 async function handleDumpmodCommand(context) {
   const [fileArg] = context.positionals;
   if (!fileArg) {
-    context.writeStderrLine("Usage: dumpmod <file>");
+    context.writeStderrLine(getCliCommandUsage("dumpmod"));
     context.exit(2);
   }
   const resolvedFile = resolveCliProjectFile(context.projectRootFs, fileArg, "File");
@@ -106966,9 +107185,14 @@ function writePrettyReferences(context, result) {
   }
 }
 async function handleGotoCommand(context) {
-  const input = parseNavigationInput(context, false);
+  let input;
+  try {
+    input = parseNavigationInput(context, false);
+  } catch (error51) {
+    exitWithError(context, error51, 2);
+  }
   if (!input) {
-    context.writeStderrLine("Usage: goto <file>[:line[:column]] [line] [column]");
+    context.writeStderrLine(getCliCommandUsage("goto"));
     context.exit(2);
   }
   const resolvedFile = resolveCliProjectFile(context.projectRootFs, input.file, "File");
@@ -107021,9 +107245,14 @@ async function handleGotoCommand(context) {
     context.exit(1);
 }
 async function handleRefsCommand(context) {
-  const input = parseNavigationInput(context, true);
+  let input;
+  try {
+    input = parseNavigationInput(context, true);
+  } catch (error51) {
+    exitWithError(context, error51, 2);
+  }
   if (!input) {
-    context.writeStderrLine("Usage: refs <file>[:line[:column]] [line] [column] OR refs --file <file> [--line <line> --col <column>]");
+    context.writeStderrLine(getCliCommandUsage("refs"));
     context.exit(2);
   }
   const pretty = !context.hasFlag("--json");
@@ -107109,6 +107338,7 @@ var init_navigation3 = __esm({
     init_location2();
     init_projectFile();
     init_pretty();
+    init_context();
   }
 });
 
@@ -107260,7 +107490,7 @@ async function handleGrepCommand(context) {
     exitWithError(context, error51, 2);
   }
   if ((querySource ? 1 : 0) + (patternSource ? 1 : 0) !== 1) {
-    context.writeStderrLine("Usage: grep <regex> [--root <dir>] OR grep --query '<tree-sitter query>' [--root <dir>]");
+    context.writeStderrLine(getCliCommandUsage("grep"));
     context.exit(2);
   }
   if (querySource && maxHits !== void 0) {
@@ -108172,7 +108402,7 @@ function deletedPathsForChange2(change2) {
 async function buildAffectedReportFromContext(context) {
   const inputs = await collectChangedFileInputs(context);
   if (!inputs.files.length) {
-    throw new Error("Usage: codegraph affected <file...> [--stdin] [--base <ref> --head <ref>] [--root <path>]");
+    throw new Error(getCliCommandUsage("affected"));
   }
   const normalizedChangedFiles = Array.from(new Set(inputs.files.map((input) => normalizeChangedFileInput(context.projectRootFs, input)))).sort();
   const normalizedDeletedFiles = Array.from(new Set(inputs.deletedFiles.map((input) => normalizeChangedFileInput(context.projectRootFs, input)))).sort();
@@ -108568,10 +108798,15 @@ async function loadGraph(context) {
 async function handleDepsCommand(context) {
   const [fileArg] = context.positionals;
   if (!fileArg) {
-    context.writeStderrLine(`Usage: ${context.command} <file|file::symbol|symbol:...> [--depth N] [--json]`);
+    context.writeStderrLine(getCliCommandUsage(context.command));
     context.exit(2);
   }
   const depthRaw = context.getOpt("--depth");
+  const all = context.hasFlag("--all");
+  if (all && depthRaw !== void 0) {
+    context.writeStderrLine("--all cannot be combined with --depth.");
+    context.exit(2);
+  }
   let depth;
   try {
     depth = parseOptionalNonNegativeIntegerOption(depthRaw, "--depth");
@@ -108648,18 +108883,21 @@ async function handleDepsCommand(context) {
     context.exit(1);
   }
   targetFile = matchedGraphNode;
-  const results = context.command === "deps" ? getDependencies(loaded.graph, targetFile, {
-    ...depth !== void 0 ? { depth } : {},
-    ...loaded.adjacency ? { adjacency: loaded.adjacency } : {}
-  }) : getReverseDependencies(loaded.graph, targetFile, {
-    ...depth !== void 0 ? { depth } : {},
-    ...loaded.adjacency ? { adjacency: loaded.adjacency } : {}
-  });
+  const effectiveDepth = depth ?? 1;
+  const traversalOptions = {
+    ...loaded.adjacency ? { adjacency: loaded.adjacency } : {},
+    ...json3 && !all ? { depth: effectiveDepth + 1 } : {}
+  };
+  const allResults = context.command === "deps" ? getDependencies(loaded.graph, targetFile, traversalOptions) : getReverseDependencies(loaded.graph, targetFile, traversalOptions);
+  const results = all ? allResults : allResults.filter((result) => result.depth <= effectiveDepth);
+  const truncated = results.length !== allResults.length;
+  const omittedCount = allResults.length - results.length;
   if (json3) {
-    context.writeJSONLine(results);
+    context.writeJSONLine({ items: results, truncated });
     return;
   }
-  context.writeStdoutLine(`${context.command === "deps" ? "Dependencies" : "Reverse dependencies"} for ${fileArg}:`);
+  const depthDescription = all ? "all depths" : `depth ${effectiveDepth}`;
+  context.writeStdoutLine(`${context.command === "deps" ? "Dependencies" : "Reverse dependencies"} for ${fileArg} (${depthDescription}; ${omittedCount} omitted):`);
   for (const result of results) {
     const rel = toProjectDisplayPath(context.projectRootFs, result.file);
     context.writeStdoutLine(`${"  ".repeat(result.depth)} ${rel} (depth ${result.depth})`);
@@ -108668,7 +108906,7 @@ async function handleDepsCommand(context) {
 async function handlePathCommand(context) {
   const [fromArg, toArg] = context.positionals;
   if (!fromArg || !toArg) {
-    context.writeStderrLine("Usage: path <from-file> <to-file> [--json]");
+    context.writeStderrLine(getCliCommandUsage("path"));
     context.exit(2);
   }
   const json3 = context.hasFlag("--json");
@@ -109932,10 +110170,7 @@ function resolveCliRootPolicy(input) {
     if (!isLegacyImpactRoot) {
       return {
         status: "error",
-        messages: [
-          `Unexpected positional argument for impact: ${impactRootArg}`,
-          "Usage: codegraph impact [project-root] [--provider git|github|raw] [options]"
-        ]
+        messages: [`Unexpected positional argument for impact: ${impactRootArg}`, getCliCommandUsage("impact")]
       };
     }
   }
@@ -110028,6 +110263,7 @@ var init_rootPolicy = __esm({
   "dist/cli/rootPolicy.js"() {
     "use strict";
     init_paths();
+    init_options();
     WINDOWS_DRIVE_QUALIFIED_PATTERN = /^[A-Za-z]:[\\/]/;
     WINDOWS_DRIVE_RELATIVE_ROOT_PATTERN = /^[\\/](?![\\/])/;
   }
@@ -110804,6 +111040,10 @@ async function runCliWithActiveRuntime(rawArgs) {
       writeStdoutLine(CLI_HELP_TEXT.trimEnd());
       return;
     }
+    if (command === "advanced") {
+      writeStdoutLine(ADVANCED_HELP_TEXT.trimEnd());
+      return;
+    }
     if (!isKnownCliCommand(command)) {
       writeStderrLine(`Unknown command "${command}".`);
       const suggestions = suggestCliCommands(command);