@wrongstack/tools 0.68.0 → 0.77.0

package/dist/{codebase-stats-tool-C8ApERbn.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,82 @@ interface CodebaseStatsOutput {
     sizeBytes: number;
     indexPath: string;
     version: number;
+    /** Non-empty when the index is not ready or is still building. */
+    indexStatus?: string;
 }
 
-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, codebaseIndexTool as g, codebaseSearchTool as h, codebaseStatsTool as i };
+/**
+ * Background indexing coordinator.
+ *
+ * Wraps {@link runIndexer} with two concerns the agent loop and the CLI wiring
+ * both need but neither should own:
+ *
+ * 1. **Serialization** — every reindex (startup full scan, per-edit incremental,
+ *    external file-watch) goes through one process-wide promise-chain mutex.
+ *    `writer.ts` opens a synchronous `node:sqlite` `DatabaseSync` connection per
+ *    `IndexStore`; two concurrent `runIndexer` runs on the same `index.db` would
+ *    race the writer and risk `SQLITE_BUSY`. The mutex makes them queue instead.
+ *
+ * 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;
+    indexDir?: string;
+    force?: boolean;
+}): Promise<IndexResult>;
+/**
+ * Debounced, fire-and-forget incremental reindex of specific files. Used by the
+ * per-edit toolCall middleware and the external file watcher. Non-indexable
+ * paths are dropped. Errors are reported via the optional `onError` callback and
+ * never thrown to the caller (background work must not crash a turn).
+ */
+declare function enqueueReindex(opts: {
+    projectRoot: string;
+    files: string[];
+    indexDir?: string;
+    debounceMs?: number;
+    onError?: (err: unknown) => void;
+}): void;
+/** 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, getIndexState as l, isIndexReady as m, isIndexableFile as n, isIndexing as o, onIndexStateChange as p, runStartupIndex as r };