agentic-relay 4.0.0 → 4.1.0

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/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"';

package/bin/lib/update-check.mjs

@@ -0,0 +1,121 @@
+/**
+ * Async update notifier (the Vercel/update-notifier pattern, zero-dep).
+ *
+ * The CLI never blocks on the network: each run reads a tiny local state file
+ * and prints a one-line stderr nag if a newer version was seen on a PREVIOUS
+ * run; when the state is older than 24h it spawns a detached, unref'd child
+ * (this module with --refresh) that fetches the registry and rewrites the
+ * state for next time.
+ *
+ * Suppressed when: AGENT_RELAY_NO_UPDATE_CHECK / NO_UPDATE_NOTIFIER / CI env
+ * vars are set, stderr isn't a TTY (don't pollute piped/scripted runs), or the
+ * CLI is running out of an ephemeral npx cache (npx users get @latest anyway).
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, realpathSync } from "fs";
+import { homedir } from "os";
+import { join, dirname, sep } from "path";
+import { spawn } from "child_process";
+import { fileURLToPath } from "url";
+
+export const STATE_PATH = join(homedir(), ".config", "agent-relay", "update-check.json");
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const SELF_PATH = fileURLToPath(import.meta.url);
+
+/** Numeric-dotted semver compare: 1 if a > b, -1 if a < b, 0 if equal. */
+export function compareSemver(a, b) {
+  const pa = String(a).split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = String(b).split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const da = pa[i] || 0;
+    const db = pb[i] || 0;
+    if (da !== db) return da > db ? 1 : -1;
+  }
+  return 0;
+}
+
+/**
+ * Pure suppression predicate (exported for tests). env/tty/binPath injected.
+ */
+export function shouldSuppress({ env, stderrIsTTY, binPath }) {
+  if (env.AGENT_RELAY_NO_UPDATE_CHECK || env.NO_UPDATE_NOTIFIER || env.CI) return true;
+  if (!stderrIsTTY) return true;
+  if (binPath) {
+    let real = binPath;
+    try {
+      real = realpathSync(binPath);
+    } catch {
+      /* keep as-is */
+    }
+    if (real.includes(`${sep}_npx${sep}`) || binPath.includes(`${sep}_npx${sep}`)) return true;
+  }
+  return false;
+}
+
+export function readState(statePath = STATE_PATH) {
+  try {
+    return JSON.parse(readFileSync(statePath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+export function writeState(state, statePath = STATE_PATH) {
+  try {
+    mkdirSync(dirname(statePath), { recursive: true });
+    writeFileSync(statePath, JSON.stringify(state, null, 2) + "\n");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Called at the top of every CLI run. Never throws, never blocks: prints the
+ * nag from cached state and (at most once per 24h) spawns the background
+ * refresh.
+ */
+export function maybeNotifyUpdate({ currentVersion, binPath = process.argv[1] }) {
+  try {
+    if (shouldSuppress({ env: process.env, stderrIsTTY: Boolean(process.stderr.isTTY), binPath })) {
+      return;
+    }
+    const state = readState();
+    if (state?.latest_version && compareSemver(state.latest_version, currentVersion) > 0) {
+      process.stderr.write(
+        `agentrelay ${state.latest_version} is available (you have ${currentVersion}) — npm i -g agentic-relay\n`,
+      );
+    }
+    const last = state?.last_check_ts ? Date.parse(state.last_check_ts) : 0;
+    if (!Number.isFinite(last) || Date.now() - last > CHECK_INTERVAL_MS) {
+      spawn(process.execPath, [SELF_PATH, "--refresh"], { detached: true, stdio: "ignore" }).unref();
+    }
+  } catch {
+    // The nag must never break a command.
+  }
+}
+
+/** Background refresh: fetch the registry, persist state, exit. */
+async function refresh() {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 5000);
+  try {
+    const res = await fetch("https://registry.npmjs.org/agentic-relay/latest", {
+      signal: controller.signal,
+    });
+    if (!res.ok) return;
+    const data = await res.json();
+    if (data?.version) {
+      writeState({ last_check_ts: new Date().toISOString(), latest_version: data.version });
+    }
+  } catch {
+    // Offline/registry down — try again next interval.
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Self-run refresh mode (spawned detached by maybeNotifyUpdate).
+if (process.argv[1] === SELF_PATH && process.argv[2] === "--refresh") {
+  refresh();
+}

package/bin/lib/zip.mjs

@@ -0,0 +1,139 @@
+/**
+ * Pure-JS zip extraction — no system `unzip` dependency (Windows ships none).
+ *
+ * Deliberately minimal: reads the END-OF-CENTRAL-DIRECTORY record and walks the
+ * central directory (never trusting local headers for sizes — that's what makes
+ * archives written with data descriptors / flag bit 3 work), then inflates each
+ * entry with node:zlib. Supported: store (method 0) and deflate (method 8).
+ * Rejected with explicit errors: zip64, encrypted entries, other methods.
+ *
+ * Security posture (matches the old `unzip` path, or stricter):
+ *  - zip-slip guard runs over ALL entry names before anything is written
+ *  - symlink entries are materialized as regular files (no link-then-write-through)
+ *  - nothing from the archive is ever executed
+ */
+
+import { mkdirSync, writeFileSync } from "fs";
+import { dirname, join, resolve, sep } from "path";
+import { inflateRawSync } from "zlib";
+
+const EOCD_SIG = 0x06054b50; // end of central directory
+const CEN_SIG = 0x02014b50; // central directory file header
+const LOC_SIG = 0x04034b50; // local file header
+const ZIP64_LOCATOR_SIG = 0x07064b50; // zip64 EOCD locator
+
+/** Reject any archive entry that escapes the destination (absolute or ../). */
+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}`);
+    }
+  }
+}
+
+/**
+ * Locate the EOCD record (scan backwards over the max 22-byte record +
+ * 65535-byte comment tail). Throws on zip64 archives and missing records.
+ */
+export function findEndOfCentralDirectory(buf) {
+  const min = Math.max(0, buf.length - 22 - 65535);
+  for (let i = buf.length - 22; i >= min; i--) {
+    if (buf.readUInt32LE(i) !== EOCD_SIG) continue;
+    const totalEntries = buf.readUInt16LE(i + 10);
+    const cdSize = buf.readUInt32LE(i + 12);
+    const cdOffset = buf.readUInt32LE(i + 16);
+    if (
+      totalEntries === 0xffff ||
+      cdSize === 0xffffffff ||
+      cdOffset === 0xffffffff ||
+      (i >= 20 && buf.readUInt32LE(i - 20) === ZIP64_LOCATOR_SIG)
+    ) {
+      throw new Error("zip64 archives are not supported");
+    }
+    return { cdOffset, cdSize, totalEntries };
+  }
+  throw new Error("invalid zip: end-of-central-directory record not found");
+}
+
+/**
+ * Walk the central directory. Sizes/offsets come from here, NEVER from local
+ * headers, so data-descriptor zips (local sizes = 0) extract correctly.
+ */
+export function listZipEntries(buf) {
+  const { cdOffset, totalEntries } = findEndOfCentralDirectory(buf);
+  const entries = [];
+  let p = cdOffset;
+  for (let n = 0; n < totalEntries; n++) {
+    if (p + 46 > buf.length || buf.readUInt32LE(p) !== CEN_SIG) {
+      throw new Error("invalid zip: corrupt central directory");
+    }
+    const flags = buf.readUInt16LE(p + 8);
+    const method = buf.readUInt16LE(p + 10);
+    const compressedSize = buf.readUInt32LE(p + 20);
+    const uncompressedSize = buf.readUInt32LE(p + 24);
+    const nameLen = buf.readUInt16LE(p + 28);
+    const extraLen = buf.readUInt16LE(p + 30);
+    const commentLen = buf.readUInt16LE(p + 32);
+    const localHeaderOffset = buf.readUInt32LE(p + 42);
+    const name = buf.toString("utf-8", p + 46, p + 46 + nameLen);
+    if (flags & 0x1) {
+      throw new Error(`encrypted zip entries are not supported: ${name}`);
+    }
+    entries.push({
+      name,
+      method,
+      compressedSize,
+      uncompressedSize,
+      localHeaderOffset,
+      isDirectory: name.endsWith("/"),
+    });
+    p += 46 + nameLen + extraLen + commentLen;
+  }
+  return entries;
+}
+
+/** Decompress one entry's bytes (seeks via the local header it points at). */
+export function readEntryData(buf, entry) {
+  const p = entry.localHeaderOffset;
+  if (p + 30 > buf.length || buf.readUInt32LE(p) !== LOC_SIG) {
+    throw new Error(`invalid zip: bad local header for ${entry.name}`);
+  }
+  // The local header's OWN name/extra lengths govern where data starts (its
+  // extra field can differ from the central directory's).
+  const nameLen = buf.readUInt16LE(p + 26);
+  const extraLen = buf.readUInt16LE(p + 28);
+  const start = p + 30 + nameLen + extraLen;
+  const data = buf.subarray(start, start + entry.compressedSize);
+  if (entry.method === 0) return Buffer.from(data);
+  if (entry.method === 8) return inflateRawSync(data);
+  throw new Error(`unsupported zip compression method ${entry.method} for ${entry.name}`);
+}
+
+/**
+ * Extract an in-memory zip buffer into destDir. Returns the list of file paths
+ * written. Validates every entry name against zip-slip BEFORE any write.
+ */
+export function extractZip(buf, destDir) {
+  const entries = listZipEntries(buf);
+  assertNoZipSlip(entries.map((e) => e.name), destDir);
+  mkdirSync(destDir, { recursive: true });
+  const placed = [];
+  for (const entry of entries) {
+    const target = join(destDir, entry.name);
+    if (entry.isDirectory) {
+      mkdirSync(target, { recursive: true });
+      continue;
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    // Symlink entries (unix mode S_IFLNK in external attrs) are intentionally
+    // written as regular files containing the link target text.
+    writeFileSync(target, readEntryData(buf, entry));
+    placed.push(target);
+  }
+  return placed;
+}