pi-ast-sgrep 2.0.2 → 2.2.0

package/dist/runtime/index-health.js

@@ -0,0 +1,111 @@
+/**
+ * Index-file health: format probing, completion classification,
+ * rebuild-failure reporting, containment helper. Imports types + sqlite.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { INDEX_FORMAT_VERSION, RuntimeError } from "./types.js";
+import { openIndexDatabase } from "./sqlite.js";
+export function pathContained(parent, child) {
+    const rel = relative(parent, child);
+    const first = rel.split(/[\\/]/u, 1)[0];
+    return rel === "" || (!isAbsolute(rel) && first !== "..");
+}
+export function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+export function indexHealth(status) {
+    const index = record(status.index);
+    const state = typeof index?.status === "string" ? index.status :
+        typeof status.index_status === "string" ? status.index_status : undefined;
+    if (state === "incompatible" || index?.compatible === false || status.index_compatible === false)
+        return "incompatible";
+    if (state === "missing" || index?.exists === false || status.indexed === false)
+        return "missing";
+    if (state === "ready" || state === "current" || index?.exists === true || status.indexed === true)
+        return "ready";
+    if (typeof status.index_path === "string" && typeof status.file_count === "number") {
+        // A present-but-empty index answers nothing: report it as unindexed so the
+        // caller indexes instead of reading zero rows as a legitimate no-match.
+        return status.file_count > 0 ? "ready" : "missing";
+    }
+    throw new RuntimeError("INDEX_STATUS_UNKNOWN", "ast-sgrep status did not report index freshness", { index: status.index, index_status: status.index_status });
+}
+export function incompatibleStatusFailure(cause) {
+    // RuntimeError (CLI envelope) or a plain sticky/NAPI error — both carry the
+    // native version-window message as text. The class gate is intentionally
+    // dropped: this classifier only feeds the rebuild decision.
+    const details = cause instanceof RuntimeError ? cause.details : undefined;
+    const text = `${cause instanceof Error ? cause.message : String(cause)} ${JSON.stringify(details ?? {})}`;
+    return /incompatib|unsupported.{0,24}schema|schema.{0,24}(version|mismatch)|(newer|older) than supported/i.test(text);
+}
+export function indexCompletion(response, requireWalkErrors) {
+    const stats = record(response.stats) ?? response;
+    const failed = stats.files_failed;
+    const walkErrors = stats.walk_errors;
+    if (!Number.isSafeInteger(failed) || failed < 0
+        || (requireWalkErrors ? typeof walkErrors !== "boolean" : walkErrors !== undefined && typeof walkErrors !== "boolean")) {
+        throw new RuntimeError("INDEX_RESPONSE_INVALID", "ast-sgrep index response omitted valid completion status", { filesFailed: failed, walkErrors, requireWalkErrors });
+    }
+    return {
+        failed: failed,
+        walkErrors: walkErrors === true,
+    };
+}
+export function indexPathFor(root, env) {
+    const configured = env.ASGREP_INDEX_PATH;
+    if (!configured)
+        return join(root, ".asgrep", "index.db");
+    const resolved = resolve(root, configured);
+    return extname(resolved) === ".db" ? resolved : join(resolved, "index.db");
+}
+export function indexQuarantines(indexPath) {
+    const quarantinePrefix = `${basename(indexPath)}.corrupt`;
+    try {
+        return readdirSync(dirname(indexPath), { withFileTypes: true })
+            .filter((entry) => entry.isFile() && (entry.name === quarantinePrefix || entry.name.startsWith(`${quarantinePrefix}.`)))
+            .map((entry) => join(dirname(indexPath), entry.name))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** Classify a rebuild failure and identify recovery copies made by this attempt. */
+export function throwIndexRebuildFailed(cause, indexPath, quarantinesBefore) {
+    const newQuarantines = indexQuarantines(indexPath).filter((path) => !quarantinesBefore.has(path));
+    const recoveryPaths = [
+        ...newQuarantines,
+        ...(existsSync(indexPath) ? [indexPath] : []),
+    ];
+    const causeText = cause instanceof Error ? cause.message : String(cause);
+    throw new RuntimeError("INDEX_REBUILD_FAILED", "Incompatible index rebuild failed: " + causeText + "; the prior index remains recoverable", {
+        indexPath,
+        recoveryPath: recoveryPaths[0] ?? indexPath,
+        recoveryPaths,
+        priorIndexPreserved: recoveryPaths.length > 0,
+        expectedIndexFormat: INDEX_FORMAT_VERSION,
+        cause: causeText,
+        repair: "run /asgrep-reindex, or remove the project's .asgrep directory and run /asgrep-index",
+    });
+}
+/** Read the on-disk index format marker. The binary is the authority on what it can read. */
+export function inspectIndexFile(path) {
+    if (!existsSync(path))
+        return "missing";
+    let database;
+    try {
+        database = openIndexDatabase(path, { readOnly: true });
+        const row = database.prepare("PRAGMA user_version").get();
+        const version = Number(Object.values(row ?? {})[0]);
+        if (!Number.isSafeInteger(version) || version <= 0)
+            return "incompatible";
+        return version;
+    }
+    catch {
+        return "incompatible";
+    }
+    finally {
+        database?.close();
+    }
+}

package/dist/runtime/runtime.d.ts

@@ -0,0 +1,48 @@
+import { resolveBinary } from "ast-sgrep";
+import { type MachineEnvelope, type PiExec, type RunOptions, type RuntimeContext } from "./types.js";
+import { resolveConfig, type ConfigSources } from "./config.js";
+import { type IndexHealth } from "./index-health.js";
+export { CONFIG_SCHEMA_VERSION, DEFAULT_FRESHNESS_WAIT_MS, DEFAULT_MAX_OUTPUT_BYTES, DEFAULT_REFRESH_INTERVAL_MS, DEFAULT_TIMEOUT_MS, INDEX_FORMAT_VERSION, MACHINE_SCHEMA_VERSION, RUNTIME_VERSION, RuntimeError, } from "./types.js";
+export type { ExecOptions, ExecResult, MachineEnvelope, PiExec, RunOptions, RuntimeContext, } from "./types.js";
+export { migrateConfig, resolveConfig, rollbackConfig } from "./config.js";
+export type { ConfigSources, LegacyRuntimeConfig, RuntimeConfig, RuntimeConfigInput, } from "./config.js";
+export { FreshnessCoordinator, type FreshnessCoordinatorOptions, type FreshnessRuntime, type FreshnessWatchFactory, } from "./freshness.js";
+export type { IndexHealth } from "./index-health.js";
+export declare function resolveRuntimeRoot(projectCwd: string, requestedRoot?: string, allowOutsideProject?: boolean): Promise<string>;
+type BinaryResolver = typeof resolveBinary;
+export interface RuntimeDependencies {
+    resolveBinary?: BinaryResolver;
+}
+export declare class AstSgrepRuntime {
+    #private;
+    private readonly pi;
+    readonly watchExternalChanges = true;
+    readonly config: ReturnType<typeof resolveConfig>;
+    constructor(pi: PiExec, sources?: ConfigSources, dependencies?: RuntimeDependencies);
+    resolveRoot(context: RuntimeContext): Promise<string>;
+    resolveIndexPath(root: string): string;
+    /**
+     * Index format check. The configured binary is the sole authority on its own
+     * schema window (exact-match: it refuses both older and newer), so the local
+     * probe is only a pre-filter:
+     *   missing/unreadable -> cheap no-spawn health answers;
+     *   version == INDEX_FORMAT_VERSION (this release's shipped format) -> ready;
+     *   otherwise -> consult the binary's declared index_schema_version once
+     *   (cached), because a configured ASGREP_BIN/dev build may be newer than the
+     *   shipped constant. Index newer than the binary -> INDEX_VERSION_TOO_NEW
+     *   (never modified); older -> "incompatible" and rebuild migrates in place.
+     */
+    inspectIndexCompatibility(context: RuntimeContext): Promise<IndexHealth>;
+    private supportedIndexFormat;
+    rebuildIncompatibleIndex(context: RuntimeContext, options?: RunOptions): Promise<MachineEnvelope>;
+    run(args: readonly string[], context: RuntimeContext, options?: RunOptions): Promise<MachineEnvelope>;
+    /** Absolute path to the native binary (for sticky serve / stdin batch spawn). */
+    resolveBinaryPath(options?: {
+        env?: NodeJS.ProcessEnv;
+    }): string;
+    /** Merged process env for native Code Mode workers. */
+    nativeEnv(options?: {
+        env?: NodeJS.ProcessEnv;
+    }): NodeJS.ProcessEnv;
+    checkCompatibility(context: RuntimeContext, options?: RunOptions): Promise<MachineEnvelope>;
+}

package/dist/runtime/runtime.js

@@ -0,0 +1,265 @@
+import { realpath } from "node:fs/promises";
+import { constants, accessSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { resolveBinary } from "ast-sgrep";
+import { CONFIG_SCHEMA_VERSION, DEFAULT_MAX_OUTPUT_BYTES, DEFAULT_REFRESH_INTERVAL_MS, DEFAULT_TIMEOUT_MS, INDEX_FORMAT_VERSION, MACHINE_SCHEMA_VERSION, RUNTIME_VERSION, RuntimeError, RESOLVED_ROOT, } from "./types.js";
+import { finitePositive, migrateConfig, resolveConfig, rollbackConfig, } from "./config.js";
+import { indexCompletion, indexPathFor, indexQuarantines, inspectIndexFile, pathContained, record, throwIndexRebuildFailed, } from "./index-health.js";
+// The public surface of ./runtime is a contract (package.json exports +
+// tests): re-export the symbols that moved to their own modules.
+export { CONFIG_SCHEMA_VERSION, DEFAULT_FRESHNESS_WAIT_MS, DEFAULT_MAX_OUTPUT_BYTES, DEFAULT_REFRESH_INTERVAL_MS, DEFAULT_TIMEOUT_MS, INDEX_FORMAT_VERSION, MACHINE_SCHEMA_VERSION, RUNTIME_VERSION, RuntimeError, } from "./types.js";
+export { migrateConfig, resolveConfig, rollbackConfig } from "./config.js";
+export { FreshnessCoordinator, } from "./freshness.js";
+export async function resolveRuntimeRoot(projectCwd, requestedRoot, allowOutsideProject = false) {
+    let project;
+    let candidate;
+    try {
+        project = await realpath(resolve(projectCwd));
+        candidate = await realpath(resolve(project, requestedRoot ?? "."));
+    }
+    catch (cause) {
+        throw new RuntimeError("INVALID_ROOT", "Project or requested root does not exist", { projectCwd, requestedRoot, cause: cause instanceof Error ? cause.message : String(cause) });
+    }
+    if (!allowOutsideProject && !pathContained(project, candidate)) {
+        throw new RuntimeError("ROOT_OUTSIDE_PROJECT", "Requested root resolves outside the project", { project, requestedRoot, resolvedRoot: candidate });
+    }
+    return candidate;
+}
+function getBinary(config, env, resolver) {
+    let binary;
+    try {
+        const options = config.binaryPath ? { binaryPath: config.binaryPath, env } : { env };
+        binary = resolver(options);
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        if (config.binaryPath) {
+            throw new RuntimeError("BINARY_NOT_FOUND", `Configured ast-sgrep binary is unavailable: ${config.binaryPath}`, { binaryPath: config.binaryPath, cause: message });
+        }
+        throw new RuntimeError("BINARY_RESOLUTION_FAILED", "Unable to resolve an ast-sgrep binary for this platform", { cause: message });
+    }
+    try {
+        accessSync(binary, constants.X_OK);
+    }
+    catch (cause) {
+        throw new RuntimeError("BINARY_NOT_EXECUTABLE", `ast-sgrep binary is not executable: ${binary}`, { binaryPath: binary, cause: cause instanceof Error ? cause.message : String(cause) });
+    }
+    return binary;
+}
+function byteLength(value) { return Buffer.byteLength(value, "utf8"); }
+/** Present-field version identity checks. Pass `requireIdentity` for version --json. */
+function assertVersionTriple(envelope, requireIdentity = false) {
+    // Compound guards (same short-circuit as nested if): check only when required or field present.
+    if ((requireIdentity || envelope.version !== undefined) && envelope.version !== RUNTIME_VERSION) {
+        throw new RuntimeError("VERSION_MISMATCH", "ast-sgrep binary version does not match the extension", { expected: RUNTIME_VERSION, actual: envelope.version });
+    }
+    if ((requireIdentity || envelope.machine_schema_version !== undefined) && envelope.machine_schema_version !== MACHINE_SCHEMA_VERSION) {
+        throw new RuntimeError("PROTOCOL_MISMATCH", "ast-sgrep binary reports an incompatible machine protocol", { expected: MACHINE_SCHEMA_VERSION, actual: envelope.machine_schema_version });
+    }
+}
+/**
+ * Nonzero CLI exit: prefer structured failed envelope (OPERATIONAL_ERROR), else PROCESS_FAILED.
+ * Always throws — error-path extract so parseEnvelope keeps success-path protocol field checks.
+ */
+function throwNonzeroProcessFailure(result, code) {
+    try {
+        const value = record(JSON.parse(result.stdout));
+        // Wire-valid ok:false asgrep envelope → structured operational failure (not PROCESS_FAILED).
+        if (value && value.tool === "asgrep" && value.schema_version === MACHINE_SCHEMA_VERSION && value.ok === false) {
+            const failure = record(value.error);
+            const message = typeof failure?.message === "string" ? failure.message : "ast-sgrep reported an operational failure";
+            throw new RuntimeError("OPERATIONAL_ERROR", message, { command: value.command, error: failure, exitCode: code });
+        }
+    }
+    catch (cause) {
+        if (cause instanceof RuntimeError)
+            throw cause;
+    }
+    throw new RuntimeError("PROCESS_FAILED", `ast-sgrep exited with code ${code}`, {
+        exitCode: code,
+        signal: result.signal ?? undefined,
+        stderr: result.stderr.slice(0, 1024),
+    });
+}
+/** Map exec failures (abort / timeout / generic) to RuntimeError. Re-throws RuntimeError as-is. */
+function rethrowExecFailure(cause, options, timeout) {
+    if (cause instanceof RuntimeError)
+        throw cause;
+    if (options.signal?.aborted || (cause instanceof Error && cause.name === "AbortError")) {
+        throw new RuntimeError("CANCELLED", "ast-sgrep execution was cancelled");
+    }
+    const message = cause instanceof Error ? cause.message : String(cause);
+    if (/timeout|timed out/i.test(message)) {
+        throw new RuntimeError("TIMEOUT", `ast-sgrep exceeded ${timeout}ms`, { timeoutMs: timeout });
+    }
+    throw new RuntimeError("EXEC_FAILED", "Unable to execute ast-sgrep", { cause: message });
+}
+function parseEnvelope(result, limit) {
+    const stdoutBytes = byteLength(result.stdout);
+    const stderrBytes = byteLength(result.stderr);
+    // Byte lengths are non-negative: sum > limit covers either-side overflow and combined cap.
+    if (stdoutBytes + stderrBytes > limit) {
+        throw new RuntimeError("OUTPUT_LIMIT", "ast-sgrep output exceeded the configured limit", { limit, stdoutBytes, stderrBytes });
+    }
+    const code = result.exitCode ?? result.code ?? 0;
+    if (code !== 0) {
+        throwNonzeroProcessFailure(result, code);
+    }
+    let value;
+    try {
+        value = JSON.parse(result.stdout);
+    }
+    catch (cause) {
+        throw new RuntimeError("MALFORMED_OUTPUT", "ast-sgrep returned malformed JSON", { cause: cause instanceof Error ? cause.message : String(cause) });
+    }
+    const envelope = record(value);
+    if (!envelope)
+        throw new RuntimeError("MALFORMED_OUTPUT", "ast-sgrep returned a non-object JSON payload");
+    // Protocol field varieties (Ashby Keep) — sequential wire-contract checks stay here.
+    if (envelope.tool !== "asgrep")
+        throw new RuntimeError("TOOL_MISMATCH", "Response is not from ast-sgrep", { actual: envelope.tool });
+    if (envelope.schema_version !== MACHINE_SCHEMA_VERSION)
+        throw new RuntimeError("PROTOCOL_MISMATCH", "Unsupported ast-sgrep machine protocol", { expected: MACHINE_SCHEMA_VERSION, actual: envelope.schema_version });
+    if (typeof envelope.ok !== "boolean")
+        throw new RuntimeError("MALFORMED_OUTPUT", "ast-sgrep response is missing boolean ok");
+    if (!envelope.ok) {
+        // Preserve pre-extract failure shape: plain object check (arrays allowed as error bag).
+        const failure = envelope.error && typeof envelope.error === "object" ? envelope.error : undefined;
+        const message = typeof failure?.message === "string" ? failure.message : "ast-sgrep reported an operational failure";
+        throw new RuntimeError("OPERATIONAL_ERROR", message, { command: envelope.command, error: failure });
+    }
+    assertVersionTriple(envelope);
+    return envelope;
+}
+export class AstSgrepRuntime {
+    pi;
+    watchExternalChanges = true;
+    config;
+    #resolver;
+    #environment;
+    constructor(pi, sources = {}, dependencies = {}) {
+        this.pi = pi;
+        this.#environment = sources.environment ?? process.env;
+        this.config = resolveConfig({ ...sources, environment: this.#environment });
+        this.#resolver = dependencies.resolveBinary ?? resolveBinary;
+    }
+    async resolveRoot(context) {
+        return context[RESOLVED_ROOT]
+            ? resolveRuntimeRoot(context.cwd)
+            : resolveRuntimeRoot(context.cwd, this.config.root, this.config.allowOutsideProject);
+    }
+    resolveIndexPath(root) {
+        return indexPathFor(root, { ...this.#environment, ...this.config.env });
+    }
+    /**
+     * Index format check. The configured binary is the sole authority on its own
+     * schema window (exact-match: it refuses both older and newer), so the local
+     * probe is only a pre-filter:
+     *   missing/unreadable -> cheap no-spawn health answers;
+     *   version == INDEX_FORMAT_VERSION (this release's shipped format) -> ready;
+     *   otherwise -> consult the binary's declared index_schema_version once
+     *   (cached), because a configured ASGREP_BIN/dev build may be newer than the
+     *   shipped constant. Index newer than the binary -> INDEX_VERSION_TOO_NEW
+     *   (never modified); older -> "incompatible" and rebuild migrates in place.
+     */
+    async inspectIndexCompatibility(context) {
+        const root = await this.resolveRoot(context);
+        const indexPath = indexPathFor(root, { ...this.#environment, ...this.config.env });
+        const version = inspectIndexFile(indexPath);
+        if (version === "missing" || version === "incompatible")
+            return version;
+        if (version === INDEX_FORMAT_VERSION)
+            return "ready";
+        const supported = await this.supportedIndexFormat(context);
+        if (version === supported)
+            return "ready";
+        if (version > supported) {
+            throw new RuntimeError("INDEX_VERSION_TOO_NEW", "Index schema is newer than the configured ast-sgrep binary", {
+                actual: version,
+                supported,
+                rollbackSafe: true,
+            });
+        }
+        return "incompatible";
+    }
+    /** The configured binary's declared index schema, or this release's shipped floor. */
+    #indexFormatProbe;
+    supportedIndexFormat(context) {
+        if (!this.#indexFormatProbe) {
+            const probe = this.run(["version", "--json"], context)
+                .then((envelope) => {
+                const declared = envelope.index_schema_version;
+                return typeof declared === "number" && Number.isSafeInteger(declared) && declared > 0
+                    ? declared
+                    : INDEX_FORMAT_VERSION;
+            });
+            this.#indexFormatProbe = probe;
+            // A failed probe (binary missing/exec error) must not be cached forever.
+            probe.catch(() => {
+                if (this.#indexFormatProbe === probe)
+                    this.#indexFormatProbe = undefined;
+            });
+        }
+        return this.#indexFormatProbe;
+    }
+    async rebuildIncompatibleIndex(context, options = {}) {
+        const root = await this.resolveRoot(context);
+        const env = { ...this.#environment, ...this.config.env, ...options.env };
+        const indexPath = indexPathFor(root, env);
+        const quarantinesBefore = new Set(indexQuarantines(indexPath));
+        try {
+            // Core reindex prepares files before opening one bulk transaction and
+            // commits rewrites plus stale-row pruning together. Keeping the same DB
+            // inode avoids stale warm NAPI sessions and removes rename crash windows.
+            const response = await this.run(["reindex", ".", "--json"], { cwd: root }, options);
+            const { failed, walkErrors } = indexCompletion(response, true);
+            if (failed > 0 || walkErrors) {
+                throw new RuntimeError("INDEX_UPDATE_INCOMPLETE", "ast-sgrep did not complete the incompatible-index rebuild", { failed, walkErrors, force: true });
+            }
+            if ((await this.inspectIndexCompatibility(context)) !== "ready") {
+                throw new RuntimeError("INDEX_REBUILD_INVALID", "Rebuilt index has an incompatible format", { expected: INDEX_FORMAT_VERSION });
+            }
+            return response;
+        }
+        catch (cause) {
+            throwIndexRebuildFailed(cause, indexPath, quarantinesBefore);
+        }
+    }
+    async run(args, context, options = {}) {
+        if (!Array.isArray(args) || args.some((arg) => typeof arg !== "string"))
+            throw new RuntimeError("INVALID_ARGUMENTS", "Arguments must be a string array");
+        if (options.signal?.aborted)
+            throw new RuntimeError("CANCELLED", "ast-sgrep execution was cancelled");
+        const root = await this.resolveRoot(context);
+        const timeout = finitePositive(options.timeoutMs, this.config.timeoutMs, "timeoutMs");
+        const env = this.#mergedEnv(options.env);
+        const binary = getBinary(this.config, env, this.#resolver);
+        try {
+            const execOptions = { cwd: root, env, timeout };
+            if (options.signal)
+                execOptions.signal = options.signal;
+            const result = await this.pi.exec(binary, Object.freeze([...args]), execOptions);
+            return parseEnvelope(result, this.config.maxOutputBytes);
+        }
+        catch (cause) {
+            rethrowExecFailure(cause, options, timeout);
+        }
+    }
+    /** environment < config.env < options.env < NO_COLOR — the merge every path shares. */
+    #mergedEnv(extra) {
+        return { ...this.#environment, ...this.config.env, ...extra, NO_COLOR: "1" };
+    }
+    /** Absolute path to the native binary (for sticky serve / stdin batch spawn). */
+    resolveBinaryPath(options = {}) {
+        return getBinary(this.config, this.#mergedEnv(options.env), this.#resolver);
+    }
+    /** Merged process env for native Code Mode workers. */
+    nativeEnv(options = {}) {
+        return this.#mergedEnv(options.env);
+    }
+    async checkCompatibility(context, options = {}) {
+        const value = await this.run(["version", "--json"], context, options);
+        assertVersionTriple(value, true);
+        return value;
+    }
+}

package/dist/runtime/sqlite.d.ts

@@ -0,0 +1,15 @@
+export type SqliteBackend = "node" | "bun";
+export interface IndexStatement {
+    get(...params: unknown[]): unknown;
+    run(...params: unknown[]): unknown;
+}
+export interface IndexDatabase {
+    prepare(sql: string): IndexStatement;
+    exec(sql: string): unknown;
+    close(): void;
+}
+export declare function sqliteBackend(): SqliteBackend;
+/** Open the index DB with Node `node:sqlite` or Bun `bun:sqlite`. */
+export declare function openIndexDatabase(path: string, options?: {
+    readOnly?: boolean;
+}): IndexDatabase;

package/dist/runtime/sqlite.js

@@ -0,0 +1,63 @@
+import { createRequire } from "node:module";
+let cached;
+function bunVersion() {
+    return process.versions.bun;
+}
+function loadModule(specifier) {
+    return createRequire(import.meta.url)(specifier);
+}
+function loadBackend() {
+    if (cached)
+        return cached;
+    if (bunVersion() !== undefined) {
+        cached = { backend: "bun", Ctor: requireCtor(loadModule("bun:sqlite"), "Database") };
+        return cached;
+    }
+    try {
+        cached = { backend: "node", Ctor: requireCtor(loadModule("node:sqlite"), "DatabaseSync") };
+        return cached;
+    }
+    catch (nodeError) {
+        try {
+            cached = { backend: "bun", Ctor: requireCtor(loadModule("bun:sqlite"), "Database") };
+            return cached;
+        }
+        catch {
+            throw new Error("No SQLite backend available (node:sqlite and bun:sqlite both failed)", {
+                cause: nodeError,
+            });
+        }
+    }
+}
+function requireCtor(mod, name) {
+    const Ctor = mod[name];
+    if (typeof Ctor !== "function") {
+        throw new Error(`SQLite module is missing ${name}`);
+    }
+    return Ctor;
+}
+export function sqliteBackend() {
+    return loadBackend().backend;
+}
+/** Open the index DB with Node `node:sqlite` or Bun `bun:sqlite`. */
+export function openIndexDatabase(path, options = {}) {
+    const { backend, Ctor } = loadBackend();
+    const readOnly = options.readOnly === true;
+    const database = backend === "bun"
+        ? new Ctor(path, { readonly: readOnly, create: !readOnly })
+        : new Ctor(path, { readOnly });
+    return {
+        prepare(sql) {
+            const statement = database.prepare?.(sql) ?? database.query?.(sql);
+            if (!statement)
+                throw new Error("SQLite statement API is unavailable");
+            return statement;
+        },
+        exec(sql) {
+            return database.exec(sql);
+        },
+        close() {
+            database.close();
+        },
+    };
+}

package/dist/runtime/types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Shared leaf module: version constants, wire types, RuntimeError.
+ * Imports nothing from sibling modules — any file may depend on it.
+ */
+export declare const RUNTIME_VERSION = "2.1.0";
+export declare const MACHINE_SCHEMA_VERSION = "1.0.0";
+export declare const CONFIG_SCHEMA_VERSION: 1;
+/** Index format this release ships. Must equal INDEX_SCHEMA_VERSION in crates/ast-sgrep-core (check-contract gates it). */
+export declare const INDEX_FORMAT_VERSION: 16;
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+export declare const DEFAULT_MAX_OUTPUT_BYTES: number;
+export declare const DEFAULT_REFRESH_INTERVAL_MS = 30000;
+/** Max one caller waits on a shared index refresh before serving stale. */
+export declare const DEFAULT_FRESHNESS_WAIT_MS = 10000;
+export interface RuntimeContext {
+    cwd: string;
+}
+export declare const RESOLVED_ROOT: unique symbol;
+export type InternalRuntimeContext = RuntimeContext & {
+    [RESOLVED_ROOT]?: true;
+};
+export interface RunOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    env?: Readonly<Record<string, string>>;
+}
+export interface ExecOptions {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    signal?: AbortSignal;
+    timeout?: number;
+}
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    code?: number | null;
+    exitCode?: number | null;
+    signal?: string | null;
+}
+export interface PiExec {
+    exec(command: string, args: readonly string[], options: ExecOptions): Promise<ExecResult>;
+}
+export interface MachineEnvelope {
+    tool: "asgrep";
+    schema_version: string;
+    ok: boolean;
+    version?: string;
+    machine_schema_version?: string;
+    [key: string]: unknown;
+}
+export declare class RuntimeError extends Error {
+    readonly code: string;
+    readonly details: Readonly<Record<string, unknown>>;
+    constructor(code: string, message: string, details?: Readonly<Record<string, unknown>>);
+}

package/dist/runtime/types.js

@@ -0,0 +1,25 @@
+/**
+ * Shared leaf module: version constants, wire types, RuntimeError.
+ * Imports nothing from sibling modules — any file may depend on it.
+ */
+export const RUNTIME_VERSION = "2.1.0";
+export const MACHINE_SCHEMA_VERSION = "1.0.0";
+export const CONFIG_SCHEMA_VERSION = 1;
+/** Index format this release ships. Must equal INDEX_SCHEMA_VERSION in crates/ast-sgrep-core (check-contract gates it). */
+export const INDEX_FORMAT_VERSION = 16;
+export const DEFAULT_TIMEOUT_MS = 30_000;
+export const DEFAULT_MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+export const DEFAULT_REFRESH_INTERVAL_MS = 30_000;
+/** Max one caller waits on a shared index refresh before serving stale. */
+export const DEFAULT_FRESHNESS_WAIT_MS = 10_000;
+export const RESOLVED_ROOT = Symbol("resolvedRoot");
+export class RuntimeError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = "AstSgrepRuntimeError";
+    }
+}

package/dist/ui/card.d.ts

@@ -0,0 +1,66 @@
+/** Pi TUI result card — supernova-style: the call slot is empty; one card
+ * owns the whole lifecycle (running → ops ledger → result → error). Rows are
+ * fixed-column and theme-painted; nothing here writes to the model channel. */
+import { type HitLike, type PresentTheme } from "./present.js";
+/** renderCall component that paints nothing — the result card owns display. */
+export declare const EMPTY_CALL: {
+    render: () => string[];
+    invalidate(): void;
+};
+export type CardModel = {
+    command: string;
+    title: Array<string | null | undefined>;
+    hits?: HitLike[];
+    /** Applied edit diffs: path + line + removed/added line arrays. */
+    edits?: Array<{
+        path?: string;
+        line?: number;
+        removed?: string[];
+        added?: string[];
+        truncated?: boolean;
+    }>;
+    ops?: Array<{
+        tool: string;
+        target: string;
+        ok: boolean;
+        ms: number;
+    }>;
+    resultLines?: string[];
+    /** Warnings that qualify the answer (stale index, unindexed repo). */
+    notes?: string[];
+    error?: string;
+    running?: boolean;
+    expanded?: boolean;
+};
+export declare class AsgrepCard {
+    theme: PresentTheme | undefined;
+    model: CardModel | undefined;
+    cache: {
+        width: number;
+        lines: string[];
+    } | undefined;
+    set(theme: PresentTheme | undefined, model: CardModel): void;
+    invalidate(): void;
+    render(width?: number): string[];
+}
+type ResultLike = {
+    isError?: boolean;
+    content?: Array<{
+        type: string;
+        text?: string;
+    }>;
+    details?: unknown;
+};
+type RenderOptions = {
+    expanded?: boolean;
+    isPartial?: boolean;
+};
+type RenderContext = {
+    lastComponent?: unknown;
+    args?: object;
+};
+/** Build the card model from the tool result's details payload. */
+export declare function cardModel(result: ResultLike, options: RenderOptions, callArgs?: Record<string, unknown>): CardModel;
+/** renderResult entrypoint: bind one card per result slot, feed it details. */
+export declare function renderAsgrepResult(result: ResultLike, options: RenderOptions, theme: PresentTheme, context?: RenderContext): AsgrepCard;
+export {};