agentic-relay 4.3.1 → 5.0.1

package/bin/lib/doctor.mjs

@@ -1,222 +0,0 @@
-/**
- * `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/test/budget.test.mjs

@@ -1,31 +0,0 @@
-/**
- * Tests for the `budget` command's dollar→cents conversion + validation.
- * Run: `node --test bin/test/`.
- */
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { dollarsToCents } from "../lib/commands.mjs";
-
-test("dollarsToCents: whole dollars → cents", () => {
-  assert.equal(dollarsToCents("--daily-cap", 50), 5000);
-  assert.equal(dollarsToCents("--daily-cap", "50"), 5000);
-});
-
-test("dollarsToCents: fractional dollars round to nearest cent", () => {
-  assert.equal(dollarsToCents("--auto-approve", 2.5), 250);
-  assert.equal(dollarsToCents("--auto-approve", "0.99"), 99);
-  assert.equal(dollarsToCents("--auto-approve", 1.01), 101);
-});
-
-test("dollarsToCents: zero is allowed (e.g. auto-approve nothing)", () => {
-  assert.equal(dollarsToCents("--auto-approve", 0), 0);
-});
-
-test("dollarsToCents: negative is a usage error", () => {
-  assert.throws(() => dollarsToCents("--daily-cap", -5), (e) => e.usage === true);
-});
-
-test("dollarsToCents: non-numeric is a usage error", () => {
-  assert.throws(() => dollarsToCents("--daily-cap", "abc"), (e) => e.usage === true);
-  assert.throws(() => dollarsToCents("--daily-cap", "5dollars"), (e) => e.usage === true);
-});

package/bin/test/cache.test.mjs

@@ -1,111 +0,0 @@
-/**
- * Tests for the banked-cache contract: race-safe `listSpecHeadlines` (reads
- * spec files, no index.json) and `resolveCapability`'s spec-file id fallback
- * (so a depth session resolves from what a breadth subagent banked). No network.
- * Run: `node --test bin/test/cache.test.mjs`.
- */
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { mkdtempSync, rmSync, existsSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { Cache } from "../lib/cache.mjs";
-import { resolveCapability, cmdCache } from "../lib/commands.mjs";
-
-const ISO = "2026-05-24T00:00:00.000Z";
-
-function withCache(fn) {
-  const dir = mkdtempSync(join(tmpdir(), "agent-relay-bank-"));
-  try {
-    return fn(dir, new Cache(dir));
-  } finally {
-    rmSync(dir, { recursive: true, force: true });
-  }
-}
-
-test("listSpecHeadlines: returns slug+name+summary+feature-count, no index.json needed", () => {
-  withCache((dir, cache) => {
-    cache.writeSpec("a-tool", {
-      slug: "a-tool", name: "A", summary: "does A",
-      features: [{ feature: "x", how: "y" }], agent_id: "agent-a", ts: ISO,
-    });
-    cache.writeSpec("b-tool", { slug: "b-tool", name: "B", summary: "does B", features: [], ts: ISO });
-
-    const h = cache.listSpecHeadlines();
-    assert.equal(h.length, 2);
-    const a = h.find((x) => x.slug === "a-tool");
-    assert.equal(a.name, "A");
-    assert.equal(a.summary, "does A");
-    assert.equal(a.features, 1);
-    assert.equal(a.agent_id, "agent-a");
-    // Race-safe: the put path never wrote a shared index.json.
-    assert.equal(existsSync(join(dir, "index.json")), false);
-  });
-});
-
-test("listSpecHeadlines: tolerates a spec missing the optional fields", () => {
-  withCache((_dir, cache) => {
-    cache.writeSpec("bare", { slug: "bare", ts: ISO }); // no name/summary/features
-    const h = cache.listSpecHeadlines();
-    assert.equal(h.length, 1);
-    assert.equal(h[0].slug, "bare");
-    assert.equal(h[0].summary, null);
-    assert.equal(h[0].features, null);
-  });
-});
-
-test("resolveCapability: falls back to the banked spec's agent_id (no network)", async () => {
-  await withCache(async (dir, cache) => {
-    cache.writeSpec("a-tool", {
-      slug: "a-tool", name: "A Tool", summary: "s", features: [],
-      agent_id: "agent-a", ts: ISO,
-    });
-    // No index.json, refresh falsy → must resolve from the spec file alone.
-    const r = await resolveCapability("a-tool", { cacheDir: dir, noCache: false });
-    assert.equal(r.agentId, "agent-a");
-    assert.equal(r.slug, "a-tool");
-    assert.equal(r.name, "A Tool");
-  });
-});
-
-test("cache put: soft contract warnings (missing session_id/summary/features), still stores", () => {
-  withCache((dir, cache) => {
-    const f = join(dir, "min.json");
-    writeFileSync(f, JSON.stringify({ slug: "bare-tool", name: "Bare" }));
-    const r = cmdCache("put", "bare-tool", { cacheDir: dir, file: f });
-    assert.equal(r.stored, true);
-    assert.equal(r.warnings.length, 3);
-    assert.match(r.warnings.join(" "), /session_id/);
-    assert.match(r.warnings.join(" "), /summary/);
-    assert.match(r.warnings.join(" "), /features/);
-    assert.ok(cache.readSpec("bare-tool")); // warned, but banked anyway
-
-    // A contract-complete spec yields no warnings.
-    writeFileSync(
-      f,
-      JSON.stringify({
-        slug: "full-tool",
-        session_id: "s-1",
-        summary: "maps the surface",
-        features: [{ feature: "x", how: "y", status: "surface_only" }],
-      }),
-    );
-    const r2 = cmdCache("put", "full-tool", { cacheDir: dir, file: f });
-    assert.deepEqual(r2.warnings, []);
-    assert.ok(cache.readSpec("full-tool"));
-
-    // features[] present but entries missing status → one targeted warning.
-    writeFileSync(
-      f,
-      JSON.stringify({
-        slug: "statusless-tool",
-        session_id: "s-2",
-        summary: "mapped",
-        features: [{ feature: "x", how: "y" }, { feature: "z", how: "w", status: "coded" }],
-      }),
-    );
-    const r3 = cmdCache("put", "statusless-tool", { cacheDir: dir, file: f });
-    assert.equal(r3.warnings.length, 1);
-    assert.match(r3.warnings[0], /1 feature\(s\) missing status/);
-  });
-});

package/bin/test/doctor.test.mjs

@@ -1,76 +0,0 @@
-/**
- * Tests for `agentrelay doctor` (pure pieces) and the sysenv probes that are
- * testable without touching the real npm install.
- * Run: `node --test bin/test/doctor.test.mjs`.
- */
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { sep } from "node:path";
-import { checkNodeVersion, summarize, fmtDoctor } from "../lib/doctor.mjs";
-import { dirOnPath, npmGlobalBinDir, globalBinShimPath, isEphemeralBin } from "../lib/sysenv.mjs";
-
-test("checkNodeVersion: >=18 ok, <18 fail", () => {
-  assert.equal(checkNodeVersion("18.0.0").status, "ok");
-  assert.equal(checkNodeVersion("23.11.0").status, "ok");
-  assert.equal(checkNodeVersion("16.20.2").status, "fail");
-  assert.match(checkNodeVersion("16.20.2").detail, /needs Node >= 18/);
-});
-
-test("summarize: warns don't fail the doctor, fails do", () => {
-  const okWarn = summarize([
-    { status: "ok" },
-    { status: "warn" },
-  ]);
-  assert.equal(okWarn.ok, true);
-  assert.equal(okWarn.exitCode, 0);
-
-  const withFail = summarize([{ status: "ok" }, { status: "fail" }]);
-  assert.equal(withFail.ok, false);
-  assert.equal(withFail.exitCode, 1);
-});
-
-test("fmtDoctor renders one line per check + a verdict line", () => {
-  const out = fmtDoctor({
-    checks: [
-      { status: "ok", label: "Node.js version", detail: "v20.0.0" },
-      { status: "warn", label: "API key", detail: "not found" },
-    ],
-    doctor_ok: true,
-  });
-  const lines = out.split("\n");
-  assert.equal(lines.length, 3);
-  assert.match(lines[0], /^✓ /);
-  assert.match(lines[1], /^! /);
-  assert.match(lines[2], /no blocking problems/);
-});
-
-test("dirOnPath: exact component match, trailing-slash tolerant", () => {
-  const delim = process.platform === "win32" ? ";" : ":";
-  const pathVar = ["/usr/bin", "/opt/homebrew/bin/"].join(delim);
-  assert.equal(dirOnPath("/opt/homebrew/bin", pathVar), true);
-  assert.equal(dirOnPath("/usr/bin", pathVar), true);
-  assert.equal(dirOnPath("/usr/local/bin", pathVar), false);
-  assert.equal(dirOnPath(null, pathVar), false);
-});
-
-test("npmGlobalBinDir/globalBinShimPath shape per platform", () => {
-  const prefix = process.platform === "win32" ? "C:\\npm" : "/opt/homebrew";
-  const binDir = npmGlobalBinDir(prefix);
-  const shim = globalBinShimPath(prefix, "agentrelay");
-  if (process.platform === "win32") {
-    assert.equal(binDir, prefix);
-    assert.ok(shim.endsWith("agentrelay.cmd"));
-  } else {
-    assert.equal(binDir, `${prefix}/bin`);
-    assert.ok(shim.endsWith("/bin/agentrelay"));
-  }
-  assert.equal(npmGlobalBinDir(null), null);
-});
-
-test("isEphemeralBin flags npx-cache paths and dangling symlinks", () => {
-  const npxBin = ["", "Users", "x", ".npm", "_npx", "ab12", "node_modules", ".bin", "agentrelay"].join(sep);
-  assert.equal(isEphemeralBin(npxBin, "/tmp/pkg"), true);
-  // A path that doesn't exist → realpath throws → treated as not-usable.
-  assert.equal(isEphemeralBin("/definitely/not/a/real/bin", "/tmp/pkg"), true);
-  assert.equal(isEphemeralBin(null, "/tmp/pkg"), false);
-});

package/schema/deliverable.json

@@ -1,45 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://attentionmarket-auth.vercel.app/schema/deliverable.json",
-  "title": "BankedSpec",
-  "description": "The cache contract for a banked capability spec (`.agent-relay/specs/<slug>.json`). A breadth subagent drives an SE agent to full coverage and writes this; it passes only `summary` back to the main agent, which later reads the full file (`agentrelay cache show <slug>`) when implementing. Light required spine (slug, name, summary, features) the main agent can always rely on; any additional keys the subagent finds useful are allowed.",
-  "type": "object",
-  "required": ["slug", "name", "summary", "features"],
-  "additionalProperties": true,
-  "properties": {
-    "slug": { "type": "string", "description": "Stable kebab-case key (also the file name)." },
-    "name": { "type": "string" },
-    "summary": {
-      "type": "string",
-      "description": "1-3 sentences: what this capability offers + bottom line. This is what the breadth subagent returns to the main agent and what `cache ls` shows for triage."
-    },
-    "features": {
-      "type": "array",
-      "description": "The breadth detail — one entry per capability/feature the agent covered.",
-      "items": {
-        "type": "object",
-        "required": ["feature", "how"],
-        "additionalProperties": true,
-        "properties": {
-          "feature": { "type": "string", "description": "What it does." },
-          "how": { "type": "string", "description": "How to use it (endpoint/params/pattern)." },
-          "snippets": {
-            "type": "array",
-            "items": {
-              "type": "object",
-              "properties": {
-                "lang": { "type": "string" },
-                "path": { "type": "string" },
-                "desc": { "type": "string" },
-                "code": { "type": "string" }
-              }
-            }
-          },
-          "gotchas": { "type": "array", "items": { "type": "string" } }
-        }
-      }
-    },
-    "agent_id": { "type": ["string", "null"], "description": "The only id needed to open a session (ad_unit + price resolved server-side)." },
-    "ts": { "type": "string", "format": "date-time" }
-  }
-}