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. */
+constfs=require("node:fs");
+constLOG=process.env.E2E_LOG;
+
+functioncanned(p){
+constbase={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."};
+returnbase;
+}
+
+global.fetch=async(url,opts={})=>{
+constu=newURL(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",
+);
+constdata=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. */
+constpath=require("node:path");
+constfs=require("node:fs");
+const{ spawnSync }=require("node:child_process");
+
+constROOT=path.join(__dirname,"..");
+constBIN=path.join(ROOT,"dist","bin.cjs");
+constSTUB=path.join(__dirname,"fetch-stub.cjs");
+constLOG="/tmp/e2e-requests.log";
+
+constcases=require("./cases.cjs");
+
+functionrun(args){
+fs.writeFileSync(LOG,"");
+constenv={ ...process.env,RECOUP_API_KEY: "test-key",E2E_LOG: LOG};
+constr=spawnSync("node",["--require",STUB,BIN, ...args],{
+ env,input: "",encoding: "utf8",timeout: 15000,
+});
+constlog=fs.readFileSync(LOG,"utf8").trim();
+constreqs=log ? log.split("\n").map((l)=>JSON.parse(l)) : [];
+return{code: r.status,stdout: r.stdout||"",stderr: r.stderr||"", reqs };
+}
+
+letpass=0,fail=0;
+constrows=[];
+for(const[name,args,m,p,expectOk]ofcases){
+const{ code, stdout, stderr, reqs }=run(args);
+letok=true,note="";
+if(expectOk){
+if(code!==0){ok=false;note=`exit ${code}: ${stderr.trim().slice(0,50)}`;}
+elseif(reqs.length===0){ok=false;note="no request made";}
+else{
+constreq=reqs[reqs.length-1];
+if(req.method!==m){ok=false;note=`method ${req.method}!=${m}`;}
+elseif(req.path!==p){ok=false;note=`path ${req.path}!=${p}`;}
+elseif(req.apiKey!=="test-key"){ok=false;note="missing x-api-key";}
+elsenote=`${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";}
+elseif(!/error:/i.test(stderr)){ok=false;note=`no error msg (${stderr.slice(0,30)})`;}
+elseif(reqs.length>0){ok=false;note="made network call before validating";}
+elsenote="fast-fail: "+stderr.trim().split("\n")[0].replace(/^error:\s*/i,"").slice(0,46);
+}
+rows.push([ok ? "PASS" : "FAIL",name,note]);
+ok ? pass++ : fail++;
+}
+constw=Math.max(...rows.map((x)=>x[1].length));
+constout=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\""
  },