@introspection-ai/cli 0.18.1 → 0.20.0

package/README.md

@@ -6,7 +6,8 @@ operating agents across local development and the Introspection platform.
 ```bash
 npm install -g @introspection-ai/cli
 
-# authenticate and inspect the available commands
+# install Pi when missing, then align Recipes and coding-agent plugins
+introspection setup
 introspection login
 introspection --help
 ```
@@ -19,6 +20,7 @@ npx @introspection-ai/cli --help
 
 The platform-specific CLI and its Rust judge engine are delivered via an
 optional dependency (`@introspection-ai/cli-<os>-<cpu>`) selected automatically
-by npm.
+by npm. The CLI requires Node.js 24 or newer. On Node 18–23 the npm launcher
+installs but every command exits with upgrade instructions.
 
 Full documentation: https://github.com/introspection-org/introspection-cli

package/bin/introspection.js

@@ -6,6 +6,10 @@
 "use strict";
 
 const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const MIN_NODE_MAJOR = 24;
 
 const PACKAGES = {
   "darwin-arm64": "@introspection-ai/cli-darwin-arm64",
@@ -15,6 +19,137 @@ const PACKAGES = {
   "win32-x64": "@introspection-ai/cli-win32-x64",
 };
 
+const PACKAGE_MANAGER_ENV = "INTROSPECTION_CLI_PACKAGE_MANAGER";
+const PACKAGE_MANAGER_PATH_ENV = "INTROSPECTION_CLI_PACKAGE_MANAGER_PATH";
+const LOCKFILES = [
+  ["pnpm-lock.yaml", "pnpm"],
+  ["yarn.lock", "yarn"],
+  ["bun.lock", "bun"],
+  ["bun.lockb", "bun"],
+  ["package-lock.json", "npm"],
+];
+
+/**
+ * Identify the package manager that owns this launcher. This mirrors Vercel's
+ * update-command approach: use install metadata while it is available, then
+ * walk the installed package tree for a lockfile or a distinctive global-store
+ * path. An uncertain answer stays uncertain; the native CLI will show generic
+ * reinstall guidance rather than silently falling back to npm.
+ */
+function detectPackageManager({
+  entrypoint = __filename,
+  existsSync = fs.existsSync,
+  realpathSync = fs.realpathSync,
+} = {}) {
+  const logical = path.resolve(entrypoint);
+  let physical;
+  try {
+    physical = realpathSync(entrypoint);
+  } catch {
+    physical = logical;
+  }
+  const locations = [...new Set([logical, physical])];
+  const normalized = locations.map(location =>
+    location.replaceAll("\\", "/").toLowerCase()
+  );
+  const globalLocations = normalized.filter(location =>
+    location.includes("/pnpm/global/") ||
+    location.includes("/yarn/global/") ||
+    location.includes("/.bun/install/global/") ||
+    location.includes("/lib/node_modules/") ||
+    location.includes("/appdata/roaming/npm/node_modules/")
+  );
+  if (globalLocations.length === 0) {
+    return null;
+  }
+
+  if (globalLocations.some(location =>
+    location.includes("/.pnpm/") || location.includes("/pnpm/global/")
+  )) {
+    return "pnpm";
+  }
+  if (globalLocations.some(location => location.includes("/yarn/global/"))) {
+    return "yarn";
+  }
+  if (globalLocations.some(location => location.includes("/.bun/install/global/"))) {
+    return "bun";
+  }
+  if (
+    globalLocations.some(location =>
+      location.includes("/lib/node_modules/") ||
+      location.includes("/appdata/roaming/npm/node_modules/")
+    )
+  ) {
+    return "npm";
+  }
+
+  for (const location of locations) {
+    for (let dir = path.dirname(location); ; dir = path.dirname(dir)) {
+      for (const [lockfile, manager] of LOCKFILES) {
+        if (existsSync(path.join(dir, lockfile))) {
+          return manager;
+        }
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Resolve the package-manager executable from the launcher's own installation
+ * prefix. Never consult PATH: it may now point at another NVM/Corepack prefix.
+ */
+function findOwningPackageManager(
+  manager,
+  {
+    entrypoint = __filename,
+    invokedAs = process.argv[1],
+    platform = process.platform,
+    existsSync = fs.existsSync,
+    realpathSync = fs.realpathSync,
+  } = {}
+) {
+  if (!manager) return null;
+  const executable = platform === "win32" ? `${manager}.cmd` : manager;
+  const candidates = [];
+  const invokedSibling = invokedAs
+    ? path.join(path.dirname(path.resolve(invokedAs)), executable)
+    : null;
+
+  const logical = path.resolve(entrypoint);
+  let physical;
+  try {
+    physical = realpathSync(entrypoint);
+  } catch {
+    physical = logical;
+  }
+  for (const location of [...new Set([logical, physical])]) {
+    const normalized = location.replaceAll("\\", "/");
+    const lower = normalized.toLowerCase();
+    const addFromMarker = (marker, suffix) => {
+      const offset = lower.indexOf(marker);
+      if (offset !== -1) {
+        candidates.push(path.join(normalized.slice(0, offset), ...suffix));
+      }
+    };
+
+    if (manager === "npm") {
+      addFromMarker("/lib/node_modules/", ["bin", executable]);
+      addFromMarker("/node_modules/", [executable]);
+    } else if (manager === "pnpm") {
+      addFromMarker("/global/", [executable]);
+    } else if (manager === "bun") {
+      addFromMarker("/install/global/", ["bin", executable]);
+    }
+  }
+  if (invokedSibling) candidates.push(invokedSibling);
+
+  return candidates.find(candidate => existsSync(candidate)) || null;
+}
+
 function resolveBinary() {
   const key = `${process.platform}-${process.arch}`;
   const pkg = PACKAGES[key];
@@ -36,21 +171,61 @@ function resolveBinary() {
   }
 }
 
-let binary;
-try {
-  binary = resolveBinary();
-} catch (err) {
-  console.error(err.message);
-  process.exit(1);
+function requireSupportedNode(version = process.versions.node) {
+  const major = Number.parseInt(version.split(".")[0], 10);
+  if (!Number.isInteger(major) || major < MIN_NODE_MAJOR) {
+    throw new Error(
+      `Introspection CLI requires Node.js ${MIN_NODE_MAJOR} or newer; ` +
+        `this command is running on Node.js ${version}.\n\n` +
+        `Upgrade the Node runtime that launches \`introspection\`, then reinstall:\n` +
+        `  npm install -g @introspection-ai/cli@latest`
+    );
+  }
 }
 
-const result = spawnSync(binary, process.argv.slice(2), { stdio: "inherit" });
-if (result.error) {
-  console.error(result.error.message);
-  process.exit(1);
+function main() {
+  let binary;
+  try {
+    requireSupportedNode();
+    binary = resolveBinary();
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+
+  const manager = detectPackageManager();
+  const managerPath = findOwningPackageManager(manager);
+  const env = manager && managerPath
+    ? {
+        ...process.env,
+        [PACKAGE_MANAGER_ENV]: manager,
+        [PACKAGE_MANAGER_PATH_ENV]: managerPath,
+      }
+    : process.env;
+  const result = spawnSync(binary, process.argv.slice(2), {
+    stdio: "inherit",
+    env,
+  });
+  if (result.error) {
+    console.error(result.error.message);
+    process.exit(1);
+  }
+  // Re-raise a terminating signal as our own exit; otherwise pass the code.
+  if (result.signal) {
+    process.kill(process.pid, result.signal);
+  }
+  process.exit(result.status ?? 0);
 }
-// Re-raise a terminating signal as our own exit; otherwise pass the code.
-if (result.signal) {
-  process.kill(process.pid, result.signal);
+
+if (require.main === module) {
+  main();
 }
-process.exit(result.status ?? 0);
+
+module.exports = {
+  MIN_NODE_MAJOR,
+  PACKAGE_MANAGER_ENV,
+  PACKAGE_MANAGER_PATH_ENV,
+  detectPackageManager,
+  findOwningPackageManager,
+  requireSupportedNode,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@introspection-ai/cli",
-  "version": "0.18.1",
+  "version": "0.20.0",
   "description": "CLI for operating agents on the Introspection platform",
   "keywords": [
     "introspection",
@@ -18,18 +18,23 @@
   "bin": {
     "introspection": "bin/introspection.js"
   },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "test": "node --test test/*.test.js"
+  },
   "files": [
     "bin/introspection.js",
+    "scripts/postinstall.js",
     "README.md"
   ],
   "engines": {
-    "node": ">=24"
+    "node": ">=18"
   },
   "optionalDependencies": {
-    "@introspection-ai/cli-darwin-arm64": "0.18.1",
-    "@introspection-ai/cli-darwin-x64": "0.18.1",
-    "@introspection-ai/cli-linux-x64": "0.18.1",
-    "@introspection-ai/cli-linux-arm64": "0.18.1",
-    "@introspection-ai/cli-win32-x64": "0.18.1"
+    "@introspection-ai/cli-darwin-arm64": "0.20.0",
+    "@introspection-ai/cli-darwin-x64": "0.20.0",
+    "@introspection-ai/cli-linux-x64": "0.20.0",
+    "@introspection-ai/cli-linux-arm64": "0.20.0",
+    "@introspection-ai/cli-win32-x64": "0.20.0"
   }
 }

package/scripts/postinstall.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+"use strict";
+
+// Installation hooks are advisory only: package managers may suppress or skip
+// them, and installing this package does not authorize changing Pi or coding
+// agent hosts. The idempotent setup command owns those machine-level changes.
+// Human-only output follows the CLI's stderr + TTY contract.
+if (process.stderr.isTTY) {
+  process.stderr.write(`
+Introspection CLI installed. To install or align Pi, Recipes, and plugins, run:
+
+  introspection setup
+`);
+}