@wrongstack/tools 0.73.1 → 0.77.0

package/dist/{background-indexer-sbsseCCC.d.ts → background-indexer-C70RD7LU.d.ts}

@@ -11,6 +11,8 @@ interface CodebaseIndexOutput {
     langStats: Record<string, number>;
     durationMs: number;
     errors: string[];
+    /** Advisory note when the indexer was skipped (e.g. another index in progress). */
+    note?: string;
 }
 
 /** Language a symbol belongs to. */
@@ -122,6 +124,8 @@ interface CodebaseSearchOutput {
     results: SearchResult[];
     total: number;
     query: string;
+    /** Non-empty when the index blocked the search (not ready, indexing, failed). */
+    indexStatus?: string;
 }
 
 /**
@@ -142,6 +146,8 @@ interface CodebaseStatsOutput {
     sizeBytes: number;
     indexPath: string;
     version: number;
+    /** Non-empty when the index is not ready or is still building. */
+    indexStatus?: string;
 }
 
 /**
@@ -159,17 +165,43 @@ interface CodebaseStatsOutput {
  * 2. **Debounce** — rapid successive edits to the same file (editor autosave,
  *    multi-edit) coalesce into a single reindex, keyed per `(indexDir, file)`.
  *
+ * 3. **State tracking** — exposes whether the initial index has completed (`ready`)
+ *    and whether a build is in progress (`indexing`), so downstream tools
+ *    (codebase-search, codebase-stats) can gate on it and UIs can show progress.
+ *
  * `runIndexer` only reads `opts` (and ignores its `_ctx` parameter), so callers
  * outside the agent loop pass a minimal stub cast to the expected shape — no
  * live agent `Context` is required.
  */
 
+/** True once the first full-project index has completed (success or failure). */
+declare function isIndexReady(): boolean;
+/** True while an index build is actively running. */
+declare function isIndexing(): boolean;
+/** Current indexing progress: { currentFile, totalFiles, ready, indexing }. */
+declare function getIndexState(): {
+    ready: boolean;
+    indexing: boolean;
+    currentFile: number;
+    totalFiles: number;
+    lastError: string | null;
+};
+/**
+ * Optional callback fired on every lifecycle transition (started, progress,
+ * completed, failed). Plug into the event bus or a TUI dispatcher to surface
+ * the indexing state in real time.
+ */
+type IndexStateListener = (state: ReturnType<typeof getIndexState>) => void;
+declare function onIndexStateChange(listener: IndexStateListener): () => void;
 /** True when the file's extension maps to a language the indexer can parse. */
 declare function isIndexableFile(filePath: string): boolean;
 /**
  * Run a full-project scan and await it. Used at session start and by the manual
  * `/codebase-reindex` command. Incremental by default (unchanged files skipped
  * via mtime, so repeat runs are cheap); pass `force` to clear and rebuild.
+ *
+ * Sets the global `_ready` flag on completion so downstream tools know the
+ * index is usable.
  */
 declare function runStartupIndex(opts: {
     projectRoot: string;
@@ -192,4 +224,4 @@ declare function enqueueReindex(opts: {
 /** Cancel all pending debounced reindexes. For teardown / tests. */
 declare function cancelPendingReindexes(): void;
 
-export { type FileMeta as F, type IndexResult as I, type Ref as R, SCHEMA_VERSION as S, type FileSymbols as a, type IndexStats as b, type SearchResult as c, type Symbol as d, type SymbolKind as e, type SymbolLang as f, cancelPendingReindexes as g, codebaseIndexTool as h, codebaseSearchTool as i, codebaseStatsTool as j, enqueueReindex as k, isIndexableFile as l, runStartupIndex as r };
+export { type FileMeta as F, type IndexResult as I, type Ref as R, SCHEMA_VERSION as S, type FileSymbols as a, type IndexStats as b, type SearchResult as c, type Symbol as d, type SymbolKind as e, type SymbolLang as f, cancelPendingReindexes as g, codebaseIndexTool as h, codebaseSearchTool as i, codebaseStatsTool as j, enqueueReindex as k, getIndexState as l, isIndexReady as m, isIndexableFile as n, isIndexing as o, onIndexStateChange as p, runStartupIndex as r };

package/dist/builtin.js

@@ -2676,7 +2676,41 @@ async function loadGitignoreMatcher(projectRoot) {
   return compileGitignore(lines);
 }
 
+// src/codebase-index/background-indexer.ts
+var _ready = false;
+var _indexing = false;
+var _currentFile = 0;
+var _totalFiles = 0;
+var _lastError = null;
+function setIndexReady() {
+  _ready = true;
+}
+function getIndexState() {
+  return {
+    ready: _ready,
+    indexing: _indexing,
+    currentFile: _currentFile,
+    totalFiles: _totalFiles,
+    lastError: _lastError
+  };
+}
+var _listeners = [];
+function emitState() {
+  const state = getIndexState();
+  for (const l of _listeners) l(state);
+}
+function _setIndexProgress(current, total) {
+  _currentFile = current;
+  _totalFiles = total;
+  emitState();
+}
+Promise.resolve();
+
 // src/codebase-index/indexer.ts
+var YIELD_EVERY_N = 50;
+function yieldEventLoop() {
+  return new Promise((resolve7) => setImmediate(resolve7));
+}
 var DEFAULT_IGNORE = [
   "node_modules",
   ".git",
@@ -2780,7 +2814,12 @@ async function runIndexer(_ctx, opts) {
   if (!force) {
     for (const meta of store.getAllFileMetas()) existingMeta.set(meta.file, meta);
   }
-  for (const file of files) {
+  for (let fi = 0; fi < files.length; fi++) {
+    const file = files[fi];
+    _setIndexProgress(fi + 1, files.length);
+    if (fi > 0 && fi % YIELD_EVERY_N === 0) {
+      await yieldEventLoop();
+    }
     let stat10;
     try {
       stat10 = await fs12.stat(file);
@@ -2900,6 +2939,7 @@ var codebaseIndexTool = {
       langs: input.langs,
       indexDir: codebaseIndexDirOverride(ctx)
     });
+    setIndexReady();
     return result;
   }
 };
@@ -3035,6 +3075,31 @@ var codebaseSearchTool = {
     required: ["query"]
   },
   async execute(input, ctx) {
+    const state = getIndexState();
+    if (!state.ready) {
+      return {
+        results: [],
+        total: 0,
+        query: input.query,
+        indexStatus: state.indexing ? `Indexing in progress (${state.currentFile}/${state.totalFiles} files) \u2014 retry in a moment.` : "Index not yet built. The codebase is being indexed at startup \u2014 search will be available shortly."
+      };
+    }
+    if (state.indexing) {
+      return {
+        results: [],
+        total: 0,
+        query: input.query,
+        indexStatus: `Index refresh in progress (${state.currentFile}/${state.totalFiles} files). Results may be incomplete.`
+      };
+    }
+    if (state.lastError) {
+      return {
+        results: [],
+        total: 0,
+        query: input.query,
+        indexStatus: `Index build failed: ${state.lastError}. Try /codebase-reindex.`
+      };
+    }
     const store = new IndexStore(ctx.projectRoot, { indexDir: codebaseIndexDirOverride(ctx) });
     try {
       const limit = Math.min(input.limit ?? 20, 100);
@@ -3092,6 +3157,32 @@ var codebaseStatsTool = {
     additionalProperties: false
   },
   async execute(_input, ctx) {
+    const idxState = getIndexState();
+    if (!idxState.ready) {
+      return {
+        totalSymbols: 0,
+        totalFiles: 0,
+        byLang: {},
+        byKind: {},
+        lastIndexed: null,
+        sizeBytes: 0,
+        indexPath: "",
+        version: SCHEMA_VERSION,
+        indexStatus: idxState.indexing ? `Indexing in progress (${idxState.currentFile}/${idxState.totalFiles} files).` : "Index not yet built."
+      };
+    }
+    if (idxState.indexing) {
+      const store2 = new IndexStore(ctx.projectRoot, { indexDir: codebaseIndexDirOverride(ctx) });
+      try {
+        const stats = store2.getStats();
+        return {
+          ...stats,
+          indexStatus: `Index refresh in progress (${idxState.currentFile}/${idxState.totalFiles} files). Stats may be incomplete.`
+        };
+      } finally {
+        store2.close();
+      }
+    }
     const store = new IndexStore(ctx.projectRoot, { indexDir: codebaseIndexDirOverride(ctx) });
     try {
       const stats = store.getStats();
@@ -6589,9 +6680,10 @@ var todoTool = {
   name: "todo",
   category: "Session",
   description: "Manage the session-level todo list. This is the primary mechanism for tracking multi-step work. The list is fully replaced on every call (not appended).",
-  usageHint: "BEST PRACTICE for complex tasks:\n- At the beginning of a non-trivial task, create a clear todo list with specific, actionable items.\n- Only **one** item should be `in_progress` at any time.\n- Update the list frequently as work progresses (mark items done, add new ones, change status).\n- The system and user can see this list, so keep it honest and up-to-date.\nThis tool is extremely valuable for maintaining focus and giving the user visibility into your plan.",
+  usageHint: "BEST PRACTICE for complex tasks:\n- At the beginning of a non-trivial task, create a clear todo list with specific, actionable items.\n- Only **one** item should be `in_progress` at any time.\n- Update the list frequently as work progresses (mark items done, add new ones, change status).\n- **Re-order items** to reflect current priorities \u2014 the full list is replaced each call, so item order is entirely under your control.\n- When all items are completed the board auto-clears \u2014 you do NOT need to send an empty list.\n- The system and user can see this list, so keep it honest and up-to-date.\nThis tool is extremely valuable for maintaining focus and giving the user visibility into your plan.",
   permission: "auto",
   mutating: false,
+  // mutates only conversation state (ctx.todos), not external state — no confirmation needed
   timeoutMs: 1e3,
   inputSchema: {
     type: "object",