@wrongstack/tools 0.284.1 → 0.286.0

package/dist/background-indexer-BeDBxfSh.d.ts

@@ -1,371 +0,0 @@
-import { Tool } from '@wrongstack/core';
-
-declare const codebaseIndexTool: Tool<CodebaseIndexInput, CodebaseIndexOutput>;
-interface CodebaseIndexInput {
-    force?: boolean | undefined;
-    langs?: string[] | undefined;
-}
-interface CodebaseIndexOutput {
-    filesIndexed: number;
-    symbolsIndexed: number;
-    langStats: Record<string, number>;
-    durationMs: number;
-    errors: string[];
-    /** Advisory note when the indexer was skipped (e.g. another index in progress). */
-    note?: string | undefined;
-}
-
-/** Language a symbol belongs to. */
-type SymbolLang = 'ts' | 'js' | 'tsx' | 'jsx' | 'go' | 'py' | 'rs' | 'json' | 'yaml';
-/** What kind of symbol this is. */
-type SymbolKind = 'class' | 'interface' | 'enum' | 'type' | 'function' | 'method' | 'var' | 'const' | 'let' | 'property' | 'parameter' | 'namespace' | 'object' | 'literal' | 'schema' | 'struct' | 'trait' | 'impl' | 'static' | 'mod';
-/** A single indexed code symbol. */
-interface Symbol {
-    id: number;
-    lang: SymbolLang;
-    kind: SymbolKind;
-    name: string;
-    file: string;
-    line: number;
-    col: number;
-    signature: string;
-    docComment: string;
-    scope: string;
-    text: string;
-}
-/** Extracted symbols and cross-references for one file. */
-interface FileSymbols {
-    file: string;
-    lang: SymbolLang;
-    symbols: Symbol[];
-    refs?: Ref[] | undefined;
-    mtimeMs: number;
-}
-/** Source file metadata tracked for incremental indexing. */
-interface FileMeta {
-    file: string;
-    lang: SymbolLang;
-    mtimeMs: number;
-    symbolCount: number;
-    lastIndexed: number;
-}
-/** Statistics about the index. */
-interface IndexStats {
-    totalSymbols: number;
-    totalFiles: number;
-    byLang: Record<SymbolLang, number>;
-    byKind: Record<SymbolKind, number>;
-    indexPath: string;
-    lastIndexed: number | null;
-    sizeBytes: number;
-    version: number;
-}
-/** Result of a search query. */
-interface SearchResult {
-    id: number;
-    name: string;
-    kind: SymbolKind;
-    lang: SymbolLang;
-    file: string;
-    line: number;
-    col: number;
-    signature: string;
-    docComment: string;
-    score: number;
-    snippet: string;
-    /** Original LSP SymbolKind number if the result was filtered by an LSP kind. */
-    lspKind?: number | undefined;
-}
-/** Result of a full reindex. */
-interface IndexResult {
-    filesIndexed: number;
-    symbolsIndexed: number;
-    langStats: Record<SymbolLang, number>;
-    durationMs: number;
-    errors: string[];
-}
-/** What kind of reference this is. */
-type CallType = 'call' | 'type_ref' | 'inherit' | 'implement' | 'import';
-/** A cross-reference between two symbols (who references whom). */
-interface Ref {
-    id?: number | undefined;
-    fromId: number;
-    toName: string;
-    toId?: number | undefined;
-    callType: CallType;
-    line: number;
-}
-declare const SCHEMA_VERSION = 2;
-
-/**
- * `codebase-search` tool — search the symbol index with BM25 ranking.
- *
- * Usage: codebase-search({
- *   query: string,        // search terms
- *   kind?: string,       // class|function|interface|method|const|...
- *   lang?: string,       // ts|tsx|js|jsx|go|py|rs
- *   file?: string,       // filter to a specific file path (substring match)
- *   limit?: number,      // max results (default 20, max 100)
- * })
- *
- * Returns: [{ name, kind, lang, file, line, signature, snippet, score }, ...]
- *
- * The query executes in the index worker via FTS5 (`MATCH` + native `bm25()`)
- * — the main thread never opens SQLite, so a contended or wedged index can
- * slow this tool down but can never freeze the terminal.
- */
-
-declare const codebaseSearchTool: Tool<CodebaseSearchInput, CodebaseSearchOutput>;
-interface CodebaseSearchInput {
-    query: string;
-    kind?: string | undefined;
-    lang?: string | undefined;
-    file?: string | undefined;
-    limit?: number | undefined;
-    lspKind?: number | undefined;
-    /**
-     * When true, hints that LSP-based search should be preferred over the index.
-     * The built-in tool ignores this (index-only), but when the LSP plugin is
-     * active it intercepts the tool and provides live LSP workspaceSymbol results.
-     */
-    preferLsp?: boolean | undefined;
-}
-interface CodebaseSearchOutput {
-    results: SearchResult[];
-    total: number;
-    query: string;
-    /** Non-empty when the index blocked the search (not ready, indexing, failed). */
-    indexStatus?: string | undefined;
-}
-
-/**
- * `codebase-stats` tool — report index health and statistics.
- *
- * Usage: codebase-stats({})
- *
- * Returns: { totalSymbols, totalFiles, byLang, byKind, lastIndexed, sizeBytes, version }
- */
-
-declare const codebaseStatsTool: Tool<Record<string, never>, CodebaseStatsOutput>;
-interface CodebaseStatsOutput {
-    totalSymbols: number;
-    totalFiles: number;
-    byLang: Record<string, number>;
-    byKind: Record<string, number>;
-    lastIndexed: number | null;
-    sizeBytes: number;
-    indexPath: string;
-    version: number;
-    /** Non-empty when the index is not ready or is still building. */
-    indexStatus?: string | undefined;
-}
-
-/**
- * Circuit breaker for the codebase indexer.
- *
- * The indexer can wedge: a hung filesystem, a parser pathology, or another
- * wstack process holding the SQLite write lock (several surfaces — TUI, WebUI,
- * parallel terminals — share one per-project `index.db`). Without protection,
- * every queued reindex piles up behind the process-wide mutex, `isIndexing()`
- * stays true forever, and anything that awaits an index run (the startup scan,
- * `/codebase-reindex`) locks its terminal.
- *
- * Standard three-state breaker:
- *
- *   closed    — normal operation; consecutive failures are counted.
- *   open      — after `failureThreshold` consecutive failures, every request
- *               is rejected fast ({@link CircuitOpenError}) for `cooldownMs`.
- *   half-open — after the cooldown exactly one probe run is admitted;
- *               success closes the circuit, failure re-opens it.
- *
- * Watchdog timeouts ({@link IndexTimeoutError}) count as failures;
- * caller-initiated aborts (session teardown) do not — the background indexer
- * makes that distinction before recording.
- *
- * Lock conflicts ({@link LockError}) do NOT count as failures — they are expected
- * transient conditions when multiple wstack surfaces share the same `index.db`.
- * The index store retries automatically; a LockError only reaches the circuit
- * breaker when all retries are exhausted.
- */
-type CircuitState = 'closed' | 'open' | 'half-open';
-interface CircuitSnapshot {
-    state: CircuitState;
-    consecutiveFailures: number;
-    lastFailure: string | null;
-    /** ms until an open circuit admits a half-open probe (0 unless open). */
-    cooldownRemainingMs: number;
-}
-/** Thrown when a run is rejected because the circuit is open. */
-declare class CircuitOpenError extends Error {
-    readonly name = "CircuitOpenError";
-}
-/** Thrown by the background indexer's watchdog when a run exceeds its timeout. */
-declare class IndexTimeoutError extends Error {
-    readonly name = "IndexTimeoutError";
-}
-interface CircuitBreakerOptions {
-    /** Consecutive failures before the circuit opens. Default: 3. */
-    failureThreshold?: number | undefined;
-    /** How long an open circuit rejects requests before allowing a probe. Default: 60s. */
-    cooldownMs?: number | undefined;
-    /** Injectable clock for tests. Default: Date.now. */
-    now?: (() => number) | undefined;
-}
-declare class IndexCircuitBreaker {
-    private readonly failureThreshold;
-    private readonly cooldownMs;
-    private readonly now;
-    private state;
-    private consecutiveFailures;
-    private openedAt;
-    private lastFailure;
-    private probeInFlight;
-    constructor(opts?: CircuitBreakerOptions);
-    /**
-     * True when a run may proceed. An open circuit transitions to half-open once
-     * the cooldown has elapsed, admitting exactly one probe; further requests
-     * are rejected until that probe settles via recordSuccess/recordFailure.
-     */
-    allowRequest(): boolean;
-    recordSuccess(): void;
-    recordFailure(err: unknown): void;
-    /** Force-close the circuit (manual recovery: `/codebase-reindex`). */
-    reset(): void;
-    snapshot(): CircuitSnapshot;
-}
-/**
- * Process-wide breaker shared by every index path (startup scan, per-edit
- * incremental, external watcher, the `codebase-index` tool). Module-level for
- * the same reason the mutex is: there is one `index.db` per project and one
- * indexing pipeline per process.
- */
-declare const indexCircuitBreaker: IndexCircuitBreaker;
-/** Reset the shared breaker — used by `/codebase-reindex` and tests. */
-declare function resetIndexCircuitBreaker(): void;
-
-/**
- * Message protocol between the index host (main thread) and the index worker.
- *
- * Plain structured-cloneable shapes only — no class instances, no functions.
- * Errors cross the boundary as strings and are re-wrapped by the host.
- */
-
-interface SearchOpArgs {
-    projectRoot: string;
-    indexDir?: string | undefined;
-    query: string;
-    kind?: string | undefined;
-    lang?: string | undefined;
-    file?: string | undefined;
-    lspKind?: number | undefined;
-    limit: number;
-}
-interface StatsOpArgs {
-    projectRoot: string;
-    indexDir?: string | undefined;
-}
-interface SearchOpResult {
-    results: SearchResult[];
-    total: number;
-}
-
-/**
- * Index host — the main-thread coordinator for all codebase-index operations.
- *
- * Production mode runs every operation (full scans, per-file reindexes,
- * searches, stats) in a dedicated worker thread (`worker.ts`), so the
- * synchronous `node:sqlite` calls and the TypeScript parser can never block
- * the main event loop — the failure mode that used to freeze terminals is
- * structurally impossible. When the built worker file is not present (tests
- * run from source, exotic runtimes) or `WRONGSTACK_INDEX_INLINE=1` is set,
- * operations fall back to running inline through the same service layer.
- *
- * Concerns owned here, in front of either execution mode:
- *
- * 1. **Serialization** — every write run (startup scan, per-edit incremental,
- *    external file-watch, manual reindex) goes through one process-wide
- *    promise-chain mutex so two runs never race the same `index.db` writer.
- * 2. **Debounce** — rapid successive edits to the same file coalesce into a
- *    single reindex, keyed per `(indexDir, file)`.
- * 3. **Watchdog** — every operation is raced against a timeout. In worker
- *    mode a timeout hard-terminates the worker (it respawns lazily on the
- *    next request); inline it aborts the run's signal. Either way the mutex
- *    chain always advances and the promise always settles.
- * 4. **Circuit breaker** — repeated failures/timeouts pause indexing instead
- *    of queuing more work behind a wedged pipeline. See circuit-breaker.ts.
- * 5. **State tracking** — ready/indexing/progress flags + change listeners
- *    for the TUI status chip and the search/stats tools' gating.
- */
-
-/** 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, circuit }. */
-declare function getIndexState(): {
-    ready: boolean;
-    indexing: boolean;
-    currentFile: number;
-    totalFiles: number;
-    lastError: string | null;
-    /** Circuit-breaker state — `open` means indexing is paused after repeated failures. */
-    circuit: CircuitSnapshot;
-};
-/**
- * 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;
-/**
- * Tear down the index host (worker + pending debounces). Call on process
- * shutdown; safe to call when nothing is running.
- */
-declare function shutdownCodebaseIndexHost(): void;
-/** True when the file's extension maps to a language the indexer can parse. */
-declare function isIndexableFile(filePath: string): boolean;
-declare function runStartupIndex(opts: {
-    projectRoot: string;
-    indexDir?: string | undefined;
-    force?: boolean | undefined;
-    langs?: string[] | undefined;
-    signal?: AbortSignal | undefined;
-    /** Watchdog timeout for the whole run. Default: 120s. */
-    timeoutMs?: number | undefined;
-}): 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 | undefined;
-    debounceMs?: number | undefined;
-    /** Watchdog timeout per file. Default: 30s. */
-    timeoutMs?: number | undefined;
-    onError?: ((err: unknown) => void) | undefined;
-}): void;
-/** Cancel all pending debounced reindexes. For teardown / tests. */
-declare function cancelPendingReindexes(): void;
-/**
- * Ranked symbol search against the index. The query runs in the index worker
- * (or inline in fallback mode) — the main thread never opens SQLite. Reads
- * don't take the write mutex (WAL readers don't block the writer) and don't
- * feed the circuit breaker; a wedged read still trips the watchdog, which
- * recycles the worker.
- */
-declare function searchCodebaseIndex(args: SearchOpArgs, opts?: {
-    timeoutMs?: number | undefined;
-    signal?: AbortSignal | undefined;
-}): Promise<SearchOpResult>;
-/** Index health/statistics, fetched off the main thread like searches. */
-declare function codebaseIndexStats(args: StatsOpArgs, opts?: {
-    timeoutMs?: number | undefined;
-    signal?: AbortSignal | undefined;
-}): Promise<IndexStats>;
-
-export { CircuitOpenError as C, type FileMeta as F, type IndexResult as I, type Ref as R, type Symbol as S, type SymbolKind as a, type SymbolLang as b, type SearchResult as c, type IndexStats as d, type CircuitSnapshot as e, type CircuitState as f, type FileSymbols as g, IndexCircuitBreaker as h, IndexTimeoutError as i, SCHEMA_VERSION as j, cancelPendingReindexes as k, codebaseIndexStats as l, codebaseIndexTool as m, codebaseSearchTool as n, codebaseStatsTool as o, enqueueReindex as p, getIndexState as q, indexCircuitBreaker as r, isIndexReady as s, isIndexableFile as t, isIndexing as u, onIndexStateChange as v, resetIndexCircuitBreaker as w, runStartupIndex as x, searchCodebaseIndex as y, shutdownCodebaseIndexHost as z };

package/dist/exec-2OKoT6tk.d.ts

@@ -1,121 +0,0 @@
-import { Tool } from '@wrongstack/core';
-
-/**
- * Heuristic danger detection for `exec` tool commands.
- *
- * Layered on top of `BLOCKED_ARG_PATTERNS` (which is a hard-deny list for
- * clear sandbox escapes) and `bash-kill-guard.ts` (which protects WrongStack
- * itself from kill). This module assigns a danger level to a command/arg
- * pair so the caller can decide whether to:
- *
- *   - 'safe'        → execute normally
- *   - 'caution'     → execute and emit a warning line to the tool output
- *   - 'destructive' → route through the existing confirm flow
- *                     (`execTool.permission === 'confirm'`) instead of
- *                     hard-deny, so the user can still proceed if intentional
- *
- * Design constraints:
- *   - Deterministic: no randomness, no I/O, no time. Same input → same output.
- *   - No LLM calls. Patterns are regex / exact-match.
- *   - Per-rule `id` so config can override specific rules via
- *     `tools.exec.danger.bypass`.
- *   - Reasons are human-readable, joined with "; " for the confirm prompt.
- *
- * Caution rules are deliberately permissive — they execute and emit a
- * warning rather than blocking. The rationale: many of these patterns
- * (python -c, sudo) are part of legitimate dev workflows,
- * so a hard deny would block too much. A warning gives the user a
- * chance to notice "wait, I didn't mean to do that" without forcing
- * them to add a config override for every script.
- */
-type DangerLevel = 'safe' | 'caution' | 'destructive';
-interface DangerAssessment {
-    level: DangerLevel;
-    reasons: string[];
-    /** Stable id of the matched rule, for tests and config-override. */
-    matchedRule?: string;
-}
-/**
- * Evaluate the danger level of a (cmd, args) pair.
- *
- * Returns 'safe' if no rule fires, otherwise the highest level among all
- * matching rules. The 'matchedRule' field is the *last* rule that fired
- * (stable, since rules are evaluated in declaration order).
- *
- * Optional `bypass` argument: a set of rule ids that should be SKIPPED
- * even if they would otherwise match. Wired from
- * `config.tools.exec.danger.bypass` (see `ExecDangerConfig` in
- * `@wrongstack/core/src/types/config.ts`). Unknown ids are silently
- * ignored — forward-compat: a rule added in a future version can be
- * referenced before the user upgrades their config schema.
- *
- * This function is the single source of truth for danger classification;
- * it is pure (no side effects) and unit-tested in `danger-detect.test.ts`.
- */
-declare function detectDanger(cmd: string, args: readonly string[], bypass?: ReadonlySet<string>): DangerAssessment;
-
-/**
- * Apply the configured exec command policy. Recomputes the effective allowlist
- * as `DEFAULT ∪ allow − deny`. Call once at boot from
- * `config.tools.exec.{allow,deny}`. Idempotent (always rebuilt from defaults).
- *
- * SECURITY: `allow` must originate from TRUSTED config only — the config loader
- * strips `tools.exec.allow` from the untrusted in-project repo config before it
- * reaches here. `deny` is safe from any source (it only narrows).
- */
-declare function configureExecPolicy(opts?: {
-    allow?: readonly string[] | undefined;
-    deny?: readonly string[] | undefined;
-}): void;
-/** Reset the exec allowlist to the built-in defaults (tests / re-init). */
-declare function resetExecPolicy(): void;
-/**
- * Apply the configured danger-bypass policy. Each id in `bypass` is
- * added to the effective skip set; duplicates are fine. Idempotent.
- *
- * Call once at boot from `config.tools.exec.danger.bypass`.
- */
-declare function configureDangerBypass(opts?: {
-    bypass?: readonly string[] | undefined;
-}): void;
-/** Reset the danger-bypass set to empty (tests / re-init). */
-declare function resetDangerBypass(): void;
-/**
- * Read-only view of the active bypass set. `detectDanger()` takes a
- * `bypass` argument directly, so consumers should prefer passing this
- * rather than reading the set and matching themselves.
- */
-declare function getDangerBypass(): ReadonlySet<string>;
-/** Whether `cmd` is currently in the effective exec allowlist. */
-declare function isExecCommandAllowed(cmd: string): boolean;
-/** Snapshot of the effective allowlist (sorted) — for tests / diagnostics. */
-declare function getExecAllowlist(): string[];
-interface ExecInput {
-    command: string;
-    args?: string[] | undefined;
-    cwd?: string | undefined;
-    timeout?: number | undefined;
-}
-interface ExecOutput {
-    command: string;
-    args: string[];
-    stdout: string;
-    stderr: string;
-    exitCode: number;
-    truncated: boolean;
-    allowed: boolean;
-    /**
-     * Heuristic danger assessment of the (cmd, args) pair. Populated for every
-     * call (not just blocked ones) so the UI/TUI can render a banner when the
-     * level is 'caution' or 'destructive'. See `_danger-detect.ts` for the
-     * rule set.
-     *
-     * Pre-execution error returns (allowlist miss, circuit breaker, etc.)
-     * report `level: 'safe'` because the command never actually ran; the UI
-     * should surface the error separately and not also a danger warning.
-     */
-    danger: DangerAssessment;
-}
-declare const execTool: Tool<ExecInput, ExecOutput>;
-
-export { type DangerAssessment as D, type DangerLevel as a, configureExecPolicy as b, configureDangerBypass as c, detectDanger as d, execTool as e, getExecAllowlist as f, getDangerBypass as g, resetExecPolicy as h, isExecCommandAllowed as i, resetDangerBypass as r };