@wrongstack/tools 0.305.1 → 0.306.2

package/dist/codebase-index/codebase-search-tool.d.ts

@@ -17,6 +17,11 @@
  */
 import type { Tool } from '@wrongstack/core/types';
 import type { SearchResult } from './schema.js';
+/**
+ * Language ids the index understands. Single source for the `lang` enum here
+ * and the `langs` validation in codebase-index-tool.ts.
+ */
+export declare const INDEXABLE_LANG_IDS: readonly ['ts', 'tsx', 'js', 'jsx', 'go', 'py', 'rs', 'json', 'yaml'];
 export declare const codebaseSearchTool: Tool<CodebaseSearchInput, CodebaseSearchOutput>;
 interface CodebaseSearchInput {
     query: string;

package/dist/codebase-index/index.js

@@ -8491,6 +8491,160 @@ function ensureCodebaseIndexServer(options) {
 }
 
 // src/codebase-index/codebase-index-tool.ts
+import { ToolValidationError } from "@wrongstack/core/types";
+
+// src/codebase-index/codebase-search-tool.ts
+import { toErrorMessage as toErrorMessage2 } from "@wrongstack/core/utils";
+var INDEXABLE_LANG_IDS = [
+  "ts",
+  "tsx",
+  "js",
+  "jsx",
+  "go",
+  "py",
+  "rs",
+  "json",
+  "yaml"
+];
+var codebaseSearchTool = {
+  name: "codebase-search",
+  category: "Project",
+  icon: "index",
+  description: "Search code symbols using a fast SQLite+BM25 index, with optional LSP fallback. Prefer this before broad `tree`, `glob`, or `grep` exploration when finding code by name or concept. Use `grep` instead for exact text, regexes, unsupported content, or concrete usage sites. Set `preferLsp: true` for live precision when the LSP plugin is active (supersedes codebase-lsp-search).",
+  usageHint: "FIRST CHOICE FOR INDEXABLE CODE UNDERSTANDING:\n\n- Call before broad `tree`, `glob`, or `grep` exploration when locating symbols, concepts, definitions, or candidate modules.\n- `kind` filter is very useful (e.g. only functions or only interfaces).\n- Combine with `file` filter to scope to a specific directory or module.\n- If `indexStatus` reports no persisted data, run `codebase-index` and retry.",
+  permission: "auto",
+  mutating: false,
+  capabilities: ["fs.read"],
+  // The index host has its own 30s read watchdog. Leave enough headroom for
+  // worker teardown and structured timeout reporting.
+  timeoutMs: 35e3,
+  inputSchema: {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        description: "Search query \u2014 searches symbol names, signatures, and doc comments"
+      },
+      kind: {
+        type: "string",
+        enum: [
+          "class",
+          "interface",
+          "enum",
+          "type",
+          "function",
+          "method",
+          "var",
+          "const",
+          "let",
+          "property",
+          "parameter",
+          "namespace",
+          "object",
+          "literal",
+          "schema",
+          "struct",
+          "trait",
+          "impl",
+          "static",
+          "mod"
+        ],
+        description: "Filter by indexed symbol kind"
+      },
+      lang: {
+        type: "string",
+        enum: [...INDEXABLE_LANG_IDS],
+        description: "Filter by indexed language"
+      },
+      lspKind: {
+        type: "integer",
+        description: "Filter by LSP SymbolKind number (e.g. 5=Class, 12=Function, 11=Interface, 10=Enum)"
+      },
+      file: {
+        type: "string",
+        description: "Filter to files matching this path substring"
+      },
+      limit: {
+        type: "integer",
+        description: "Maximum results to return (default 20, max 100)",
+        minimum: 1,
+        maximum: 100
+      },
+      preferLsp: {
+        type: "boolean",
+        description: "Prefer live LSP results over the index. Ignored unless the LSP plugin is active; when it is active and this is true, results come from live workspaceSymbol queries."
+      }
+    },
+    required: ["query"]
+  },
+  async execute(input, ctx, execOpts) {
+    const state = getIndexState();
+    if (state.indexing && !state.ready) {
+      return {
+        results: [],
+        total: 0,
+        query: input.query,
+        indexStatus: `Indexing in progress (${state.currentFile}/${state.totalFiles} files) \u2014 retry in a moment.`
+      };
+    }
+    if (state.lastError) {
+      const circuit = state.circuit;
+      const retryHint = circuit.state === "open" ? `Indexing is paused (circuit open, retry in ${Math.ceil(circuit.cooldownRemainingMs / 1e3)}s); the user can run /codebase-reindex to retry now.` : "Try /codebase-reindex.";
+      return {
+        results: [],
+        total: 0,
+        query: input.query,
+        indexStatus: `Index build failed: ${state.lastError}. ${retryHint}`
+      };
+    }
+    const limit = Math.max(1, Math.min(Math.trunc(input.limit ?? 20), 100));
+    let searched;
+    try {
+      searched = await searchCodebaseIndex(
+        {
+          projectRoot: ctx.projectRoot,
+          indexDir: codebaseIndexDirOverride(ctx),
+          query: input.query,
+          kind: input.kind?.toLowerCase(),
+          lang: input.lang?.toLowerCase(),
+          file: input.file,
+          lspKind: input.lspKind,
+          limit
+        },
+        { signal: execOpts?.signal }
+      );
+    } catch (err) {
+      if (execOpts?.signal?.aborted) throw err;
+      return {
+        results: [],
+        total: 0,
+        query: input.query,
+        indexStatus: `Index query failed: ${toErrorMessage2(err)}. Fall back to grep/glob for this lookup.`
+      };
+    }
+    const { results, total } = searched;
+    let hasPersistedIndex = state.ready || total > 0;
+    if (!hasPersistedIndex) {
+      try {
+        const stats = await codebaseIndexStats(
+          { projectRoot: ctx.projectRoot, indexDir: codebaseIndexDirOverride(ctx) },
+          { signal: execOpts?.signal }
+        );
+        hasPersistedIndex = stats.totalFiles > 0 || stats.lastIndexed !== null;
+      } catch {
+      }
+    }
+    return {
+      results,
+      total,
+      query: input.query,
+      ...hasPersistedIndex ? {} : { indexStatus: "No persisted index data found. Run codebase-index to build it." }
+    };
+  }
+};
+
+// src/codebase-index/codebase-index-tool.ts
+var MAX_REPORTED_ERRORS = 20;
 var codebaseIndexTool = {
   name: "codebase-index",
   category: "Project",
@@ -8516,12 +8670,23 @@ var codebaseIndexTool = {
       },
       langs: {
         type: "array",
-        items: { type: "string" },
-        description: "Limit reindex to specific languages: ts, tsx, js, jsx, go, py, rs"
+        items: { type: "string", enum: [...INDEXABLE_LANG_IDS] },
+        description: `Limit reindex to specific languages: ${INDEXABLE_LANG_IDS.join(", ")}`
       }
     }
   },
   async execute(input, ctx, execOpts) {
+    if (input.langs) {
+      const unknown = input.langs.filter(
+        (lang) => !INDEXABLE_LANG_IDS.includes(lang)
+      );
+      if (unknown.length > 0) {
+        throw new ToolValidationError({
+          message: `codebase-index: unknown lang(s) ${unknown.map((l) => `"${l}"`).join(", ")}. Valid ids: ${INDEXABLE_LANG_IDS.join(", ")}.`,
+          field: "langs"
+        });
+      }
+    }
     if (isIndexing()) {
       return {
         filesIndexed: 0,
@@ -8543,23 +8708,32 @@ var codebaseIndexTool = {
         note: `Codebase indexing is paused after repeated failures (last: ${circuit.lastFailure ?? "unknown"}). Auto-retry possible in ${Math.ceil(circuit.cooldownRemainingMs / 1e3)}s; the user can run /codebase-reindex to retry immediately.`
       };
     }
-    return await runStartupIndex({
+    const result = await runStartupIndex({
       projectRoot: ctx.projectRoot,
       force: input.force ?? false,
       langs: input.langs,
       indexDir: codebaseIndexDirOverride(ctx),
       signal: execOpts?.signal
     });
+    if (result.errors.length > MAX_REPORTED_ERRORS) {
+      const hidden = result.errors.length - MAX_REPORTED_ERRORS;
+      return {
+        ...result,
+        errors: [...result.errors.slice(0, MAX_REPORTED_ERRORS), `+${hidden} more`]
+      };
+    }
+    return result;
   }
 };
 
 // src/codebase-index/codebase-incoming-calls-tool.ts
+import { toErrorMessage as toErrorMessage3 } from "@wrongstack/core/utils";
 var codebaseIncomingCallsTool = {
   name: "codebase-incoming-calls",
   category: "Project",
   icon: "index",
-  description: "Find all callers of a function, method, or symbol \u2014 who invokes or references it. Uses the codebase index ref graph for instant, exact results. Always use this instead of grep when checking impact of a change.",
-  usageHint: 'CALL THIS BEFORE REFACTORING OR CHANGING ANY FUNCTION:\n\n- NEVER use grep or manual line reading to check where a function is called.\n- ALWAYS call codebase-incoming-calls({ symbol: "funcName" }) first.\n- Returns exact files, line numbers, caller signatures, and call types in milliseconds.\n- Use `file` to disambiguate when multiple symbols share a name.\n- Combine with codebase-outgoing-calls to see what the symbol itself calls.\nIf the index is not built, run codebase-index first.',
+  description: "Find all callers of a function, method, or symbol \u2014 who invokes or references it. Uses the codebase index ref graph for instant, exact results. Prefer this over grep for change-impact checks when the index is available.",
+  usageHint: 'CALL THIS BEFORE REFACTORING OR CHANGING ANY FUNCTION:\n\n- Prefer this over grep when the index is available; fall back to grep when the index is cold/unavailable or for dynamic dispatch the ref graph cannot see.\n- Call codebase-incoming-calls({ symbol: "funcName" }) before editing the symbol.\n- Returns exact files, line numbers, caller signatures, and call types in milliseconds.\n- Use `file` to disambiguate when multiple symbols share a name.\n- Combine with codebase-outgoing-calls to see what the symbol itself calls.\nIf the index is not built, run codebase-index first.',
   permission: "auto",
   mutating: false,
   capabilities: ["fs.read"],
@@ -8611,16 +8785,27 @@ var codebaseIncomingCallsTool = {
     }
     const limit = Math.max(1, Math.min(Math.trunc(input.limit ?? 50), 200));
     const transitive = input.transitive === true;
-    const { calls, symbolFound, ambiguous, totalMatches } = await incomingCallsService2(
-      {
-        projectRoot: ctx.projectRoot,
-        indexDir: codebaseIndexDirOverride(ctx),
+    let serviced;
+    try {
+      serviced = await incomingCallsService2(
+        {
+          projectRoot: ctx.projectRoot,
+          indexDir: codebaseIndexDirOverride(ctx),
+          symbol: input.symbol,
+          file: input.file,
+          limit,
+          transitive
+        }
+      );
+    } catch (err) {
+      return {
         symbol: input.symbol,
-        file: input.file,
-        limit,
-        transitive
-      }
-    );
+        calls: [],
+        total: 0,
+        indexStatus: `Index query failed: ${toErrorMessage3(err)}. Fall back to grep for this lookup.`
+      };
+    }
+    const { calls, symbolFound, ambiguous, totalMatches } = serviced;
     if (!symbolFound) {
       let hasPersistedIndex = state.ready;
       if (!hasPersistedIndex) {
@@ -8665,12 +8850,13 @@ var codebaseIncomingCallsTool = {
 };
 
 // src/codebase-index/codebase-outgoing-calls-tool.ts
+import { toErrorMessage as toErrorMessage4 } from "@wrongstack/core/utils";
 var codebaseOutgoingCallsTool = {
   name: "codebase-outgoing-calls",
   category: "Project",
   icon: "index",
   description: "Find all functions/methods/symbols that a given symbol calls or depends on \u2014 its callees. Uses the codebase index ref graph for instant, exact results. Use this to understand a function's dependencies before modifying it.",
-  usageHint: 'USE THIS TO UNDERSTAND A FUNCTION\'S DEPENDENCIES:\n\n- Call codebase-outgoing-calls({ symbol: "funcName" }) to see everything it calls.\n- Returns exact files, line numbers, callee signatures, and call types in milliseconds.\n- Use `file` to disambiguate when multiple symbols share a name.\n- Pair with codebase-incoming-calls for a complete impact picture: incoming = who calls you, outgoing = what you call.\nIf the index is not built, run codebase-index first.',
+  usageHint: 'USE THIS TO UNDERSTAND A FUNCTION\'S DEPENDENCIES:\n\n- Prefer this over grep when the index is available; fall back to grep when the index is cold/unavailable or for dynamic dispatch the ref graph cannot see.\n- Call codebase-outgoing-calls({ symbol: "funcName" }) to see everything it calls.\n- Returns exact files, line numbers, callee signatures, and call types in milliseconds.\n- Use `file` to disambiguate when multiple symbols share a name.\n- Pair with codebase-incoming-calls for a complete impact picture: incoming = who calls you, outgoing = what you call.\nIf the index is not built, run codebase-index first.',
   permission: "auto",
   mutating: false,
   capabilities: ["fs.read"],
@@ -8722,16 +8908,27 @@ var codebaseOutgoingCallsTool = {
     }
     const limit = Math.max(1, Math.min(Math.trunc(input.limit ?? 50), 200));
     const transitive = input.transitive === true;
-    const { calls, symbolFound, unresolvedCount, totalMatches } = await outgoingCallsService2(
-      {
-        projectRoot: ctx.projectRoot,
-        indexDir: codebaseIndexDirOverride(ctx),
+    let serviced;
+    try {
+      serviced = await outgoingCallsService2(
+        {
+          projectRoot: ctx.projectRoot,
+          indexDir: codebaseIndexDirOverride(ctx),
+          symbol: input.symbol,
+          file: input.file,
+          limit,
+          transitive
+        }
+      );
+    } catch (err) {
+      return {
         symbol: input.symbol,
-        file: input.file,
-        limit,
-        transitive
-      }
-    );
+        calls: [],
+        total: 0,
+        indexStatus: `Index query failed: ${toErrorMessage4(err)}. Fall back to grep for this lookup.`
+      };
+    }
+    const { calls, symbolFound, unresolvedCount, totalMatches } = serviced;
     if (!symbolFound) {
       let hasPersistedIndex = state.ready;
       if (!hasPersistedIndex) {
@@ -8775,132 +8972,6 @@ var codebaseOutgoingCallsTool = {
   }
 };
 
-// src/codebase-index/codebase-search-tool.ts
-var codebaseSearchTool = {
-  name: "codebase-search",
-  category: "Project",
-  icon: "index",
-  description: "Search code symbols using a fast SQLite+BM25 index, with optional LSP fallback. Prefer this before broad `tree`, `glob`, or `grep` exploration when finding code by name or concept. Set `preferLsp: true` for live precision when the LSP plugin is active (supersedes codebase-lsp-search).",
-  usageHint: "FIRST CHOICE FOR INDEXABLE CODE UNDERSTANDING:\n\n- Call before broad `tree`, `glob`, or `grep` exploration when locating symbols, concepts, definitions, or candidate modules.\n- `kind` filter is very useful (e.g. only functions or only interfaces).\n- Combine with `file` filter to scope to a specific directory or module.\n- If `indexStatus` reports no persisted data, run `codebase-index` and retry.\nUse `grep` afterwards for exact text, regexes, unsupported content, or concrete usage sites.",
-  permission: "auto",
-  mutating: false,
-  capabilities: ["fs.read"],
-  // The index host has its own 30s read watchdog. Leave enough headroom for
-  // worker teardown and structured timeout reporting.
-  timeoutMs: 35e3,
-  inputSchema: {
-    type: "object",
-    properties: {
-      query: {
-        type: "string",
-        description: "Search query \u2014 searches symbol names, signatures, and doc comments"
-      },
-      kind: {
-        type: "string",
-        enum: [
-          "class",
-          "interface",
-          "enum",
-          "type",
-          "function",
-          "method",
-          "var",
-          "const",
-          "let",
-          "property",
-          "parameter",
-          "namespace",
-          "object",
-          "literal",
-          "schema",
-          "struct",
-          "trait",
-          "impl",
-          "static",
-          "mod"
-        ],
-        description: "Filter by indexed symbol kind"
-      },
-      lang: {
-        type: "string",
-        enum: ["ts", "tsx", "js", "jsx", "go", "py", "rs", "json", "yaml"],
-        description: "Filter by indexed language"
-      },
-      lspKind: {
-        type: "integer",
-        description: "Filter by LSP SymbolKind number (e.g. 5=Class, 12=Function, 11=Interface, 10=Enum)"
-      },
-      file: {
-        type: "string",
-        description: "Filter to files matching this path substring"
-      },
-      limit: {
-        type: "integer",
-        description: "Maximum results to return (default 20, max 100)",
-        minimum: 1,
-        maximum: 100
-      },
-      preferLsp: {
-        type: "boolean",
-        description: "Prefer live LSP results over the index. Index-only when the LSP plugin is not active. When the LSP plugin is active and this is true, results come from live workspaceSymbol queries."
-      }
-    },
-    required: ["query"]
-  },
-  async execute(input, ctx, execOpts) {
-    const state = getIndexState();
-    if (state.indexing && !state.ready) {
-      return {
-        results: [],
-        total: 0,
-        query: input.query,
-        indexStatus: `Indexing in progress (${state.currentFile}/${state.totalFiles} files) \u2014 retry in a moment.`
-      };
-    }
-    if (state.lastError) {
-      const circuit = state.circuit;
-      const retryHint = circuit.state === "open" ? `Indexing is paused (circuit open, retry in ${Math.ceil(circuit.cooldownRemainingMs / 1e3)}s); the user can run /codebase-reindex to retry now.` : "Try /codebase-reindex.";
-      return {
-        results: [],
-        total: 0,
-        query: input.query,
-        indexStatus: `Index build failed: ${state.lastError}. ${retryHint}`
-      };
-    }
-    const limit = Math.max(1, Math.min(Math.trunc(input.limit ?? 20), 100));
-    const { results, total } = await searchCodebaseIndex(
-      {
-        projectRoot: ctx.projectRoot,
-        indexDir: codebaseIndexDirOverride(ctx),
-        query: input.query,
-        kind: input.kind?.toLowerCase(),
-        lang: input.lang?.toLowerCase(),
-        file: input.file,
-        lspKind: input.lspKind,
-        limit
-      },
-      { signal: execOpts?.signal }
-    );
-    let hasPersistedIndex = state.ready || total > 0;
-    if (!hasPersistedIndex) {
-      try {
-        const stats = await codebaseIndexStats(
-          { projectRoot: ctx.projectRoot, indexDir: codebaseIndexDirOverride(ctx) },
-          { signal: execOpts?.signal }
-        );
-        hasPersistedIndex = stats.totalFiles > 0 || stats.lastIndexed !== null;
-      } catch {
-      }
-    }
-    return {
-      results,
-      total,
-      query: input.query,
-      ...hasPersistedIndex ? {} : { indexStatus: "No persisted index data found. Run codebase-index to build it." }
-    };
-  }
-};
-
 // src/codebase-index/codebase-stats-tool.ts
 var codebaseStatsTool = {
   name: "codebase-stats",
@@ -8994,9 +9065,9 @@ import * as path14 from "node:path";
 var deadCodeScanTool = {
   name: "dead-code-scan",
   category: "Project",
-  icon: "search",
+  icon: "index",
   description: "Scan TypeScript/JavaScript source files for exported symbols that appear unused anywhere in the project. Uses the codebase-index reference graph (import/call/type-ref edges) to compute transitive reachability from package.json entry points. Requires a built codebase-index (run `codebase-index` first if you get no results).",
-  usageHint: 'PASS `path` TO SCOPE THE SCAN:\n\n- Defaults to the project root (all indexed files).\n- `path` can be a directory to scope the scan (e.g. "src/util/").\n- `entryPoints` overrides auto-detected entry points (comma-separated file paths).\n\nThe scan runs against the existing index; results are best-effort.',
+  usageHint: "SCANS ALL INDEXED FILES UNDER THE PROJECT ROOT:\n\n- `projectRoot` defaults to the current project root; `indexDir` overrides the resolved index location.\n- `entryPoints` is an array of file paths that AUGMENTS the auto-discovered entry points (package.json bin/main/exports/types plus conventional src/index.ts-style files) \u2014 it does not replace them.\n\nThe scan runs against the existing index; results are best-effort (dynamic imports, external consumers, and config-driven registration are invisible).",
   permission: "auto",
   mutating: false,
   capabilities: ["fs.read"],

package/dist/codebase-index/project-server.js

@@ -2713,7 +2713,8 @@ import {
   useDaemonPerfDefaults,
   watchProjectTree
 } from "@wrongstack/core/utils";
-import { bindProjectEndpoint } from "@wrongstack/persistence";
+import { restrictFilePermissions } from "@wrongstack/core/security";
+import { atomicWrite, bindProjectEndpoint } from "@wrongstack/persistence";
 
 // src/codebase-index/indexer.ts
 import { expectDefined as expectDefined5 } from "@wrongstack/core/utils";
@@ -7785,18 +7786,16 @@ function removeMetadataIfOwned() {
   } catch {
   }
 }
-function writeMetadata() {
+async function writeMetadata() {
   fs11.mkdirSync(path14.dirname(metadataPath), { recursive: true });
-  const temporary = `${metadataPath}.${process.pid}.tmp`;
   const metadata = { ...serverInfo, authToken };
-  fs11.writeFileSync(temporary, `${JSON.stringify(metadata, null, 2)}
+  await atomicWrite(metadataPath, `${JSON.stringify(metadata, null, 2)}
 `, { mode: 384 });
-  try {
-    fs11.renameSync(temporary, metadataPath);
-  } catch {
-    fs11.rmSync(metadataPath, { force: true });
-    fs11.renameSync(temporary, metadataPath);
-  }
+  await restrictFilePermissions(metadataPath, {
+    label: "codebase-index-metadata",
+    warn: (message) => process.stderr.write(`${message}
+`)
+  });
 }
 var server = net.createServer((socket) => {
   if (idleTimer) clearTimeout(idleTimer);
@@ -7893,7 +7892,7 @@ void (async () => {
 `);
     process.exitCode = 1;
   });
-  writeMetadata();
+  await writeMetadata();
   markMetadataWritten?.();
   scheduleIdleStop();
 })();

package/dist/diff.d.ts

@@ -12,7 +12,12 @@ interface DiffOutput {
     diff: string;
     files: string[];
     truncated: boolean;
+    /**
+     * The format actually produced: 'unified' or 'stat' on the git path,
+     * 'dump' on the files-only line-numbered dump path.
+     */
     mode: string;
+    note?: string | undefined;
 }
 export declare const diffTool: Tool<DiffInput, DiffOutput>;
 export {};