agrep-cli 0.4.1 → 0.4.5

package/bin.js

@@ -13,13 +13,38 @@ const { version } = require("./package.json");
 const SPEC = process.env.AGREP_PYPI_SPEC || `agrep==${version}`;
 const args = process.argv.slice(2);
 
-function has(cmd) {
-  const probe = spawnSync(cmd, ["--version"], { stdio: "ignore", shell: false });
-  return probe.status === 0;
+// uv/pipx run agrep out of a cache that a prune wipes while this package
+// stays installed; the sentinel tracks this file instead (see teach.install_anchor).
+const ANCHOR_ENV = "AGREP_INSTALL_ANCHOR";
+
+function probe(cmd) {
+  const r = spawnSync(cmd, ["--version"], { encoding: "utf8", shell: false });
+  return !r.error && r.status === 0 ? String(r.stdout || "") : null;
+}
+
+function uvVersion(text) {
+  const m = /\buv\s+(\d+)\.(\d+)\.(\d+)/.exec(text || "");
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+// `--exclude-newer-package agrep=false` opts agrep out of a user's global
+// exclude-newer pin; only uv >= 0.9.25 parses the `=false` form, older uv
+// rejects the whole invocation, so the flag rides along only where it parses.
+function excludeNewerOptOut(v) {
+  return v !== null && (v[0] > 0 || v[1] > 9 || (v[1] === 9 && v[2] >= 25));
+}
+
+function uvArgs(uvVersionText, rest) {
+  const flag = excludeNewerOptOut(uvVersion(uvVersionText))
+    ? ["--exclude-newer-package", "agrep=false"] : [];
+  return ["tool", "run", ...flag, "--from", SPEC, "agrep", ...rest];
 }
 
 function run(cmd, cmdArgs) {
-  const r = spawnSync(cmd, cmdArgs, { stdio: "inherit", shell: false });
+  const r = spawnSync(cmd, cmdArgs, {
+    stdio: "inherit", shell: false,
+    env: { ...process.env, [ANCHOR_ENV]: __filename },
+  });
   if (r.error) {
     console.error(`agrep: failed to launch ${cmd}: ${r.error.message}`);
     process.exit(1);
@@ -27,16 +52,11 @@ function run(cmd, cmdArgs) {
   process.exit(r.status === null ? 1 : r.status);
 }
 
-if (has("uv")) {
+const uv = probe("uv");
+if (uv !== null) {
   // `uvx agrep` == `uv tool run agrep`; --from lets AGREP_PYPI_SPEC point anywhere
-  run("uv", [
-    "tool", "run",
-    "--exclude-newer-package", "agrep=false",
-    "--from", SPEC,
-    "agrep",
-    ...args,
-  ]);
-} else if (has("pipx")) {
+  run("uv", uvArgs(uv, args));
+} else if (probe("pipx") !== null) {
   run("pipx", ["run", "--spec", SPEC, "agrep", ...args]);
 } else {
   console.error(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agrep-cli",
-  "version": "0.4.1",
+  "version": "0.4.5",
   "description": "unscoped npm alias for @mundy/agrep, local search across AI coding-agent history",
   "bin": {
     "agrep": "bin.js"

package/postinstall.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-// Global installs finish enrolled, not merely downloaded: after warming uv's
-// ephemeral tool cache, run the pinned `agrep setup --yes` so the box is
-// indexed and the detected agents are taught the moment `npm install -g`
+// Global installs finish enrolled, not merely downloaded: after warming the
+// runner's ephemeral tool cache, run the pinned `agrep setup --yes` so the box
+// is indexed and the detected agents are taught the moment `npm install -g`
 // returns. Everything setup writes is disclosed in its output, owned by
 // agrep, and undone by `agrep remove`; --no-semantic defers the ~52MiB model
 // fetch to the first semantic use, and --no-archive leaves source-store
@@ -13,6 +13,7 @@
 
 "use strict";
 
+const path = require("path");
 const { spawnSync } = require("child_process");
 const { version } = require("./package.json");
 
@@ -22,6 +23,12 @@ const forced = Boolean(process.env.AGREP_POSTINSTALL_FORCE);
 const strict = Boolean(process.env.AGREP_POSTINSTALL_STRICT);
 const autoSetup = !process.env.AGREP_NO_AUTO_SETUP;
 const SETUP_TIMEOUT_MS = 15 * 60 * 1000;
+// `agrep setup` exit 3 (docs/OUTPUT_CONTRACTS.md): declined without changing
+// anything; the tool is provisioned, so this is not a failed install
+const SETUP_DECLINED = 3;
+// the sentinel must track this package, not the runner's prunable cache copy
+const ANCHOR_ENV = "AGREP_INSTALL_ANCHOR";
+const anchor = path.join(__dirname, "bin.js");
 
 if (process.env.AGREP_SKIP_POSTINSTALL) {
   process.exit(0);
@@ -31,48 +38,96 @@ if (!npmGlobal && !forced) {
   process.exit(0);
 }
 
-function has(cmd) {
-  const probe = spawnSync(cmd, ["--version"], { stdio: "ignore", shell: false });
-  return probe.status === 0;
+function probe(cmd) {
+  const r = spawnSync(cmd, ["--version"], { encoding: "utf8", shell: false });
+  return !r.error && r.status === 0 ? String(r.stdout || "") : null;
+}
+
+function uvVersion(text) {
+  const m = /\buv\s+(\d+)\.(\d+)\.(\d+)/.exec(text || "");
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+// same rule as bin.js: the `=false` opt-out parses only on uv >= 0.9.25
+function excludeNewerOptOut(v) {
+  return v !== null && (v[0] > 0 || v[1] > 9 || (v[1] === 9 && v[2] >= 25));
 }
 
 function tryRun(cmd, args, options) {
-  const result = spawnSync(cmd, args, { shell: false, ...options });
-  return !result.error && result.status === 0;
+  const result = spawnSync(cmd, args, {
+    shell: false, ...options, env: { ...process.env, [ANCHOR_ENV]: anchor },
+  });
+  return result.error ? null : result.status;
 }
 
-function agrepArgs(...rest) {
-  return [
-    "tool", "run",
-    "--exclude-newer-package", "agrep=false",
-    "--from", spec,
-    "agrep", ...rest,
-  ];
+// Resolve and cache the pinned agrep without running it for real; a failure here
+// is the runner's (network, registry, an unsupported python), not setup's.
+function provision(runner) {
+  const result = spawnSync(runner.cmd, runner.args("--version"), {
+    shell: false, encoding: "utf8", stdio: ["ignore", "ignore", "pipe"],
+    env: { ...process.env, [ANCHOR_ENV]: anchor },
+  });
+  if (result.error) return { ok: false, detail: result.error.message };
+  const lines = String(result.stderr || "").trim().split("\n").filter(Boolean);
+  return { ok: result.status === 0, detail: lines.length ? lines[lines.length - 1] : `exit ${result.status}` };
+}
+
+// bin.js's runner choice, in the same order: uv, else pipx
+function findRunner() {
+  const uv = probe("uv");
+  if (uv !== null) {
+    const flag = excludeNewerOptOut(uvVersion(uv))
+      ? ["--exclude-newer-package", "agrep=false"] : [];
+    return {
+      cmd: "uv",
+      args: (...rest) => ["tool", "run", ...flag, "--from", spec, "agrep", ...rest],
+    };
+  }
+  if (probe("pipx") !== null) {
+    return { cmd: "pipx", args: (...rest) => ["run", "--spec", spec, "agrep", ...rest] };
+  }
+  return null;
 }
 
 let done = false;
-const uvAvailable = has("uv");
-if (uvAvailable && autoSetup) {
-  // Inherited stdio: npm surfaces this with --foreground-scripts (and on
-  // failure), so every file setup touches is disclosed, never silent.
-  console.log(
-    "agrep: running one-time setup (agrep setup --yes) - writes agent instruction blocks"
-    + " and an uninstall-cleanup sentinel, all undone by `agrep remove`;"
-    + " AGREP_NO_AUTO_SETUP=1 skips this.");
-  done = tryRun(
-    "uv", agrepArgs("setup", "--yes", "--no-semantic", "--no-archive"),
-    { stdio: "inherit", timeout: SETUP_TIMEOUT_MS });
-  if (!done) {
-    console.warn("agrep: automatic setup did not finish; `agrep setup` completes it any time.");
+const runner = findRunner();
+if (runner && autoSetup) {
+  const fetched = provision(runner);
+  if (!fetched.ok) {
+    console.warn(
+      `agrep: ${runner.cmd} could not fetch ${spec} (${fetched.detail}); nothing was set up.`
+      + " once the registry is reachable, `agrep setup` runs the one-time setup.");
+  } else {
+    // Inherited stdio: npm surfaces this with --foreground-scripts (and on
+    // failure), so every file setup touches is disclosed, never silent.
+    console.log(
+      "agrep: running one-time setup (agrep setup --yes) - writes agent instruction blocks"
+      + " and an uninstall-cleanup sentinel, all undone by `agrep remove`;"
+      + " AGREP_NO_AUTO_SETUP=1 skips this.");
+    const status = tryRun(
+      runner.cmd, runner.args("setup", "--yes", "--no-semantic", "--no-archive"),
+      { stdio: "inherit", timeout: SETUP_TIMEOUT_MS });
+    done = status === 0 || status === SETUP_DECLINED;
+    if (status === null) {
+      console.warn(`agrep: could not launch ${runner.cmd} for setup; \`agrep setup\` runs it any time.`);
+    } else if (status === SETUP_DECLINED) {
+      console.warn(
+        "agrep: setup declined and changed nothing; its output above names the cause"
+        + " and the fix. `agrep setup` declines the same way until that is resolved.");
+    } else if (!done) {
+      console.warn(
+        `agrep: setup exited ${status}; its output above names each step that did not complete`
+        + " and the fix. the rest of setup still ran; `agrep setup` retries any time.");
+    }
   }
-} else if (uvAvailable) {
+} else if (runner) {
   // Warm-only: keep npm output clean; the shim provisions on first run.
-  done = tryRun("uv", agrepArgs("--version"), { stdio: "ignore" });
+  done = tryRun(runner.cmd, runner.args("--version"), { stdio: "ignore" }) === 0;
   if (!done) {
-    console.warn("agrep: uv cache warm failed; the first agrep run will retry");
+    console.warn(`agrep: ${runner.cmd} cache warm failed; the first agrep run will retry`);
   }
 } else {
-  console.warn("agrep: install uv (https://docs.astral.sh/uv) - agrep needs it on first run.");
+  console.warn("agrep: install uv (https://docs.astral.sh/uv) or pipx - agrep needs one of them on first run.");
 }
 if (!done && strict) {
   console.error("agrep: postinstall failed to provision the pinned PyPI tool");