agentic-relay 3.8.5 → 4.1.0

package/bin/lib/doctor.mjs

@@ -0,0 +1,222 @@
+/**
+ * `agentrelay doctor` — diagnose the install/runtime environment.
+ *
+ * Every check maps to a failure mode seen in the field: stale global versions,
+ * EACCES on the npm prefix, root-owned ~/.npm (kills npx AND npm i -g), the
+ * global bin dir missing from PATH, a dead/misconfigured API key. Output is
+ * one line per check (✓ ok / ! warn / ✗ fail) or a --json envelope; exit 1
+ * only when a required check fails.
+ */
+
+import { readFileSync, existsSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { resolveApiKey, CREDENTIALS_PATH, LEGACY_CREDENTIALS_PATH } from "./config.mjs";
+import { search as apiSearch } from "./api.mjs";
+import { compareSemver } from "./update-check.mjs";
+import {
+  npmGlobalPrefix,
+  npmGlobalBinDir,
+  globalBinShimPath,
+  globalPrefixWritable,
+  npmCacheOwnedByOther,
+  dirOnPath,
+  isDirWritable,
+  USER_PREFIX_RECIPE,
+  CACHE_CHOWN_RECIPE,
+} from "./sysenv.mjs";
+
+export const MIN_NODE_MAJOR = 18;
+
+/** Pure: ok/fail verdict for a Node version string. */
+export function checkNodeVersion(versionString) {
+  const major = Number(String(versionString).split(".")[0]);
+  return {
+    id: "node",
+    label: "Node.js version",
+    status: major >= MIN_NODE_MAJOR ? "ok" : "fail",
+    detail:
+      major >= MIN_NODE_MAJOR
+        ? `v${versionString}`
+        : `v${versionString} — agentrelay needs Node >= ${MIN_NODE_MAJOR}`,
+  };
+}
+
+/** Pure: aggregate checks → overall ok + exit code. */
+export function summarize(checks) {
+  const failed = checks.filter((c) => c.status === "fail");
+  return { ok: failed.length === 0, exitCode: failed.length === 0 ? 0 : 1 };
+}
+
+async function fetchLatestVersion(timeoutMs = 3000) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch("https://registry.npmjs.org/agentic-relay/latest", {
+      signal: controller.signal,
+    });
+    if (!res.ok) return null;
+    const data = await res.json();
+    return data.version || null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function apiKeySource(flagKey) {
+  if (flagKey && flagKey.trim()) return "--api-key flag";
+  if (process.env.AGENT_RELAY_API_KEY?.trim()) return "$AGENT_RELAY_API_KEY";
+  try {
+    const creds = JSON.parse(readFileSync(CREDENTIALS_PATH, "utf-8"));
+    if (creds.api_key) return CREDENTIALS_PATH;
+  } catch {
+    /* fall through */
+  }
+  try {
+    const creds = JSON.parse(readFileSync(LEGACY_CREDENTIALS_PATH, "utf-8"));
+    if (creds.api_key) return `${LEGACY_CREDENTIALS_PATH} (legacy)`;
+  } catch {
+    /* fall through */
+  }
+  return null;
+}
+
+export async function cmdDoctor(opts) {
+  const checks = [];
+
+  // 1. Node version
+  checks.push(checkNodeVersion(process.versions.node));
+
+  // 2. CLI version vs registry
+  let currentVersion = "unknown";
+  try {
+    currentVersion = JSON.parse(
+      readFileSync(new URL("../../package.json", import.meta.url), "utf-8"),
+    ).version;
+  } catch {
+    /* keep "unknown" */
+  }
+  const latest = await fetchLatestVersion();
+  const behind = latest !== null && compareSemver(latest, currentVersion) > 0;
+  checks.push({
+    id: "version",
+    label: "CLI version",
+    status: latest === null ? "warn" : behind ? "warn" : "ok",
+    detail:
+      latest === null
+        ? `${currentVersion} (couldn't reach the npm registry to compare)`
+        : behind
+          ? `${currentVersion} — ${latest} is available: npm i -g agentic-relay`
+          : `${currentVersion} (latest is ${latest})`,
+  });
+
+  // 3. API key presence
+  const key = resolveApiKey(opts.apiKey || null);
+  const source = key ? apiKeySource(opts.apiKey || null) : null;
+  checks.push({
+    id: "api_key",
+    label: "API key",
+    status: key ? "ok" : "warn",
+    detail: key
+      ? `configured via ${source}`
+      : `not found — set --api-key, $AGENT_RELAY_API_KEY, or ${CREDENTIALS_PATH}`,
+  });
+
+  // 4. API key live verification (skipped without a key)
+  if (key) {
+    try {
+      await apiSearch("doctor connectivity check", {
+        apiKey: key,
+        maxResults: 1,
+        timeoutMs: Math.min(opts.timeoutMs || 10000, 10000),
+      });
+      checks.push({ id: "api", label: "API connectivity", status: "ok", detail: "search responds" });
+    } catch (err) {
+      checks.push({
+        id: "api",
+        label: "API connectivity",
+        status: "fail",
+        detail: `search failed: ${err.message}`,
+      });
+    }
+  } else {
+    checks.push({ id: "api", label: "API connectivity", status: "warn", detail: "skipped (no key)" });
+  }
+
+  // 5. npm global prefix + writability
+  const prefix = npmGlobalPrefix();
+  if (!prefix) {
+    checks.push({ id: "prefix", label: "npm global prefix", status: "warn", detail: "npm not found on PATH" });
+  } else if (globalPrefixWritable(prefix)) {
+    checks.push({ id: "prefix", label: "npm global prefix", status: "ok", detail: `${prefix} (writable)` });
+  } else {
+    checks.push({
+      id: "prefix",
+      label: "npm global prefix",
+      status: "warn",
+      detail: `${prefix} is not writable — npm i -g will EACCES. Fix: ${USER_PREFIX_RECIPE.join("; ")}`,
+    });
+  }
+
+  // 6. ~/.npm cache ownership
+  checks.push(
+    npmCacheOwnedByOther()
+      ? {
+          id: "npm_cache",
+          label: "npm cache (~/.npm)",
+          status: "warn",
+          detail: `owned by another user — breaks npx AND npm i -g. Fix: ${CACHE_CHOWN_RECIPE}`,
+        }
+      : { id: "npm_cache", label: "npm cache (~/.npm)", status: "ok", detail: "owned by you" },
+  );
+
+  // 7 + 8. global bin shim exists + its dir is on PATH
+  const shim = globalBinShimPath(prefix, "agentrelay");
+  const binDir = npmGlobalBinDir(prefix);
+  const shimExists = Boolean(shim) && existsSync(shim);
+  checks.push({
+    id: "global_bin",
+    label: "global `agentrelay` bin",
+    status: shimExists ? "ok" : "warn",
+    detail: shimExists ? shim : `not found in ${binDir || "npm's global bin dir"} — run: npm i -g agentic-relay`,
+  });
+  checks.push({
+    id: "path",
+    label: "global bin dir on PATH",
+    status: dirOnPath(binDir) ? "ok" : "warn",
+    detail: dirOnPath(binDir)
+      ? binDir
+      : `${binDir || "npm's global bin dir"} is not on PATH — add it to your shell profile`,
+  });
+
+  // 9. working directory writable (cache + deliverables land here)
+  checks.push({
+    id: "cwd",
+    label: "working dir writable",
+    status: isDirWritable(process.cwd()) ? "ok" : "warn",
+    detail: process.cwd(),
+  });
+
+  // 10. zip capability (informational — pure-JS, no system unzip needed)
+  checks.push({
+    id: "zip",
+    label: "deliverable unzip",
+    status: "ok",
+    detail: "pure-JS extractor (no system `unzip` required)",
+  });
+
+  const { ok, exitCode } = summarize(checks);
+  return { checks, doctor_ok: ok, exit_code: exitCode, config_dir: join(homedir(), ".config", "agent-relay") };
+}
+
+const ICONS = { ok: "✓", warn: "!", fail: "✗" };
+
+export function fmtDoctor(envelope) {
+  const lines = (envelope.checks || []).map(
+    (c) => `${ICONS[c.status] || "?"} ${c.label.padEnd(26)} ${c.detail}`,
+  );
+  lines.push(envelope.doctor_ok ? "doctor: no blocking problems found" : "doctor: blocking problems found (✗)");
+  return lines.join("\n");
+}

package/bin/lib/fetch.mjs

@@ -3,27 +3,23 @@
  * subfolder of the working directory.
  *
  * v1 is deliberately dumb: the artifact is an OPAQUE blob. If it's a zip we
- * extract it; otherwise we drop the file in as-is. We NEVER execute anything
- * from the bundle (no install scripts, no running code) — there is no content
- * scanning yet, so contents are inert files for the user/agent to inspect.
+ * extract it (pure-JS extractor — works on Windows, no system `unzip` needed);
+ * otherwise we drop the file in as-is. We NEVER execute anything from the
+ * bundle (no install scripts, no running code) — there is no content scanning
+ * yet, so contents are inert files for the user/agent to inspect.
  *
  * Security: verify sha256 before unpacking; detect zip by magic bytes (not
  * extension); reject any archive entry that escapes the destination (zip-slip);
  * never extract into the project root.
  */
 
-import {
-  writeFileSync,
-  mkdirSync,
-  existsSync,
-  rmSync,
-  readdirSync,
-  statSync,
-} from "fs";
-import { join, resolve, basename, sep } from "path";
-import { tmpdir } from "os";
+import { writeFileSync, mkdirSync, existsSync } from "fs";
+import { join, resolve, basename } from "path";
 import { createHash } from "crypto";
-import { execFileSync } from "child_process";
+import { extractZip, assertNoZipSlip } from "./zip.mjs";
+
+// Re-exported for callers/tests that import the slip guard from here.
+export { assertNoZipSlip };
 
 const ZIP_MAGIC = Buffer.from([0x50, 0x4b, 0x03, 0x04]); // "PK\x03\x04"
 
@@ -73,44 +69,6 @@ export function uniqueDir(base) {
   throw new Error(`could not find a free destination near ${base}`);
 }
 
-/**
- * Validate that an `unzip -l` listing contains no zip-slip entries (absolute
- * paths or `..` traversal that escapes dest). Returns the list of entry names.
- * Pure-ish: takes the raw listing text so it's unit-testable.
- */
-export function zipEntriesFromListing(listingText) {
-  // `unzip -l` columns: Length  Date  Time  Name — name is everything after
-  // the 4th whitespace-delimited column. Skip header/footer lines.
-  const names = [];
-  for (const line of listingText.split("\n")) {
-    const m = line.match(/^\s*\d+\s+\S+\s+\S+\s+(.+)$/);
-    if (m && m[1] && m[1] !== "Name") names.push(m[1].trim());
-  }
-  return names;
-}
-
-export function assertNoZipSlip(entryNames, destDir) {
-  const destRoot = resolve(destDir) + sep;
-  for (const name of entryNames) {
-    if (name.startsWith("/") || name.includes("\0")) {
-      throw new Error(`unsafe archive entry (absolute path): ${name}`);
-    }
-    const target = resolve(destDir, name);
-    if (target !== resolve(destDir) && !target.startsWith(destRoot)) {
-      throw new Error(`unsafe archive entry (path traversal / zip-slip): ${name}`);
-    }
-  }
-}
-
-function hasUnzip() {
-  try {
-    execFileSync("unzip", ["-v"], { stdio: "ignore" });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 /**
  * Download + unpack. opts: { url, dest?, checksum?, filename?, fetchImpl? }.
  * Returns { ok, dest, kind, filename, checksum_sha256, placed: [...] }.
@@ -138,29 +96,15 @@ export async function cmdFetch(opts) {
   const dest = uniqueDir(opts.dest || `./${slug}`);
 
   if (isZip(buf)) {
-    if (!hasUnzip()) {
-      throw new Error("`unzip` is required to extract a zip artifact but was not found on PATH");
-    }
-    const tmpZip = join(tmpdir(), `agent-relay-fetch-${digest.slice(0, 12)}.zip`);
-    writeFileSync(tmpZip, buf);
-    try {
-      // Zip-slip guard: inspect entries before extracting.
-      const listing = execFileSync("unzip", ["-l", tmpZip], { encoding: "utf-8" });
-      const entries = zipEntriesFromListing(listing);
-      assertNoZipSlip(entries, dest);
-
-      mkdirSync(dest, { recursive: true });
-      // -o overwrite within the freshly-created dest only; -d targets dest.
-      execFileSync("unzip", ["-o", "-q", tmpZip, "-d", dest], { stdio: "ignore" });
-    } finally {
-      try { rmSync(tmpZip, { force: true }); } catch { /* ignore */ }
-    }
+    // Pure-JS extraction straight from the in-memory buffer — zip-slip is
+    // validated against all entry names inside extractZip before any write.
+    const placed = extractZip(buf, dest);
     return {
       ok: true,
       kind: "zip",
       dest,
       checksum_sha256: digest,
-      placed: listPlaced(dest),
+      placed,
     };
   }
 
@@ -178,12 +122,3 @@ export async function cmdFetch(opts) {
     placed: [outPath],
   };
 }
-
-function listPlaced(dir, acc = []) {
-  for (const name of readdirSync(dir)) {
-    const p = join(dir, name);
-    if (statSync(p).isDirectory()) listPlaced(p, acc);
-    else acc.push(p);
-  }
-  return acc;
-}

package/bin/lib/install-args.mjs

@@ -0,0 +1,67 @@
+/**
+ * Installer argument parsing — extracted from install.mjs so it's unit-testable
+ * (install.mjs self-runs main() on import).
+ *
+ * Field-observed footgun this guards against: `--api-key= am_live_x` (a space
+ * after the `=`). The old parser captured an empty key and silently dropped
+ * the real one as an ignored positional; on a non-TTY stdin the installer then
+ * hung on the interactive prompt. Now a bare `am_live_*` positional is rescued
+ * as the key (with a warning), and an empty `--api-key=` is reported clearly.
+ */
+
+export function parseInstallArgs(args) {
+  const flags = {
+    targets: null,
+    all: args.includes("--all"),
+    project: args.includes("--project"),
+    apiKey: null,
+    librechat: null,
+    // Legacy single-flag shortcuts (kept for backward compat)
+    legacyClaude: args.includes("--claude"),
+    legacyCodex: args.includes("--codex"),
+    legacyCursor: args.includes("--cursor"),
+  };
+  const warnings = [];
+  let sawEmptyApiKeyFlag = false;
+
+  for (const arg of args) {
+    if (arg.startsWith("--target=")) {
+      flags.targets = arg
+        .slice("--target=".length)
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    } else if (arg.startsWith("--api-key=")) {
+      flags.apiKey = arg.slice("--api-key=".length);
+      if (!flags.apiKey) sawEmptyApiKeyFlag = true;
+    } else if (arg.startsWith("--librechat=")) {
+      flags.librechat = arg.slice("--librechat=".length);
+    }
+  }
+
+  // Support `--api-key VALUE` (space-separated) too.
+  const consumedPositionals = new Set();
+  const keyIdx = args.indexOf("--api-key");
+  if (keyIdx !== -1 && args[keyIdx + 1] && !args[keyIdx + 1].startsWith("--")) {
+    flags.apiKey = args[keyIdx + 1];
+    consumedPositionals.add(keyIdx + 1);
+  }
+
+  // Rescue: a bare `am_live_*` positional when no usable key was parsed —
+  // the classic `--api-key= <key>` typo (space around the `=`).
+  if (!flags.apiKey) {
+    const idx = args.findIndex(
+      (a, i) => !a.startsWith("--") && !consumedPositionals.has(i) && /^am_live_/.test(a),
+    );
+    if (idx !== -1) {
+      flags.apiKey = args[idx];
+      warnings.push(
+        "interpreted a bare argument as the API key — write it as --api-key=<key> (no space around \"=\")",
+      );
+    } else if (sawEmptyApiKeyFlag) {
+      warnings.push("--api-key= was given with no value — ignoring it");
+    }
+  }
+
+  return { flags, warnings };
+}

package/bin/lib/parse.mjs

@@ -10,7 +10,6 @@
  *   1. plain JSON.parse
  *   2. JSON.parse after doubling lone backslashes (those not starting a valid escape)
  *   3. JSON.parse after also escaping raw control chars that appear *inside* strings
- *   4. caller falls back to field extraction (extractFields) as a last resort
  */
 
 /** Double backslashes that aren't part of a valid JSON escape sequence. */
@@ -82,67 +81,3 @@ export function lenientParse(text) {
   return { ok: false, error: lastErr };
 }
 
-/**
- * Pull the first balanced JSON object out of free text — handles ```json
- * fences and objects embedded in prose. Returns the parsed object or null.
- */
-export function extractJsonObject(text) {
-  if (typeof text !== "string") return null;
-
-  // Prefer a fenced ```json block if present.
-  const fence = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
-  const candidates = [];
-  if (fence) candidates.push(fence[1]);
-
-  // Then any balanced {...} span (greedy from first { to matching }).
-  const start = text.indexOf("{");
-  if (start !== -1) {
-    let depth = 0;
-    let inStr = false;
-    let esc = false;
-    for (let i = start; i < text.length; i++) {
-      const ch = text[i];
-      if (esc) { esc = false; continue; }
-      if (ch === "\\") { esc = true; continue; }
-      if (ch === '"') { inStr = !inStr; continue; }
-      if (inStr) continue;
-      if (ch === "{") depth++;
-      else if (ch === "}") {
-        depth--;
-        if (depth === 0) {
-          candidates.push(text.slice(start, i + 1));
-          break;
-        }
-      }
-    }
-  }
-
-  for (const c of candidates) {
-    const parsed = lenientParse(c);
-    if (parsed.ok && parsed.value && typeof parsed.value === "object") {
-      return parsed.value;
-    }
-  }
-  return null;
-}
-
-/**
- * Last-resort field extraction: pull `"key": "..."` string values from raw text
- * when the whole payload won't parse. Only handles flat string fields.
- */
-export function extractFields(text, keys) {
-  const out = {};
-  if (typeof text !== "string") return out;
-  for (const key of keys) {
-    const re = new RegExp(`"${key}"\\s*:\\s*"((?:[^"\\\\]|\\\\.)*)"`);
-    const m = text.match(re);
-    if (m) {
-      try {
-        out[key] = JSON.parse(`"${m[1]}"`);
-      } catch {
-        out[key] = m[1];
-      }
-    }
-  }
-  return out;
-}

package/bin/lib/sysenv.mjs

@@ -0,0 +1,152 @@
+/**
+ * System-environment probes shared by the installer and `agentrelay doctor`.
+ *
+ * These exist because the failure modes they detect are exactly the ones that
+ * made "successful" installs produce `command not found` in the field:
+ *  - npx prepends its ephemeral cache .bin to PATH, shadowing (or faking) a
+ *    real global install for the lifetime of the npx process
+ *  - npm's global prefix may not be writable (system Node → EACCES)
+ *  - ~/.npm may contain root-owned files (old sudo npm) which kills BOTH
+ *    `npm install -g` and npx itself
+ *  - npm's global bin dir may not be on the user's PATH
+ */
+
+import { existsSync, realpathSync, accessSync, statSync, constants } from "fs";
+import { homedir } from "os";
+import { join, sep, dirname } from "path";
+import { execSync } from "child_process";
+
+/** Where a command actually resolves on this PATH, or null. */
+export function resolveCommandPath(cmd) {
+  try {
+    const probe = process.platform === "win32" ? `where ${cmd}` : `command -v ${cmd}`;
+    const out = execSync(probe, { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
+    return out.split("\n")[0].trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+export function realpathSafe(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+/**
+ * True when a resolved bin path is an ephemeral npx/npm-exec shim (or a copy
+ * inside the running package itself), not a real install. A dangling symlink
+ * also counts as not-a-usable-install.
+ */
+export function isEphemeralBin(binPath, pkgRoot) {
+  if (!binPath) return false;
+  let real = binPath;
+  try {
+    real = realpathSync(binPath);
+  } catch {
+    return true;
+  }
+  return (
+    real.includes(`${sep}_npx${sep}`) ||
+    binPath.includes(`${sep}_npx${sep}`) ||
+    (pkgRoot ? real.startsWith(realpathSafe(pkgRoot)) : false)
+  );
+}
+
+/** npm's global prefix (e.g. /opt/homebrew, %AppData%\npm), or null. */
+export function npmGlobalPrefix() {
+  try {
+    const out = execSync("npm prefix -g", { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
+    return out.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/** The dir npm links global bins into for a given prefix. */
+export function npmGlobalBinDir(prefix) {
+  if (!prefix) return null;
+  return process.platform === "win32" ? prefix : join(prefix, "bin");
+}
+
+/** Path of this package's global bin shim under a prefix (win32 → .cmd). */
+export function globalBinShimPath(prefix, binName) {
+  const dir = npmGlobalBinDir(prefix);
+  if (!dir) return null;
+  return join(dir, process.platform === "win32" ? `${binName}.cmd` : binName);
+}
+
+export function isDirWritable(dir) {
+  if (!dir) return false;
+  try {
+    accessSync(dir, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Can `npm install -g` write where it needs to? Checks the global
+ * node_modules (or the nearest existing parent) under the prefix.
+ */
+export function globalPrefixWritable(prefix) {
+  if (!prefix) return false;
+  const nm =
+    process.platform === "win32" ? join(prefix, "node_modules") : join(prefix, "lib", "node_modules");
+  let probe = nm;
+  while (probe && !existsSync(probe)) {
+    const parent = dirname(probe);
+    if (parent === probe) break;
+    probe = parent;
+  }
+  return isDirWritable(probe);
+}
+
+/**
+ * True when ~/.npm contains ANY entry owned by a different uid (the classic
+ * root-owned-cache breakage from an old `sudo npm` — the offending files are
+ * usually buried deep in _cacache, with user-owned parents). posix only; on
+ * win32 returns false. Uses `find -not -uid` with an early exit; falls back
+ * to a top-level stat if find is unavailable.
+ */
+export function npmCacheOwnedByOther() {
+  if (process.platform === "win32" || typeof process.getuid !== "function") return false;
+  const npmDir = join(homedir(), ".npm");
+  if (!existsSync(npmDir)) return false;
+  const uid = process.getuid();
+  try {
+    const out = execSync(`find "${npmDir}" -not -uid ${uid} -print 2>/dev/null | head -1`, {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return out.trim().length > 0;
+  } catch {
+    try {
+      return statSync(npmDir).uid !== uid;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/** Is a directory on the current PATH (exact component match)? */
+export function dirOnPath(dir, pathVar = process.env.PATH || "") {
+  if (!dir) return false;
+  const delim = process.platform === "win32" ? ";" : ":";
+  const norm = (p) => p.replace(/[/\\]+$/, "");
+  return pathVar.split(delim).map(norm).includes(norm(dir));
+}
+
+/** The official npm user-level-prefix recipe for EACCES on the global prefix. */
+export const USER_PREFIX_RECIPE = [
+  "mkdir -p ~/.npm-global",
+  "npm config set prefix '~/.npm-global'",
+  '# add to your shell profile:  export PATH="$HOME/.npm-global/bin:$PATH"',
+  "npm i -g agentic-relay",
+];
+
+/** The fix for a root-owned ~/.npm cache (also fixes npx itself). */
+export const CACHE_CHOWN_RECIPE = 'sudo chown -R $(id -u):$(id -g) "$HOME/.npm"';