@emptyos/client 0.1.0

package/lib/cli.js

@@ -0,0 +1,985 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { CLIENT_VERSION, ID_PATTERN, PROTOCOL_VERSION } from './constants.js';
+import {
+  readConfig,
+  selectComputer,
+  validateAlias,
+  validateReleaseCatalog,
+  validateTarget,
+  writeConfig,
+} from './config.js';
+import { ClientError, UsageError } from './errors.js';
+import { gitCaptured, gitInherited } from './git.js';
+import {
+  cleanPutStage,
+  derivedThingId,
+  inspectGeneratedSource,
+  inspectManifestedSource,
+  stageGeneratedThing,
+} from './thing-put.js';
+import { readThingId } from './manifest.js';
+import { runCaptured, runInherited } from './process.js';
+import { rawSsh, rpcCaptured, rpcFileCaptured, rpcFileInherited, rpcInherited } from './rpc.js';
+import { commandHelpText, commandInventory, helpResponse, isKnownCommandFamily, topHelpText } from './commands.js';
+import { humanCatalogSpec, parseCatalogJson } from './catalog-output.js';
+import { updateComputer, validateCatalogUrl } from './platform-update.js';
+import { runTunnelProxy } from './tunnel-proxy.js';
+import { defaultSkillsDir, installSkill } from './skill-install.js';
+import { deriveComputerAlias, pairComputer, validateOwnerOrigin } from './pairing.js';
+import { koanLines, withKoan } from './koans.js';
+
+export async function main(rawArgv, {
+  env = process.env,
+  stdin = process.stdin,
+  stdout = process.stdout,
+  stderr = process.stderr,
+  pairComputerImpl = pairComputer,
+} = {}) {
+  let json = false;
+  try {
+    if (rawArgv[0] === '__ssh-tunnel') {
+      if (rawArgv.length !== 3) throw new ClientError('Internal SSH tunnel helper received invalid arguments');
+      return await runTunnelProxy(rawArgv[1], rawArgv[2], { stdin, stdout });
+    }
+    const parsed = parseGlobalOptions(rawArgv);
+    const argv = parsed.argv;
+    const separator = argv.indexOf('--');
+    json = argv.slice(0, separator === -1 ? argv.length : separator).includes('--json');
+
+    if (argv.length === 1 && argv[0] === '--version') {
+      stdout.write(`empty client ${CLIENT_VERSION} (protocol ${PROTOCOL_VERSION})\n`);
+      return 0;
+    }
+    if (argv.length === 0) {
+      stdout.write(withKoan(helpResponse(['--help']).text, { env, stdout }));
+      return 0;
+    }
+    const help = helpResponse(argv);
+    if (help) {
+      if (help.error) stderr.write(`empty: ${help.error}\n${help.text}`);
+      else stdout.write(help.top ? withKoan(help.text, { env, stdout }) : help.text);
+      return help.code;
+    }
+
+    if (argv[0] === 'connect') {
+      return await commandConnect(argv.slice(1), parsed.computer, { env, stdout, pairComputerImpl });
+    }
+    if (argv[0] === 'computers') {
+      return commandComputers(argv.slice(1), parsed.computer, { env, stdout });
+    }
+    if (argv[0] === 'computer') {
+      return await commandComputer(argv.slice(1), parsed.computer, { env, stdout, stderr, pairComputerImpl });
+    }
+    if (argv[0] === 'skill') return commandSkill(argv.slice(1), parsed.computer, { env, stdout });
+    if (argv[0] === 'ssh') return await commandSsh(argv.slice(1), parsed.computer, { env });
+    if (argv[0] === 'put') return await commandPut(argv.slice(1), parsed.computer, { env, stdout, stderr });
+    if (argv[0] === 'clone') return await commandClone(argv.slice(1), parsed.computer, { env, stdout, stderr });
+    if (argv[0] === 'commands') return await commandCommands(argv.slice(1), parsed.computer, { env, stdout, stderr });
+    if (argv[0] === 'thing' && argv[1] === 'add') {
+      throw new ClientError(
+        '`thing add` takes a path already on the computer and is unavailable from a workstation; use `empty put <local-path>` instead',
+        'resident-only-command',
+      );
+    }
+    const selected = selectComputer(readConfig(env), parsed.computer);
+    const catalog = humanCatalogSpec(argv);
+    if (catalog) return await commandHumanCatalog(selected, argv, catalog, { env, stdout, stderr });
+    if (isKnownCommandFamily(argv[0])) return await rpcInherited(selected, argv, env);
+    return await forwardExtensionCommand(selected, argv, env);
+  } catch (error) {
+    const message = error?.message || String(error);
+    if (json) stdout.write(`${JSON.stringify({ error: message, ...(typeof error?.code === 'string' ? { code: error.code } : {}) })}\n`);
+    else {
+      stderr.write(`empty: ${message}\n`);
+      const help = error instanceof UsageError ? (error.command ? commandHelpText(error.command) : topHelpText()) : null;
+      if (help) stderr.write(`\n${help}`);
+    }
+    return 1;
+  }
+}
+
+function parseGlobalOptions(rawArgv) {
+  const argv = [];
+  let computer;
+  let optionsEnded = false;
+  for (let i = 0; i < rawArgv.length; i += 1) {
+    const arg = rawArgv[i];
+    if (arg === '--') {
+      optionsEnded = true;
+      argv.push(...rawArgv.slice(i));
+      break;
+    }
+    if (!optionsEnded && arg === '--computer') {
+      if (computer !== undefined) throw new ClientError('--computer may only be specified once');
+      computer = validateAlias(rawArgv[i + 1]);
+      i += 1;
+      continue;
+    }
+    if (!optionsEnded && arg.startsWith('--computer=')) {
+      if (computer !== undefined) throw new ClientError('--computer may only be specified once');
+      computer = validateAlias(arg.slice('--computer='.length));
+      continue;
+    }
+    argv.push(arg);
+  }
+  return { argv, computer };
+}
+
+async function commandComputer(args, explicitComputer, context) {
+  const [subcommand, ...rest] = args;
+  if (explicitComputer && ['add', 'use', 'remove'].includes(subcommand)) {
+    throw new UsageError(`--computer cannot be used with local profile command \`computer ${subcommand}\``, `computer ${subcommand}`);
+  }
+  if (subcommand === 'add') return computerAdd(rest, context);
+  if (subcommand === 'use') return computerUse(rest, context);
+  if (subcommand === 'show') return computerShow(rest, explicitComputer, context);
+  if (subcommand === 'update') return computerUpdate(rest, explicitComputer, context);
+  if (subcommand === 'remove') return computerRemove(rest, context);
+  throw new UsageError(`Unknown computer command "${subcommand ?? ''}"`, 'computer');
+}
+
+function commandSkill(args, explicitComputer, { env, stdout }) {
+  const [subcommand, ...rest] = args;
+  if (subcommand !== 'install') throw new UsageError(`Unknown skill command "${subcommand ?? ''}"`, 'skill install');
+  if (explicitComputer) {
+    throw new UsageError('--computer cannot be used with local command `skill install`', 'skill install');
+  }
+  const json = takeJson(rest);
+  let dir;
+  for (let index = 0; index < json.args.length; index += 1) {
+    const option = json.args[index];
+    if (option === '--dir') {
+      if (dir !== undefined) throw new UsageError('--dir may only be specified once', 'skill install');
+      dir = json.args[++index];
+      if (!dir || dir.startsWith('--')) throw new UsageError('--dir needs a <path>', 'skill install');
+    } else {
+      throw new UsageError(`Unknown skill install option ${JSON.stringify(option)}`, 'skill install');
+    }
+  }
+  const installed = installSkill(dir ?? defaultSkillsDir(env));
+  if (json.enabled) stdout.write(`${JSON.stringify({ installed })}\n`);
+  else stdout.write(`Installed skill to ${installed}\n`);
+  return 0;
+}
+
+async function commandConnect(args, explicitComputer, { env, stdout, pairComputerImpl }) {
+  if (explicitComputer) {
+    throw new UsageError('--computer cannot be used with local command `connect`', 'connect');
+  }
+  const [ownerOrigin, ...options] = args;
+  if (!ownerOrigin || ownerOrigin.startsWith('--')) {
+    throw new UsageError('`connect` needs a <computer-url>', 'connect');
+  }
+  let alias;
+  let label;
+  let browser = true;
+  for (let index = 0; index < options.length; index += 1) {
+    const option = options[index];
+    if (option === '--as') {
+      if (alias !== undefined) throw new UsageError('--as may only be specified once', 'connect');
+      alias = options[++index];
+      if (!alias || alias.startsWith('--')) throw new UsageError('--as needs an alias', 'connect');
+      validateAlias(alias);
+    } else if (option === '--label') {
+      if (label !== undefined) throw new UsageError('--label may only be specified once', 'connect');
+      label = options[++index];
+      if (!label || label.startsWith('--')) throw new UsageError('--label needs a value', 'connect');
+    } else if (option === '--no-browser') {
+      if (!browser) throw new UsageError('--no-browser may only be specified once', 'connect');
+      browser = false;
+    } else {
+      throw new UsageError(`Unknown connect option ${JSON.stringify(option)}`, 'connect');
+    }
+  }
+  const origin = validateOwnerOrigin(ownerOrigin);
+  await pairComputerImpl({
+    alias: alias ?? deriveComputerAlias(origin),
+    ownerOrigin: origin,
+    label,
+    browser,
+  }, { env, stdout });
+  return 0;
+}
+
+async function computerAdd(args, { env, stdout, stderr }) {
+  const json = takeJson(args);
+  const [alias, ...options] = json.args;
+  let target;
+  let releaseCatalog;
+  for (let index = 0; index < options.length; index += 1) {
+    const option = options[index];
+    if (option === '--host' && target === undefined) {
+      target = options[++index];
+      if (!target) throw new UsageError('--host needs a host', 'computer add');
+    }
+    else if (option === '--release-catalog' && releaseCatalog === undefined) {
+      releaseCatalog = options[++index];
+      if (!releaseCatalog) throw new UsageError('--release-catalog needs an HTTPS URL', 'computer add');
+    } else throw new UsageError(`Unknown computer add option ${JSON.stringify(option)}`, 'computer add');
+  }
+  if (!alias || !target) {
+    throw new UsageError('`computer add` needs an <alias> and --host <host>', 'computer add');
+  }
+  validateAlias(alias);
+  validateTarget(target);
+  if (releaseCatalog !== undefined) releaseCatalog = validateReleaseCatalog(releaseCatalog);
+  const config = readConfig(env);
+  if (config.computers[alias]) throw new ClientError(`Computer "${alias}" is already configured`);
+
+  const check = await rpcCaptured(target, ['--version', '--json'], env);
+  if (check.code !== 0) {
+    stdout.write(check.stdout);
+    stderr.write(check.stderr);
+    if (check.transportHint) stderr.write(check.transportHint);
+    return check.code;
+  }
+  const version = parseComputerVersion(check.stdout, alias);
+
+  config.computers[alias] = { target, ...(releaseCatalog ? { releaseCatalog } : {}) };
+  writeConfig(config, env);
+  if (json.enabled) stdout.write(`${JSON.stringify({ alias, target, protocolVersion: version.protocolVersion, ...(releaseCatalog ? { releaseCatalog } : {}) })}\n`);
+  else {
+    stdout.write(config.defaultComputer
+      ? `Added computer ${alias} (${target}); the default computer remains ${config.defaultComputer}\nSwitch with \`empty computer use ${alias}\`\n`
+      : `Added computer ${alias} (${target}); no default computer is selected\nSelect it with \`empty computer use ${alias}\`\n`);
+  }
+  return 0;
+}
+
+function commandComputers(args, explicitComputer, { env, stdout }) {
+  if (explicitComputer) {
+    throw new UsageError('--computer cannot be used with local profile command `computers`', 'computers');
+  }
+  const json = takeJson(args);
+  if (json.args.length) throw new UsageError('`computers` takes no arguments', 'computers');
+  const config = readConfig(env);
+  const entries = Object.entries(config.computers).sort(([a], [b]) => a.localeCompare(b));
+  const computers = entries
+    .map(([alias, profile]) => ({ alias, target: profile.target, default: alias === config.defaultComputer }));
+  if (json.enabled) stdout.write(`${JSON.stringify({ defaultComputer: config.defaultComputer, computers })}\n`);
+  else if (computers.length === 0) {
+    stdout.write([
+      'No computers configured',
+      ...koanLines({ env, stdout }),
+      '',
+      'Connect through EmptyOS:',
+      '  empty connect <computer-url> [--as <alias>]',
+      '',
+      'Or add a direct SSH host:',
+      '  empty computer add <alias> --host <host>',
+      '',
+    ].join('\n'));
+  }
+  else {
+    const width = Math.max(...entries.map(([alias]) => alias.length));
+    for (const [alias, profile] of entries) {
+      const marker = alias === config.defaultComputer ? '  (default)' : '';
+      stdout.write(`${alias.padEnd(width)}  ${computerDisplayTarget(profile)}${marker}\n`);
+    }
+    if (config.defaultComputer === null) stdout.write('\nNo default computer is selected; choose one with `empty computer use <alias>`\n');
+    stdout.write('\nConnect another computer with `empty connect <computer-url>`\n');
+  }
+  return 0;
+}
+
+function computerUse(args, { env, stdout }) {
+  const json = takeJson(args);
+  if (json.args.length !== 1) throw new UsageError('`computer use` needs an <alias>', 'computer use');
+  const alias = validateAlias(json.args[0]);
+  const config = readConfig(env);
+  if (!config.computers[alias]) throw new ClientError(`Computer "${alias}" is not configured`);
+  config.defaultComputer = alias;
+  writeConfig(config, env);
+  if (json.enabled) stdout.write(`${JSON.stringify({ defaultComputer: alias })}\n`);
+  else stdout.write(`Default computer is now ${alias}\n`);
+  return 0;
+}
+
+function computerShow(args, explicitComputer, { env, stdout }) {
+  const json = takeJson(args);
+  if (json.args.length) throw new UsageError('`computer show` takes no arguments', 'computer show');
+  const selected = selectComputer(readConfig(env), explicitComputer);
+  const result = {
+    alias: selected.alias,
+    target: selected.target,
+    source: selected.source,
+    transport: selected.ownerOrigin ? 'emptyos-ssh-tunnel' : 'ssh',
+    ...(selected.releaseCatalog ? { releaseCatalog: selected.releaseCatalog } : {}),
+  };
+  if (json.enabled) stdout.write(`${JSON.stringify(result)}\n`);
+  else stdout.write(`${result.alias}  ${computerDisplayTarget(selected)}  (${result.source})\n`);
+  return 0;
+}
+
+function computerDisplayTarget(profile) {
+  return profile.ownerOrigin ? new URL(profile.ownerOrigin).hostname : profile.target;
+}
+
+async function computerUpdate(args, explicitComputer, context) {
+  const json = takeJson(args);
+  let check = false;
+  let apply = false;
+  let release;
+  let catalog;
+  let resume;
+  for (let index = 0; index < json.args.length; index += 1) {
+    const option = json.args[index];
+    if (option === '--check') {
+      if (check) throw new UsageError('--check may only be specified once', 'computer update');
+      check = true;
+    } else if (option === '--apply') {
+      if (apply) throw new UsageError('--apply may only be specified once', 'computer update');
+      apply = true;
+    } else if (option === '--release') {
+      if (release !== undefined) throw new UsageError('--release may only be specified once', 'computer update');
+      release = json.args[++index];
+      if (!release) throw new UsageError('--release needs a local artifact path', 'computer update');
+    } else if (option === '--catalog') {
+      if (catalog !== undefined) throw new UsageError('--catalog may only be specified once', 'computer update');
+      catalog = json.args[++index];
+      if (!catalog) throw new UsageError('--catalog needs an HTTPS URL', 'computer update');
+      catalog = validateCatalogUrl(catalog);
+    } else if (option === '--resume') {
+      if (resume !== undefined) throw new UsageError('--resume may only be specified once', 'computer update');
+      resume = json.args[++index];
+      if (!resume) throw new UsageError('--resume needs a retained stage name', 'computer update');
+      if (!/^stage\.[A-Za-z0-9]{1,64}$/.test(resume)) {
+        throw new UsageError('--resume needs a stage name printed by computer update', 'computer update');
+      }
+    } else {
+      throw new UsageError(`Unknown computer update option ${JSON.stringify(option)}`, 'computer update');
+    }
+  }
+  if (check && apply) throw new UsageError('--check and --apply cannot be combined', 'computer update');
+  if (release && catalog) throw new UsageError('--release and --catalog cannot be combined', 'computer update');
+  if (resume && (check || apply || release || catalog)) {
+    throw new UsageError('--resume cannot be combined with check, apply, release, or catalog options', 'computer update');
+  }
+  const selected = selectComputer(readConfig(context.env), explicitComputer);
+  return updateComputer(selected, { check, release, catalog, resume, json: json.enabled }, context);
+}
+
+function computerRemove(args, { env, stdout }) {
+  const json = takeJson(args);
+  if (json.args.length !== 1) throw new UsageError('`computer remove` needs an <alias>', 'computer remove');
+  const alias = validateAlias(json.args[0]);
+  const config = readConfig(env);
+  if (!config.computers[alias]) throw new ClientError(`Computer "${alias}" is not configured`);
+  delete config.computers[alias];
+  if (config.defaultComputer === alias) config.defaultComputer = null;
+  writeConfig(config, env);
+  if (json.enabled) stdout.write(`${JSON.stringify({ removed: alias })}\n`);
+  else stdout.write(`Removed computer ${alias}\n`);
+  return 0;
+}
+
+function commandSsh(args, explicitComputer, { env }) {
+  const config = readConfig(env);
+  const selected = selectComputer(config, explicitComputer);
+  if (args.length > 0 && args[0] !== '--') throw new UsageError('Remote command arguments must follow `empty ssh --`', 'ssh');
+  return rawSsh(selected, args[0] === '--' ? args.slice(1) : [], env);
+}
+
+function parseComputerVersion(output, alias) {
+  let version;
+  try {
+    version = JSON.parse(output);
+  } catch {
+    throw new ClientError(`Computer "${alias}" returned an invalid protocol response; check SSH routing and retry`, 'protocol-error');
+  }
+  if (version.product !== 'EmptyOS' || version.component !== 'computer-cli' || typeof version.version !== 'string') {
+    throw new ClientError(`Computer "${alias}" did not identify itself as an EmptyOS computer CLI; check the configured host`, 'protocol-error');
+  }
+  if (version.protocolVersion !== PROTOCOL_VERSION) {
+    throw new ClientError(
+      `Computer "${alias}" uses protocol ${JSON.stringify(version.protocolVersion)}; client requires ${PROTOCOL_VERSION}; update the client and computer together`,
+      'protocol-error',
+    );
+  }
+  return version;
+}
+
+async function commandPut(args, explicitComputer, { env, stdout, stderr }) {
+  const options = parsePut(args);
+  const source = path.resolve(options.source);
+  const bound = await findBoundCheckout(source, env);
+  if (bound) {
+    if (options.as !== null || options.name !== null || options.projectId !== null || options.public) {
+      throw new UsageError('Metadata options are only valid for an initial put, not a bound Thing checkout', 'put');
+    }
+    return commandPublish(bound, explicitComputer, options.json, { env, stdout, stderr });
+  }
+
+  const sourceInfo = inspectGeneratedSource(source);
+  const manifested = sourceInfo.kind === 'manifested-thing' ? await inspectManifestedSource(source, env) : null;
+  if (manifested) sourceInfo.manifested = manifested;
+  const inferredId = manifested?.id ?? derivedThingId(source, sourceInfo.kind);
+  if (options.as !== null && manifested && options.as !== manifested.id) {
+    throw new ClientError(
+      `--as ${JSON.stringify(options.as)} does not match thing.yaml id ${JSON.stringify(manifested.id)}; update thing.yaml or remove --as`,
+      'manifest-assertion-failed',
+    );
+  }
+  if (options.name !== null && manifested && options.name !== manifested.name) {
+    throw new ClientError(
+      `--name ${JSON.stringify(options.name)} does not match thing.yaml name ${JSON.stringify(manifested.name)}; update thing.yaml or remove --name`,
+      'manifest-assertion-failed',
+    );
+  }
+  if (options.projectId !== null && manifested && options.projectId !== manifested.project) {
+    throw new ClientError(
+      `--project ${JSON.stringify(options.projectId)} does not match thing.yaml project ${JSON.stringify(manifested.project)}; update thing.yaml or remove --project`,
+      'manifest-assertion-failed',
+    );
+  }
+  if (manifested?.type === 'service' && (options.public || manifested.visibility === 'public')) {
+    throw new ClientError(
+      'Public service Things are not supported; keep visibility private and retry without --public',
+      'unsupported-public-service',
+    );
+  }
+  if (options.public && manifested && manifested.visibility !== 'public') {
+    throw new ClientError(
+      '--public does not match the private manifested Thing; set visibility: public in thing.yaml or remove --public',
+      'manifest-assertion-failed',
+    );
+  }
+  const id = options.as ?? inferredId;
+  if (!ID_PATTERN.test(id)) {
+    throw new ClientError(
+      `Derived Thing id ${JSON.stringify(id)} does not match [a-z0-9-]+; choose one with --as <id>`,
+      'invalid-generated-id',
+    );
+  }
+  const name = options.name ?? id;
+  const selected = selectComputer(readConfig(env), explicitComputer);
+  const capabilityFailure = await requireComputerCapability(
+    selected,
+    'thingImport',
+    1,
+    'put',
+    { env, stdout, stderr, json: options.json },
+  );
+  if (capabilityFailure !== null) return capabilityFailure;
+
+  const staged = await stageGeneratedThing(sourceInfo, id, name, {
+    env,
+    projectId: options.projectId,
+    visibility: options.public ? 'public' : 'private',
+  });
+  try {
+    const remoteArgs = [
+      'thing', 'import', id,
+      '--expected-head', staged.head,
+      '--source-kind', staged.sourceKind,
+      '--file-count', String(staged.fileCount),
+      '--byte-count', String(staged.byteCount),
+    ];
+    if (sourceInfo.kind === 'manifested-thing') {
+      if (options.name !== null) remoteArgs.push('--assert-name', options.name);
+      if (options.projectId !== null) remoteArgs.push('--assert-project', options.projectId);
+      if (options.public) remoteArgs.push('--assert-public');
+    }
+    if (options.json) remoteArgs.push('--json');
+    if (!options.json) return await rpcFileInherited(selected, remoteArgs, staged.bundle, env);
+    const result = await rpcFileCaptured(selected, remoteArgs, staged.bundle, env);
+    return relayRemoteResult(result, true, { stdout, stderr }, 'Thing upload failed');
+  } finally {
+    cleanPutStage(staged.stage);
+  }
+}
+
+function parsePut(args) {
+  const json = takeJson(args);
+  let source = null;
+  let as = null;
+  let name = null;
+  let projectId = null;
+  let publicValue = false;
+  let optionsEnded = false;
+  for (let index = 0; index < json.args.length; index += 1) {
+    const argument = json.args[index];
+    if (!optionsEnded && argument === '--') {
+      optionsEnded = true;
+    } else if (!optionsEnded && argument === '--public') {
+      if (publicValue) throw new UsageError('--public may only be specified once', 'put');
+      publicValue = true;
+    } else if (!optionsEnded && ['--as', '--name', '--project'].includes(argument)) {
+      const field = argument === '--as' ? 'as' : argument === '--name' ? 'name' : 'projectId';
+      const current = field === 'as' ? as : field === 'name' ? name : projectId;
+      if (current !== null) throw new UsageError(`${argument} may only be specified once`, 'put');
+      const value = json.args[++index];
+      if (!value) throw new UsageError(`${argument} needs a value`, 'put');
+      if (field === 'as') as = value;
+      else if (field === 'name') name = value;
+      else projectId = value;
+    } else if (!optionsEnded && ['--as=', '--name=', '--project='].some((prefix) => argument.startsWith(prefix))) {
+      const [flag, value] = argument.split(/=(.*)/s, 2);
+      if (!value) throw new UsageError(`${flag} needs a value`, 'put');
+      if (flag === '--as') {
+        if (as !== null) throw new UsageError('--as may only be specified once', 'put');
+        as = value;
+      } else if (flag === '--name') {
+        if (name !== null) throw new UsageError('--name may only be specified once', 'put');
+        name = value;
+      } else {
+        if (projectId !== null) throw new UsageError('--project may only be specified once', 'put');
+        projectId = value;
+      }
+    } else if (!optionsEnded && argument.startsWith('--')) {
+      throw new UsageError(`Unknown put option ${JSON.stringify(argument)}`, 'put');
+    } else if (source === null) {
+      source = argument;
+    } else {
+      throw new UsageError('`put` takes exactly one <path>', 'put');
+    }
+  }
+  if (source === null) throw new UsageError('`put` needs a <path>', 'put');
+  if (as !== null && !ID_PATTERN.test(as)) throw new UsageError('Thing id must match [a-z0-9-]+', 'put');
+  if (projectId !== null && !ID_PATTERN.test(projectId)) throw new UsageError('Project id must match [a-z0-9-]+', 'put');
+  return { source, as, name, projectId, public: publicValue, json: json.enabled };
+}
+
+async function findBoundCheckout(source, env) {
+  let stat;
+  try {
+    stat = fs.lstatSync(source);
+  } catch {
+    return null;
+  }
+  const cwd = stat.isDirectory() ? source : path.dirname(source);
+  const rootResult = await capturedGit(['rev-parse', '--show-toplevel'], { cwd, env }, 'Cannot inspect the source repository');
+  if (rootResult.code !== 0) return null;
+  const root = rootResult.stdout.trim();
+  if (fs.realpathSync(root) !== fs.realpathSync(source)) return null;
+  for (const key of ['emptyos.computer', 'emptyos.profileTarget', 'emptyos.target']) {
+    const result = await capturedGit(['config', '--local', '--get', key], { cwd: root, env }, `Cannot inspect ${key} binding`);
+    if (result.code !== 0 || !result.stdout.trim()) return null;
+  }
+  return root;
+}
+
+async function requireComputerCapability(selected, capability, minimum, feature, { env, stdout, stderr, json = false }) {
+  const check = await rpcCaptured(selected, ['--version', '--json'], env);
+  if (check.code !== 0) {
+    return relayRemoteResult(check, json, { stdout, stderr }, `Cannot check computer ${JSON.stringify(selected.alias)}`);
+  }
+  const version = parseComputerVersion(check.stdout, selected.alias);
+  if (!Number.isInteger(version.capabilities?.[capability]) || version.capabilities[capability] < minimum) {
+    throw new ClientError(
+      `Computer "${selected.alias}" does not support ${feature}; update it with \`${selected.source === 'explicit' ? `empty --computer ${selected.alias} computer update` : 'empty computer update'}\` and retry`,
+      'unsupported-capability',
+    );
+  }
+  return null;
+}
+
+async function commandClone(args, explicitComputer, { env, stdout, stderr }) {
+  const json = takeJson(args);
+  if (json.args.length < 1) throw new UsageError('`clone` needs an <id>', 'clone');
+  if (json.args.length > 2) throw new UsageError('`clone` takes only an <id> and an optional [directory]', 'clone');
+  const [id, directory = id] = json.args;
+  if (!ID_PATTERN.test(id)) throw new UsageError('Thing id must match [a-z0-9-]+', 'clone');
+  const selected = selectComputer(readConfig(env), explicitComputer);
+  const destinationExisted = fs.existsSync(directory);
+
+  const describe = await rpcCaptured(selected, ['thing', 'describe', id, '--json'], env);
+  if (describe.code !== 0) {
+    return relayRemoteResult(describe, json.enabled, { stdout, stderr }, `Cannot describe Thing ${JSON.stringify(id)}`);
+  }
+
+  if (json.enabled) {
+    const clone = await capturedGit(
+      ['clone', '--', `${selected.target}:things/${id}`, directory],
+      { env, profile: selected },
+      `Cannot clone Thing ${JSON.stringify(id)}; check the destination and retry`,
+    );
+    requireGitSuccess(clone, `Cannot clone Thing ${JSON.stringify(id)}; check the destination and retry`);
+  } else {
+    const cloneCode = await inheritedGit(
+      ['clone', '--', `${selected.target}:things/${id}`, directory],
+      { env, profile: selected },
+    );
+    if (cloneCode !== 0) return cloneCode;
+  }
+  try {
+    const rootResult = await capturedGit(['-C', directory, 'rev-parse', '--show-toplevel'], { env }, 'Cannot inspect cloned repository');
+    requireGitSuccess(rootResult, 'Cannot inspect cloned repository');
+    const root = rootResult.stdout.trim();
+    const manifestId = readThingId(root);
+    if (manifestId !== id) {
+      throw new ClientError(
+        `Cloned Thing id "${manifestId}" does not match requested id "${id}"; remove the destination and clone again`,
+        'clone-binding-failed',
+      );
+    }
+
+    for (const [key, value] of [
+      ['emptyos.computer', selected.alias],
+      ['emptyos.profileTarget', selected.target],
+      ['emptyos.target', `thing://${id}`],
+    ]) {
+      const result = await capturedGit(['-C', root, 'config', '--local', key, value], { env }, `Cannot bind cloned repository (${key})`);
+      requireGitSuccess(result, `Cannot bind cloned repository (${key})`);
+    }
+    if (json.enabled) {
+      stdout.write(`${JSON.stringify({
+        id,
+        directory: root,
+        computer: selected.alias,
+        profileTarget: selected.target,
+        target: `thing://${id}`,
+      })}\n`);
+    }
+    else stdout.write(`Bound ${root} to ${selected.alias}:thing://${id}\n`);
+    return 0;
+  } catch (error) {
+    if (!destinationExisted) fs.rmSync(directory, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+async function commandPublish(root, explicitComputer, json, { env, stdout, stderr }) {
+  const binding = await readBinding(root, env);
+
+  if (explicitComputer && explicitComputer !== binding.computer) {
+    throw new ClientError(
+      `--computer "${explicitComputer}" does not match repository binding "${binding.computer}"; clone from the intended computer instead`,
+      'binding-mismatch',
+    );
+  }
+  const config = readConfig(env);
+  const profile = config.computers[binding.computer];
+  if (!profile) {
+    throw new ClientError(`Bound computer "${binding.computer}" is not configured; restore that profile or clone again`, 'binding-mismatch');
+  }
+  if (profile.target !== binding.profileTarget) {
+    throw new ClientError(
+      `Computer "${binding.computer}" now targets "${profile.target}", but this checkout was cloned from "${binding.profileTarget}"; restore the profile target or clone again`,
+      'binding-mismatch',
+    );
+  }
+  const expectedTarget = `thing://${binding.id}`;
+  if (binding.target !== expectedTarget) throw new ClientError(`Invalid repository target "${binding.target}"; clone the Thing again`, 'binding-mismatch');
+  const manifestId = readThingId(root);
+  if (manifestId !== binding.id) {
+    throw new ClientError(
+      `thing.yaml id "${manifestId}" does not match repository binding "${binding.id}"; restore the bound id or clone again`,
+      'binding-mismatch',
+    );
+  }
+  await validateOrigin(root, profile.target, binding.id, env);
+
+  const branch = await capturedGit(['symbolic-ref', '--quiet', '--short', 'HEAD'], { cwd: root, env }, 'Cannot inspect the current branch');
+  if (branch.code !== 0 || !branch.stdout.trim()) throw new ClientError('This checkout is on a detached HEAD; check out a branch before running `put`', 'detached-head');
+  const status = await capturedGit(['status', '--porcelain'], { cwd: root, env }, 'Cannot inspect repository status');
+  requireGitSuccess(status, 'Cannot inspect repository status');
+  if (status.stdout.length !== 0) throw new ClientError('This checkout has uncommitted changes; commit or stash them before running `put`', 'dirty-worktree');
+
+  validateVerify(root);
+  const trackedVerify = await capturedGit(['ls-files', '--error-unmatch', '--', 'verify'], { cwd: root, env }, 'Cannot inspect ./verify');
+  if (trackedVerify.code !== 0) {
+    throw new ClientError('`put` requires ./verify to be tracked by Git; add it, commit, and retry', 'verify-invalid');
+  }
+  if (json) {
+    const localVerify = await runVerifyCaptured(root, env);
+    if (localVerify.code !== 0) {
+      const detail = localVerify.stderr.trim() || localVerify.stdout.trim();
+      throw new ClientError(
+        `${detail ? `./verify failed: ${detail}` : `./verify failed with exit code ${localVerify.code}`}; fix ./verify and retry`,
+        'verify-failed',
+      );
+    }
+  } else {
+    const localVerifyCode = await runVerify(root, env);
+    if (localVerifyCode !== 0) return localVerifyCode;
+  }
+  const statusAfterVerify = await capturedGit(['status', '--porcelain'], { cwd: root, env }, 'Cannot inspect repository status after ./verify');
+  requireGitSuccess(statusAfterVerify, 'Cannot inspect repository status after ./verify');
+  if (statusAfterVerify.stdout.length !== 0) {
+    throw new ClientError('./verify left tracked or untracked changes; clean them and run `put` again', 'dirty-worktree');
+  }
+
+  if (json) {
+    const fetch = await capturedGit(
+      ['fetch', 'origin'],
+      { cwd: root, env, profile },
+      'Cannot fetch origin; check the bound computer and retry',
+    );
+    requireGitSuccess(fetch, 'Cannot fetch origin; check the bound computer and retry');
+  } else {
+    const fetchCode = await inheritedGit(['fetch', 'origin'], { cwd: root, env, profile });
+    if (fetchCode !== 0) return fetchCode;
+  }
+  const remote = await capturedGit(
+    ['ls-remote', '--symref', 'origin', 'HEAD'],
+    { cwd: root, env, profile },
+    'Cannot resolve the origin default branch',
+  );
+  requireGitSuccess(remote, 'Cannot resolve the origin default branch');
+  const { defaultBranch, liveHead } = parseRemoteHead(remote.stdout);
+
+  const headResult = await capturedGit(['rev-parse', 'HEAD'], { cwd: root, env }, 'Cannot resolve local HEAD');
+  requireGitSuccess(headResult, 'Cannot resolve local HEAD');
+  const sha = requireFullSha(headResult.stdout.trim(), 'local HEAD');
+  const ancestor = await capturedGit(['merge-base', '--is-ancestor', liveHead, sha], { cwd: root, env }, 'Cannot compare local HEAD with the live origin head');
+  if (ancestor.code === 1) {
+    throw new ClientError(
+      `Local HEAD does not contain origin/${defaultBranch} (${liveHead}); fetch and rebase, then run \`put\` again`,
+      'stale-publication',
+    );
+  }
+  requireGitSuccess(ancestor, 'Cannot compare local HEAD with the live origin head');
+
+  const parents = await capturedGit(['rev-list', '--parents', '-n', '1', sha], { cwd: root, env }, 'Cannot inspect the candidate commit');
+  requireGitSuccess(parents, 'Cannot inspect the candidate commit');
+  const parts = parents.stdout.trim().split(/\s+/);
+  if (parts.length !== 2 || parts[0] !== sha || parts[1] !== liveHead) {
+    throw new ClientError(
+      `\`put\` requires exactly one non-merge commit on top of origin/${defaultBranch}; squash or rebase this checkout to one commit`,
+      'stale-publication',
+    );
+  }
+
+  const candidateRef = `refs/emptyos/candidates/${sha}`;
+  if (json) {
+    const push = await capturedGit(
+      ['push', 'origin', `HEAD:${candidateRef}`],
+      { cwd: root, env, profile },
+      'Cannot push the candidate commit; check the bound computer and retry',
+    );
+    requireGitSuccess(push, 'Cannot push the candidate commit; check the bound computer and retry');
+  } else {
+    const pushCode = await inheritedGit(['push', 'origin', `HEAD:${candidateRef}`], { cwd: root, env, profile });
+    if (pushCode !== 0) return pushCode;
+  }
+  const activateArgs = ['thing', 'activate', binding.id, '--sha', sha, '--expected-base', liveHead];
+  if (json) activateArgs.push('--json');
+  if (!json) return rpcInherited(profile, activateArgs, env);
+  const activation = await rpcCaptured(profile, activateArgs, env);
+  return relayRemoteResult(activation, true, { stdout, stderr }, 'Thing activation failed');
+}
+
+async function commandCommands(args, explicitComputer, { env, stdout, stderr }) {
+  const json = takeJson(args);
+  if (json.args.length) throw new UsageError('`commands` takes no arguments', 'commands');
+  const selected = selectComputer(readConfig(env), explicitComputer);
+  const response = await rpcCaptured(selected, ['commands', '--json'], env);
+  if (response.code !== 0) {
+    stdout.write(response.stdout);
+    stderr.write(response.stderr);
+    return response.code;
+  }
+  let resident;
+  try { resident = JSON.parse(response.stdout); }
+  catch { throw new ClientError(`Computer "${selected.alias}" returned an invalid command inventory`, 'invalid-command-inventory'); }
+  if (!resident || !Array.isArray(resident.commands) || !Array.isArray(resident.collisions)) {
+    throw new ClientError(`Computer "${selected.alias}" returned an invalid command inventory`, 'invalid-command-inventory');
+  }
+  const byCommand = new Map();
+  for (const command of resident.commands) byCommand.set(command.command, command);
+  for (const command of commandInventory()) {
+    const existing = byCommand.get(command.command);
+    byCommand.set(command.command, existing ? { ...existing, summary: command.summary || existing.summary, location: command.location } : command);
+  }
+  const result = {
+    commands: [...byCommand.values()].sort((a, b) => a.command.localeCompare(b.command)),
+    collisions: resident.collisions,
+    dirty: Boolean(resident.dirty),
+  };
+  if (json.enabled) stdout.write(`${JSON.stringify(result)}\n`);
+  else {
+    for (const command of result.commands) if (!command.hidden) stdout.write(`${command.command}${command.summary ? `\t${command.summary}` : ''}\n`);
+    for (const collision of result.collisions) stderr.write(`empty: warning: Local command ${collision.command} collides with built-in ${collision.collision}\n`);
+    if (result.dirty) stderr.write('empty: warning: Local extensions have uncommitted changes; commit them before using Undo\n');
+  }
+  return 0;
+}
+
+// An unknown first token is either a resident extension command or a typo.
+// Ask the computer's inventory before forwarding so a typo fails here with
+// client usage instead of the resident CLI's client-blind usage screen. A
+// failed or unreadable probe degrades to forwarding.
+async function forwardExtensionCommand(selected, argv, env) {
+  const probe = await rpcCaptured(selected, ['commands', '--json'], env);
+  if (probe.code === 0 && !extensionRouteMatches(probe.stdout, argv)) {
+    throw new UsageError(`Unknown command "${argv[0]}"`);
+  }
+  return rpcInherited(selected, argv, env);
+}
+
+function extensionRouteMatches(stdout, argv) {
+  let inventory;
+  try { inventory = JSON.parse(stdout); } catch { return true; }
+  if (!Array.isArray(inventory?.commands)) return true;
+  return inventory.commands.some((command) => Array.isArray(command.route)
+    && command.route.length > 0
+    && command.route.every((word, index) => argv[index] === word));
+}
+
+async function commandHumanCatalog(selected, argv, catalog, { env, stdout, stderr }) {
+  const probe = await rpcCaptured(selected, [...argv, '--json'], env);
+  if (probe.code !== 0) return rpcInherited(selected, argv, env);
+  const value = parseCatalogJson(catalog.command, probe.stdout);
+  if (value === null || !catalog.empty(value)) return rpcInherited(selected, argv, env);
+
+  if (catalog.humanEmptyOutput !== undefined) {
+    const human = await rpcCaptured(selected, argv, env);
+    stdout.write(human.stdout === catalog.humanEmptyOutput ? '' : human.stdout);
+    stderr.write(human.stderr);
+    if (human.code !== 0) {
+      return human.code;
+    }
+    if (human.stdout !== catalog.humanEmptyOutput) return 0;
+  } else {
+    stderr.write(probe.stderr);
+  }
+  stdout.write(catalog.message(selected.alias, koanLines({ env, stdout })));
+  return 0;
+}
+
+async function readBinding(root, env) {
+  const values = {};
+  for (const [field, key] of [
+    ['computer', 'emptyos.computer'],
+    ['profileTarget', 'emptyos.profileTarget'],
+    ['target', 'emptyos.target'],
+  ]) {
+    const result = await capturedGit(['config', '--local', '--get', key], { cwd: root, env }, `Cannot inspect ${key} binding`);
+    if (result.code !== 0 || !result.stdout.trim()) {
+      throw new ClientError(`This repository has no ${key} binding; use \`empty clone <id>\``, 'binding-missing');
+    }
+    values[field] = result.stdout.trim();
+  }
+  try {
+    validateAlias(values.computer);
+    validateTarget(values.profileTarget);
+  } catch (error) {
+    throw new ClientError(`${error.message}; clone the Thing again`, 'binding-mismatch');
+  }
+  const match = /^thing:\/\/([a-z0-9-]+)$/.exec(values.target);
+  if (!match) throw new ClientError(`Invalid repository target "${values.target}"; clone the Thing again`, 'binding-mismatch');
+  values.id = match[1];
+  return values;
+}
+
+async function validateOrigin(root, target, id, env) {
+  const expected = `${target}:things/${id}`;
+  const fetchUrl = await capturedGit(['config', '--local', '--get', 'remote.origin.url'], { cwd: root, env }, 'Cannot inspect origin URL');
+  if (fetchUrl.code !== 0 || fetchUrl.stdout.trim() !== expected) {
+    throw new ClientError(
+      `The origin URL must remain ${JSON.stringify(expected)}; clone the Thing again instead of retargeting it`,
+      'binding-mismatch',
+    );
+  }
+  const pushUrls = await capturedGit(['config', '--local', '--get-all', 'remote.origin.pushurl'], { cwd: root, env }, 'Cannot inspect origin push URL');
+  if (pushUrls.code !== 0 && pushUrls.code !== 1) requireGitSuccess(pushUrls, 'Cannot inspect origin push URL');
+  const configured = pushUrls.stdout.split(/\r?\n/).filter(Boolean);
+  if (configured.some((url) => url !== expected)) {
+    throw new ClientError(
+      `The origin push URL must remain ${JSON.stringify(expected)}; remove the custom push URL or clone again`,
+      'binding-mismatch',
+    );
+  }
+}
+
+function validateVerify(root) {
+  const file = path.join(root, 'verify');
+  let stat;
+  try {
+    stat = fs.lstatSync(file);
+  } catch (error) {
+    if (error.code === 'ENOENT') throw new ClientError('`put` requires an executable ./verify file; restore it, commit, and retry', 'verify-missing');
+    throw error;
+  }
+  if (stat.isSymbolicLink() || !stat.isFile() || (stat.mode & 0o111) === 0) {
+    throw new ClientError('`put` requires ./verify to be an executable regular file, not a symlink; fix it, commit, and retry', 'verify-invalid');
+  }
+}
+
+function runVerify(root, env) {
+  return runInherited(path.join(root, 'verify'), [], { cwd: root, env });
+}
+
+async function runVerifyCaptured(root, env) {
+  try {
+    return await runCaptured(path.join(root, 'verify'), [], { cwd: root, env });
+  } catch (error) {
+    throw new ClientError(`Cannot run ./verify: ${error.message}; fix ./verify and retry`, 'verify-failed');
+  }
+}
+
+function parseRemoteHead(output) {
+  let defaultRef;
+  let liveHead;
+  for (const line of output.split(/\r?\n/)) {
+    const symbolic = /^ref:\s+(refs\/heads\/[^\s]+)\s+HEAD$/.exec(line);
+    if (symbolic) defaultRef = symbolic[1];
+    const head = /^([0-9a-fA-F]{40,64})\s+HEAD$/.exec(line);
+    if (head) liveHead = head[1].toLowerCase();
+  }
+  if (!defaultRef || !liveHead) throw new ClientError('The origin remote did not advertise a default branch and HEAD; repair the remote or clone again', 'git-failed');
+  return { defaultBranch: defaultRef.slice('refs/heads/'.length), liveHead };
+}
+
+function requireFullSha(value, label) {
+  if (!/^[0-9a-fA-F]{40,64}$/.test(value)) throw new ClientError(`Cannot resolve ${label} to a full commit id`, 'git-failed');
+  return value.toLowerCase();
+}
+
+function requireGitSuccess(result, fallback) {
+  if (result.code === 0) return;
+  const detail = result.stderr.trim() || result.stdout.trim();
+  throw new ClientError(detail ? `${fallback}: ${detail}` : fallback, 'git-failed');
+}
+
+async function capturedGit(args, options, fallback) {
+  try {
+    return await gitCaptured(args, options);
+  } catch (error) {
+    throw new ClientError(`${fallback}: ${error.message}`, 'git-failed');
+  }
+}
+
+async function inheritedGit(args, options) {
+  try {
+    return await gitInherited(args, options);
+  } catch (error) {
+    throw new ClientError(`Cannot run Git: ${error.message}`, 'git-failed');
+  }
+}
+
+function relayRemoteResult(result, json, { stdout, stderr }, fallback) {
+  if (!json || isJsonValue(result.stdout)) {
+    stdout.write(result.stdout);
+    stderr.write(result.stderr);
+    if (!json && result.transportHint) stderr.write(result.transportHint);
+    return result.code;
+  }
+  const detail = result.stderr.trim() || result.stdout.trim();
+  throw new ClientError(
+    result.code === 0
+      ? `${fallback}: the computer returned a non-JSON response; update the client and computer together, then retry`
+      : `${fallback}; check SSH connectivity and retry${detail ? `: ${detail}` : ''}`,
+    result.code === 0 ? 'protocol-error' : 'transport-failed',
+  );
+}
+
+function isJsonValue(output) {
+  try {
+    const value = JSON.parse(output);
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+  } catch {
+    return false;
+  }
+}
+
+function commandName(argv) {
+  return argv.slice(0, 2).join(' ');
+}
+
+function takeJson(args) {
+  const filtered = args.filter((arg) => arg !== '--json');
+  return { enabled: filtered.length !== args.length, args: filtered };
+}