@ornncompute/cli 0.2.24 → 1.0.25

package/src/catalog-shell.mjs

@@ -0,0 +1,1350 @@
+import { HARDWARE_CATALOG_PATH } from "../vendor/capabilities/cli.js";
+
+import {
+  CliApiError,
+  cliRequest,
+  operatorRequest,
+  resolveApiBaseUrl,
+  resolveInstallerBaseUrl,
+} from "./api-client.mjs";
+import {
+  clearPendingWorkspace,
+  loadAuthSession,
+  loadPendingWorkspace,
+  savePendingWorkspace,
+} from "./auth-store.mjs";
+import {
+  AdminUsageError,
+  adminCommandData,
+  adminRootData,
+  finalizeAdminResult,
+  resolveAdminRequest,
+  writeAdminHelpHuman,
+  writeAdminResultHuman,
+  writeAdminRootHuman,
+} from "./admin-shell.mjs";
+import { adminCommandName, preflightAdminCommand } from "./admin-command-handlers.mjs";
+import { AdminMutationError } from "./admin-mutations.mjs";
+import { loadCapabilities } from "./capability-catalog.mjs";
+import {
+  continueConnectWithHandlers,
+  resolveConnectTargetWithHandlers,
+} from "./connect-mode-handlers.mjs";
+import { dispatchLaunchWithHandlers } from "./launch-mode-handlers.mjs";
+import { updateCommand } from "./update.mjs";
+import {
+  executeExternalBucketCommand,
+  writeExternalBucketResultHuman,
+} from "./external-bucket-commands.mjs";
+import { executeEvidenceCommand } from "./evidence-commands.mjs";
+import {
+  executeKubernetesClusterCommand,
+  kubernetesConnectModeHandler,
+  kubernetesLaunchModeHandler,
+} from "./kubernetes-commands.mjs";
+import {
+  executeSessionCommand,
+  parseSessionCommandInput,
+  SessionCommandError,
+} from "./session-commands.mjs";
+import {
+  createInteractionRuntime,
+  InteractionError,
+  isInteractionExecution,
+  parseSemanticArguments,
+} from "./interaction-runtime.mjs";
+import { executeMountCommand } from "./mount-commands.mjs";
+import {
+  executeStorageCommand,
+  StorageCommandError,
+  writeStorageResultHuman,
+} from "./storage-commands.mjs";
+import {
+  exportVpnSecret,
+  hasLocalNetworkAddress,
+  prepareVpnSecretExport,
+  wireGuardPublicKeyFromFile,
+} from "./vpn-secret-output.mjs";
+import { createSlurmConnectModeHandler, slurmLaunchModeHandler } from "./slurm-commands.mjs";
+import {
+  bareMetalLaunchModeHandler,
+  createBareMetalConnectModeHandler,
+  createVmConnectModeHandler,
+  executeMachineCommand,
+  executeSshKeyCommand,
+  vmLaunchModeHandler,
+} from "./vm-commands.mjs";
+import { waitForGoal } from "./wait-runtime.mjs";
+
+const MACHINE_SCHEMA = "ornn.cli/v1";
+const UPDATE_CHANNEL = "stable";
+const FORMATS = { human: true, json: true, ndjson: true };
+const SESSION_CAPABILITY_IDS = new Set(["identity.context", "identity.login", "identity.logout"]);
+export const CLI_EXIT_STATUS = Object.freeze({
+  success: 0,
+  failure: 1,
+  usage: 2,
+  actionRequired: 3,
+  partial: 4,
+  authorization: 5,
+  unavailable: 6,
+  timeout: 124,
+  interrupted: 130,
+});
+
+class VnextUsageError extends Error {
+  constructor(message, { code = "usage_error", field } = {}) {
+    super(message);
+    this.name = "VnextUsageError";
+    this.code = code;
+    this.field = field;
+  }
+}
+
+class VnextContractError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = "VnextContractError";
+    this.code = code;
+  }
+}
+
+function extractFormat(argv) {
+  const remaining = [];
+  let format;
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--format" || argument.startsWith("--format=")) {
+      if (format !== undefined) {
+        return {
+          error: new VnextUsageError("--format may be supplied only once.", { field: "format" }),
+          format,
+          remaining,
+        };
+      }
+      const inline = argument.startsWith("--format=") ? argument.slice("--format=".length) : null;
+      const value = inline ?? argv[index + 1];
+      if (!value || (!inline && value.startsWith("-"))) {
+        return {
+          error: new VnextUsageError("--format requires human, json, or ndjson.", {
+            field: "format",
+          }),
+          format,
+          remaining,
+        };
+      }
+      if (inline === null) index += 1;
+      format = value;
+      continue;
+    }
+    remaining.push(argument);
+  }
+  if (format !== undefined && FORMATS[format] !== true) {
+    return {
+      error: new VnextUsageError(`Unsupported format: ${format}. Choose human, json, or ndjson.`, {
+        field: "format",
+      }),
+      format,
+      remaining,
+    };
+  }
+  return { error: null, format, remaining };
+}
+
+function vnextCommand(capability) {
+  return capability.cli?.vnext?.command ?? capability.cli?.command ?? [];
+}
+
+function customerCommands(catalog) {
+  return catalog
+    .filter((capability) => capability.cli?.vnext?.audience === "customer")
+    .sort((left, right) => {
+      const leftOrder = left.cli.vnext.order ?? Number.MAX_SAFE_INTEGER;
+      const rightOrder = right.cli.vnext.order ?? Number.MAX_SAFE_INTEGER;
+      return (
+        leftOrder - rightOrder ||
+        vnextCommand(left).join(" ").localeCompare(vnextCommand(right).join(" "))
+      );
+    });
+}
+
+function commandMatch(catalog, argv) {
+  return customerCommands(catalog)
+    .filter((capability) => vnextCommand(capability).every((part, index) => argv[index] === part))
+    .sort((left, right) => vnextCommand(right).length - vnextCommand(left).length)[0];
+}
+
+function editDistance(left, right) {
+  const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+  for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
+    const current = [leftIndex];
+    for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) {
+      current[rightIndex] = Math.min(
+        current[rightIndex - 1] + 1,
+        previous[rightIndex] + 1,
+        previous[rightIndex - 1] + (left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1)
+      );
+    }
+    previous.splice(0, previous.length, ...current);
+  }
+  return previous[right.length];
+}
+
+function suggestedCommand(catalog, input) {
+  if (!input || input.startsWith("-")) return null;
+  const roots = [
+    ...new Set(customerCommands(catalog).map((capability) => vnextCommand(capability)[0])),
+  ];
+  const candidates = roots
+    .map((command) => ({ command, distance: editDistance(input, command) }))
+    .sort(
+      (left, right) => left.distance - right.distance || left.command.localeCompare(right.command)
+    );
+  return candidates[0]?.distance <= 2 ? candidates[0].command : null;
+}
+
+function commandGroup(catalog, path) {
+  const matches = customerCommands(catalog).filter((capability) => {
+    const command = vnextCommand(capability);
+    return path.length < command.length && path.every((part, index) => command[index] === part);
+  });
+  return matches.length ? matches : null;
+}
+
+function retiredSyntaxError(argv, findLegacyCliMigration, migrationGuideUrl) {
+  if (argv.includes("--json")) {
+    const replacement = argv
+      .map((argument) => (argument === "--json" ? "--format json" : argument))
+      .join(" ");
+    return new VnextUsageError(
+      `Retired syntax: --json. Use \`ornn ${replacement}\`. See ${migrationGuideUrl}`,
+      { code: "legacy_command_removed", field: "format" }
+    );
+  }
+  if (argv.includes("--interactive")) {
+    const replacement = argv
+      .map((argument) => (argument === "--interactive" ? "--guided" : argument))
+      .join(" ");
+    return new VnextUsageError(
+      `Retired syntax: --interactive. Use \`ornn ${replacement}\`. See ${migrationGuideUrl}`,
+      { code: "legacy_command_removed", field: "guided" }
+    );
+  }
+  const migration = findLegacyCliMigration?.(argv);
+  if (!migration) return null;
+  return new VnextUsageError(
+    `Retired command: ornn ${migration.legacy.join(" ")}. Use \`${migration.replacement}\`. See ${migrationGuideUrl}`,
+    { code: "legacy_command_removed" }
+  );
+}
+
+function resolveRequest(catalog, argv, findLegacyCliMigration, migrationGuideUrl) {
+  if (argv.length === 0 || (argv.length === 1 && (argv[0] === "--help" || argv[0] === "-h"))) {
+    return { kind: "root", command: "help" };
+  }
+  if (argv[0] === "--help" || argv[0] === "-h") {
+    return {
+      kind: "error",
+      command: "help",
+      error: new VnextUsageError("Usage: ornn [--format human|json|ndjson]"),
+    };
+  }
+
+  const retired = retiredSyntaxError(argv, findLegacyCliMigration, migrationGuideUrl);
+  if (retired) {
+    return { kind: "error", command: argv.slice(0, 2).join(" ") || "help", error: retired };
+  }
+
+  if (argv[0] === "admin") {
+    return { kind: "admin", command: "admin", argv: argv.slice(1) };
+  }
+
+  if (argv[0] === "help") {
+    if (argv.length === 1) return { kind: "root", command: "help" };
+    if (argv[1] === "admin") {
+      return { kind: "admin", command: "admin", argv: ["help", ...argv.slice(2)] };
+    }
+    const targetArgv = argv.slice(1);
+    const target = commandMatch(catalog, targetArgv);
+    if (target && targetArgv.length === vnextCommand(target).length) {
+      return {
+        kind: "help",
+        command: `help ${vnextCommand(target).join(" ")}`,
+        capability: target,
+      };
+    }
+    const group = commandGroup(catalog, targetArgv);
+    if (group) {
+      return {
+        kind: "help-group",
+        command: `help ${targetArgv.join(" ")}`,
+        path: targetArgv,
+        capabilities: group,
+      };
+    }
+    const suggestion = suggestedCommand(catalog, argv[1]);
+    return {
+      kind: "error",
+      command: `help ${argv[1]}`,
+      error: new VnextUsageError(
+        suggestion
+          ? `Unknown command: ${argv[1]}. Did you mean \`ornn help ${suggestion}\`?`
+          : `Unknown command: ${targetArgv.join(" ")}. Run \`ornn help\` to list registered commands.`,
+        { code: "unknown_command" }
+      ),
+    };
+  }
+
+  const trailingHelp = argv.at(-1) === "--help" || argv.at(-1) === "-h";
+  if (trailingHelp) {
+    const targetArgv = argv.slice(0, -1);
+    const group = commandGroup(catalog, targetArgv);
+    if (group) {
+      return {
+        kind: "help-group",
+        command: `help ${targetArgv.join(" ")}`,
+        path: targetArgv,
+        capabilities: group,
+      };
+    }
+  }
+
+  const capability = commandMatch(catalog, argv);
+  if (capability) {
+    const command = vnextCommand(capability);
+    const rest = argv.slice(command.length);
+    const helpFlags = rest.filter((argument) => argument === "--help" || argument === "-h");
+    if (helpFlags.length) {
+      if (rest.length !== 1) {
+        return {
+          kind: "error",
+          command: command.join(" "),
+          error: new VnextUsageError(`Usage: ${capability.cli.vnext.human}`),
+        };
+      }
+      return { kind: "help", command: `help ${command.join(" ")}`, capability };
+    }
+    if (rest.length && capability.cli.vnext.arguments !== "semantic") {
+      return {
+        kind: "error",
+        command: command.join(" "),
+        error: new VnextUsageError(`Usage: ${capability.cli.vnext.human}`),
+      };
+    }
+    return { kind: "command", command: command.join(" "), capability, argv: rest };
+  }
+
+  const suggestion = suggestedCommand(catalog, argv[0]);
+  return {
+    kind: "error",
+    command: argv[0] ?? "help",
+    error: new VnextUsageError(
+      suggestion
+        ? `Unknown command: ${argv[0]}. Did you mean \`ornn ${suggestion} --help\`?`
+        : `Unknown command: ${argv.join(" ")}. Run \`ornn help\` to list registered commands.`,
+      { code: "unknown_command" }
+    ),
+  };
+}
+
+function commandData(capability) {
+  const help = capability.cli.vnext;
+  return {
+    command: vnextCommand(capability).join(" "),
+    outcome: help.outcome,
+    human: help.human,
+    automation: help.automation,
+    accepted_references: help.acceptedReferences ?? [],
+    review: help.review ?? null,
+    resumable_states: help.resumableStates ?? [],
+    related: help.related ?? [],
+  };
+}
+
+function rootData(catalog) {
+  const commands = customerCommands(catalog);
+  return {
+    journey: commands
+      .filter((capability) => capability.cli.vnext.category === "journey")
+      .map(commandData),
+    session: commands
+      .filter((capability) => capability.cli.vnext.category === "session")
+      .map(commandData),
+    platform: commands
+      .filter((capability) => capability.cli.vnext.category === "platform")
+      .map(commandData),
+    advanced_resources: [
+      ...new Set(
+        commands
+          .filter((capability) => capability.cli.vnext.category === "resource")
+          .map((capability) => vnextCommand(capability)[0])
+      ),
+    ],
+  };
+}
+
+function completionData(catalog, shell) {
+  const paths = customerCommands(catalog).map((capability) => vnextCommand(capability).join(" "));
+  if (shell === "fish") {
+    const children = {};
+    const lines = ["complete -c ornn -f"];
+    for (const path of paths) {
+      const parts = path.split(" ");
+      for (let index = 0; index < parts.length; index += 1) {
+        const parent = parts.slice(0, index).join(" ");
+        (children[parent] ??= []).push(parts[index]);
+      }
+    }
+    for (const [parent, candidates] of Object.entries(children)) {
+      const unique = [...new Set(candidates)].sort().join(" ");
+      const condition = parent
+        ? ` -n '__fish_seen_subcommand_from ${parent.split(" ").join(" ")}'`
+        : " -n '__fish_use_subcommand'";
+      lines.push(`complete -c ornn -f${condition} -a '${unique}'`);
+    }
+    return { commands: paths, script: `${lines.join("\n")}\n`, shell };
+  }
+  const quotedPaths = paths.map((path) => `'${path}'`).join(" ");
+  if (shell === "zsh") {
+    return {
+      commands: paths,
+      shell,
+      script: `#compdef ornn\n_ornn() {\n  local -a paths candidates\n  paths=(${quotedPaths})\n  local prefix=\"\${(j: :)words[2,CURRENT-1]}\" path rest\n  for path in \"\${paths[@]}\"; do\n    if [[ -z \"$prefix\" ]]; then rest=\"$path\"\n    elif [[ \"$path\" == \"$prefix \"* ]]; then rest=\"\${path#$prefix }\"\n    else continue\n    fi\n    candidates+=(\"\${rest%% *}\")\n  done\n  compadd -a candidates\n}\ncompdef _ornn ornn\n`,
+    };
+  }
+  return {
+    commands: paths,
+    shell,
+    script: `_ornn_complete() {\n  local current=\"\${COMP_WORDS[COMP_CWORD]}\" prefix=\"\" path rest candidate candidates=\"\"\n  local paths=(${quotedPaths})\n  if (( COMP_CWORD > 1 )); then prefix=\"\${COMP_WORDS[*]:1:COMP_CWORD-1}\"; fi\n  for path in \"\${paths[@]}\"; do\n    if [[ -z \"$prefix\" ]]; then rest=\"$path\"\n    elif [[ \"$path\" == \"$prefix \"* ]]; then rest=\"\${path#\"$prefix \"}\"\n    else continue\n    fi\n    candidate=\"\${rest%% *}\"\n    [[ \" $candidates \" == *\" $candidate \"* ]] || candidates+=\" $candidate\"\n  done\n  COMPREPLY=( $(compgen -W \"$candidates\" -- \"$current\") )\n}\ncomplete -F _ornn_complete ornn\n`,
+  };
+}
+
+function groupData(path, capabilities) {
+  return {
+    path: path.join(" "),
+    commands: capabilities.map(commandData),
+  };
+}
+
+function resultEnvelope(
+  command,
+  data,
+  outcome = { class: "ready", phase: "complete" },
+  page = null
+) {
+  return {
+    schema: MACHINE_SCHEMA,
+    type: "result",
+    command,
+    outcome,
+    data,
+    resume: null,
+    action: null,
+    page,
+    errors: [],
+  };
+}
+function executionEnvelope(command, execution) {
+  return {
+    ...resultEnvelope(command, execution.data, execution.outcome, execution.page ?? null),
+    action: execution.action ?? null,
+    errors: execution.errors ?? [],
+    resume: execution.resume ?? null,
+  };
+}
+
+function errorDetail(error) {
+  const payload = error?.detail;
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
+  if (payload.detail && typeof payload.detail === "object" && !Array.isArray(payload.detail)) {
+    return payload.detail;
+  }
+  if (payload.error && typeof payload.error === "object" && !Array.isArray(payload.error)) {
+    return payload.error;
+  }
+  return payload;
+}
+
+function modeledError(error) {
+  if (error instanceof SessionCommandError) {
+    return {
+      action: error.action,
+      exitCode: error.exitCode,
+      outcomeClass: error.outcomeClass,
+      error: {
+        code: error.code,
+        message: error.message,
+        retryable: error.retryable,
+      },
+    };
+  }
+  if (error instanceof StorageCommandError) {
+    return {
+      action: error.action ?? null,
+      exitCode: error.exitCode,
+      outcomeClass: error.outcomeClass,
+      error: {
+        code: error.code,
+        message: error.message,
+        retryable: error.retryable,
+        ...(error.field ? { field: error.field } : {}),
+      },
+    };
+  }
+
+  if (
+    error instanceof VnextUsageError ||
+    error instanceof AdminUsageError ||
+    error instanceof VnextContractError ||
+    error instanceof AdminMutationError ||
+    error instanceof InteractionError
+  ) {
+    return {
+      action: error.action ?? null,
+      exitCode:
+        error instanceof VnextContractError
+          ? CLI_EXIT_STATUS.failure
+          : error instanceof InteractionError
+            ? error.exitCode
+            : CLI_EXIT_STATUS.usage,
+      outcomeClass: error.outcomeClass,
+      error: {
+        code: error.code,
+        message: error.message,
+        retryable: error.retryable ?? false,
+        ...(error.field ? { field: error.field } : {}),
+      },
+    };
+  }
+
+  const detail = errorDetail(error);
+  const suppliedCode = detail?.code;
+  if (typeof suppliedCode === "string" && /^[a-z][a-z0-9_]*$/.test(suppliedCode)) {
+    const retryable = detail.retryable === true;
+    return {
+      exitCode:
+        error?.status === 401 || error?.status === 403
+          ? CLI_EXIT_STATUS.authorization
+          : retryable
+            ? CLI_EXIT_STATUS.unavailable
+            : CLI_EXIT_STATUS.failure,
+      error: { code: suppliedCode, message: error.message, retryable },
+    };
+  }
+  if (error instanceof CliApiError && (error.status === 401 || error.status === 403)) {
+    return {
+      exitCode: CLI_EXIT_STATUS.authorization,
+      error: {
+        code: error.status === 401 ? "authentication_required" : "authorization_denied",
+        message: error.message,
+        retryable: false,
+      },
+    };
+  }
+  if (error instanceof CliApiError && (error.status === undefined || error.status >= 500)) {
+    return {
+      exitCode: CLI_EXIT_STATUS.unavailable,
+      error: { code: "service_unavailable", message: error.message, retryable: true },
+    };
+  }
+  return {
+    exitCode: CLI_EXIT_STATUS.failure,
+    error: {
+      code: "command_failed",
+      message: error instanceof Error ? error.message : String(error),
+      retryable: false,
+    },
+  };
+}
+
+function errorEnvelope(command, modeled) {
+  return {
+    ...resultEnvelope(command, null, {
+      class: modeled.outcomeClass ?? "failed",
+      phase: modeled.error.code,
+    }),
+    action: modeled.action ?? null,
+    errors: [modeled.error],
+  };
+}
+
+function writeMachine(stdout, format, envelope) {
+  const serialized = JSON.stringify(envelope);
+  stdout.write(format === "json" ? `${JSON.stringify(envelope, null, 2)}\n` : `${serialized}\n`);
+}
+
+function writeExecutionMachine(stdout, format, command, execution) {
+  if (format === "ndjson") {
+    for (const progress of execution.progress ?? []) {
+      writeMachine(stdout, format, {
+        ...resultEnvelope(command, progress.data ?? null, progress.outcome),
+        type: "progress",
+        ...(progress.sequence !== undefined ? { sequence: progress.sequence } : {}),
+        ...(progress.observedAt !== undefined ? { observed_at: progress.observedAt } : {}),
+        ...(progress.message !== undefined ? { message: progress.message } : {}),
+        action: progress.action ?? null,
+        errors: progress.errors ?? [],
+        resume: progress.resume ?? null,
+      });
+    }
+  }
+  writeMachine(stdout, format, executionEnvelope(command, execution));
+}
+
+function writeRootHuman(stdout, catalog) {
+  const data = rootData(catalog);
+  const writeCommands = (title, commands) => {
+    stdout.write(`${title}:\n`);
+    for (const command of commands) {
+      stdout.write(`  ${command.command}  ${command.outcome}\n`);
+    }
+    stdout.write("\n");
+  };
+  stdout.write("Ornn CLI\n\n");
+  stdout.write("Usage:\n  ornn <command> [options]\n\n");
+  stdout.write("Available commands:\n\n");
+  writeCommands("Journey", data.journey);
+  writeCommands("Session", data.session);
+  writeCommands("Platform", data.platform);
+  stdout.write("Advanced resources:\n");
+  for (const resource of data.advanced_resources) stdout.write(`  ${resource}\n`);
+  stdout.write(
+    "\nRun `ornn resources` for advanced outcomes or `ornn help <command>` for scoped help.\n"
+  );
+  stdout.write("Redirected commands require --format human, json, or ndjson.\n");
+}
+
+function writeHelpHuman(stdout, capability) {
+  const data = commandData(capability);
+  stdout.write(`${data.command}\n\nOutcome: ${data.outcome}\n\n`);
+  stdout.write(`Usage:\n  ${data.human}\n\nAutomation:\n  ${data.automation}\n`);
+  stdout.write(
+    `\nAccepted references: ${data.accepted_references.length ? data.accepted_references.join(", ") : "none"}\n`
+  );
+  stdout.write(`Review: ${data.review ?? "none"}\n`);
+  stdout.write(
+    `Resumable states: ${data.resumable_states.length ? data.resumable_states.join(", ") : "none"}\n`
+  );
+  stdout.write(
+    `Related: ${data.related.length ? data.related.map((command) => `ornn ${command}`).join(", ") : "none"}\n`
+  );
+  stdout.write("Environment: redirected vNext commands require --format human, json, or ndjson.\n");
+}
+
+function writeGroupHelpHuman(stdout, path, capabilities) {
+  stdout.write(`${path.join(" ")}\n\nAvailable commands:\n`);
+  for (const capability of capabilities) {
+    const data = commandData(capability);
+    stdout.write(`  ${data.human}\n    ${data.outcome}\n`);
+  }
+  stdout.write("\nRun `ornn help <full-command>` for references, review, and recovery details.\n");
+}
+
+function writeStatusHuman(stdout, snapshot) {
+  stdout.write(`${snapshot?.overallStatusLabel ?? snapshot?.status ?? "Status available"}\n`);
+  if (snapshot?.overallDetail) stdout.write(`${snapshot.overallDetail}\n`);
+  if (snapshot?.generatedAtLabel) stdout.write(`Generated: ${snapshot.generatedAtLabel}\n`);
+  for (const group of snapshot?.groups ?? []) {
+    stdout.write(`${group.name}: ${group.statusLabel}\n`);
+  }
+}
+
+function writeContextHuman(stdout, data) {
+  const user = data.user?.email ?? data.user?.id ?? "unknown";
+  stdout.write(`User: ${user}\n`);
+  if (data.selected_organization) {
+    stdout.write(`Organization: ${data.selected_organization.name}\n`);
+    stdout.write(`Approved: ${data.selected_organization.approved ? "yes" : "no"}\n`);
+  } else {
+    stdout.write("Organization: none selected\n");
+    stdout.write("Approved: not selected\n");
+  }
+  stdout.write("Available organizations:\n");
+  if (!data.organizations?.length) {
+    stdout.write("  none\n");
+    return;
+  }
+  for (const organization of data.organizations) {
+    stdout.write(
+      `  ${organization.name} (${organization.approved ? "approved" : "not approved"})\n`
+    );
+  }
+}
+
+function writeCommandHuman(stdout, stderr, capability, execution) {
+  const { action, data, errors = [] } = execution;
+  if (capability.id === "identity.status") {
+    writeStatusHuman(stdout, data);
+    return;
+  }
+  if (capability.id === "identity.login") {
+    if (data.session_saved) stdout.write("Logged in to Ornn.\n");
+    if (data.user) writeContextHuman(stdout, data);
+    if (action?.type === "browser") {
+      stderr.write(`Complete login in a browser:\n${action.url}\nCode: ${action.code}\n`);
+    } else if (action?.command) {
+      stderr.write(`Next: ${action.command}\n`);
+    }
+    return;
+  }
+  if (capability.id === "identity.context") {
+    writeContextHuman(stdout, data);
+    if (action?.command) stderr.write(`Next: ${action.command}\n`);
+    return;
+  }
+  if (capability.id === "identity.logout") {
+    stdout.write(
+      data.remote_session_revoked ? "Logged out of Ornn.\n" : "Local Ornn session cleared.\n"
+    );
+    for (const error of errors) stderr.write(`${error.message}\n`);
+    return;
+  }
+  if (capability.id === "cli.version") {
+    stdout.write(`Ornn CLI ${data.version}\n`);
+    stdout.write(`Machine schema: ${data.machine_schema}\n`);
+    stdout.write(`Update channel: ${data.update_channel}\n`);
+    return;
+  }
+  if (capability.id === "cli.resources") {
+    stdout.write("Advanced resources\n");
+    if (!data.resources.length) {
+      stdout.write("No advanced resource commands are registered yet.\n");
+      return;
+    }
+    for (const resource of data.resources) {
+      stdout.write(`${resource.command}: ${resource.outcome}\n`);
+      stdout.write(`  Human: ${resource.human}\n`);
+      stdout.write(`  Automation: ${resource.automation}\n`);
+    }
+    return;
+  }
+  if (capability.id === "cli.completion") {
+    stdout.write(data.script);
+    return;
+  }
+  if (capability.id.startsWith("storage.volumes.")) {
+    writeStorageResultHuman(stdout, capability.id, execution);
+    return;
+  }
+  if (capability.id.startsWith("storage.external-buckets.")) {
+    writeExternalBucketResultHuman(stdout, stderr, capability.id, execution);
+    return;
+  }
+  if (execution.presentation?.lines) {
+    for (const line of execution.presentation.lines) stdout.write(`${line}\n`);
+    if (execution.presentation.next) stderr.write(`Next: ${execution.presentation.next}\n`);
+    return;
+  }
+  if (action?.url) {
+    stderr.write(`${action.description ?? "External action required"}\n${action.url}\n`);
+    const command =
+      action.command ??
+      (execution.resume?.ref
+        ? `ornn ${vnextCommand(capability).join(" ")} --resume ${execution.resume.ref}`
+        : null);
+    if (command) stderr.write(`Next: ${command}\n`);
+  } else if (data !== null && data !== undefined) {
+    stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+  }
+}
+
+const CUSTOMER_FORBIDDEN_FIELDS = {
+  client_secret: true,
+  clientSecret: true,
+  payment_secret: true,
+  paymentSecret: true,
+  operator: true,
+  operatorId: true,
+  operatorName: true,
+  operator_id: true,
+  operator_name: true,
+  internal_owner: true,
+  internalOwner: true,
+  payment_intent_client_secret: true,
+  checkout_key: true,
+  checkoutKey: true,
+  provider_id: true,
+  provider_name: true,
+  providerId: true,
+  providerName: true,
+  paymentIntentClientSecret: true,
+  payment_provider: true,
+  paymentProvider: true,
+  provider: true,
+  site_operator: true,
+  siteOperator: true,
+  site_operator_id: true,
+  site_operator_name: true,
+  siteOperatorId: true,
+  siteOperatorName: true,
+  reconciliation: true,
+  reconciliation_status: true,
+  reconciliationStatus: true,
+  stripe_client_secret: true,
+  stripeClientSecret: true,
+  stripe_invoice_id: true,
+  stripeInvoiceId: true,
+  supplier: true,
+  supplier_id: true,
+  supplier_name: true,
+  supplierId: true,
+  supplierName: true,
+};
+
+function assertCustomerResultSafe(value) {
+  if (Array.isArray(value)) {
+    for (const item of value) assertCustomerResultSafe(item);
+    return;
+  }
+  if (!value || typeof value !== "object") return;
+  for (const [key, child] of Object.entries(value)) {
+    if (CUSTOMER_FORBIDDEN_FIELDS[key] === true) {
+      throw new VnextContractError(
+        "The gateway returned an unexpected response shape.",
+        "customer_result_unsafe"
+      );
+    }
+    assertCustomerResultSafe(child);
+  }
+}
+
+function parseCapabilityInput(capability, rawInput) {
+  const parsed = capability.input.safeParse(rawInput);
+  if (parsed.success) return parsed.data;
+  const issue = parsed.error.issues[0];
+  if (issue?.path?.[0] === "$positionals") {
+    const usage = capability.cli?.vnext?.human ?? `ornn ${vnextCommand(capability).join(" ")}`;
+    throw new VnextUsageError(`Usage: ${usage}`);
+  }
+  const field = issue?.path?.length ? issue.path.join(".") : undefined;
+  throw new InteractionError(issue?.message ?? "Invalid command input.", {
+    code: "invalid_input",
+    exitCode: CLI_EXIT_STATUS.usage,
+    field,
+  });
+}
+
+async function customerCapabilityFetch(io, path, init = {}, sessionSnapshot) {
+  const authRequired = path !== "/v1/cli/status";
+  const session = sessionSnapshot?.current;
+  const method = init.method ?? "GET";
+  if (authRequired && sessionSnapshot && !session?.accessToken) {
+    throw new CliApiError("Not logged in. Run `ornn login` first.", { status: 401 });
+  }
+  if (authRequired && sessionSnapshot && !["GET", "HEAD"].includes(method)) {
+    const current = await loadAuthSession({ env: io.env });
+    if (current?.accessToken !== session?.accessToken) {
+      throw new InteractionError(
+        "Authentication changed while this command was running; no mutation was sent. Review and retry.",
+        {
+          code: "auth_session_changed",
+          exitCode: 3,
+        }
+      );
+    }
+  }
+  return cliRequest({
+    authRequired,
+    endpoint: path,
+    env: io.env,
+    fetchImpl: io.fetchImpl,
+    headers: init.headers,
+    method,
+    ...(authRequired && session ? { session } : {}),
+    ...(init.body !== undefined ? { body: init.body } : {}),
+    ...(init.signal !== undefined ? { signal: init.signal } : {}),
+  });
+}
+
+async function executeCapability(
+  capability,
+  catalog,
+  io,
+  version,
+  {
+    audience = "customer",
+    input,
+    role = "user",
+    confirmed = false,
+    argv = [],
+    executionRuntime,
+  } = {}
+) {
+  const sessionCommand = SESSION_CAPABILITY_IDS.has(capability.id);
+  const authSnapshot = executionRuntime?.authSnapshot;
+  if (
+    audience === "customer" &&
+    !sessionCommand &&
+    authSnapshot &&
+    authSnapshot.current === undefined
+  ) {
+    authSnapshot.current = await loadAuthSession({ env: io.env });
+  }
+  const rawInput =
+    input ??
+    (sessionCommand ? parseSessionCommandInput(capability.id, argv) : parseSemanticArguments(argv));
+  const interaction =
+    audience === "customer" && !sessionCommand
+      ? createInteractionRuntime({
+          eligibleHuman: executionRuntime.eligibleHuman,
+          extensions: {
+            ...executionRuntime.interactionExtensions,
+            externalBuckets(command, externalBucketInput) {
+              return executeExternalBucketCommand(command, externalBucketInput, {
+                fetch: (path, init) => customerCapabilityFetch(io, path, init, authSnapshot),
+                interaction: this,
+                signal: io.signal,
+                sleep: io.sleep,
+                stderr: io.stderr,
+              });
+            },
+            evidence(command, evidenceInput) {
+              return executeEvidenceCommand(command, evidenceInput, {
+                fetch: (path, init) => customerCapabilityFetch(io, path, init, authSnapshot),
+                interaction: this,
+                now: io.now,
+                signal: io.signal,
+                sleep:
+                  io.sleep ??
+                  ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds))),
+                stdout: io.stdout ?? process.stdout,
+              });
+            },
+            now: io.now,
+            signal: io.signal,
+            sleep: io.sleep,
+            stderr: io.stderr ?? process.stderr,
+            cluster(command, clusterInput) {
+              return executeKubernetesClusterCommand(command, clusterInput, {
+                fetch: (path, init) => customerCapabilityFetch(io, path, init, authSnapshot),
+                interaction: this,
+                now: io.now,
+                signal: io.signal,
+                sleep: io.sleep,
+                stderr: io.stderr ?? process.stderr,
+              });
+            },
+            mounts(command, mountInput) {
+              return executeMountCommand(command, mountInput, {
+                fetch: (path, init) => customerCapabilityFetch(io, path, init, authSnapshot),
+                interaction: this,
+              });
+            },
+            storage(command, storageInput) {
+              return executeStorageCommand(command, storageInput, {
+                env: io.env,
+                fetch: (path, init) => customerCapabilityFetch(io, path, init, authSnapshot),
+                fetchImpl: io.fetchImpl,
+                interaction: this,
+              });
+            },
+          },
+          format: executionRuntime.format,
+          formatProvided: executionRuntime.formatProvided,
+          io,
+          options: rawInput,
+        })
+      : null;
+  const installerBaseUrl =
+    audience === "admin"
+      ? (resolveInstallerBaseUrl({ env: io.env }) ??
+        `${resolveApiBaseUrl({ env: io.env })}/v1/orchestrator`)
+      : undefined;
+  const parsedInput = parseCapabilityInput(capability, rawInput);
+  let data;
+  try {
+    data = await capability.execute(
+      {
+        actor: "",
+        confirmed,
+        installerBaseUrl,
+        role,
+        fetch: (path, init = {}) => {
+          if (executionRuntime?.transport) return executionRuntime.transport(path, init);
+          if (
+            audience === "admin" &&
+            capability.id === "listings.create" &&
+            path === HARDWARE_CATALOG_PATH
+          ) {
+            return operatorRequest({
+              endpoint: "/catalog/hardware",
+              env: io.env,
+              fetchImpl: io.fetchImpl,
+              method: init.method ?? "GET",
+              ...(init.headers !== undefined ? { headers: init.headers } : {}),
+              ...(init.signal !== undefined ? { signal: init.signal } : {}),
+            });
+          }
+          if (audience === "admin") {
+            const search = new URL(path, "https://cli.invalid").search;
+            const endpoint =
+              capability.id === "telemetry.latest"
+                ? `/telemetry/latest${search}`
+                : capability.id === "logs.latest"
+                  ? `/logs/latest${search}`
+                  : path;
+            return operatorRequest({
+              endpoint,
+              env: io.env,
+              fetchImpl: io.fetchImpl,
+              method: init.method ?? "GET",
+              ...(init.body !== undefined ? { body: init.body } : {}),
+              ...(init.headers !== undefined ? { headers: init.headers } : {}),
+              ...((init.signal ?? io.signal) !== undefined
+                ? { signal: init.signal ?? io.signal }
+                : {}),
+            });
+          }
+          return customerCapabilityFetch(io, path, init, authSnapshot);
+        },
+        cli: {
+          catalog,
+          interaction: interaction ?? undefined,
+          completion: async ({ shell }) => completionData(catalog, shell),
+          machineSchema: MACHINE_SCHEMA,
+          session: (command, sessionInput) =>
+            executeSessionCommand(command, sessionInput, {
+              ...executionRuntime,
+              sessionSnapshot: authSnapshot,
+            }),
+          updateChannel: UPDATE_CHANNEL,
+          version,
+        },
+      },
+      parsedInput
+    );
+  } finally {
+    interaction?.close();
+  }
+  if (audience === "customer") assertCustomerResultSafe(data);
+  if (audience === "admin" || sessionCommand || isInteractionExecution(data)) return data;
+  return {
+    action: null,
+    data,
+    errors: [],
+    exitCode: CLI_EXIT_STATUS.success,
+    outcome: { class: "ready", phase: "complete" },
+    page: null,
+    presentation: null,
+    resume: null,
+  };
+}
+
+async function resolveAdminRole(io) {
+  await cliRequest({
+    endpoint: "/v1/staff/context",
+    env: io.env,
+    fetchImpl: io.fetchImpl,
+    method: "HEAD",
+    raw: true,
+  });
+  return "admin";
+}
+
+export async function runCatalogCli(argv, io, { version }) {
+  const capabilities = await loadCapabilities();
+  const catalog = capabilities.catalog;
+  const parsed = extractFormat(argv);
+  const request = resolveRequest(
+    catalog,
+    parsed.remaining,
+    capabilities.findLegacyCliMigration,
+    capabilities.CLI_MIGRATION_GUIDE_URL
+  );
+
+  const stdin = io.stdin ?? process.stdin;
+  const stdout = io.stdout ?? process.stdout;
+  const stderr = io.stderr ?? process.stderr;
+  const format = parsed.format ?? "human";
+  const machine = format === "json" || format === "ndjson";
+  const eligibleHuman = !machine && stdin.isTTY === true && stdout.isTTY === true;
+  if (parsed.error) {
+    const modeled = modeledError(parsed.error);
+    if (machine) {
+      writeMachine(stdout, format, errorEnvelope(request.command, modeled));
+    } else {
+      stderr.write(`${modeled.error.message}\n`);
+    }
+    return {
+      exitCode: modeled.exitCode,
+      suppressUpdateNotification: true,
+    };
+  }
+  const customerRawPrint =
+    request.kind === "command" &&
+    request.capability.id === "vpn.connections.configure" &&
+    parsed.remaining.includes("--print");
+  const rawPrint =
+    (request.kind === "admin" && parsed.remaining.includes("--print")) || customerRawPrint;
+  const unformattedUpdate = request.kind === "command" && request.capability.id === "cli.update";
+  if (
+    parsed.format === undefined &&
+    !eligibleHuman &&
+    !rawPrint &&
+    !unformattedUpdate &&
+    request.kind !== "error"
+  ) {
+    stderr.write(
+      "Output format is required outside an interactive terminal. Choose --format human, --format json, or --format ndjson.\n"
+    );
+    return {
+      exitCode: CLI_EXIT_STATUS.usage,
+      suppressUpdateNotification: true,
+    };
+  }
+
+  const success = {
+    exitCode: CLI_EXIT_STATUS.success,
+    suppressUpdateNotification: machine,
+  };
+  let activeCommand = request.command;
+  try {
+    if (request.kind === "error") throw request.error;
+    if (request.kind === "root") {
+      const data = rootData(catalog);
+      if (machine) writeMachine(stdout, format, resultEnvelope(request.command, data));
+      else writeRootHuman(stdout, catalog);
+      return success;
+    }
+    if (request.kind === "help") {
+      const data = commandData(request.capability);
+      if (machine) writeMachine(stdout, format, resultEnvelope(request.command, data));
+      else writeHelpHuman(stdout, request.capability);
+      return success;
+    }
+    if (request.kind === "help-group") {
+      const data = groupData(request.path, request.capabilities);
+      if (machine) writeMachine(stdout, format, resultEnvelope(request.command, data));
+      else writeGroupHelpHuman(stdout, request.path, request.capabilities);
+      return success;
+    }
+    if (request.kind === "command" && request.capability.id === "cli.update") {
+      if (machine) {
+        throw new VnextUsageError("ornn update supports human output only. Use --format human.", {
+          field: "format",
+        });
+      }
+      const input = parseCapabilityInput(
+        request.capability,
+        parseSemanticArguments(request.argv ?? [])
+      );
+      const exitCode = await updateCommand({
+        allowMajor: input.major === true,
+        binPath: io.binPath ?? process.argv[1],
+        currentVersion: version,
+        env: io.env,
+        fetchImpl: io.fetchImpl,
+        platform: io.platform,
+        spawnProcess: io.spawnProcess,
+        stderr,
+        stdout,
+      });
+      return {
+        exitCode,
+        suppressUpdateNotification: true,
+      };
+    }
+    if (request.kind === "admin") {
+      const earlyCommand = adminCommandName(catalog, request.argv);
+      if (earlyCommand) activeCommand = earlyCommand;
+      preflightAdminCommand(catalog, request.argv, {
+        eligibleHuman,
+        machine,
+      });
+      const role = await resolveAdminRole(io);
+      const adminRequest = resolveAdminRequest(catalog, capabilities.ADMIN_CLI_ROOTS, request.argv);
+      activeCommand = adminRequest.command;
+      if (adminRequest.kind === "root") {
+        const data = adminRootData(catalog, capabilities.ADMIN_CLI_ROOTS, adminRequest.root);
+        if (machine) writeMachine(stdout, format, resultEnvelope(adminRequest.command, data));
+        else writeAdminRootHuman(stdout, data);
+        return success;
+      }
+      if (adminRequest.kind === "help") {
+        const data = adminCommandData(adminRequest.capability);
+        if (machine) writeMachine(stdout, format, resultEnvelope(adminRequest.command, data));
+        else writeAdminHelpHuman(stdout, adminRequest.capability);
+        return success;
+      }
+      const execute = (input, { confirmed = false, transport } = {}) =>
+        executeCapability(adminRequest.capability, catalog, io, version, {
+          audience: "admin",
+          confirmed,
+          executionRuntime: transport ? { transport } : undefined,
+          input,
+          role,
+        });
+      const fetch = (path, init = {}) =>
+        operatorRequest({
+          endpoint: path,
+          env: io.env,
+          fetchImpl: io.fetchImpl,
+          method: init.method ?? "GET",
+          ...(init.body !== undefined ? { body: init.body } : {}),
+          ...(init.headers !== undefined ? { headers: init.headers } : {}),
+          ...(init.signal !== undefined ? { signal: init.signal } : {}),
+        });
+      const execution = adminRequest.handler
+        ? await adminRequest.handler.run({
+            capability: adminRequest.capability,
+            execute,
+            fetch,
+            input: adminRequest.input,
+            mutation: adminRequest.mutation,
+            role,
+            runtime: {
+              eligibleHuman,
+              env: io.env,
+              formatProvided: parsed.format !== undefined,
+              machine,
+              now: io.now,
+              signal: io.signal,
+              sleep: io.sleep,
+              stderr,
+              stdin,
+              stdout,
+            },
+          })
+        : {
+            data: await execute(adminRequest.input),
+            exitCode: CLI_EXIT_STATUS.success,
+            outcome: { class: "ready", phase: "complete" },
+          };
+      if (execution.raw || execution.suppressResult) {
+        return {
+          exitCode: execution.exitCode ?? CLI_EXIT_STATUS.success,
+          suppressUpdateNotification: true,
+        };
+      }
+      const result = finalizeAdminResult(
+        adminRequest.capability,
+        execution.data,
+        execution.pagination ?? adminRequest.pagination
+      );
+      const envelope = {
+        ...resultEnvelope(adminRequest.command, result.data, execution.outcome, result.page),
+        action: execution.action ?? null,
+        errors: execution.errors ?? [],
+        resume: execution.resume ?? null,
+      };
+      if (machine) writeMachine(stdout, format, envelope);
+      else writeAdminResultHuman(stdout, adminRequest.command, result);
+      return {
+        exitCode: execution.exitCode ?? CLI_EXIT_STATUS.success,
+        suppressUpdateNotification:
+          machine || (execution.exitCode ?? CLI_EXIT_STATUS.success) !== CLI_EXIT_STATUS.success,
+      };
+    }
+
+    const authSnapshot = {};
+    const execution = await executeCapability(request.capability, catalog, io, version, {
+      argv: request.argv ?? [],
+      executionRuntime: {
+        authSnapshot,
+        eligibleHuman,
+        env: io.env,
+        fetchImpl: io.fetchImpl,
+        machine,
+        format,
+        formatProvided: parsed.format !== undefined,
+        interactionExtensions: {
+          exportSecret: (options) => exportVpnSecret(options, { machine, stdout }),
+          prepareSecretExport: prepareVpnSecretExport,
+          wireGuardPublicKeyFromFile,
+          hasLocalNetworkAddress,
+          workspaceResume: {
+            clear: (id) =>
+              clearPendingWorkspace(id, {
+                env: io.env,
+                expectedAccessToken: authSnapshot.current?.accessToken,
+              }),
+            load: () => loadPendingWorkspace({ env: io.env, session: authSnapshot.current }),
+            save: (value) =>
+              savePendingWorkspace(value, {
+                env: io.env,
+                expectedAccessToken: authSnapshot.current?.accessToken,
+              }),
+          },
+          launch: (state) =>
+            dispatchLaunchWithHandlers(state, [
+              bareMetalLaunchModeHandler,
+              vmLaunchModeHandler,
+              kubernetesLaunchModeHandler,
+              slurmLaunchModeHandler,
+              ...(io.launchModeHandlers ?? []),
+            ]),
+          sshKeys: (command, input, context) =>
+            executeSshKeyCommand(command, input, context, context.cli.interaction),
+          machines: (command, input, context) =>
+            executeMachineCommand(command, input, context, context.cli.interaction),
+          waitForGoal: (options) =>
+            waitForGoal(options, {
+              format,
+              now: io.now,
+              signal: io.signal,
+              sleep: io.sleep,
+              stderr,
+              stdout,
+            }),
+          resolveConnectTarget: (state) =>
+            resolveConnectTargetWithHandlers(
+              state,
+              io.connectModeHandlers ?? [
+                createSlurmConnectModeHandler({ spawnProcess: io.spawnProcess }),
+                createBareMetalConnectModeHandler({ spawnProcess: io.spawnProcess }),
+                createVmConnectModeHandler({ spawnProcess: io.spawnProcess }),
+                kubernetesConnectModeHandler,
+              ]
+            ),
+          async continueConnect(state) {
+            if (io.connectModeHandlers) {
+              return continueConnectWithHandlers(state, io.connectModeHandlers);
+            }
+            const normalized = {
+              ...state,
+              context: state.context ?? {
+                fetch: (path, init) => customerCapabilityFetch(io, path, init, authSnapshot),
+              },
+              input: state.input ?? this.options,
+              interaction: state.interaction ?? this,
+            };
+            return continueConnectWithHandlers(normalized, [
+              createSlurmConnectModeHandler({ spawnProcess: io.spawnProcess }),
+              createBareMetalConnectModeHandler({ spawnProcess: io.spawnProcess }),
+              createVmConnectModeHandler({ spawnProcess: io.spawnProcess }),
+              kubernetesConnectModeHandler,
+            ]);
+          },
+        },
+        now: io.now,
+        openBrowserImpl: io.openBrowser,
+        sleep: io.sleep,
+        signal: io.signal,
+        stderr,
+        stdin,
+        stdout,
+      },
+    });
+    if (customerRawPrint) {
+      return {
+        exitCode: execution.exitCode ?? CLI_EXIT_STATUS.success,
+        suppressUpdateNotification: true,
+      };
+    }
+    if (machine) writeExecutionMachine(stdout, format, request.command, execution);
+    else writeCommandHuman(stdout, stderr, request.capability, execution);
+    return {
+      exitCode: execution.exitCode,
+      suppressUpdateNotification: machine || execution.exitCode !== CLI_EXIT_STATUS.success,
+    };
+  } catch (error) {
+    const modeled = modeledError(error);
+    if (machine) {
+      writeMachine(stdout, format, errorEnvelope(activeCommand, modeled));
+    } else {
+      stderr.write(`${modeled.error.message}\n`);
+      if (modeled.action?.command) stderr.write(`Next: ${modeled.action.command}\n`);
+    }
+    return { exitCode: modeled.exitCode, suppressUpdateNotification: true };
+  }
+}