probe-research 0.10.6 → 0.12.0

package/README.md

@@ -6,14 +6,33 @@ The Probe Research setup wizard.
 npx probe-research
 ```
 
-Installs and configures [Probe Research](https://research.prbe.ai) for Claude Code.
-It asks which capabilities you want, installs only those plugins, and finishes
-with a single browser approval.
+Signs in to [Probe Research](https://research.prbe.ai) through your browser and
+opens the main wizard menu. If you create an account, finish onboarding on the
+website first. Its final step gives you a command like:
+
+```bash
+npx probe-research install ABCD234567
+```
+
+The 10-character code signs you in once without another browser approval, and
+`install` opens the guided tooling setup for Claude Code, Codex, or pi. Choose
+your agents and confirm the capabilities before anything is installed. Each
+selected agent receives its own capture credential when capture is enabled.
+
+`npx probe-research ABCD234567` also signs in, then opens the main menu.
+`npx probe-research install` runs guided setup with browser sign-in. Expired or
+already-used codes need to be replaced on the website.
 
 This package is a thin launcher. Probe Research is a Python CLI; this exists so
 the entry point matches the `npx <tool>` shape people already expect. It resolves
 a real `probe` (via an existing install, `uv`, or `pipx`) and hands over — there
 is no reimplementation here that could drift from the CLI.
 
-Re-run it any time to change what's enabled, diagnose a problem, update, print
-the manual steps, or remove Probe from the device.
+The main menu requires a signed-in account. Choose **Sign out** to clear this
+device's credentials, stop capture, and exit the wizard. Run the command again
+to sign in to another account. You can also change what's enabled, diagnose a
+problem, update, print the manual steps, or remove Probe from the device.
+
+Publishing this launcher requires `probe-research>=0.147.0` to be available on
+PyPI first. That CLI version introduces website sign-in codes; older installed
+CLIs are upgraded before the launcher forwards the new commands.

package/bin/probe-research.js

@@ -27,6 +27,20 @@ const os = require("node:os");
 
 const DIST = "probe-research";
 
+/**
+ * Where the published-version manifest lives. The SessionStart hook already
+ * reads this exact endpoint to decide whether to nudge, so the launcher and the
+ * nudge cannot disagree about what "latest" means.
+ *
+ * `PROBE_BASE_URL` is honoured for the same reason the hook honours it: a
+ * self-hosted tenant's latest is not this one's, and asking the wrong host
+ * would tell them they are behind forever.
+ */
+const MANIFEST_PATH = "/v1/client-version";
+const DEFAULT_BASE = "https://api.research.prbe.ai";
+/** How long a currency check may delay a command that could already run. */
+const MANIFEST_TIMEOUT_MS = 1500;
+
 /**
  * The minimum CLI version this launcher needs — NOT this package's own version.
  *
@@ -49,14 +63,37 @@ const DIST = "probe-research";
  * to repair the thing it installed. A healthy 0.26.x install pays one refetch,
  * which is the right trade against a broken one staying broken forever.
  *
- * (1) is why it is now 0.36.0. The dashboard's last onboarding step hands out
+ * (1) was why it was 0.36.0. The dashboard's last onboarding step hands out
  * `npx probe-research backfill`, and `probe backfill` does not exist before
  * 0.36.0. Arguments are forwarded to whatever `probe` this launcher resolves,
  * so under the old floor a user with 0.35.0 on PATH gets `No such command
  * 'backfill'` from a command the product just told them to run. A floor is the
  * only thing that can catch it: the copied command is identical either way.
+ *
+ * (1) also raised the floor to 0.56.0, and the failure is quieter. 0.56.0 adds the
+ * BULK verbs an automated caller reaches for rather than a human:
+ *
+ *   probe artifact add --from-manifest FILE   import many files in one process
+ *   probe artifact move ID --to LEVEL         promote/demote/lateral
+ *   probe metrics backfill RUN --key K        a whole derived curve, one request
+ *
+ * The first of those is the one that makes a floor load-bearing. It exists
+ * because per-file `artifact add` costs a process start and a slug resolution
+ * each, so 200k files is tens of CPU-hours -- which means whatever issues it is
+ * importing at that scale, unattended. Against a pre-0.56.0 `probe` on PATH,
+ * `--from-manifest` is an unknown OPTION: the CLI exits 2 having queued
+ * nothing, and there is no operator watching to read it. The old floor is
+ * satisfied by every one of those installs.
+ *
+ * PUBLISHING ORDER MATTERS. `${DIST}>=${target}` must resolve, so this package
+ * may only be `npm publish`ed once a CLI at or above the floor is live on PyPI.
+ * That ordering is not enforced anywhere: the PyPI release is automated and
+ * `npm publish` is manual, so it is a human who has to get it right. Raising
+ * the floor ahead of the release strands the from-zero entry point.
  */
-const MIN_CLI = "0.36.0";
+// 0.147.0 adds positional website sign-in codes to wizard/install. Publish this
+// launcher only after that CLI release is available on PyPI.
+const MIN_CLI = "0.147.0";
 const UV_INSTALL = "curl -LsSf https://astral.sh/uv/install.sh | sh";
 
 /** Compare dotted numeric versions. Returns true when `a` >= `b`. */
@@ -86,10 +123,43 @@ function installedVersion() {
   return m ? m[1] : null;
 }
 
+function baseUrl() {
+  const env = process.env.PROBE_BASE_URL;
+  if (env && /^https?:\/\//.test(env)) return env.replace(/\/+$/, "");
+  return DEFAULT_BASE;
+}
+
+/**
+ * The newest published CLI, or null if that cannot be established quickly.
+ *
+ * NULL IS THE IMPORTANT RETURN. Offline, behind a proxy, self-hosted with the
+ * route absent, or simply slow -- every one of those must leave a working local
+ * install runnable. A currency check that can strand a user offline is worse
+ * than the staleness it fixes, so every failure here falls open.
+ */
+async function latestVersion() {
+  try {
+    const res = await fetch(`${baseUrl()}${MANIFEST_PATH}`, {
+      signal: AbortSignal.timeout(MANIFEST_TIMEOUT_MS),
+      headers: { accept: "application/json" },
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    const found = body && body.cli && body.cli.latest;
+    return typeof found === "string" && /^\d+(\.\d+)+$/.test(found) ? found : null;
+  } catch {
+    return null;
+  }
+}
+
 function has(cmd) {
-  const probe = process.platform === "win32" ? "where" : "command";
-  const args = process.platform === "win32" ? [cmd] : ["-v", cmd];
-  const r = spawnSync(probe, args, { stdio: "ignore", shell: true });
+  // ONE shell string, never (command, args[], shell:true): Node deprecated that
+  // pairing in DEP0190 because the args are concatenated rather than escaped,
+  // and it printed a security warning on every single launcher run. `cmd` is a
+  // literal at all three call sites, so there is nothing to escape here -- but
+  // a warning users see on the from-zero entry point is its own problem.
+  const line = process.platform === "win32" ? `where ${cmd}` : `command -v ${cmd}`;
+  const r = spawnSync(line, { stdio: "ignore", shell: true });
   return r.status === 0;
 }
 
@@ -104,27 +174,61 @@ function run(cmd, args) {
   process.exit(r.status === null ? 1 : r.status);
 }
 
-function main() {
+/** The optional one-time sign-in code is independent of the install action. */
+function cliArgs(args) {
+  if (!args.length) return ["wizard"];
+  if (/^[A-Z0-9]{10}$/.test(args[0])) {
+    // `code install` and `install code` both retain the same two arguments.
+    if (args[1] === "install") return ["install", args[0], ...args.slice(2)];
+    return ["wizard", ...args];
+  }
+  return args;
+}
+
+async function main() {
   const args = process.argv.slice(2);
   // `npx probe-research` with no arguments runs the wizard — that is the entire
   // reason this package exists, so it should not require remembering a verb.
-  const forwarded = args.length ? args : ["wizard"];
+  const forwarded = cliArgs(args);
   const wanted = MIN_CLI;
 
-  // Only hand off to an existing install if it is at least as new as this
-  // launcher. Otherwise fall through and let uv/pipx fetch a matching CLI.
+  // Hand off to an existing install only when it is BOTH above the floor and
+  // current. The floor alone is not enough, and that was the bug: `npx <tool>`
+  // means "run the latest", but a floor is satisfied forever, so anyone who had
+  // ever installed the CLI was frozen on it and npx silently never delivered
+  // another update.
+  //
+  // That is the same failure the `--refresh` flag below exists to fix -- uv
+  // serving whatever it resolved on day one -- in the other branch. It was
+  // fixed there and left standing here.
+  let latest = null;
   if (has("probe")) {
     const found = installedVersion();
-    if (found && atLeast(found, wanted)) return run("probe", forwarded);
-    console.error(
-      `probe-research: installed probe ${found || "(unknown version)"} is older than ` +
-        `${wanted}; fetching the latest…`,
-    );
+    if (found && atLeast(found, wanted)) {
+      latest = await latestVersion();
+      // Unknown latest means run what we have: see latestVersion's contract.
+      if (!latest || atLeast(found, latest)) return run("probe", forwarded);
+      console.error(
+        `probe-research: probe ${found} is behind ${latest}; fetching the latest…`,
+      );
+    } else {
+      console.error(
+        `probe-research: installed probe ${found || "(unknown version)"} is older than ` +
+          `${wanted}; fetching the latest…`,
+      );
+    }
   }
   // A FLOOR, not an exact pin. Unpinned, `uv tool run --from probe-research`
   // reuses an already-installed 0.8.2 tool; pinned exactly, it demands a PyPI
   // version that may not exist. `>=` fixes both.
-  const spec = `${DIST}>=${wanted}`;
+  // Resolve to the newest version we actually know about, not merely the floor.
+  // `uv tool run` reuses an installed tool that satisfies the constraint, so a
+  // stale 0.46.0 satisfies `>=0.36.0` and uv hands back the very version we
+  // just decided was out of date -- the currency check above would print
+  // "fetching the latest" and then change nothing. Measured exactly that before
+  // this line existed.
+  const target = latest && atLeast(latest, wanted) ? latest : wanted;
+  const spec = `${DIST}>=${target}`;
   // REFRESH. uv caches the ENVIRONMENT it built for a requirement, so a range
   // like `>=0.10.0` keeps serving whatever it resolved the FIRST time — every
   // user frozen on the version they happened to run on day one, with the
@@ -162,8 +266,13 @@ function main() {
   // because it was resolved before the install ran.
   const uv = `${os.homedir()}/.local/bin/uv`;
   return run(uv, [
-    "tool", "run", "--refresh", "--from", `${DIST}>=${wanted}`, "probe", ...forwarded,
+    "tool", "run", "--refresh", "--from", spec, "probe", ...forwarded,
   ]);
 }
 
-main();
+main().catch((err) => {
+  // A throw here would exit 0 under an unhandled rejection on some Node builds,
+  // which reads as success to whatever invoked the launcher.
+  console.error(`probe-research: ${err && err.message ? err.message : err}`);
+  process.exit(1);
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "probe-research",
-  "version": "0.10.6",
-  "description": "Setup wizard for Probe Research in Claude Code. Runs from zero with npx.",
+  "version": "0.12.0",
+  "description": "Setup wizard for Probe Research in Claude Code and Codex. Runs from zero with npx.",
   "bin": {
     "probe-research": "bin/probe-research.js"
   },
@@ -19,6 +19,7 @@
   "homepage": "https://research.prbe.ai/connect",
   "keywords": [
     "claude-code",
+    "codex",
     "mlops",
     "experiment-tracking",
     "probe-research"