@mechasm/cli 0.0.0-stage → 0.1.1

package/src/cli.js

@@ -0,0 +1,581 @@
+#!/usr/bin/env node
+import { open, readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { Readable } from 'node:stream';
+import { createWriteStream } from 'node:fs';
+import { pipeline } from 'node:stream/promises';
+import { rm, stat } from 'node:fs/promises';
+import { setTimeout as delay } from 'node:timers/promises';
+import { randomUUID } from 'node:crypto';
+import { createCliClient, CliError, DEFAULT_API_URL } from './api-client.js';
+import { runServiceForeground, serviceStart, serviceStatus, serviceStop } from './service.js';
+import { clearLocalApproval, setLocalApproval } from './local-approvals.js';
+import { CLI_VERSION } from './version.js';
+import { runDoctor } from './diagnostics.js';
+import { notifyUpdate } from './notifier.js';
+
+const HELP = `Mechasm CLI
+
+Usage:
+  mechasm login [--api-url URL] [--device-name NAME] [--no-browser] [--json]
+  mechasm logout|whoami [--api-url URL] [--token-stdin] [--json]
+  mechasm projects list [--api-url URL] [--token-stdin] [--json]
+  mechasm projects create --name NAME --url URL [--team TEAM_ID] [--idempotency-key KEY] [options]
+  mechasm teams list [options]
+  mechasm variables list --project ID [options]
+  mechasm variables set KEY --project ID (--value-stdin|--value-file FILE) [options]
+  mechasm variables unset KEY --project ID [options]
+  mechasm tests create --project ID --name NAME [--prompt TEXT|--prompt-file FILE] [--tags LIST] [--wait] [--idempotency-key KEY] [--json]
+  mechasm tests edit --project ID TEST_ID [--prompt TEXT|--prompt-file FILE] [--name NAME] [--tags LIST] [--enabled true|false] [--wait] [--idempotency-key KEY] [--json]
+  mechasm tests list --project ID [--offset N] [--limit N] [--json]
+  mechasm tests get TEST_ID --project ID [--json]
+  mechasm tests run TEST_ID --project ID [--wait] [--idempotency-key KEY] [--json]
+  mechasm runs status|get|wait|logs|stop|video|trace|variables RUN_ID --project ID [--follow] [--after CURSOR] [--out FILE] [--json]
+  mechasm local register --project ID --url URL --ports LIST [options]
+  mechasm local list --project ID [options]
+  mechasm local select --project ID DEVICE_ID [options]
+  mechasm local ports set --project ID LIST [--url URL] [options]
+  mechasm local unregister --project ID [options]
+  mechasm service start|stop|status|foreground [options]
+  mechasm doctor [--api-url URL] [--token-stdin] [--json]
+  mechasm update [--json]
+  mechasm --version
+
+Options:
+  --api-url URL       API origin (HTTPS, or HTTP loopback for development)
+  --token-stdin       Read scoped API token from stdin
+  --project ID        Explicit project ID
+  --team ID           Approved team for project creation; optional when only one team is approved
+  --value-file FILE   Read a project variable value from a file
+  --value-stdin       Read a project variable value from stdin
+  --device-name NAME  Initial device name; editable during browser approval
+  --prompt TEXT       Test prompt
+  --prompt-file FILE  Read test prompt from file (use - for stdin)
+                      Use Markdown for headings, lists, and clear steps; plain text also works.
+  --name NAME         Project or test name
+  --tags LIST         Comma-separated test tags
+  --offset N          Test list offset (default 0)
+  --limit N           Test list page size (1 to 100, default 50)
+  --enabled BOOL      Enable or disable test
+  --idempotency-key KEY  Reuse key after an unknown mutation result
+  --url URL           Project or local app URL
+  --ports LIST        Comma-separated local ports
+  --wait              Wait for test generation or run completion; metadata-only operations return immediately
+  --follow            Follow run logs until it finishes
+  --after CURSOR      Resume run log history
+  --out FILE          Save video or trace to a new file
+  --json              JSON output on stdout; errors on stderr
+
+Commands that start a run return its workspace URL; plain output shows it as "View run".
+No command opens a local public listener. Project IDs are required for test and run operations.
+`;
+const RUNNER_MANAGED_VARIABLES = new Set(['CI_TOKEN', 'RUN_WS_TOKEN', 'WS_AUTH_COOKIE']);
+
+function parseArgs(argv) {
+  const parsed = { positionals: [], optionsSeen: new Set(), apiUrl: DEFAULT_API_URL, json: false, noBrowser: false, tokenStdin: false };
+  const values = new Set(['--api-url', '--device-name', '--project', '--team', '--prompt', '--prompt-file', '--name', '--tags', '--enabled', '--url', '--ports', '--out', '--after', '--offset', '--limit', '--idempotency-key', '--manifest-url', '--public-key-file', '--startup-guard-token', '--value-file']);
+  const flags = new Set(['--json', '--no-browser', '--token-stdin', '--wait', '--follow', '--value-stdin']);
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') parsed.help = true;
+    else if (flags.has(arg)) {
+      parsed.optionsSeen.add(arg);
+      parsed[arg.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase())] = true;
+    }
+    else if (values.has(arg)) {
+      parsed.optionsSeen.add(arg);
+      const value = argv[++i];
+      if (value === undefined || value.startsWith('--') || (value === '' && arg !== '--tags')) throw new CliError(`${arg} needs a value.`, 2);
+      parsed[arg.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase())] = value;
+    } else if (arg.startsWith('--')) throw new CliError(`Unknown option: ${arg}`, 2);
+    else parsed.positionals.push(arg);
+  }
+  return parsed;
+}
+
+function validateOptions(args, allowed) {
+  for (const option of args.optionsSeen) if (!allowed.has(option)) throw new CliError(`${option} does not apply to this command.`, 2);
+}
+
+async function stdinToken(enabled) {
+  if (!enabled) return undefined;
+  let value = '';
+  for await (const chunk of process.stdin) {
+    value += chunk;
+    if (Buffer.byteLength(value, 'utf8') > 4096) throw new CliError('Token input exceeds 4096 bytes.', 2);
+  }
+  return value.trim();
+}
+
+async function promptText(args) {
+  if (args.prompt !== undefined && args.promptFile !== undefined) throw new CliError('Use either --prompt or --prompt-file.', 2);
+  if (args.prompt !== undefined) return args.prompt.trim();
+  if (args.promptFile) return (args.promptFile === '-' ? await readStdinText() : await readFile(args.promptFile, 'utf8')).trim();
+  if (!process.stdin.isTTY) return (await readStdinText()).trim();
+  throw new CliError('Provide a prompt with --prompt, --prompt-file, or stdin.', 2);
+}
+
+function promptWillReadFromStdin(args, subcommand) {
+  if (args.prompt !== undefined || args.promptFile !== undefined || process.stdin.isTTY) return false;
+  return subcommand === 'create' ||
+    (subcommand === 'edit' && args.name === undefined && args.tags === undefined && args.enabled === undefined);
+}
+
+function parseTags(value) {
+  return value.split(',').map((tag) => tag.trim()).filter(Boolean);
+}
+
+function mutation(action, key) {
+  return (async () => {
+    let pause = 250;
+    const deadline = Date.now() + 30_000;
+    while (true) {
+      try { return await action(); }
+      catch (error) {
+        error.idempotencyKey = key;
+        if (error.apiCode !== 'operation_in_progress' || Date.now() >= deadline) throw error;
+        await delay(pause);
+        pause = Math.min(4000, pause * 2);
+      }
+    }
+  })();
+}
+
+async function readStdinText() {
+  let value = '';
+  for await (const chunk of process.stdin) {
+    value += chunk;
+    if (Buffer.byteLength(value, 'utf8') > 256 * 1024) throw new CliError('Prompt input exceeds 256 KiB.', 2);
+  }
+  return value;
+}
+
+async function variableValue(args) {
+  if (args.valueStdin === Boolean(args.valueFile)) throw new CliError('Pass exactly one of --value-stdin or --value-file.', 2);
+  if (args.valueStdin && args.tokenStdin) throw new CliError('Variable value and token cannot both use stdin; use --value-file with --token-stdin.', 2);
+  const value = args.valueStdin ? await readStdinText() : await readFile(args.valueFile, 'utf8');
+  if (Buffer.byteLength(value, 'utf8') > 64 * 1024) throw new CliError('Variable value exceeds 64 KiB.', 2);
+  if (!value.trim()) throw new CliError('Variable value cannot be empty; use variables unset to remove it.', 2);
+  return value;
+}
+
+function output(value, json) {
+  if (json) console.log(JSON.stringify(value));
+  else if (value?.runUrl || value?.run?.runUrl) {
+    if (value.run) {
+      const { runUrl, ...runDetails } = value.run;
+      console.log(JSON.stringify(runDetails, null, 2));
+    } else {
+      if (value.testId) console.log(`Test ID: ${value.testId}`);
+      if (value.runId) console.log(`Run ID: ${value.runId}`);
+    }
+    console.log(`View run: ${value.runUrl || value.run.runUrl}`);
+  }
+  else if (value?.user) {
+    const identity = [value.user.name, value.user.id].filter(Boolean).join(' / ');
+    console.log(`Signed in${identity ? ` as ${identity}` : ''}${value.deviceName ? ` (${value.deviceName})` : ''}.`);
+  }
+  else if (Array.isArray(value?.projects)) {
+    if (!value.projects.length) console.log('No projects available.');
+    else for (const project of value.projects) console.log(`${project.id}  ${project.name}  ${project.url}`);
+  } else if (Array.isArray(value?.tests)) {
+    if (!value.tests.length) console.log('No tests found.');
+    else for (const test of value.tests) console.log(`${test.id}  ${test.name || test.prompt || ''}  ${test.status || ''}`.trimEnd());
+  } else if (value?.project) console.log(`${value.project.id}  ${value.project.name}  ${value.project.url}`);
+  else if (value?.variable) console.log(value.variable.key);
+  else if (Array.isArray(value?.teams)) {
+    if (!value.teams.length) console.log('No teams available.');
+    else for (const team of value.teams) console.log(`${team.id}  ${team.name}  ${team.slug}`.trimEnd());
+  } else if (Array.isArray(value?.keys)) {
+    if (!value.keys.length) console.log('No variables set.');
+    else for (const key of value.keys) console.log(key);
+  } else if (value?.test) console.log(JSON.stringify(value.test, null, 2));
+  else if (value?.run) console.log(JSON.stringify(value.run, null, 2));
+  else if (value?.loggedOut) console.log('Logged out.');
+  else console.log(JSON.stringify(value, null, 2));
+}
+
+function projectId(args) {
+  if (!args.project) throw new CliError('Pass an explicit --project ID.', 2);
+  return args.project;
+}
+
+function localUrl(value) {
+  let url;
+  try { url = new URL(value); } catch { throw new CliError('--url must be a valid loopback URL.', 2); }
+  if (!['http:', 'https:'].includes(url.protocol) || !['localhost', '127.0.0.1', '::1', '[::1]'].includes(url.hostname.toLowerCase()) || url.username || url.password) {
+    throw new CliError('--url must use localhost, 127.0.0.1, or ::1 without credentials.', 2);
+  }
+  return url;
+}
+
+function localHost(url) {
+  return ['::1', '[::1]'].includes(url.hostname.toLowerCase()) ? '::1' : '127.0.0.1';
+}
+
+function localPorts(value, url) {
+  if (!value) throw new CliError('Pass --ports with a comma-separated port list.', 2);
+  const numbers = value.split(',').map((part) => {
+    if (!/^\d+$/.test(part.trim())) throw new CliError(`Invalid port: ${part}`, 2);
+    const port = Number(part);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) throw new CliError(`Port must be between 1 and 65535: ${part}`, 2);
+    return port;
+  });
+  const ports = [...new Set(numbers)];
+  const mainPort = Number(url.port || (url.protocol === 'https:' ? 443 : 80));
+  if (!ports.includes(mainPort)) throw new CliError(`Port list must include the URL port ${mainPort}.`, 2);
+  if (ports.length > 16) throw new CliError('A project can expose at most 16 local ports.', 2);
+  return ports;
+}
+
+function localServiceOnline(state) {
+  return Boolean(state.running && state.lastHeartbeatAt && !state.lastError && Date.now() - Date.parse(state.lastHeartbeatAt) < 60_000);
+}
+
+function commandId(value, label) {
+  if (!value) throw new CliError(`Pass ${label} ID.`, 2);
+  return value;
+}
+
+async function waitForRun(client, project, runId, json, token, logs = false, cursor = undefined) {
+  const controller = new AbortController();
+  const stop = () => controller.abort();
+  process.once('SIGINT', stop);
+  process.once('SIGTERM', stop);
+  let lastRun;
+  try {
+    while (!controller.signal.aborted) {
+      const page = await longPollLogs(client, project, runId, cursor, token, controller.signal);
+      for (const event of page?.events || []) {
+        if (logs) output(event, json);
+      }
+      cursor = page?.nextCursor ?? cursor;
+      if (page?.terminal && page?.hasMore === false) {
+        lastRun = (await client.getRun(project, runId, token)).run;
+        return lastRun;
+      }
+    }
+    throw new CliError(`Stopped waiting for run ${runId}.`, 130);
+  } catch (error) {
+    if (error.name === 'AbortError' && !logs) throw new CliError(`Stopped waiting for run ${runId}.`, 130);
+    if (error.name === 'AbortError') return;
+    throw error;
+  } finally {
+    process.off('SIGINT', stop);
+    process.off('SIGTERM', stop);
+    if (!json && !logs) process.stderr.write('\n');
+  }
+}
+
+async function followLogs(client, project, runId, args, token) {
+  let cursor = args.after;
+  const controller = new AbortController();
+  const stop = () => controller.abort();
+  process.once('SIGINT', stop);
+  process.once('SIGTERM', stop);
+  try {
+    while (!controller.signal.aborted) {
+      const page = await longPollLogs(client, project, runId, cursor, token, controller.signal);
+      for (const event of page?.events || []) {
+        if (args.json) console.log(JSON.stringify({ type: 'event', event }));
+        else output(event, false);
+      }
+      if (page?.nextCursor != null && page.nextCursor !== cursor) {
+        cursor = page.nextCursor;
+        if (args.json) console.log(JSON.stringify({ type: 'cursor', cursor }));
+      }
+      if (page?.terminal && page?.hasMore === false) return;
+    }
+    throw new CliError(`Stopped following run ${runId}.`, 130);
+  } catch (error) {
+    if (error.name === 'AbortError') throw new CliError(`Stopped following run ${runId}.`, 130);
+    throw error;
+  } finally {
+    process.off('SIGINT', stop);
+    process.off('SIGTERM', stop);
+  }
+}
+
+async function longPollLogs(client, project, runId, cursor, token, signal) {
+  let pause = 1000;
+  while (true) {
+    try { return await client.runLogs(project, runId, cursor, token, { wait: true, signal }); }
+    catch (error) {
+      if (signal.aborted || error.name === 'AbortError' || error.exitCode === 2 || error.exitCode === 3 || error.exitCode === 4) throw error;
+      await delay(pause, undefined, { signal });
+      pause = Math.min(pause * 2, 30_000);
+    }
+  }
+}
+
+async function saveArtifact(client, project, runId, kind, outputPath, token) {
+  const download = await client.downloadRunArtifact(project, runId, kind, token);
+  const safeId = String(runId).replace(/[^A-Za-z0-9_-]/g, '_');
+  const path = resolve(outputPath || `mechasm-${safeId}-${kind}.${kind === 'video' ? 'webm' : 'zip'}`);
+  const file = await open(path, 'wx', 0o600);
+  try {
+    if (!download.body) throw new CliError('Artifact response did not include a download stream.');
+    await pipeline(Readable.fromWeb(download.body), file.createWriteStream({ autoClose: true }));
+    const bytes = (await stat(path)).size;
+    await file.close().catch(() => {});
+    return { path, bytes, contentType: download.contentType };
+  } catch (error) {
+    await file.close().catch(() => {});
+    await rm(path, { force: true });
+    throw error;
+  }
+}
+
+function runFailed(run) {
+  return ['failed', 'error', 'stopped', 'cancelled', 'canceled'].includes(String(run?.status || '').toLowerCase());
+}
+
+export async function runCli() {
+try {
+  if (process.argv.slice(2).includes('--version') || process.argv.slice(2).includes('-V')) {
+    console.log(CLI_VERSION);
+    return;
+  }
+  const args = parseArgs(process.argv.slice(2));
+  const [command, subcommand, id, ...extra] = args.positionals;
+  if (args.help || command === 'help' || !command) {
+    process.stdout.write(HELP);
+    process.exitCode = !command && !args.help ? 2 : 0;
+  } else {
+    const portList = command === 'local' && subcommand === 'ports' && id === 'set' ? extra[0] : undefined;
+    if (extra.length > (portList === undefined ? 0 : 1)) throw new CliError('Unexpected extra arguments. Run `mechasm --help`.', 2);
+    if (args.tokenStdin && command === 'login') throw new CliError('--token-stdin applies to authenticated commands, not login.', 2);
+    const promptFromStdin = command === 'tests' && ['create', 'edit'].includes(subcommand) && promptWillReadFromStdin(args, subcommand);
+    if (args.tokenStdin && command === 'tests' && ['create', 'edit'].includes(subcommand) &&
+        (args.promptFile === '-' || promptFromStdin)) {
+      throw new CliError('Use --token-stdin with --prompt or --prompt-file FILE; stdin cannot supply both token and prompt.', 2);
+    }
+    if (args.deviceName && command !== 'login') throw new CliError('--device-name applies only to login.', 2);
+    if (args.noBrowser && command !== 'login') throw new CliError('--no-browser applies only to login.', 2);
+    if (args.startupGuardToken && (command !== 'service' || subcommand !== 'foreground')) throw new CliError('Startup guard token is internal to service startup.', 2);
+    const common = new Set(['--api-url', '--json']);
+    const authOptions = new Set([...common, '--token-stdin']);
+    const commandOptions = command === 'login'
+      ? new Set([...common, '--device-name', '--no-browser'])
+      : command === 'whoami' || command === 'logout'
+        ? authOptions
+        : command === 'projects'
+          ? new Set([...authOptions, ...(subcommand === 'create' ? ['--name', '--url', '--team', '--idempotency-key'] : [])])
+          : command === 'teams'
+            ? authOptions
+            : command === 'variables'
+              ? new Set([...authOptions, '--project', ...(subcommand === 'set' ? ['--value-stdin', '--value-file'] : [])])
+          : command === 'tests' && ['create', 'edit'].includes(subcommand)
+            ? new Set([...authOptions, '--project', '--prompt', '--prompt-file', '--name', '--tags', '--enabled', '--wait', '--idempotency-key'])
+          : command === 'tests'
+              ? new Set([...authOptions, '--project', ...(subcommand === 'run' ? ['--wait', '--idempotency-key'] : subcommand === 'list' ? ['--offset', '--limit'] : [])])
+              : command === 'runs' && subcommand === 'logs'
+                ? new Set([...authOptions, '--project', '--follow', '--after'])
+                : command === 'runs' && ['video', 'trace'].includes(subcommand)
+                  ? new Set([...authOptions, '--project', '--out'])
+                  : command === 'runs'
+                    ? new Set([...authOptions, '--project'])
+                    : command === 'local' && subcommand === 'register'
+                      ? new Set([...authOptions, '--project', '--url', '--ports'])
+                      : command === 'local' && subcommand === 'ports'
+                        ? new Set([...authOptions, '--project', '--url', '--ports'])
+                        : command === 'local'
+                          ? new Set([...authOptions, '--project'])
+                          : command === 'service'
+                            ? new Set([...common, ...(subcommand === 'foreground' ? ['--startup-guard-token'] : [])])
+                              : command === 'update'
+                              ? new Set(['--json'])
+                            : command === 'doctor'
+                              ? authOptions
+                            : common;
+    validateOptions(args, commandOptions);
+    const client = createCliClient(args.apiUrl);
+    if (command === 'login') {
+      const result = await client.login({ deviceName: args.deviceName, noBrowser: args.noBrowser, json: args.json });
+      if (args.json) output(result, true);
+    } else if (command === 'help') {
+      process.stdout.write(HELP);
+    } else {
+      const token = await stdinToken(args.tokenStdin);
+      if (command === 'update') {
+        if (subcommand) throw new CliError('Update configuration is no longer supported. Use npm to manage CLI upgrades.', 2);
+        output({ message: 'Upgrade with `npm install -g @mechasm/cli@latest`.' }, args.json);
+      }
+      else if (command === 'doctor') {
+        const result = await runDoctor(args.apiUrl, token);
+        output(result, args.json);
+        if (!result.ok) process.exitCode = 1;
+      }
+      else if (command === 'whoami') output((await client.whoami(token)).data, args.json);
+      else if (command === 'projects' && subcommand === 'list') output((await client.projects(token)).data, args.json);
+      else if (command === 'projects' && subcommand === 'create') {
+        if (!args.name?.trim() || args.name.trim().length > 120) throw new CliError('projects create needs --name (1 to 120 characters).', 2);
+        if (!args.url) throw new CliError('projects create needs --url.', 2);
+        let url;
+        try { url = new URL(args.url); } catch { throw new CliError('--url must be a valid HTTP or HTTPS URL.', 2); }
+        if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) throw new CliError('--url must be a valid HTTP or HTTPS URL without credentials.', 2);
+        const key = args.idempotencyKey || randomUUID();
+        if (!/^[A-Za-z0-9_-]{8,128}$/.test(key)) throw new CliError('--idempotency-key must be 8 to 128 safe characters.', 2);
+        const body = { name: args.name.trim(), url: url.toString() };
+        if (args.team) body.teamId = args.team;
+        const result = await mutation(() => client.createProject(body, token, key), key);
+        output(result, args.json);
+      }
+      else if (command === 'teams' && subcommand === 'list') output(await client.listTeams(token), args.json);
+      else if (command === 'variables') {
+        const project = projectId(args);
+        const key = id;
+        if (subcommand === 'list') {
+          const result = await client.projectVariables(project, token);
+          output({ keys: Array.isArray(result?.keys) ? result.keys.filter((item) => typeof item === 'string') : [] }, args.json);
+        }
+        else {
+          if (!key || key.length > 255 || key !== key.toUpperCase() || /\s/.test(key)) throw new CliError('Variable keys must be 1 to 255 characters, uppercase, and contain no whitespace.', 2);
+          if (RUNNER_MANAGED_VARIABLES.has(key)) throw new CliError('This variable is managed by the runner and cannot be changed.', 2);
+          const value = subcommand === 'set' ? await variableValue(args) : undefined;
+          try {
+            if (subcommand === 'set') {
+              await client.setProjectVariable(project, key, value, token);
+            } else if (subcommand === 'unset') await client.unsetProjectVariable(project, key, token);
+            else throw new CliError('Unknown variables command. Run `mechasm --help`.', 2);
+          } catch (error) {
+            if (error instanceof CliError && error.exitCode === 2) throw error;
+            const safe = new CliError(`Could not ${subcommand === 'unset' ? 'remove' : 'set'} project variable.`, error.exitCode || 1);
+            safe.apiCode = error.apiCode;
+            throw safe;
+          }
+          output({ variable: { key }, ...(subcommand === 'unset' ? { removed: true } : { saved: true }) }, args.json);
+        }
+      }
+      else if (command === 'logout') { await client.logout(token); output({ loggedOut: true }, args.json); }
+      else if (command === 'tests') {
+        const project = projectId(args);
+        let result;
+        if (subcommand === 'create') {
+          const prompt = await promptText(args);
+          if (!prompt) throw new CliError('Prompt cannot be empty.', 2);
+          if (!args.name?.trim()) throw new CliError('tests create needs --name.', 2);
+          const key = args.idempotencyKey || randomUUID();
+          if (!/^[A-Za-z0-9_-]{8,128}$/.test(key)) throw new CliError('--idempotency-key must be 8 to 128 safe characters.', 2);
+          const body = { prompt, name: args.name.trim() };
+          if (args.tags !== undefined) body.tags = parseTags(args.tags);
+          result = await mutation(() => client.createTest(project, body, token, key), key);
+        } else if (subcommand === 'edit') {
+          const testId = commandId(id, 'test');
+          const body = {};
+          if (args.prompt !== undefined || args.promptFile !== undefined || promptWillReadFromStdin(args, 'edit')) body.prompt = await promptText(args);
+          if (args.name) body.name = args.name;
+          if (args.tags !== undefined) body.tags = parseTags(args.tags);
+          if (args.enabled !== undefined) {
+            if (!['true', 'false'].includes(args.enabled)) throw new CliError('--enabled must be true or false.', 2);
+            body.enabled = args.enabled === 'true';
+          }
+          if (body.prompt !== undefined && !body.prompt.trim()) throw new CliError('Prompt cannot be empty.', 2);
+          if (!Object.keys(body).length) throw new CliError('Pass --prompt, --prompt-file, stdin, --name, --tags, or --enabled.', 2);
+          const key = args.idempotencyKey || randomUUID();
+          if (!/^[A-Za-z0-9_-]{8,128}$/.test(key)) throw new CliError('--idempotency-key must be 8 to 128 safe characters.', 2);
+          result = await mutation(() => client.editTest(project, testId, body, token, key), key);
+        } else if (subcommand === 'list') {
+          const offset = args.offset === undefined ? undefined : Number(args.offset);
+          const limit = args.limit === undefined ? undefined : Number(args.limit);
+          if (offset !== undefined && (!Number.isSafeInteger(offset) || offset < 0)) throw new CliError('--offset must be a non-negative integer.', 2);
+          if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 1 || limit > 100)) throw new CliError('--limit must be an integer from 1 to 100.', 2);
+          result = await client.listTests(project, token, { offset, limit });
+        }
+        else if (subcommand === 'get') result = await client.getTest(project, commandId(id, 'test'), token);
+        else if (subcommand === 'run') {
+          const key = args.idempotencyKey || randomUUID();
+          if (!/^[A-Za-z0-9_-]{8,128}$/.test(key)) throw new CliError('--idempotency-key must be 8 to 128 safe characters.', 2);
+          result = await mutation(() => client.runTest(project, commandId(id, 'test'), token, key), key);
+        }
+        else throw new CliError('Unknown tests command. Run `mechasm --help`.', 2);
+        if (args.wait) {
+          const runId = result.runId;
+          if (runId) {
+            const run = await waitForRun(client, project, runId, args.json, token);
+            result = { ...result, run };
+          } else if (subcommand !== 'edit') {
+            throw new CliError('This operation did not start a run to wait for.');
+          }
+        }
+        output(result, args.json);
+        if (runFailed(result?.run)) process.exitCode = 5;
+      } else if (command === 'runs') {
+        const project = projectId(args);
+        const runId = commandId(id, 'run');
+        let result;
+        if (subcommand === 'get' || subcommand === 'status') result = await client.getRun(project, runId, token);
+        else if (subcommand === 'wait') result = { run: await waitForRun(client, project, runId, args.json, token) };
+        else if (subcommand === 'logs') {
+          if (args.follow) await followLogs(client, project, runId, args, token);
+          else result = await client.runLogs(project, runId, args.after, token);
+        } else if (subcommand === 'stop') result = await client.stopRun(project, runId, token) ?? { stopped: true, runId };
+        else if (subcommand === 'variables') result = await client.runVariables(project, runId, token);
+        else if (subcommand === 'video' || subcommand === 'trace') result = await saveArtifact(client, project, runId, subcommand, args.out, token);
+        else throw new CliError('Unknown runs command. Run `mechasm --help`.', 2);
+        if (result !== undefined) {
+          output(result, args.json);
+          if (runFailed(result?.run)) process.exitCode = 5;
+        }
+      } else if (command === 'local') {
+        const project = projectId(args);
+        let result;
+        if (subcommand === 'register') {
+          if (!args.url) throw new CliError('local register needs --url.', 2);
+          const service = await serviceStatus();
+          if (!localServiceOnline(service)) throw new CliError('Start the local service and confirm it is connected before registering this runner.', 3);
+          if (service.apiUrl !== args.apiUrl) throw new CliError(`Local service uses ${service.apiUrl}; pass that origin with --api-url.`, 2);
+          const url = localUrl(args.url);
+          const ports = localPorts(args.ports, url);
+          const deviceId = (await client.whoami(token)).data.deviceId;
+          result = await client.registerLocal(project, url.toString(), ports, token);
+          await setLocalApproval(client.origin, project, deviceId, ports, localHost(url));
+        } else if (subcommand === 'list') result = await client.localDevices(project, token);
+        else if (subcommand === 'select') result = await client.selectLocalRunner(project, commandId(id, 'device'), token);
+        else if (subcommand === 'unregister') {
+          result = await client.unregisterLocal(project, token) ?? { unregistered: true, projectId: project };
+          await clearLocalApproval(client.origin, project);
+        }
+        else if (subcommand === 'ports' && id === 'set') {
+          const portsInput = args.ports || portList;
+          if (!portsInput) throw new CliError('local ports set needs a comma-separated port list.', 2);
+          const service = await serviceStatus();
+          if (!localServiceOnline(service)) throw new CliError('Start the local service and confirm it is connected before approving ports.', 3);
+          if (service.apiUrl !== args.apiUrl) throw new CliError(`Local service uses ${service.apiUrl}; pass that origin with --api-url.`, 2);
+          const identity = (await client.whoami(token)).data;
+          const saved = await client.localProject(project, token);
+          const selected = saved.selectedDeviceId ?? saved.localRunnerId;
+          if (!selected || selected !== identity.deviceId) throw new CliError('This CLI device is not the selected local runner for the project.', 4);
+          const url = localUrl(args.url || saved.url).toString();
+          const ports = localPorts(portsInput, new URL(url));
+          result = await client.registerLocal(project, url, ports, token);
+          await setLocalApproval(client.origin, project, identity.deviceId, ports, localHost(new URL(url)));
+        } else throw new CliError('Unknown local command. Run `mechasm --help`.', 2);
+        output(result, args.json);
+      } else if (command === 'service') {
+        if (['status', 'stop'].includes(subcommand) && args.tokenStdin) throw new CliError('Local service commands use saved credentials, not --token-stdin.', 2);
+        let result;
+        if (subcommand === 'start') {
+          result = await serviceStart(args.apiUrl);
+        }
+        else if (subcommand === 'status') result = await serviceStatus();
+        else if (subcommand === 'stop') result = await serviceStop();
+        else if (subcommand === 'foreground') await runServiceForeground(args.apiUrl, args.startupGuardToken);
+        else throw new CliError('Unknown service command. Run `mechasm --help`.', 2);
+        if (result !== undefined) output(result, args.json);
+      } else {
+        throw new CliError('Unknown command. Run `mechasm --help`.', 2);
+      }
+    }
+  }
+} catch (error) {
+  const code = error instanceof CliError ? error.exitCode : 1;
+  if (process.argv.includes('--json')) console.error(JSON.stringify({ error: error.message, exitCode: code, ...(error.idempotencyKey ? { idempotencyKey: error.idempotencyKey } : {}) }));
+  else console.error(`Error: ${error.message}${error.idempotencyKey ? `\nRetry with --idempotency-key ${error.idempotencyKey}.` : ''}`);
+  process.exitCode = code;
+}
+finally {
+  const argv = process.argv.slice(2);
+  if (!argv.includes('--version') && !argv.includes('-V') && !(argv[0] === 'service' && argv[1] === 'foreground')) void notifyUpdate();
+}
+}

package/src/diagnostics.js

@@ -0,0 +1,31 @@
+import { CLI_VERSION } from './version.js';
+import { createCliClient } from './api-client.js';
+import { serviceStatus } from './service.js';
+
+export async function runDoctor(apiUrl, stdinToken) {
+  const checks = [{ name: 'version', status: 'ok', detail: CLI_VERSION }];
+  const client = createCliClient(apiUrl);
+  try {
+    const response = await fetch(`${client.origin}/health`, { signal: AbortSignal.timeout(3000), redirect: 'error' });
+    checks.push({ name: 'api', status: response.ok ? 'ok' : 'fail', detail: response.ok ? 'reachable' : `HTTP ${response.status}` });
+  } catch {
+    checks.push({ name: 'api', status: 'fail', detail: 'unreachable' });
+  }
+  if (checks.find(({ name }) => name === 'api').status === 'ok') {
+    try {
+      await client.whoami(stdinToken, { timeoutMs: 3000 });
+      checks.push({ name: 'credentials', status: 'ok', detail: 'signed in' });
+    } catch (error) {
+      checks.push({ name: 'credentials', status: 'fail', detail: error.exitCode === 3 ? 'not signed in; run mechasm login' : 'could not verify; check API access and run mechasm login' });
+    }
+  } else {
+    checks.push({ name: 'credentials', status: 'info', detail: 'not checked because API is unreachable' });
+  }
+  try {
+    const state = await serviceStatus();
+    checks.push({ name: 'service', status: state.running ? (state.lastError ? 'fail' : 'ok') : 'info', detail: state.running ? (state.lastError ? 'running but not responding; run mechasm service status' : 'running') : 'stopped; run mechasm service start for local-app runs' });
+  } catch {
+    checks.push({ name: 'service', status: 'fail', detail: 'status unavailable' });
+  }
+  return { checks, ok: checks.every(({ status }) => status !== 'fail') };
+}