@caveman-ai/cloud 0.1.0-rc.30 → 0.1.0-rc.33

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,7 +22,7 @@ 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).
 
 ## 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,16 @@ async function setup(args){
  return run(args,{client,context,login,call,cvm:realpathSync(fileURLToPath(import.meta.url))});
 }
 
+// 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:'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.
@@ -229,5 +242,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});
 }