pi-ast-sgrep 2.5.2 → 2.5.3

package/README.md

@@ -6,7 +6,9 @@ Native Code Mode, structural, graph, and semantic code search for [Pi](https://g
 
 `pi-ast-sgrep` gives Pi a warm, project-aware search engine for understanding code. It finds behavior by intent, resolves definitions and callers, traces relationships, matches syntax-aware patterns, joins two indexed channels, and searches local semantic embeddings. The primary `asgrep` tool lets Pi compose several searches in one JavaScript program instead of spending one model round trip per lookup.
 
-**v2.0.0** · 13 languages · local-first semantic · critic + two-channel `AND` · **Code Mode** (on by default, no API key)
+**v2.5.3** (native engine 2.5.2) · 15 languages · local-first semantic · critic + two-channel `AND` · **Code Mode** (on by default, no API key)
+
+**2.5.3 recovery fix:** Missing `ASGREP_BIN`/`AST_SGREP_BINARY` developer builds now fall back to the verified bundled binary with a warning. Explicit `binaryPath` settings and invalid binaries remain strict. `asgrep_read` works without a search backend or index, `/asgrep-doctor` reports component versions, and the launcher dependency now requires at least 2.5.2. Update with `pi update npm:pi-ast-sgrep`, then reload Pi.
 
 **Upgrading to 2.0:** this is a breaking semver release because the cloud/Ollama embedding backends were removed. Update the Pi package normally; local hashed semantic search remains the default, optional neural embeddings remain in-process, and indexes that still store `embed_backend=cloud|ollama` fail closed until `/asgrep-reindex`. One-shot tools and Code Mode now put bounded hits in `content` so the model sees them, not only display-only `details`.
 

package/dist/codemode/connector.d.ts

@@ -104,4 +104,5 @@ export declare function createAsgrepConnector(host: BatchCapableHost, context: {
 }, options?: {
     signal?: AbortSignal;
     scope?: string;
+    localReads?: boolean;
 }): ConnectorBundle;

package/dist/codemode/connector.js

@@ -80,6 +80,8 @@ export function createAsgrepConnector(host, context, options = {}) {
     };
     const call = async (tool, args, signal) => {
         const opts = callOptions(signal);
+        if (tool === "read" && options.localReads)
+            return fallbackCall(tool, args, opts.signal);
         if (NATIVE_FALLBACK_TOOLS.has(tool) && nativeMissing.has(tool))
             return fallbackCall(tool, args, opts.signal);
         try {

package/dist/host/commands.js

@@ -14,17 +14,25 @@ async function runCommand(runtime, command, ctx, args) {
             error: { code: "INVALID_ARGUMENTS", message: `/${command} does not accept arguments`, details: { args } },
         };
     }
+    let diagnostics;
     try {
+        if (command === "asgrep-doctor")
+            diagnostics = await runtime.diagnostics?.({ cwd: ctx.cwd });
         const response = await runtime.run([command.slice("asgrep-".length), ".", "--json"], { cwd: ctx.cwd });
-        return { ok: true, command, response };
+        return { ok: true, command, response, ...(diagnostics ? { diagnostics } : {}) };
     }
     catch (cause) {
-        return { ok: false, command, error: errorDetails(cause) };
+        return { ok: false, command, error: errorDetails(cause), ...(diagnostics ? { diagnostics } : {}) };
     }
 }
 function compactCommandResult(result) {
+    const diagnostics = result.diagnostics;
+    const versions = diagnostics
+        ? `extension=${diagnostics.extension ?? "unknown"} launcher=${diagnostics.launcher ?? "unknown"} native=${diagnostics.native ?? "unavailable"}`
+        : "";
+    const warning = typeof diagnostics?.warning === "string" ? diagnostics.warning : "";
     if (!result.ok)
-        return `${result.command} failed [${result.error.code}]: ${result.error.message}`;
+        return bounded([`${result.command} failed [${result.error.code}]: ${result.error.message}`, versions, warning].filter(Boolean).join(" · "));
     const response = result.response;
     const counts = response.counts && typeof response.counts === "object"
         ? Object.entries(response.counts).map(([key, value]) => `${key}=${String(value)}`).join(" ")
@@ -32,7 +40,7 @@ function compactCommandResult(result) {
     const state = typeof response.status === "string" ? response.status
         : typeof response.index_status === "string" ? response.index_status
             : response.ok ? "healthy" : "failed";
-    return bounded([`${result.command}: ${state}`, counts].filter(Boolean).join(" · "));
+    return bounded([`${result.command}: ${state}`, counts, versions, warning].filter(Boolean).join(" · "));
 }
 export function registerAstSgrepCommands(pi, runtime = new AstSgrepRuntime(pi)) {
     for (const [name, description] of COMMANDS) {
@@ -42,7 +50,7 @@ export function registerAstSgrepCommands(pi, runtime = new AstSgrepRuntime(pi))
                 const ctx = context;
                 const result = await runCommand(runtime, name, ctx, args);
                 const output = ctx.hasUI ? compactCommandResult(result) : JSON.stringify(result);
-                ctx.ui.notify(output, result.ok ? "info" : "error");
+                ctx.ui.notify(output, result.ok ? result.diagnostics?.warning ? "warning" : "info" : "error");
             },
         });
     }

package/dist/host/results.d.ts

@@ -14,6 +14,10 @@ export type RuntimeLike = {
     nativeEnv?(options?: {
         env?: NodeJS.ProcessEnv;
     }): NodeJS.ProcessEnv;
+    binaryWarning?(): string | undefined;
+    diagnostics?(context: {
+        cwd: string;
+    }): Promise<Record<string, unknown>>;
     config?: {
         timeoutMs?: number;
         maxOutputBytes?: number;
@@ -42,6 +46,8 @@ export type CommandContext = ToolContext & {
     };
 };
 export type CommandResult = {
+    diagnostics?: Record<string, unknown>;
+} & ({
     ok: true;
     command: string;
     response: MachineEnvelope;
@@ -53,7 +59,7 @@ export type CommandResult = {
         message: string;
         details: Readonly<Record<string, unknown>>;
     };
-};
+});
 export type Update = (result: {
     content: Array<{
         type: "text";

package/dist/host/tools.js

@@ -281,7 +281,7 @@ export function registerAstSgrepTools(pi, runtime = new AstSgrepRuntime(pi), fre
     const requireBackend = (availability, context) => {
         if (availability.kind !== "unavailable")
             return;
-        throw new RuntimeError("BACKEND_UNAVAILABLE", "ast-sgrep backend unavailable (no NAPI session and no CLI binary)", {
+        throw new RuntimeError("BACKEND_UNAVAILABLE", `ast-sgrep backend unavailable (no NAPI session and no CLI binary)${availability.cause ? `: ${availability.cause}` : ""}. Run /asgrep-doctor for recovery details.`, {
             backend: "unavailable",
             // Agent-facing mirrors of the closed unavailable variant (not an open product).
             napi: false,
@@ -502,6 +502,11 @@ export function registerAstSgrepTools(pi, runtime = new AstSgrepRuntime(pi), fre
             catch {
                 // Doctor reports backend errors; a failed warmup must not block the session.
             }
+            finally {
+                const warning = runtime.binaryWarning?.();
+                if (warning && ctx.hasUI)
+                    ctx.ui.notify(warning, "warning");
+            }
         })();
     });
     pi.on("session_shutdown", () => {
@@ -716,14 +721,13 @@ export function registerAstSgrepTools(pi, runtime = new AstSgrepRuntime(pi), fre
         async execute(_toolCallId, params, signal, onUpdate, ctx) {
             report(onUpdate, "read", "started");
             try {
-                ensurePool();
+                // Reading source must remain available when the binary or index is broken.
                 const options = signal ? { signal } : {};
-                const { root, scope, freshness: fresh } = await freshRoot(ctx.cwd, signal);
-                const sticky = await pool.acquire(root);
-                const bundle = createAsgrepConnector({ run: (a, c, o) => runtime.run(a, c, o), sticky }, rootedAt(root), { ...options, ...(scope ? { scope } : {}) });
+                const { root, scope } = await anchorRoot(ctx.cwd);
+                const bundle = createAsgrepConnector({ run: (a, c, o) => runtime.run(a, c, o) }, rootedAt(root), { ...options, localReads: true, ...(scope ? { scope } : {}) });
                 const response = await bundle.asgrep.read(params);
                 report(onUpdate, "read", "completed");
-                return success("read", response, { backend: pool.backend(), ...(fresh ? { freshness: fresh } : {}) });
+                return success("read", response, { backend: "filesystem" });
             }
             catch (cause) {
                 return failure("read", cause, signal);

package/dist/runtime/runtime.d.ts

@@ -40,6 +40,9 @@ export declare class AstSgrepRuntime {
     resolveBinaryPath(options?: {
         env?: NodeJS.ProcessEnv;
     }): string;
+    binaryWarning(): string | undefined;
+    /** Report installed layers even if the project's index cannot be opened. */
+    diagnostics(context: RuntimeContext): Promise<Record<string, unknown>>;
     /** Merged process env for native Code Mode workers. */
     nativeEnv(options?: {
         env?: NodeJS.ProcessEnv;

package/dist/runtime/runtime.js

@@ -1,6 +1,7 @@
 import { realpath } from "node:fs/promises";
-import { constants, accessSync } from "node:fs";
-import { isAbsolute, resolve } from "node:path";
+import { constants, accessSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { createRequire } from "node:module";
 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";
@@ -25,18 +26,37 @@ export async function resolveRuntimeRoot(projectCwd, requestedRoot, allowOutside
     }
     return candidate;
 }
-function getBinary(config, env, resolver) {
+function getBinary(config, env, resolver, onRecovery) {
     let binary;
+    let warning;
     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 });
+        const failure = cause;
+        // Missing environment-only dev builds may recover, never explicit settings,
+        // permissions, empty artifacts, checksum failures, PATH, or downloads.
+        if (onRecovery && (env.ASGREP_BIN || env.AST_SGREP_BINARY) && failure?.code === "ASGREP_EXECUTABLE_MISSING" &&
+            (failure.cause?.code === "ENOENT" || failure.cause?.code === "ENOTDIR")) {
+            const variable = env.ASGREP_BIN ? "ASGREP_BIN" : "AST_SGREP_BINARY";
+            try {
+                binary = resolver({ env: { ...env, ASGREP_BIN: undefined, AST_SGREP_BINARY: undefined } });
+            }
+            catch (fallbackCause) {
+                const fallback = fallbackCause instanceof Error ? fallbackCause.message : String(fallbackCause);
+                throw new RuntimeError("BINARY_RESOLUTION_FAILED", `Missing ${variable} override (${config.binaryPath ?? env[variable]}); bundled binary unavailable: ${fallback}. Run /asgrep-doctor and reinstall pi-ast-sgrep with optional dependencies enabled.`, { cause: message, fallbackCause: fallback });
+            }
+            warning = `Ignored missing ${variable}=${config.binaryPath ?? env[variable]}; using bundled binary ${binary}. Remove the stale export from your shell configuration.`;
+        }
+        else {
+            const hint = "Correct binaryPath or unset ASGREP_BIN/AST_SGREP_BINARY; run /asgrep-doctor.";
+            if (config.binaryPath) {
+                throw new RuntimeError("BINARY_NOT_FOUND", `Configured ast-sgrep binary is unavailable: ${config.binaryPath}. ${message}. ${hint}`, { binaryPath: config.binaryPath, cause: message, hint });
+            }
+            throw new RuntimeError("BINARY_RESOLUTION_FAILED", `Unable to resolve an ast-sgrep binary for this platform: ${message}. Run /asgrep-doctor.`, { 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);
@@ -44,6 +64,8 @@ function getBinary(config, env, resolver) {
     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) });
     }
+    if (warning)
+        onRecovery?.(warning);
     return binary;
 }
 function byteLength(value) { return Buffer.byteLength(value, "utf8"); }
@@ -153,11 +175,15 @@ export class AstSgrepRuntime {
     config;
     #resolver;
     #environment;
+    #recoverMissingOverride;
+    #binaryWarning;
     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;
+        this.#recoverMissingOverride = ![sources.explicitProjectConfig, sources.projectSettings, sources.globalSettings, sources.defaults]
+            .some(source => source?.binaryPath !== undefined);
     }
     async resolveRoot(context) {
         return context[RESOLVED_ROOT]
@@ -249,7 +275,7 @@ export class AstSgrepRuntime {
         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);
+        const binary = this.resolveBinaryPath({ env });
         try {
             const execOptions = { cwd: root, env, timeout };
             if (options.signal)
@@ -267,7 +293,35 @@ export class AstSgrepRuntime {
     }
     /** Absolute path to the native binary (for sticky serve / stdin batch spawn). */
     resolveBinaryPath(options = {}) {
-        return getBinary(this.config, this.#mergedEnv(options.env), this.#resolver);
+        this.#binaryWarning = undefined;
+        return getBinary(this.config, this.#mergedEnv(options.env), this.#resolver, this.#recoverMissingOverride ? warning => { this.#binaryWarning = warning; } : undefined);
+    }
+    binaryWarning() { return this.#binaryWarning; }
+    /** Report installed layers even if the project's index cannot be opened. */
+    async diagnostics(context) {
+        const versionAt = (path) => {
+            try {
+                return JSON.parse(readFileSync(path, "utf8")).version ?? "unknown";
+            }
+            catch {
+                return "unknown";
+            }
+        };
+        const result = {
+            extension: versionAt(new URL("../../package.json", import.meta.url)),
+        };
+        try {
+            const launcher = createRequire(import.meta.url).resolve("ast-sgrep");
+            result.launcher = versionAt(join(dirname(launcher), "..", "package.json"));
+            result.binaryPath = this.resolveBinaryPath();
+            result.native = (await this.checkCompatibility(context)).version;
+        }
+        catch (cause) {
+            result.error = cause instanceof Error ? cause.message : String(cause);
+        }
+        if (this.#binaryWarning)
+            result.warning = this.#binaryWarning;
+        return result;
     }
     /** Merged process env for native Code Mode workers. */
     nativeEnv(options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ast-sgrep",
-  "version": "2.5.2",
+  "version": "2.5.3",
   "description": "Native Code Mode, structural, graph, and semantic code search for Pi",
   "type": "module",
   "license": "MIT",
@@ -63,7 +63,7 @@
     "node": ">=22.19.0"
   },
   "dependencies": {
-    "ast-sgrep": ">=2.0.0 <3",
+    "ast-sgrep": ">=2.5.2 <3",
     "typebox": "^1.0.0"
   },
   "peerDependencies": {