@caveman-ai/cloud 0.1.0-rc.32 → 0.1.0-rc.34

package/README.md

@@ -6,12 +6,14 @@ Every Caveman Cloud operation from the terminal, plus the Cloud MCP server.
 npx -y @caveman-ai/cloud@rc setup --project PROJECT_ID   # installs cvm, signs in, connects your coding agents
 ```
 
-`@rc` is the newest release; `latest` is still the 0.0.1 bootstrap. `npm i -g @caveman-ai/cloud@rc` installs cvm by itself.
+`@rc` is the newest release; npm's `latest` tag lags behind it, so install `@rc`. `npm i -g @caveman-ai/cloud@rc` installs cvm by itself. When cvm and the server speak different API versions, the error (and `cvm doctor`) prints the exact install command: the server's release when it reports one, else `@rc`.
 
 ```sh
 cvm login                 # browser sign-in; one sign-in for cvm and caveman
 cvm projects list
-cvm traces search --help
+cvm traces                # the verbs in one family
+cvm traces search --help  # the flags one verb takes
+cvm traces tail           # new traces as they arrive (Ctrl-C stops)
 cvm sql "SELECT model, count() FROM requests GROUP BY model"
 cvm tools list            # every operation this Cloud offers you
 cvm mcp                   # Cloud MCP server over stdio
@@ -20,9 +22,32 @@ cvm mcp                   # Cloud MCP server over stdio
 - **Sign-in.** `cvm login` signs in with the browser device flow: it prints a code and a link, opens the browser (`--no-browser` or `CAVE_NO_BROWSER=1` to skip) and waits for you to confirm. It stores the credential where `caveman login` does (the macOS Keychain, else `~/.caveman/credentials`), so either CLI's sign-in works for both; `cvm logout` signs both out. `--instance URL` (or `CAVE_API_URL`) signs in to a private install. In CI, set `CAVE_TOKEN` (and `CAVE_API_URL` for a private install).
 - **Environment.** A flag wins over the environment, and the environment over the saved login: `CAVE_API_URL`, `CAVE_PROJECT_ID`, `CAVE_TOKEN`. The saved credential is only ever sent to the address it was saved with; another `CAVE_API_URL` needs its own `CAVE_TOKEN`.
 - **Projects.** Use `--project UUID`, `CAVE_PROJECT_ID`, `cvm context bind` (writes `.caveman-cloud.json` in the repository) or the saved default.
-- **Output.** JSON when piped, readable when on a terminal; `--format json|jsonl|table`.
+- **Output.** JSON when piped, readable when on a terminal; `--format json|jsonl|table`. Help follows the same rule: `cvm`, `cvm <family>` and `cvm <family> <verb> --help` are screens on a terminal and JSON when piped, and a mistyped command names the nearest one.
 - **Exit codes.** 0 ok · 1 request failed · 2 usage or invalid input (HTTP 400/422) · 3 signed out or forbidden (401/403) · 4 conflict (409) · 5 a comparison or gate failed · 6 timeout, still running or not enough data · 7 rate limited (429).
 
+## Human Code lifecycle
+
+These fixed commands use the same saved human sign-in as `cvm login`. They do
+not expose credentials, allocate computers, or grant Code access to agent
+connections. Server authorization remains authoritative; an agent connection is
+still denied. No arbitrary HTTP paths, request bodies, or headers are accepted.
+
+```sh
+cvm human code computers
+cvm human code runtimes
+cvm human code workspace WORKSPACE_UUID
+cvm human code archive WORKSPACE_UUID --yes
+cvm human code --help
+```
+
+IDs must be canonical hyphenated UUIDs. Archive requires `--yes` (`-y`) even on
+a terminal: it terminates sessions and may delete the workspace's computer when
+no active workspace uses it. Without confirmation, no request (including login
+refresh) is made. These commands accept `--format json|jsonl|table`; `table`
+pretty-prints the lifecycle JSON. They use the built-in saved context and its
+normal environment overrides, not named operation profiles. Errors omit
+upstream response details to avoid disclosing credentials.
+
 ## Setup
 
 `cvm setup` connects your coding agents to Caveman Cloud. Each step is safe to run again, and running it again is how you repair a setup.

package/bin/ci.mjs

@@ -9,7 +9,7 @@ import {randomUUID} from 'node:crypto';
 import {join} from 'node:path';
 import {parseArgs} from 'node:util';
 import {setTimeout as delay} from 'node:timers/promises';
-import {CloudClient,CloudError,inertJSON,runCloudCLI} from '../dist/cloud-client.mjs';
+import {CloudClient,CloudError,inertJSON,runCloudCLI,versionConflictMessage} from '../dist/cloud-client.mjs';
 
 const MAX_REPORTS=20,MAX_REPORT_BYTES=10*1024*1024; // the finish route's own limits
 const say=line=>process.stderr.write(line+'\n');
@@ -29,7 +29,7 @@ export async function connect(host,project){
  client.request=async(...args)=>{try{return await request(...args);}catch(error){if(error?.code==='cave_operation_version_conflict')error.message=VERSION_CONFLICT;throw error;}};
  return client;
 }
-export const VERSION_CONFLICT='This cvm and the Caveman server speak different API versions. Upgrade cvm (npm install -g @caveman-ai/cloud@latest), or install the cvm version that matches a self-hosted server, then run the command again.';
+export const VERSION_CONFLICT=versionConflictMessage();
 function projectPath(client){
  if(!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(client.projectId??''))throw new CloudError('cave_project_required','Select a project with --project, CAVE_PROJECT_ID or cvm context bind.',2);
  return `/api/v1/projects/${client.projectId}`;

package/bin/cvm.mjs

@@ -14,6 +14,9 @@ import {parseArgs} from 'node:util';
 import {setTimeout as pause} from 'node:timers/promises';
 import {version,skillDirs,marker,installSkill} from './agents.mjs';
 
+// A reader that stops early (cvm tools list | head) closes the pipe: end
+// quietly, as Unix tools do, instead of an unhandled EPIPE stack trace.
+for(const stream of [process.stdout,process.stderr])stream.on('error',error=>{if(error.code!=='EPIPE')throw error;process.exit(process.exitCode??0);});
 const client=()=>import('../dist/cloud-client.mjs');
 const cavemanHome=process.env.CAVEMAN_HOME??join(homedir(),'.caveman');
 const credentialsPath=join(cavemanHome,'credentials');
@@ -192,6 +195,60 @@ async function setup(args){
  return run(args,{client,context,login,call,cvm:realpathSync(fileURLToPath(import.meta.url))});
 }
 
+// Fixed human lifecycle routes, deliberately outside the operation/MCP catalog.
+// The normal built-in context owns credentials; this command never exports them.
+async function humanCode(args){
+ const {CloudClient,CloudError,inertJSON}=await client();
+ const usage='cvm human code computers|runtimes|workspace ID|archive ID --yes [--format json|jsonl|table]';
+ const fail=(code,message,exit)=>new CloudError(code,message,exit);
+ let format=process.stdout.isTTY?'table':'json';
+ try{
+  let values,positionals;
+  try{({values,positionals}=parseArgs({args,strict:true,allowPositionals:true,options:{help:{type:'boolean',short:'h'},format:{type:'string'},yes:{type:'boolean',short:'y'}}}));}
+  catch{throw fail('cave_usage',`Use ${usage}.`,2);}
+  format=values.format??format;
+  if(!['json','jsonl','table'].includes(format))throw fail('cave_usage','Format must be json, jsonl, or table.',2);
+  const [family,verb,id]=positionals;
+  const write=value=>process.stdout.write(inertJSON(value,format==='table'?2:undefined)+'\n');
+  if(values.help||!positionals.length||positionals.length===1&&family==='code'){
+   write({usage,summary:'Human Code lifecycle. Uses your normal saved sign-in; agent connections remain forbidden. Archive terminates sessions and may delete an unused workspace computer. No computer allocation.'});return 0;
+  }
+  if(family!=='code'||!['computers','runtimes','workspace','archive'].includes(verb))throw fail('cave_usage',`Use ${usage}.`,2);
+  const needsID=verb==='workspace'||verb==='archive';
+  if(positionals.length!==(needsID?3:2)||needsID&&(id.length!==36||!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(id)))throw fail('cave_usage','Supply exactly one workspace UUID for workspace or archive; no ID for computers or runtimes.',2);
+  if(values.yes&&verb!=='archive')throw fail('cave_usage','--yes is only for archive.',2);
+  // Validate and confirm before even resolving context (which may refresh login).
+  if(verb==='archive'&&!values.yes)throw fail('cave_confirmation_required','Archiving terminates sessions and may delete the unused workspace computer. Repeat with --yes to confirm.',2);
+  const path=needsID?`/api/v1/code/workspaces/${encodeURIComponent(id)}${verb==='archive'?'/archive':''}`:`/api/v1/code/${verb}`;
+  try{
+   const api=new CloudClient(await context());
+   write(await api.request(path,verb==='archive'?{body:{}}:{}));return 0;
+  }catch(error){
+   // Do not print upstream bodies, messages, details, URLs or unknown errors:
+   // they can contain credentials or terminal controls. Preserve denial codes.
+   if(error.httpStatus){
+    const code=error.httpStatus===403&&error.code==='cave_agent_operation_forbidden'?'cave_agent_operation_forbidden':'cave_request_failed';
+    throw fail(code,`Code lifecycle request failed (HTTP ${error.httpStatus}).`,error.exitCode);
+   }
+   const safe={cave_auth_required:'Run cvm login.',cave_endpoint_invalid:'Cloud endpoint must be HTTPS or loopback HTTP without credentials, query or fragment.',cave_network_error:'Cloud request failed. Inspect workspace state before retrying archive.',cave_timeout:'Cloud request timed out. Inspect workspace state before retrying archive.',cave_invalid_response:'Cloud returned an invalid JSON response.',cave_result_too_large:'Cloud response exceeded the size limit.'};
+   throw fail(Object.hasOwn(safe,error.code)?error.code:'cave_failed',safe[error.code]??'Code lifecycle command failed.',error instanceof CloudError?error.exitCode:1);
+  }
+ }catch(error){
+  process.stdout.write(inertJSON({schema_version:1,ok:false,status:'failed',error:{code:error.code,message:error.message}},format==='table'?2:undefined)+'\n');return error.exitCode;
+ }
+}
+
+// What cvm answers before the client, for `cvm --help` and `cvm <family>`.
+const commands=[
+ {id:'setup',usage:'cvm setup [--project UUID] [--agent claude,codex,...] [--yes] [--no-launch] [--remove]',summary:'Connect your coding agents: sign-in, project, skill and MCP server.'},
+ {id:'login',usage:'cvm login [--instance URL] [--no-browser]',summary:'Sign in with the browser.'},
+ {id:'logout',usage:'cvm logout',summary:'Sign out and revoke this device.'},
+ {id:'mcp',usage:'cvm mcp',summary:'Serve the Cloud MCP server over stdio.'},
+ {id:'human.code',usage:'cvm human code computers|runtimes|workspace ID|archive ID --yes',summary:'Human Code lifecycle using your normal saved sign-in; no agent access.'},
+ {id:'evals.init',usage:'cvm evals init [PATH]',summary:'Write a starter eval file (example.eval.json).'},
+ {id:'evals.ci',usage:'cvm evals ci FILE... | cvm evals ci [--suite NAME] -- TEST_COMMAND',summary:'Gate a pull request on eval files or a CI test run.'},
+ {id:'evals.watch',usage:'cvm evals watch RUN_ID',summary:'Follow one run until it settles.'},
+];
 const argv=process.argv.slice(2);
 // What only the operation form of `evals validate` and `evals run` takes.
 // A bare id is the experiment to run, unless it is the value of --project.
@@ -214,6 +271,8 @@ if(argv[0]==='--version'||argv[0]==='-v'){
   process.stdout.write(JSON.stringify({schema_version:1,ok:false,status:'failed',error:{code:error.exitCode?error.code:'cave_failed',message:error.message}})+'\n');
   process.exitCode=exit;
  }
+}else if(argv[0]==='human'&&argv[1]==='code'){
+ process.exitCode=await humanCode(argv.slice(1));
 }else if(argv[0]==='mcp'&&argv.length===1){
  const {serveCloudMCP}=await import('../dist/cloud-mcp.mjs');
  // A launcher may narrow the server to the operations one task needs.
@@ -229,5 +288,5 @@ if(argv[0]==='--version'||argv[0]==='-v'){
  process.exitCode=await (argv[1]==='ci'?evalsCI:evalsWatch)(argv.slice(2),{context,login:loginCommand});
 }else{
  const {runCloudCLI}=await client();
- process.exitCode=await runCloudCLI(argv,{context,login:loginCommand});
+ process.exitCode=await runCloudCLI(argv,{context,login:loginCommand,commands});
 }