@spikedpunch/mast 0.1.0

package/dist/cli/metrics-cmd.js

@@ -0,0 +1,164 @@
+import { resolveConfig } from '../store/config.js';
+import { openDatabase } from '../graph/db.js';
+import { queryMetricsSummaryWithPercentiles, rollupMetrics, vacuumMetrics, } from '../telemetry/metrics.js';
+import { TOKENIZER_LABEL } from '../telemetry/tokenizer.js';
+import { readLockMetricsSummary, } from '../telemetry/lockMetricsSummary.js';
+// ---------------------------------------------------------------------------
+// Duration string parser  ("7d", "24h", "30m")
+// ---------------------------------------------------------------------------
+function parseSince(value) {
+    const match = /^(\d+)([dhm])$/.exec(value);
+    if (match === null) {
+        throw new Error(`Invalid --since value "${value}". Expected format: 7d, 24h, 30m`);
+    }
+    const n = match[1];
+    const unit = match[2];
+    const multipliers = { d: 86_400_000, h: 3_600_000, m: 60_000 };
+    return Number(n) * multipliers[unit];
+}
+// ---------------------------------------------------------------------------
+// Table printer — per-tool efficiency (with D6's p50/p95 duration columns)
+// ---------------------------------------------------------------------------
+function printTable(rows) {
+    if (rows.length === 0) {
+        process.stdout.write('No metrics recorded in the requested window.\n');
+        return;
+    }
+    const header = ['Tool', 'Calls', 'Tokens', 'Avg ms', 'p50 ms', 'p95 ms', 'Efficiency'];
+    const widths = [
+        Math.max(header[0].length, ...rows.map((r) => r.tool_name.length)),
+        Math.max(header[1].length, ...rows.map((r) => String(r.calls).length)),
+        Math.max(header[2].length, ...rows.map((r) => String(r.tokens_returned_total).length)),
+        Math.max(header[3].length, ...rows.map((r) => r.avg_duration_ms.toFixed(1).length)),
+        Math.max(header[4].length, ...rows.map((r) => String(r.p50_duration_ms).length)),
+        Math.max(header[5].length, ...rows.map((r) => String(r.p95_duration_ms).length)),
+        header[6].length,
+    ];
+    const pad = (s, w) => s.padEnd(w);
+    const sep = widths.map((w) => '-'.repeat(w)).join('  ');
+    const line = (cols) => cols.map((c, i) => pad(c, widths[i])).join('  ');
+    process.stdout.write(line(header) + '\n');
+    process.stdout.write(sep + '\n');
+    for (const r of rows) {
+        process.stdout.write(line([
+            r.tool_name,
+            String(r.calls),
+            String(r.tokens_returned_total),
+            r.avg_duration_ms.toFixed(1),
+            String(r.p50_duration_ms),
+            String(r.p95_duration_ms),
+            `${(r.efficiency_ratio * 100).toFixed(1)}%`,
+        ]) + '\n');
+    }
+}
+// ---------------------------------------------------------------------------
+// Table printer — lock-hold summary (D6 deliverable 2, `mast metrics --locks`)
+// ---------------------------------------------------------------------------
+function printLocksTable(callers) {
+    const header = ['Caller', 'Count', 'Hold p50', 'Hold p95', 'Hold max', 'Wait p50', 'Wait p95', 'Wait max', 'Failed'];
+    const cell = (c) => [
+        c.caller,
+        String(c.count),
+        String(c.hold_p50_ms),
+        String(c.hold_p95_ms),
+        String(c.hold_max_ms),
+        String(c.wait_p50_ms),
+        String(c.wait_p95_ms),
+        String(c.wait_max_ms),
+        String(c.failed_count),
+    ];
+    const rows = callers.map(cell);
+    const widths = header.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+    const pad = (s, w) => s.padEnd(w);
+    const line = (cols) => cols.map((c, i) => pad(c, widths[i])).join('  ');
+    const sep = widths.map((w) => '-'.repeat(w)).join('  ');
+    process.stdout.write(line(header) + '\n');
+    process.stdout.write(sep + '\n');
+    for (const r of rows)
+        process.stdout.write(line(r) + '\n');
+}
+/**
+ * Print the `--locks` report: human table or `--json`, for either a real
+ * summary or the "nothing recorded" case (missing/empty JSONL).
+ *
+ * Never throws on malformed input — {@link readLockMetricsSummary} already
+ * skips malformed lines inside {@link summarizeLockMetricsJsonl}; this
+ * function surfaces the skipped-line count as a visible warning rather than
+ * silently dropping it.
+ */
+function printLocksReport(stateDir, json) {
+    const summary = readLockMetricsSummary(stateDir) ?? {
+        callers: [],
+        malformed_line_count: 0,
+    };
+    if (json) {
+        process.stdout.write(JSON.stringify(summary, null, 2) + '\n');
+        return;
+    }
+    if (summary.callers.length === 0) {
+        process.stdout.write('No lock metrics recorded.\n');
+    }
+    else {
+        printLocksTable(summary.callers);
+    }
+    if (summary.malformed_line_count > 0) {
+        process.stdout.write(`\nWarning: skipped ${summary.malformed_line_count} malformed line(s) in lock-metrics.jsonl.\n`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Command registration
+// ---------------------------------------------------------------------------
+export function registerMetricsCommand(program) {
+    program
+        .command('metrics [path]')
+        .description('Show token-efficiency metrics from the metrics database')
+        .option('--since <window>', 'Time window: 7d, 24h, 30m (default: 7d)', '7d')
+        .option('--by-tool', 'Break down by tool name (default: true)', true)
+        .option('--rollup', 'Collapse raw rows older than --keep-days into daily roll-ups')
+        .option('--vacuum', 'Delete daily roll-up rows older than --keep-days')
+        .option('--keep-days <n>', 'Retention days for --rollup / --vacuum (default: 7 for rollup, 90 for vacuum)', undefined)
+        .option('--locks', 'Summarize structure-lock hold/wait timing by caller (store/lockMetrics.ts JSONL)')
+        .option('--json', 'Machine-readable output')
+        .option('--state-dir <dir>', 'State directory override')
+        .action(async (projectPath, opts) => {
+        const config = resolveConfig({ projectRoot: projectPath, stateDirOverride: opts.stateDir });
+        // --locks reads a flat JSONL file, not graph.db — no need to open the
+        // database at all for this branch.
+        if (opts.locks === true) {
+            printLocksReport(config.resolved_state_dir, opts.json === true);
+            return;
+        }
+        const db = openDatabase(config.resolved_state_dir);
+        try {
+            if (opts.rollup === true) {
+                const keepDays = opts.keepDays !== undefined ? Number(opts.keepDays) : 7;
+                const deleted = await rollupMetrics(db, keepDays);
+                process.stdout.write(`Rolled up ${deleted} raw metric rows (kept last ${keepDays} days).\n`);
+            }
+            if (opts.vacuum === true) {
+                const keepDays = opts.keepDays !== undefined ? Number(opts.keepDays) : 90;
+                const deleted = await vacuumMetrics(db, keepDays);
+                process.stdout.write(`Vacuumed ${deleted} daily roll-up rows (kept last ${keepDays} days).\n`);
+            }
+            if (opts.rollup !== true && opts.vacuum !== true) {
+                const sinceMs = Date.now() - parseSince(opts.since);
+                const rows = await queryMetricsSummaryWithPercentiles(db, sinceMs);
+                if (opts.json === true) {
+                    process.stdout.write(JSON.stringify(rows, null, 2) + '\n');
+                }
+                else {
+                    printTable(rows);
+                    if (rows.length > 0) {
+                        // Honesty footer (§14.5): counts are approximate for current
+                        // models; the savings ratio is robust to the per-count error.
+                        process.stdout.write(`\nTokenizer: ${TOKENIZER_LABEL}\n`);
+                    }
+                }
+            }
+        }
+        finally {
+            await db.destroy();
+        }
+    });
+}
+//# sourceMappingURL=metrics-cmd.js.map

package/dist/cli/metrics-cmd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-cmd.js","sourceRoot":"","sources":["../../src/cli/metrics-cmd.ts"],"names":[],"mappings":"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"}

package/dist/cli/program.d.ts

@@ -0,0 +1,14 @@
+import { Command } from 'commander';
+/**
+ * Builds the CLI. This is the *only* place commands are registered.
+ *
+ * `cli/index.ts` parses the program this returns, and the README drift guard in
+ * `docs-cmd.test.ts` enumerates it. Both read the same builder on purpose: a
+ * separate list of commands maintained for the test would be a second producer of
+ * one value (shape S-05), and a guard that can fall out of step with the thing it
+ * guards is worse than none — it reports green while the README rots.
+ */
+export declare function buildProgram(): Command;
+/** Every registered command name, sorted. Derived from `buildProgram`, never restated. */
+export declare function registeredCommandNames(): readonly string[];
+//# sourceMappingURL=program.d.ts.map

package/dist/cli/program.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../../src/cli/program.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAapC;;;;;;;;GAQG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAmBtC;AAED,0FAA0F;AAC1F,wBAAgB,sBAAsB,IAAI,SAAS,MAAM,EAAE,CAE1D"}

package/dist/cli/program.js

@@ -0,0 +1,44 @@
+import { Command } from 'commander';
+import { CLI_VERSION } from './version.js';
+import { registerInitCommand } from './init.js';
+import { registerIndexCommand } from './index-cmd.js';
+import { registerSearchCommand } from './search-cmd.js';
+import { registerServeCommand } from './serve.js';
+import { registerStatusCommand } from './status.js';
+import { registerInstallHooksCommand } from './install-hooks.js';
+import { registerMetricsCommand } from './metrics-cmd.js';
+import { registerQueryCommand } from './query.js';
+import { registerDocsCommand, registerSkillCommand } from './docs-cmd.js';
+import { registerUpgradeCommand } from './upgrade-cmd.js';
+/**
+ * Builds the CLI. This is the *only* place commands are registered.
+ *
+ * `cli/index.ts` parses the program this returns, and the README drift guard in
+ * `docs-cmd.test.ts` enumerates it. Both read the same builder on purpose: a
+ * separate list of commands maintained for the test would be a second producer of
+ * one value (shape S-05), and a guard that can fall out of step with the thing it
+ * guards is worse than none — it reports green while the README rots.
+ */
+export function buildProgram() {
+    const program = new Command()
+        .name('mast')
+        .description('Monorepo AST Search Tool — lexical + declaration-exact code search over an MCP or CLI surface')
+        .version(CLI_VERSION);
+    registerInitCommand(program);
+    registerIndexCommand(program);
+    registerSearchCommand(program);
+    registerServeCommand(program);
+    registerStatusCommand(program);
+    registerInstallHooksCommand(program);
+    registerMetricsCommand(program);
+    registerQueryCommand(program);
+    registerDocsCommand(program);
+    registerSkillCommand(program);
+    registerUpgradeCommand(program);
+    return program;
+}
+/** Every registered command name, sorted. Derived from `buildProgram`, never restated. */
+export function registeredCommandNames() {
+    return buildProgram().commands.map((c) => c.name()).sort();
+}
+//# sourceMappingURL=program.js.map

package/dist/cli/program.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.js","sourceRoot":"","sources":["../../src/cli/program.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE1D;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE;SAC1B,IAAI,CAAC,MAAM,CAAC;SACZ,WAAW,CAAC,+FAA+F,CAAC;SAC5G,OAAO,CAAC,WAAW,CAAC,CAAC;IAExB,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC7B,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAC/B,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAC/B,2BAA2B,CAAC,OAAO,CAAC,CAAC;IACrC,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAChC,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC7B,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAEhC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,sBAAsB;IACpC,OAAO,YAAY,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AAC7D,CAAC"}

package/dist/cli/query.d.ts

@@ -0,0 +1,46 @@
+import type { Command } from 'commander';
+/**
+ * D0 (IMPLEMENTATION_PLAN.md "Stage 4: Determinism, hygiene, and the
+ * measurement harness", "### D0 — CLI query surface"): `mast query <tool>
+ * <json>` dispatches through the exact registered MCP tool handlers instead
+ * of re-implementing tool logic, so CLI output can never drift from the MCP
+ * transport's JIT/staleness/`_stats` behavior.
+ *
+ * Every user-facing failure mode below is thrown as `QueryError` (project
+ * CLAUDE.md §8.2: throw Error subclasses, never strings) so
+ * `registerQueryCommand`'s action can map it uniformly to a stderr message +
+ * exit 1, distinct from a tool-internal error propagating unchanged.
+ */
+export declare class QueryError extends Error {
+}
+/**
+ * Every tool name the MCP surface registers, sorted.
+ *
+ * Registration is pure: each `registerXTool(server, ctx)` passes `ctx` into the
+ * async handler's closure and never dereferences it while registering (verified
+ * across all 11). This enumerates without a database by handing registration a
+ * proxy that throws on ANY property access — so if a future tool starts reading
+ * `ctx` at registration time, this fails loudly instead of quietly returning a
+ * short list, and the drift guard in `docs-cmd.test.ts` keeps its meaning.
+ */
+export declare function listRegisteredToolNames(): readonly string[];
+export interface RunQueryOptions {
+    /** State directory override, same semantics as every other CLI command's `--state-dir`. */
+    readonly stateDir?: string;
+    /** Project root path (the CLI's positional `[path]`); defaults to cwd via `resolveConfig`. */
+    readonly path?: string;
+}
+/**
+ * Dispatch a single CLI query through the exact registered MCP tool handler
+ * and return its serialized response text — byte-identical to what an MCP
+ * client would receive for the same tool + args.
+ *
+ * @throws QueryError when the resolved state dir has never been indexed, the
+ * JSON argument string fails to parse, `toolName` does not match a
+ * registered tool, or the parsed args fail that tool's own zod schema. Any
+ * other error (a tool-internal failure) propagates unchanged, same as it
+ * would over the MCP transport.
+ */
+export declare function runQuery(toolName: string, jsonArgs: string, options?: RunQueryOptions): Promise<string>;
+export declare function registerQueryCommand(program: Command): void;
+//# sourceMappingURL=query.d.ts.map

package/dist/cli/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/cli/query.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQzC;;;;;;;;;;;GAWG;AACH,qBAAa,UAAW,SAAQ,KAAK;CAAG;AAoCxC;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,IAAI,SAAS,MAAM,EAAE,CAW3D;AAED,MAAM,WAAW,eAAe;IAC9B,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,8FAA8F;IAC9F,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CA6DjH;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAwB3D"}

package/dist/cli/query.js

@@ -0,0 +1,153 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { z, ZodError } from 'zod';
+import { resolveConfig } from '../store/config.js';
+import { openDatabase } from '../graph/db.js';
+import { SqliteChunkStore } from '../store/sqliteChunkStore.js';
+import { registerAllTools } from '../mcp/register-tools.js';
+/**
+ * D0 (IMPLEMENTATION_PLAN.md "Stage 4: Determinism, hygiene, and the
+ * measurement harness", "### D0 — CLI query surface"): `mast query <tool>
+ * <json>` dispatches through the exact registered MCP tool handlers instead
+ * of re-implementing tool logic, so CLI output can never drift from the MCP
+ * transport's JIT/staleness/`_stats` behavior.
+ *
+ * Every user-facing failure mode below is thrown as `QueryError` (project
+ * CLAUDE.md §8.2: throw Error subclasses, never strings) so
+ * `registerQueryCommand`'s action can map it uniformly to a stderr message +
+ * exit 1, distinct from a tool-internal error propagating unchanged.
+ */
+export class QueryError extends Error {
+}
+/**
+ * Structural stand-in for `McpServer` that records each tool's zod schema
+ * shape and handler instead of opening a real MCP transport.
+ *
+ * `registerAllTools` only ever calls the 4-argument
+ * `tool(name, description, schemaShape, handler)` overload — every
+ * `registerXTool` in `mcp/tools/*.ts` uses exactly this call shape, and
+ * `mcp/tools/__tests__/tools.test.ts`'s `createMockServer` already narrows
+ * the same way to unit-test handlers without a transport. `as unknown as
+ * McpServer` is the one pre-approved narrowing for this file (task brief,
+ * "Capture-server dispatch") — `capture` is not, and never claims to be, a
+ * real `McpServer`; it implements only the single method every register
+ * function calls.
+ */
+function createCaptureServer() {
+    const tools = new Map();
+    const capture = {
+        tool(name, _description, schemaShape, handler) {
+            tools.set(name, { schemaShape, handler });
+        },
+    };
+    return { server: capture, tools };
+}
+/**
+ * Every tool name the MCP surface registers, sorted.
+ *
+ * Registration is pure: each `registerXTool(server, ctx)` passes `ctx` into the
+ * async handler's closure and never dereferences it while registering (verified
+ * across all 11). This enumerates without a database by handing registration a
+ * proxy that throws on ANY property access — so if a future tool starts reading
+ * `ctx` at registration time, this fails loudly instead of quietly returning a
+ * short list, and the drift guard in `docs-cmd.test.ts` keeps its meaning.
+ */
+export function listRegisteredToolNames() {
+    const { server, tools } = createCaptureServer();
+    const forbidden = new Proxy({}, {
+        get(_t, prop) {
+            throw new Error(`tool registration read ctx.${String(prop)}; listRegisteredToolNames assumes registration is pure`);
+        },
+    });
+    registerAllTools(server, forbidden);
+    return [...tools.keys()].sort();
+}
+/**
+ * Dispatch a single CLI query through the exact registered MCP tool handler
+ * and return its serialized response text — byte-identical to what an MCP
+ * client would receive for the same tool + args.
+ *
+ * @throws QueryError when the resolved state dir has never been indexed, the
+ * JSON argument string fails to parse, `toolName` does not match a
+ * registered tool, or the parsed args fail that tool's own zod schema. Any
+ * other error (a tool-internal failure) propagates unchanged, same as it
+ * would over the MCP transport.
+ */
+export async function runQuery(toolName, jsonArgs, options = {}) {
+    const config = resolveConfig({ projectRoot: options.path, stateDirOverride: options.stateDir });
+    // openDatabase() creates graph.db on first open (better-sqlite3's default
+    // behavior for a missing file), so the never-indexed case must be caught
+    // BEFORE opening it — otherwise "no index" would silently succeed against a
+    // freshly-created empty database instead of failing fast. M6 (empty-state
+    // read semantics) is explicitly out of scope; this is only a guard against
+    // openDatabase's own create-on-open side effect.
+    const graphDbPath = join(config.resolved_state_dir, 'graph.db');
+    if (!existsSync(graphDbPath)) {
+        throw new QueryError(`no index found at ${config.resolved_state_dir}; run \`mast init\` / \`mast index\` first`);
+    }
+    let parsedArgs;
+    try {
+        parsedArgs = JSON.parse(jsonArgs);
+    }
+    catch (err) {
+        throw new QueryError(`malformed JSON argument: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const db = openDatabase(config.resolved_state_dir);
+    try {
+        const chunkStore = new SqliteChunkStore(db);
+        // Each CLI invocation is its own metrics session — unlike `serve()`,
+        // there is no long-lived MCP connection to key session-scoped telemetry
+        // (mast_efficiency's "session" scope) to.
+        const ctx = { db, chunkStore, config, sessionId: randomUUID() };
+        const { server, tools } = createCaptureServer();
+        registerAllTools(server, ctx);
+        const tool = tools.get(toolName);
+        if (tool === undefined) {
+            const available = [...tools.keys()].sort().join(', ');
+            throw new QueryError(`unknown tool "${toolName}"; available tools: ${available}`);
+        }
+        let validatedArgs;
+        try {
+            // The CLI arg string crosses a trust boundary (project CLAUDE.md §3.2);
+            // this reuses the exact per-tool zod shape the MCP layer validates
+            // with, so a CLI call can never see a tool accept input the MCP
+            // transport would have rejected, or vice versa.
+            validatedArgs = z.object(tool.schemaShape).parse(parsedArgs);
+        }
+        catch (err) {
+            if (err instanceof ZodError) {
+                throw new QueryError(`invalid arguments for "${toolName}": ${JSON.stringify(err.issues, null, 2)}`);
+            }
+            throw err;
+        }
+        const result = await tool.handler(validatedArgs);
+        return result.content[0].text;
+    }
+    finally {
+        await db.destroy();
+    }
+}
+export function registerQueryCommand(program) {
+    program
+        .command('query <tool> [json] [path]')
+        .description('Invoke an MCP read tool directly from the CLI — identical output to the MCP transport (MAST_SPEC.md §8)')
+        .option('--state-dir <dir>', 'State directory')
+        .option('--json', 'Emit the exact single-line MCP response text (machine use); default pretty-prints for humans')
+        .action(async (toolName, jsonArg, path, opts) => {
+        try {
+            const text = await runQuery(toolName, jsonArg ?? '{}', { stateDir: opts.stateDir, path });
+            if (opts.json) {
+                process.stdout.write(text + '\n');
+            }
+            else {
+                process.stdout.write(JSON.stringify(JSON.parse(text), null, 2) + '\n');
+            }
+        }
+        catch (err) {
+            process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+            process.exitCode = 1;
+        }
+    });
+}
+//# sourceMappingURL=query.js.map

package/dist/cli/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../src/cli/query.ts"],"names":[],"mappings":"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"}

package/dist/cli/search-cmd.d.ts

@@ -0,0 +1,33 @@
+import type { Command } from 'commander';
+/**
+ * `mast search <query>` — the readable front door to `mast_search`.
+ *
+ * This is a presentation layer, not a second search implementation. It builds
+ * `mast_search`'s arguments and dispatches through `runQuery`, which routes to the
+ * registered MCP handler exactly as `mast query` does (D0). Ranking, JIT refresh,
+ * staleness flags, and `_stats` therefore cannot drift between the two surfaces —
+ * re-implementing any of it here is the drift D0 exists to prevent.
+ *
+ * `mast query mast_search '{...}'` remains the exact-MCP-parity surface for scripts;
+ * this one is for a human at a terminal, and prints text rather than JSON.
+ */
+export interface SearchFlags {
+    readonly limit?: string;
+    readonly type?: string;
+    readonly language?: string;
+    readonly exported?: boolean;
+    readonly file?: string;
+}
+/** Maps CLI flags onto `mast_search`'s schema fields. Absent flags are omitted, not nulled. */
+export declare function buildSearchArgs(query: string, flags: SearchFlags): string;
+/**
+ * Renders the MCP response as text.
+ *
+ * Every confidence signal the response carries is echoed. An empty result that is
+ * empty *because* the index was busy or stale reads identically to "this symbol
+ * does not exist" unless the flag is shown — the S0 confusion this package's whole
+ * severity scale is built around.
+ */
+export declare function formatSearchResults(responseText: string): string;
+export declare function registerSearchCommand(program: Command): void;
+//# sourceMappingURL=search-cmd.d.ts.map

package/dist/cli/search-cmd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-cmd.d.ts","sourceRoot":"","sources":["../../src/cli/search-cmd.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGzC;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,+FAA+F;AAC/F,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,MAAM,CAczE;AAqBD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CA8EhE;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAoB5D"}

package/dist/cli/search-cmd.js

@@ -0,0 +1,114 @@
+import { runQuery, QueryError } from './query.js';
+/** Maps CLI flags onto `mast_search`'s schema fields. Absent flags are omitted, not nulled. */
+export function buildSearchArgs(query, flags) {
+    const args = { query };
+    if (flags.limit !== undefined) {
+        // Commander hands through whatever was typed; `Number('ten')` is NaN, which
+        // would serialise as `null` and be rejected far from the mistake.
+        const limit = Number(flags.limit);
+        if (!Number.isInteger(limit))
+            throw new QueryError(`--limit must be a whole number, got "${flags.limit}"`);
+        args['limit'] = limit;
+    }
+    if (flags.type !== undefined)
+        args['chunk_type'] = flags.type;
+    if (flags.language !== undefined)
+        args['language'] = flags.language;
+    if (flags.exported === true)
+        args['only_exported'] = true;
+    if (flags.file !== undefined)
+        args['file_pattern'] = flags.file;
+    return JSON.stringify(args);
+}
+/**
+ * Renders the MCP response as text.
+ *
+ * Every confidence signal the response carries is echoed. An empty result that is
+ * empty *because* the index was busy or stale reads identically to "this symbol
+ * does not exist" unless the flag is shown — the S0 confusion this package's whole
+ * severity scale is built around.
+ */
+export function formatSearchResults(responseText) {
+    const res = JSON.parse(responseText);
+    const lines = [];
+    // Top-level flags. `mast_search` emits none of these — it reserves
+    // `file_busy_returning_stale_cache` for the other tools (mcp/tools/search.ts:33) —
+    // so this branch is kept for shape compatibility and is NOT what protects search.
+    // The three signals search really emits are handled below.
+    const signals = Object.keys(res).filter((k) => /^(file_busy|stale|index_stale|truncated|potential_truncated)/.test(k) && res[k] === true);
+    if (signals.length > 0)
+        lines.push(`! ${signals.join(', ')} — this answer may be incomplete`, '');
+    const hits = res.results ?? [];
+    const staleHits = hits.filter((h) => h.stale === true).length;
+    if (staleHits > 0) {
+        lines.push(`! ${String(staleHits)} of ${String(hits.length)} results are from files that changed since indexing —`, `  the code shown below may be out of date. Run \`mast index\` to refresh.`, '');
+    }
+    if (hits.length === 0) {
+        if (res.index_empty === true) {
+            // The M6 case (ADR 008): an answer that is empty because the system has
+            // nothing to answer FROM must not read like a searched-and-not-found.
+            lines.push('nothing is indexed at this path — this is not evidence the symbol is absent.');
+            lines.push('run `mast index` first, or check `mast status` for the path being used.');
+        }
+        else {
+            lines.push('no matches (mast indexes TypeScript, JavaScript, and Markdown only —');
+            lines.push('a symbol in any other language is invisible to it, not absent from the repo)');
+        }
+        for (const g of res.suggestions ?? []) {
+            lines.push(`  did you mean: ${g.symbol ?? '?'}${g.file_path !== undefined ? `  (${g.file_path})` : ''}`);
+        }
+    }
+    else {
+        for (const h of hits) {
+            const where = `${h.file_path ?? '?'}:${String(h.start_line ?? '?')}`;
+            const what = [h.symbol_name, h.chunk_type].filter(Boolean).join('  ');
+            const marks = [h.is_exported === true ? '(exported)' : '', h.stale === true ? '[STALE]' : '']
+                .filter(Boolean).join('  ');
+            lines.push(`${where}  ${what}${marks === '' ? '' : `  ${marks}`}`);
+            for (const l of (h.content ?? '').split('\n'))
+                lines.push(`    ${l}`);
+            lines.push('');
+        }
+    }
+    const s = res._stats;
+    const got = s?.tokens_returned;
+    const whole = s?.tokens_full_file_upper_bound;
+    // Only meaningful when something matched: with no results the bound is 0 and the
+    // line renders "7 tokens returned vs 0 — 0% MORE", a comparison against nothing
+    // printed as a verdict.
+    if (hits.length > 0 && got !== undefined && whole !== undefined) {
+        // `tokens_full_file_upper_bound` is a bound on reading the referenced files
+        // whole. On small files a ranked result set can exceed it, and the saving is
+        // then negative — reported as such rather than clamped, because a tool whose
+        // efficiency number can only ever look good is not an efficiency number.
+        const saved = whole - got;
+        const pct = whole > 0 ? Math.round((saved / whole) * 100) : 0;
+        lines.push(saved >= 0
+            ? `${String(got)} tokens returned vs ${String(whole)} to read the files whole — ${String(pct)}% saved`
+            : `${String(got)} tokens returned vs ${String(whole)} to read the files whole — ${String(-pct)}% MORE (the matched files are small enough to read outright)`);
+    }
+    return lines.join('\n');
+}
+export function registerSearchCommand(program) {
+    program
+        .command('search <query> [path]')
+        .description('Search the index and print readable results (see `mast query mast_search` for raw MCP output)')
+        .option('--state-dir <dir>', 'State directory')
+        .option('-n, --limit <n>', 'Max results (1-50, default 10)')
+        .option('-t, --type <kind>', 'Restrict to a chunk kind: function, method, class_shell, interface, type, export, block, doc')
+        .option('-l, --language <lang>', 'Restrict to typescript, javascript, or markdown')
+        .option('-e, --exported', 'Only exported symbols')
+        .option('-f, --file <glob>', 'Restrict to files matching a glob')
+        .option('--json', 'Emit the raw MCP response instead of text')
+        .action(async (query, path, opts) => {
+        try {
+            const text = await runQuery('mast_search', buildSearchArgs(query, opts), { stateDir: opts.stateDir, path });
+            process.stdout.write((opts.json === true ? text : formatSearchResults(text)) + '\n');
+        }
+        catch (err) {
+            process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+            process.exitCode = 1;
+        }
+    });
+}
+//# sourceMappingURL=search-cmd.js.map

package/dist/cli/search-cmd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-cmd.js","sourceRoot":"","sources":["../../src/cli/search-cmd.ts"],"names":[],"mappings":"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"}

package/dist/cli/serve.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+export declare function registerServeCommand(program: Command): void;
+//# sourceMappingURL=serve.d.ts.map

package/dist/cli/serve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/cli/serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIzC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAmB3D"}