test(e2e): add no-network end-to-end smoke harness

Drives the real built dist/bin.cjs with a preloaded fetch stub (no
sockets) and asserts method+path+x-api-key per command plus fast-fail
validation. Covers all 22 command groups: 82/82 cases pass.

Adds `pnpm e2e` script.

Author: claude

e2e/README.md

@@ -0,0 +1,22 @@
+# E2E smoke harness
+
+Drives the **real built CLI binary** (`dist/bin.cjs`) end-to-end with a preloaded
+`fetch` stub (`node --require ./e2e/fetch-stub.cjs`). No network or sockets — the
+stub records each outbound request and returns canned JSON, so the test exercises
+the genuine argument parsing, HTTP client (method/path/query/body + `x-api-key`),
+output formatting, and fast-fail validation paths.
+
+```bash
+pnpm e2e        # builds, then runs e2e/run-stub.cjs
+```
+
+- `cases.cjs` — `[name, argv, expectedMethod, expectedPath, expectOk]` matrix
+  covering every command group plus validation/fast-fail cases.
+- `fetch-stub.cjs` — global `fetch` replacement: logs requests, returns canned
+  responses.
+- `run-stub.cjs` — spawns the binary per case, asserts the recorded request and
+  exit behavior, writes a report to `/tmp/e2e-report.txt`.
+
+A happy-path case passes when the binary exits 0, makes exactly the expected
+`METHOD /path` call, and sends `x-api-key`. A validation case passes when the
+binary exits non-zero with an error message **before** making any network call.

e2e/cases.cjs

@@ -0,0 +1,86 @@
+/* [name, argv, expectedMethod, expectedPath, expectOk] */
+module.exports = [
+  ["whoami", ["whoami"], "GET", "/api/accounts/id", true],
+  ["accounts get", ["accounts", "get", "--account", "acc_test"], "GET", "/api/accounts/acc_test", true],
+  ["accounts credits", ["accounts", "credits", "--account", "acc_test"], "GET", "/api/accounts/acc_test/credits", true],
+  ["accounts subscription", ["accounts", "subscription", "--account", "acc_test"], "GET", "/api/accounts/acc_test/subscription", true],
+  ["accounts update", ["accounts", "update", "--name", "New"], "PATCH", "/api/accounts", true],
+  ["artists list", ["artists", "list"], "GET", "/api/artists", true],
+  ["artists create", ["artists", "create", "--name", "Daft Punk"], "POST", "/api/artists", true],
+  ["artists update", ["artists", "update", "a1", "--label", "Columbia", "--pinned"], "PATCH", "/api/artists/a1", true],
+  ["artists delete", ["artists", "delete", "a1"], "DELETE", "/api/artists/a1", true],
+  ["artists fans", ["artists", "fans", "a1", "--limit", "5"], "GET", "/api/artists/a1/fans", true],
+  ["artists scrape", ["artists", "scrape", "--artist", "a1"], "POST", "/api/artist/socials/scrape", true],
+  ["chats list", ["chats", "list", "--artist", "a1"], "GET", "/api/chats", true],
+  ["chats create", ["chats", "create", "--name", "T"], "POST", "/api/chats", true],
+  ["chats update", ["chats", "update", "--chat", "c1", "--topic", "New topic"], "PATCH", "/api/chats", true],
+  ["chats delete", ["chats", "delete", "--chat", "c1"], "DELETE", "/api/chats", true],
+  ["chats messages", ["chats", "messages", "--chat", "c1"], "GET", "/api/chats/c1/messages", true],
+  ["chats artist", ["chats", "artist", "--chat", "c1"], "GET", "/api/chats/c1/artist", true],
+  ["chats compact", ["chats", "compact", "--chat", "c1", "--chat", "c2"], "POST", "/api/chats/compact", true],
+  ["generate", ["generate", "--prompt", "hi", "--artist", "a1"], "POST", "/api/chat/generate", true],
+  ["tasks list", ["tasks", "list"], "GET", "/api/tasks", true],
+  ["tasks create", ["tasks", "create", "--title", "Daily", "--prompt", "x", "--schedule", "0 9 * * *", "--artist", "a1"], "POST", "/api/tasks", true],
+  ["tasks update", ["tasks", "update", "--id", "t1", "--enabled", "false"], "PATCH", "/api/tasks", true],
+  ["tasks delete", ["tasks", "delete", "--id", "t1"], "DELETE", "/api/tasks", true],
+  ["tasks runs", ["tasks", "runs", "--limit", "5"], "GET", "/api/tasks/runs", true],
+  ["tasks status", ["tasks", "status", "--run", "run_1"], "GET", "/api/tasks/runs", true],
+  ["pulses list", ["pulses", "list"], "GET", "/api/pulses", true],
+  ["pulses set", ["pulses", "set", "--active", "true"], "PATCH", "/api/pulses", true],
+  ["connectors list", ["connectors", "list"], "GET", "/api/connectors", true],
+  ["connectors connect", ["connectors", "connect", "--connector", "googlesheets"], "POST", "/api/connectors", true],
+  ["connectors actions", ["connectors", "actions"], "GET", "/api/connectors/actions", true],
+  ["connectors run", ["connectors", "run", "--action", "GMAIL_FETCH_EMAILS", "--params", '{"max_results":1}'], "POST", "/api/connectors/actions", true],
+  ["connectors disconnect", ["connectors", "disconnect", "--id", "ca1"], "DELETE", "/api/connectors", true],
+  ["research search", ["research", "search", "--q", "Daft Punk", "--type", "artists"], "GET", "/api/research", true],
+  ["research profile", ["research", "profile", "--artist", "Daft Punk"], "GET", "/api/research/profile", true],
+  ["research audience", ["research", "audience", "--artist", "x"], "GET", "/api/research/audience", true],
+  ["research metrics", ["research", "metrics", "--artist", "x", "--source", "spotify"], "GET", "/api/research/metrics", true],
+  ["research similar", ["research", "similar", "--artist", "x", "--genre", "high"], "GET", "/api/research/similar", true],
+  ["research deep", ["research", "deep", "--query", "q"], "POST", "/api/research/deep", true],
+  ["research web", ["research", "web", "--query", "news", "--max-results", "5"], "POST", "/api/research/web", true],
+  ["research enrich", ["research", "enrich", "--input", "https://x", "--schema", '{"type":"object"}'], "POST", "/api/research/enrich", true],
+  ["research extract", ["research", "extract", "--url", "https://x"], "POST", "/api/research/extract", true],
+  ["research track-stats", ["research", "track-stats", "--isrc", "US1", "--source", "spotify"], "GET", "/api/research/track/stats", true],
+  ["research track-measurements", ["research", "track-measurements", "--track", "tk1", "--window", "30d"], "GET", "/api/research/tracks/tk1/measurements", true],
+  ["research snapshots", ["research", "snapshots", "--isrcs", "US1,US2"], "POST", "/api/research/snapshots", true],
+  ["spotify search", ["spotify", "search", "--q", "x", "--type", "artist"], "GET", "/api/spotify/search", true],
+  ["spotify top-tracks", ["spotify", "top-tracks", "--id", "z", "--market", "US"], "GET", "/api/spotify/artist/topTracks", true],
+  ["spotify album", ["spotify", "album", "--id", "al1"], "GET", "/api/spotify/album", true],
+  ["songs list", ["songs", "list", "--artist", "a1"], "GET", "/api/songs", true],
+  ["songs presets", ["songs", "presets"], "GET", "/api/songs/analyze/presets", true],
+  ["catalogs create", ["catalogs", "create", "--name", "2024"], "POST", "/api/catalogs", true],
+  ["catalogs songs", ["catalogs", "songs", "--catalog", "cat1"], "GET", "/api/catalogs/songs", true],
+  ["catalogs add-songs", ["catalogs", "add-songs", "--catalog", "cat1", "--songs", '[{"isrc":"US1"}]'], "POST", "/api/catalogs/songs", true],
+  ["catalogs remove-songs", ["catalogs", "remove-songs", "--catalog", "cat1", "--isrc", "US1"], "DELETE", "/api/catalogs/songs", true],
+  ["models list", ["models", "list"], "GET", "/api/ai/models", true],
+  ["orgs list", ["orgs", "list"], "GET", "/api/organizations", true],
+  ["orgs create", ["orgs", "create", "--name", "Label", "--account", "acc_test"], "POST", "/api/organizations", true],
+  ["orgs add-artist", ["orgs", "add-artist", "--artist", "a1", "--org", "o1"], "POST", "/api/organizations/artists", true],
+  ["workspaces create", ["workspaces", "create", "--name", "Q1"], "POST", "/api/workspaces", true],
+  ["templates list", ["templates", "list"], "GET", "/api/agents/templates", true],
+  ["templates create", ["templates", "create", "--title", "Recap", "--description", "Weekly recap of streams", "--prompt", "Produce a weekly streaming recap report", "--tags", "a,b"], "POST", "/api/agents/templates", true],
+  ["templates favorite", ["templates", "favorite", "tpl1"], "PUT", "/api/agents/templates/tpl1/favorite", true],
+  ["templates delete", ["templates", "delete", "tpl1"], "DELETE", "/api/agents/templates/tpl1", true],
+  ["sessions create", ["sessions", "create", "--title", "Build"], "POST", "/api/sessions", true],
+  ["sessions get", ["sessions", "get", "s1"], "GET", "/api/sessions/s1", true],
+  ["sessions update", ["sessions", "update", "s1", "--status", "completed"], "PATCH", "/api/sessions/s1", true],
+  ["sandboxes list", ["sandboxes", "list"], "GET", "/api/sandboxes", true],
+  ["sandboxes file", ["sandboxes", "file", "--path", "README.md"], "GET", "/api/sandboxes/file", true],
+  ["sandboxes setup", ["sandboxes", "setup"], "POST", "/api/sandboxes/setup", true],
+  ["content templates", ["content", "templates"], "GET", "/api/content/templates", true],
+  ["content template", ["content", "template", "tpl"], "GET", "/api/content/templates/tpl", true],
+  ["content caption", ["content", "caption", "--topic", "tour"], "POST", "/api/content/caption", true],
+  ["content image", ["content", "image", "--prompt", "art", "--num", "2"], "POST", "/api/content/image", true],
+  ["content transcribe", ["content", "transcribe", "--audio", "https://a.mp3"], "POST", "/api/content/transcribe", true],
+  ["content edit", ["content", "edit", "--video", "https://v.mp4", "--template", "cut"], "PATCH", "/api/content", true],
+  ["notifications", ["notifications", "--subject", "Hi", "--text", "Body"], "POST", "/api/notifications", true],
+  // Fast-fail validation cases (must exit non-zero with Error:, no network call)
+  ["ERR generate no prompt", ["generate"], null, null, false],
+  ["ERR track-stats no id", ["research", "track-stats", "--source", "spotify"], null, null, false],
+  ["ERR accounts update empty", ["accounts", "update"], null, null, false],
+  ["ERR catalogs create empty", ["catalogs", "create"], null, null, false],
+  ["ERR tasks create missing req", ["tasks", "create", "--title", "x"], null, null, false],
+  ["ERR research lookup no args", ["research", "lookup"], null, null, false],
+  ["ERR research snapshots no scope", ["research", "snapshots"], null, null, false],
+];

e2e/fetch-stub.cjs

@@ -0,0 +1,77 @@
+/* Preloaded via `node --require`. Replaces global.fetch so the real CLI binary
+ * runs end-to-end without any network. Logs each request to E2E_LOG. */
+const fs = require("node:fs");
+const LOG = process.env.E2E_LOG;
+
+function canned(p) {
+  const base = { status: "success" };
+  if (p === "/api/accounts/id") return { accountId: "acc_test" };
+  if (/^\/api\/accounts\/[^/]+\/credits$/.test(p)) return { remaining_credits: 50, used_credits: 10, total_credits: 60, is_pro: true };
+  if (/^\/api\/accounts\/[^/]+\/subscription$/.test(p)) return { isPro: true, status: "active", plan: "pro", source: "account" };
+  if (/^\/api\/accounts\/[^/]+\/catalogs$/.test(p)) return { ...base, catalogs: [] };
+  if (/^\/api\/accounts\/[^/]+$/.test(p)) return { ...base, account: { account_id: "acc_test", name: "Test" } };
+  if (p === "/api/accounts") return { data: { account_id: "acc_test", name: "Test" } };
+  if (p === "/api/artists") return { ...base, artists: [{ account_id: "a1", name: "Daft Punk", label: "Columbia" }], artist: { account_id: "a1" } };
+  if (/^\/api\/artists\/[^/]+\/fans$/.test(p)) return { ...base, fans: [], pagination: { page: 1, total_pages: 1, total_count: 0 } };
+  if (/^\/api\/artists\/[^/]+$/.test(p)) return { ...base, artist: { account_id: "a1" }, success: true, artistId: "a1" };
+  if (p === "/api/artist/socials/scrape") return [{ runId: "r1" }];
+  if (p === "/api/chats") return { ...base, chats: [{ id: "c1", topic: "T", updated_at: "2026-06-21" }], chat: { id: "c1" } };
+  if (/^\/api\/chats\/[^/]+\/messages$/.test(p)) return { data: [] };
+  if (/^\/api\/chats\/[^/]+\/artist$/.test(p)) return { ...base, room_id: "c1", artist_id: "a1", artist_exists: true };
+  if (p === "/api/chats/compact") return { chats: [{ chatId: "c1", compacted: true }] };
+  if (p === "/api/chat/generate") return { ...base, text: "Generated answer.", roomId: "c1" };
+  if (p === "/api/tasks") return { ...base, tasks: [{ id: "t1", title: "Daily", schedule: "0 9 * * *", enabled: true }] };
+  if (p === "/api/tasks/runs") return { ...base, runs: [{ id: "run_1", status: "COMPLETED", createdAt: "2026-06-21" }] };
+  if (p === "/api/pulses") return { ...base, pulses: [{ account_id: "acc_test", active: true }] };
+  if (p === "/api/connectors") return { success: true, connectors: [{ slug: "googlesheets", connected: false }], data: { redirectUrl: "https://auth" } };
+  if (p === "/api/connectors/actions") return { success: true, actions: [{ slug: "GMAIL_FETCH_EMAILS", connectorSlug: "gmail", isConnected: true }], result: { ok: true } };
+  if (p === "/api/research") return { ...base, results: [{ id: "x", name: "Daft Punk" }] };
+  if (p.startsWith("/api/research/")) return { ...base, content: "Deep answer", citations: [], results: [], tracks: [] };
+  if (p.startsWith("/api/spotify/")) return { ...base, items: [] };
+  if (p === "/api/songs") return { ...base, songs: [{ isrc: "US1", name: "Track", album: "Album" }] };
+  if (p === "/api/songs/analyze/presets") return { ...base, presets: [{ name: "catalog_metadata", description: "x", requiresAudio: false, responseFormat: "json" }] };
+  if (p === "/api/catalogs") return { ...base, catalog: { id: "cat1" }, songs_added: 3 };
+  if (p === "/api/catalogs/songs") return { ...base, songs: [{ isrc: "US1", name: "Track", album: "Album" }] };
+  if (p === "/api/ai/models") return { models: [{ id: "m1", name: "Model One" }] };
+  if (p === "/api/organizations") return { ...base, organizations: [{ organization_id: "o1", organization_name: "Label" }], organization: { id: "o1" } };
+  if (p === "/api/organizations/artists") return { ...base, id: "link1" };
+  if (p === "/api/workspaces") return { workspace: { id: "w1", name: "Q1" } };
+  if (p === "/api/agents/templates") return { ...base, templates: [{ id: "tpl1", title: "Recap", is_private: false, is_favourite: false }], template: { id: "tpl1" } };
+  if (/^\/api\/agents\/templates\/[^/]+\/favorite$/.test(p)) return { ...base };
+  if (/^\/api\/agents\/templates\/[^/]+$/.test(p)) return { ...base, template: { id: "tpl1" } };
+  if (p === "/api/sandboxes") return { ...base, sandboxes: [{ sandboxId: "sb1", sandboxStatus: "running", createdAt: "2026-06-21" }] };
+  if (p === "/api/sandboxes/file") return { ...base, content: "file contents\n" };
+  if (p === "/api/sandboxes/files") return { ...base, uploaded: [{ path: "a.png", sha: "abc" }] };
+  if (p === "/api/sandboxes/setup") return { ...base, runId: "setup1" };
+  if (p === "/api/sessions") return { session: { id: "s1", title: "Build" }, chat: { id: "c1" } };
+  if (/^\/api\/sessions\/[^/]+$/.test(p)) return { session: { id: "s1", title: "Build", status: "running" } };
+  if (p === "/api/content/templates") return { ...base, templates: [{ name: "tpl", description: "d" }] };
+  if (/^\/api\/content\/templates\/[^/]+$/.test(p)) return { id: "tpl", name: "tpl" };
+  if (p === "/api/content/caption") return { content: "A great caption" };
+  if (p === "/api/content/image") return { imageUrl: "https://img/1.png", images: ["https://img/1.png"] };
+  if (p === "/api/content/transcribe") return { transcript: "hello world" };
+  if (p === "/api/content") return { runId: "edit1", status: "triggered" };
+  if (p === "/api/notifications") return { ...base, message: "Notification sent." };
+  return base;
+}
+
+global.fetch = async (url, opts = {}) => {
+  const u = new URL(url);
+  fs.appendFileSync(
+    LOG,
+    JSON.stringify({
+      method: opts.method || "GET",
+      path: u.pathname,
+      query: Object.fromEntries(u.searchParams.entries()),
+      body: opts.body ? JSON.parse(opts.body) : null,
+      apiKey: (opts.headers && (opts.headers["x-api-key"] || opts.headers["X-Api-Key"])) || null,
+    }) + "\n",
+  );
+  const data = canned(u.pathname);
+  return {
+    ok: true,
+    status: 200,
+    text: async () => JSON.stringify(data),
+    json: async () => data,
+  };
+};

e2e/run-stub.cjs

@@ -0,0 +1,55 @@
+/* E2E: runs the real built CLI binary with a preloaded fetch stub (no sockets).
+ * Verifies method+path+x-api-key per command, and fast-fail validation. */
+const path = require("node:path");
+const fs = require("node:fs");
+const { spawnSync } = require("node:child_process");
+
+const ROOT = path.join(__dirname, "..");
+const BIN = path.join(ROOT, "dist", "bin.cjs");
+const STUB = path.join(__dirname, "fetch-stub.cjs");
+const LOG = "/tmp/e2e-requests.log";
+
+const cases = require("./cases.cjs");
+
+function run(args) {
+  fs.writeFileSync(LOG, "");
+  const env = { ...process.env, RECOUP_API_KEY: "test-key", E2E_LOG: LOG };
+  const r = spawnSync("node", ["--require", STUB, BIN, ...args], {
+    env, input: "", encoding: "utf8", timeout: 15000,
+  });
+  const log = fs.readFileSync(LOG, "utf8").trim();
+  const reqs = log ? log.split("\n").map((l) => JSON.parse(l)) : [];
+  return { code: r.status, stdout: r.stdout || "", stderr: r.stderr || "", reqs };
+}
+
+let pass = 0, fail = 0;
+const rows = [];
+for (const [name, args, m, p, expectOk] of cases) {
+  const { code, stdout, stderr, reqs } = run(args);
+  let ok = true, note = "";
+  if (expectOk) {
+    if (code !== 0) { ok = false; note = `exit ${code}: ${stderr.trim().slice(0, 50)}`; }
+    else if (reqs.length === 0) { ok = false; note = "no request made"; }
+    else {
+      const req = reqs[reqs.length - 1];
+      if (req.method !== m) { ok = false; note = `method ${req.method}!=${m}`; }
+      else if (req.path !== p) { ok = false; note = `path ${req.path}!=${p}`; }
+      else if (req.apiKey !== "test-key") { ok = false; note = "missing x-api-key"; }
+      else note = `${req.method} ${req.path}  out:${stdout.trim().split("\n")[0].slice(0, 22)}`;
+    }
+  } else {
+    // Accept both runAction's "Error:" and Commander's built-in "error:" — both
+    // are correct fast-fails (non-zero exit, no network call made).
+    if (code === 0) { ok = false; note = "expected failure, exit 0"; }
+    else if (!/error:/i.test(stderr)) { ok = false; note = `no error msg (${stderr.slice(0, 30)})`; }
+    else if (reqs.length > 0) { ok = false; note = "made network call before validating"; }
+    else note = "fast-fail: " + stderr.trim().split("\n")[0].replace(/^error:\s*/i, "").slice(0, 46);
+  }
+  rows.push([ok ? "PASS" : "FAIL", name, note]);
+  ok ? pass++ : fail++;
+}
+const w = Math.max(...rows.map((x) => x[1].length));
+const out = rows.map(([s, n, note]) => `${s}  ${n.padEnd(w)}  ${note}`).join("\n") + `\n\n${pass}/${pass + fail} passed, ${fail} failed`;
+fs.writeFileSync("/tmp/e2e-report.txt", out + "\n");
+process.stdout.write(out + "\n");
+process.exit(fail ? 1 : 0);

package.json

@@ -13,6 +13,7 @@
   "scripts": {
     "build": "tsup",
     "test": "vitest run",
+    "e2e": "pnpm build && node e2e/run-stub.cjs",
     "lint": "eslint . --ext .ts --fix",
     "format": "prettier --write \"src/**/*.ts\""
   },