@ornncompute/cli 1.0.123 → 1.0.125

package/src/network-commands.mjs

@@ -0,0 +1,1187 @@
+import { getReservation } from "../vendor/api-client/commerce.js";
+import {
+  createNetwork,
+  createNetworkPeer,
+  deleteNetwork,
+  deleteNetworkPeer,
+  getNetwork,
+  listNetworkPeerConfigs,
+  listNetworks,
+  updateNetwork,
+} from "../vendor/api-client/orchestrator.js";
+import { z } from "zod";
+
+const CANONICAL_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const DEFAULT_LIMIT = 50;
+const unknownRecordSchema = z.record(z.string(), z.unknown());
+const MAX_LIMIT = 500;
+
+function responseStatus(error) {
+  if (!error || typeof error !== "object" || !("status" in error)) return null;
+  return typeof error.status === "number" ? error.status : null;
+}
+
+function interaction(context) {
+  // The app-owned runtime extends the shared catalog context only for CLI execution.
+  const cli = context.cli;
+  const runtime = cli?.interaction;
+  if (!runtime)
+    throw new Error("This capability must execute through the Ornn CLI interaction runtime.");
+  return runtime;
+}
+
+function text(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function shellQuote(value) {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function record(value) {
+  const parsed = unknownRecordSchema.safeParse(value);
+  return parsed.success ? parsed.data : {};
+}
+
+function integer(value) {
+  return typeof value === "number" && Number.isInteger(value) ? value : null;
+}
+
+function normalizedName(value) {
+  return value.normalize("NFKC").trim().replace(/\s+/g, " ").toLocaleLowerCase("en-US");
+}
+
+function normalizedCidr(value) {
+  const [address, rawPrefix, ...extra] = value.trim().split("/");
+  const octets = address?.split(".").map(Number) ?? [];
+  const prefix = Number(rawPrefix);
+  if (
+    extra.length ||
+    octets.length !== 4 ||
+    octets.some((octet) => !Number.isInteger(octet) || octet < 0 || octet > 255) ||
+    !Number.isInteger(prefix) ||
+    prefix < 0 ||
+    prefix > 32
+  ) {
+    return value.trim();
+  }
+  const numeric = (((octets[0] * 256 + octets[1]) * 256 + octets[2]) * 256 + octets[3]) >>> 0;
+  const mask = prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0;
+  const network = (numeric & mask) >>> 0;
+  return `${network >>> 24}.${(network >>> 16) & 0xff}.${(network >>> 8) & 0xff}.${network & 0xff}/${prefix}`;
+}
+
+function requiredOption(runtime, value, option, usage) {
+  const parsed = text(value);
+  if (!parsed) runtime.usage(`${option} is required.\n${usage}`, { field: option.slice(2) });
+  return parsed;
+}
+
+function exactPositionals(runtime, positionals, count, usage) {
+  const values = positionals ?? [];
+  if (values.length !== count || values.some((value) => !value.trim())) runtime.usage(usage);
+  return values.map((value) => value.trim());
+}
+
+function requireCanonicalTarget(runtime, value) {
+  if (!CANONICAL_ID.test(value)) {
+    runtime.usage(
+      "Private targets currently require a canonical capacity-reservation identifier so connect cannot select an ambiguous resource.",
+      { code: "canonical_reference_required", field: "target" }
+    );
+  }
+  return value;
+}
+
+function requireMutationKey(runtime, input) {
+  if (!runtime.machine) return text(input.idempotencyKey);
+  const key = text(input.idempotencyKey);
+  if (!key) {
+    runtime.usage(
+      "Machine mutations require --idempotency-key <caller-stable-key> before API I/O.",
+      {
+        code: "idempotency_key_required",
+        field: "idempotencyKey",
+      }
+    );
+  }
+  return key;
+}
+
+function mutationHeaders(key) {
+  return key ? { "Idempotency-Key": key } : undefined;
+}
+
+function lifecycle(statusValue) {
+  const status = text(statusValue)?.toLowerCase() ?? "unknown";
+  if (["active", "ready", "applied", "connected"].includes(status)) {
+    return { class: "ready", phase: "available" };
+  }
+  if (["failed", "degraded", "error"].includes(status)) {
+    return { class: "failed", phase: "needs_attention" };
+  }
+  if (["deleted", "revoked", "disconnected"].includes(status)) {
+    return { class: "ended", phase: "disconnected" };
+  }
+  if (["deleting", "revoking"].includes(status)) {
+    return { class: "working", phase: "disconnecting" };
+  }
+  return { class: "pending", phase: "configuring" };
+}
+function reservationTargetLifecycle(statusValue) {
+  const status = text(statusValue)?.toLowerCase() ?? "unknown";
+  if (status === "active") return { class: "ready", phase: "active" };
+  if (["failed", "payment_failed", "error"].includes(status)) {
+    return { class: "failed", phase: status };
+  }
+  if (
+    ["cancelled", "canceled", "completed", "ended", "expired", "rejected", "terminated"].includes(
+      status
+    )
+  ) {
+    return { class: "ended", phase: status };
+  }
+  return { class: "pending", phase: status };
+}
+
+function projectNetwork(value) {
+  const source = record(value);
+  const attachmentIds = Array.isArray(source.attached_reservation_ids)
+    ? source.attached_reservation_ids
+        .map((value) => text(value))
+        .filter((value) => Boolean(value && CANONICAL_ID.test(value)))
+    : [];
+  return {
+    id: text(source.id),
+    name: text(source.name) ?? "Unnamed private network",
+    cidr: text(source.cidr),
+    lifecycle: lifecycle(source.status),
+    attachment_count: integer(source.attached_reservation_count) ?? attachmentIds.length,
+    attached_reservation_ids: [...new Set(attachmentIds)],
+    created_at: text(source.created_at),
+    updated_at: text(source.updated_at),
+  };
+}
+
+function networkRows(payload) {
+  const source = record(payload);
+  const values = Array.isArray(payload)
+    ? payload
+    : Array.isArray(source.networks)
+      ? source.networks
+      : [];
+  return values
+    .flatMap((value) => {
+      const parsed = unknownRecordSchema.safeParse(value);
+      return parsed.success ? [parsed.data] : [];
+    })
+    .sort((left, right) => {
+      const byName = normalizedName(text(left.name) ?? "").localeCompare(
+        normalizedName(text(right.name) ?? "")
+      );
+      return byName || (text(left.id) ?? "").localeCompare(text(right.id) ?? "");
+    });
+}
+
+function networkFromMutation(payload) {
+  const source = record(payload);
+  return projectNetwork(source.network ?? source);
+}
+
+async function fetchNetworks(context) {
+  return networkRows(await listNetworks(context.fetch));
+}
+
+async function resolveNetwork(context, runtime, reference) {
+  if (CANONICAL_ID.test(reference)) {
+    return record(await getNetwork(context.fetch, reference));
+  }
+  const wanted = normalizedName(reference);
+  const matches = (await fetchNetworks(context)).filter(
+    (candidate) => normalizedName(text(candidate.name) ?? "") === wanted
+  );
+  if (matches.length === 0) {
+    runtime.error(`Private network not found: ${reference}.`, {
+      code: "private_network_not_found",
+    });
+  }
+  if (matches.length > 1) {
+    runtime.usage(
+      `More than one private network has the exact name "${reference}"; use a canonical identifier.`,
+      {
+        code: "private_network_ambiguous",
+        field: "network",
+      }
+    );
+  }
+  return matches[0];
+}
+
+function encodeCursor(command, offset) {
+  return encodeURIComponent(JSON.stringify({ command, offset }));
+}
+
+function decodeCursor(runtime, command, cursor) {
+  if (!cursor) return 0;
+  try {
+    const parsed = record(JSON.parse(decodeURIComponent(cursor)));
+    if (
+      parsed.command === command &&
+      Number.isInteger(parsed.offset) &&
+      Number(parsed.offset) >= 0
+    ) {
+      return Number(parsed.offset);
+    }
+  } catch {
+    // The stable usage error below intentionally hides cursor internals.
+  }
+  runtime.usage("The pagination cursor is invalid or belongs to another command.", {
+    code: "invalid_cursor",
+    field: "cursor",
+  });
+}
+
+function pageLimit(runtime, raw) {
+  if (raw === undefined) return DEFAULT_LIMIT;
+  const limit = Number(raw);
+  if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LIMIT) {
+    runtime.usage(`--limit must be an integer from 1 to ${MAX_LIMIT}.`, { field: "limit" });
+  }
+  return limit;
+}
+
+function page(runtime, command, rows, input) {
+  const limit = pageLimit(runtime, input.limit);
+  const offset = decodeCursor(runtime, command, input.cursor);
+  const items = rows.slice(offset, offset + limit);
+  const nextOffset = offset + items.length;
+  return {
+    items,
+    page: {
+      limit,
+      returned: items.length,
+      next_cursor: nextOffset < rows.length ? encodeCursor(command, nextOffset) : null,
+    },
+  };
+}
+
+function declined(runtime) {
+  return runtime.result({
+    data: null,
+    errors: [{ code: "action_declined", message: "No changes were made.", retryable: false }],
+    exitCode: 1,
+    outcome: { class: "ended", phase: "declined" },
+    presentation: { lines: ["No changes were made."] },
+  });
+}
+
+function networkLines(network) {
+  const state = record(network.lifecycle);
+  return [
+    `${String(network.name)} (${String(network.id ?? "unknown")})`,
+    `  CIDR: ${String(network.cidr ?? "pending")}`,
+    `  State: ${state.class} (${state.phase})`,
+  ];
+}
+
+function networkMutationExecution(runtime, network, replayed) {
+  const state = record(network.lifecycle);
+  const stateClass = String(state.class);
+  const ready = stateClass === "ready";
+  const failed = stateClass === "failed";
+  const command = ready ? "ornn connect" : `ornn private-networks show ${String(network.id)}`;
+  return runtime.result({
+    action: {
+      command,
+      description: ready
+        ? "Continue to an exact compute target."
+        : "Inspect private-network readiness before attaching or connecting.",
+      type: "command",
+    },
+    data: { private_network: network, replayed },
+    exitCode: ready ? 0 : failed ? 4 : 3,
+    outcome: ready
+      ? { class: "ready", phase: "active" }
+      : { class: String(state.class), phase: String(state.phase) },
+    presentation: {
+      lines: [
+        ready
+          ? replayed
+            ? "Private network already satisfies this request."
+            : "Private network created."
+          : failed
+            ? "Private network exists, but provisioning failed."
+            : "Private network creation was accepted and is still provisioning.",
+        ...networkLines(network),
+      ],
+      next: command,
+    },
+    resume: ready ? null : { kind: "private_network", ref: String(network.id) },
+  });
+}
+
+async function listPrivateNetworks(context, input) {
+  const runtime = interaction(context);
+  exactPositionals(
+    runtime,
+    input.$positionals,
+    0,
+    "Usage: ornn private-networks list [--limit <1-500>] [--cursor <cursor>]"
+  );
+  const rows = (await fetchNetworks(context)).map(projectNetwork);
+  const selected = page(runtime, "private-networks list", rows, input);
+  return runtime.result({
+    data: { private_networks: selected.items },
+    page: selected.page,
+    presentation: {
+      lines: selected.items.length
+        ? selected.items.flatMap(networkLines)
+        : ["No private networks found."],
+      ...(selected.page.next_cursor
+        ? { next: `ornn private-networks list --cursor ${selected.page.next_cursor}` }
+        : {}),
+    },
+  });
+}
+
+async function showPrivateNetwork(context, input) {
+  const runtime = interaction(context);
+  const [reference] = exactPositionals(
+    runtime,
+    input.$positionals,
+    1,
+    "Usage: ornn private-networks show <exact-name-or-id>"
+  );
+  const network = projectNetwork(await resolveNetwork(context, runtime, reference));
+  return runtime.result({
+    data: { private_network: network },
+    presentation: { lines: networkLines(network) },
+  });
+}
+
+async function createPrivateNetwork(context, input) {
+  const runtime = interaction(context);
+  const usage = "Usage: ornn private-networks create --name <name> [--cidr <cidr>]";
+  exactPositionals(runtime, input.$positionals, 0, usage);
+  if (!text(input.name) && input.guided === true && !runtime.machine) {
+    input.name = await runtime.ask({ label: "Private network name" });
+  }
+  const name = requiredOption(runtime, input.name, "--name", usage)
+    .normalize("NFKC")
+    .trim()
+    .replace(/\s+/g, " ");
+  const cidr = text(input.cidr) ? normalizedCidr(String(input.cidr)) : null;
+  const idempotencyKey = requireMutationKey(runtime, input);
+  const matches = (await fetchNetworks(context)).filter(
+    (candidate) => normalizedName(text(candidate.name) ?? "") === normalizedName(name)
+  );
+  if (matches.length > 1) {
+    runtime.usage(
+      `More than one private network has the exact name "${name}"; use a different name.`,
+      {
+        code: "private_network_ambiguous",
+        field: "name",
+      }
+    );
+  }
+  if (matches.length === 1) {
+    const existingCidr = text(matches[0].cidr);
+    if (cidr && (!existingCidr || normalizedCidr(existingCidr) !== cidr)) {
+      runtime.usage(
+        `Private network "${name}" already exists with different effective input. Use a new idempotency key and name after review.`,
+        { code: "private_network_replay_conflict", field: "cidr" }
+      );
+    }
+    return networkMutationExecution(runtime, projectNetwork(matches[0]), true);
+  }
+  if (
+    !(await runtime.review({
+      title: "Create private network",
+      terms: [
+        { label: "Name", value: name },
+        { label: "CIDR", value: cidr ?? "Automatically assigned" },
+      ],
+    }))
+  )
+    return declined(runtime);
+  const created = await createNetwork(
+    context.fetch,
+    { name, ...(cidr ? { cidr } : {}) },
+    {
+      headers: mutationHeaders(idempotencyKey),
+    }
+  );
+  return networkMutationExecution(runtime, networkFromMutation(created), false);
+}
+
+async function updatePrivateNetwork(context, input) {
+  const runtime = interaction(context);
+  const usage = "Usage: ornn private-networks update <exact-name-or-id> --name <new-name>";
+  const [reference] = exactPositionals(runtime, input.$positionals, 1, usage);
+  const name = requiredOption(runtime, input.name, "--name", usage)
+    .normalize("NFKC")
+    .trim()
+    .replace(/\s+/g, " ");
+  const idempotencyKey = requireMutationKey(runtime, input);
+  const current = await resolveNetwork(context, runtime, reference);
+  if (normalizedName(text(current.name) ?? "") === normalizedName(name)) {
+    const network = projectNetwork(current);
+    return runtime.result({
+      data: { private_network: network, replayed: true },
+      presentation: {
+        lines: ["Private network already has the requested name.", ...networkLines(network)],
+      },
+    });
+  }
+  if (
+    (await fetchNetworks(context)).some(
+      (candidate) => normalizedName(text(candidate.name) ?? "") === normalizedName(name)
+    )
+  ) {
+    runtime.usage(`Another private network already has the exact name "${name}".`, {
+      code: "private_network_name_conflict",
+      field: "name",
+    });
+  }
+  if (
+    !(await runtime.review({
+      title: "Update private network",
+      terms: [
+        {
+          label: "Private network",
+          value: `${text(current.name) ?? reference} (${text(current.id) ?? reference})`,
+        },
+        { label: "New name", value: name },
+      ],
+    }))
+  )
+    return declined(runtime);
+  const updated = await updateNetwork(
+    context.fetch,
+    String(current.id),
+    { name },
+    {
+      headers: mutationHeaders(idempotencyKey),
+    }
+  );
+  const network = networkFromMutation(updated);
+  return runtime.result({
+    data: { private_network: network, replayed: false },
+    presentation: { lines: ["Private network updated.", ...networkLines(network)] },
+  });
+}
+
+async function deletePrivateNetwork(context, input) {
+  const runtime = interaction(context);
+  const [reference] = exactPositionals(
+    runtime,
+    input.$positionals,
+    1,
+    "Usage: ornn private-networks delete <exact-name-or-id>"
+  );
+  const idempotencyKey = requireMutationKey(runtime, input);
+  const projected = projectNetwork(await resolveNetwork(context, runtime, reference));
+  if (
+    !(await runtime.review({
+      title: "Delete private network",
+      terms: [
+        { label: "Private network", value: `${String(projected.name)} (${String(projected.id)})` },
+        {
+          label: "Consequence",
+          value:
+            "Permanently delete this organization private network when the owner permits deletion.",
+        },
+      ],
+      prompt: "Delete this private network?",
+    }))
+  )
+    return declined(runtime);
+  await deleteNetwork(context.fetch, String(projected.id), {
+    headers: mutationHeaders(idempotencyKey),
+  });
+  return runtime.result({
+    data: { deleted: true, private_network: projected },
+    outcome: { class: "ended", phase: "deleted" },
+    presentation: {
+      lines: [`Private network deleted: ${String(projected.name)} (${String(projected.id)})`],
+    },
+  });
+}
+
+function vpnPayloadRows(payload) {
+  const source = record(payload);
+  const peers = Array.isArray(source.peers) ? source.peers : [];
+  return peers.flatMap((value) => {
+    const parsed = unknownRecordSchema.safeParse(value);
+    return parsed.success ? [parsed.data] : [];
+  });
+}
+
+function vpnPeer(payload) {
+  const peer = record(payload.peer);
+  return Object.keys(peer).length ? peer : payload;
+}
+
+function projectVpnConnection(payload, reservationId) {
+  const peer = vpnPeer(payload);
+  const network = record(payload.network);
+  return {
+    id: text(peer.id),
+    name: text(peer.label) ?? "VPN connection",
+    reservation_id: reservationId,
+    private_network_id: text(network.network_id) ?? text(network.id),
+    assigned_address: text(peer.assigned_ip),
+    lifecycle: lifecycle(peer.status),
+    created_at: text(peer.created_at),
+  };
+}
+
+function vpnLines(connection) {
+  const state = record(connection.lifecycle);
+  return [
+    `${String(connection.name)} (${String(connection.id ?? "unknown")})`,
+    `  Private target: ${String(connection.reservation_id)}`,
+    `  State: ${state.class} (${state.phase})`,
+  ];
+}
+
+async function listVpnPayloads(context) {
+  return vpnPayloadRows(await listNetworkPeerConfigs(context.fetch, "shared"));
+}
+
+async function listVpnConnections(context, input) {
+  const runtime = interaction(context);
+  const [rawTarget] = exactPositionals(
+    runtime,
+    input.$positionals,
+    1,
+    "Usage: ornn vpn-connections list <canonical-reservation-id> [--limit <1-500>] [--cursor <cursor>]"
+  );
+  const target = requireCanonicalTarget(runtime, rawTarget);
+  const connections = (await listVpnPayloads(context))
+    .map((payload) => projectVpnConnection(payload, target))
+    .sort((left, right) =>
+      normalizedName(String(left.name)).localeCompare(normalizedName(String(right.name)))
+    );
+  const selected = page(runtime, "vpn-connections list", connections, input);
+  return runtime.result({
+    data: { vpn_connections: selected.items },
+    page: selected.page,
+    presentation: {
+      lines: selected.items.length
+        ? selected.items.flatMap(vpnLines)
+        : [`No VPN connections found for private target ${target}.`],
+      ...(selected.page.next_cursor
+        ? { next: `ornn vpn-connections list ${target} --cursor ${selected.page.next_cursor}` }
+        : {}),
+    },
+  });
+}
+
+function validateSecretExport(runtime, input) {
+  const hasOutput = Boolean(text(input.output));
+  const shouldPrint = input.print === true;
+  if (hasOutput === shouldPrint) {
+    runtime.usage(
+      "Choose exactly one explicit VPN configuration destination: --print or --output <path>.",
+      {
+        code: "secret_destination_required",
+        field: "output",
+      }
+    );
+  }
+  if (shouldPrint && runtime.formatProvided) {
+    runtime.usage("--print is incompatible with an explicit --format.", {
+      code: "secret_print_format_conflict",
+      field: "format",
+    });
+  }
+  if (runtime.machine && shouldPrint) {
+    runtime.usage(
+      "Machine mode cannot mix secret bytes with a result envelope; use --output <path>.",
+      {
+        code: "secret_print_unsupported_in_machine_mode",
+        field: "print",
+      }
+    );
+  }
+  if (
+    !runtime.exportSecret ||
+    !runtime.prepareSecretExport ||
+    !runtime.wireGuardPublicKeyFromFile
+  ) {
+    runtime.error("The CLI secret-output service is unavailable.", {
+      code: "secret_output_unavailable",
+      exitCode: 6,
+      retryable: true,
+    });
+  }
+}
+async function prepareVpnExport(runtime, input) {
+  try {
+    await runtime.prepareSecretExport({
+      outputPath: text(input.output) ?? undefined,
+      overwrite: input.overwrite === true,
+      print: input.print === true,
+    });
+  } catch (error) {
+    const code = error && typeof error === "object" && "code" in error ? text(error.code) : null;
+    const message =
+      error instanceof Error && error.message
+        ? error.message
+        : "Could not prepare the VPN configuration destination.";
+    runtime.error(message, { code: code ?? "vpn_configuration_export_failed" });
+  }
+}
+
+async function exportVpnConfig(runtime, input, content, privateKeyPath, publicKey) {
+  const config = typeof content === "string" && content.length > 0 ? content : null;
+  if (!config) {
+    runtime.error("Ornn did not return a usable VPN configuration.", {
+      code: "vpn_configuration_unavailable",
+      exitCode: 6,
+      retryable: true,
+    });
+  }
+  try {
+    return await runtime.exportSecret({
+      content: config,
+      outputPath: text(input.output) ?? undefined,
+      overwrite: input.overwrite === true,
+      print: input.print === true,
+      privateKeyPath,
+      publicKey,
+    });
+  } catch (error) {
+    const code = error && typeof error === "object" && "code" in error ? text(error.code) : null;
+    const message =
+      error instanceof Error && error.message
+        ? error.message
+        : "Could not export the VPN configuration.";
+    runtime.error(message, { code: code ?? "vpn_configuration_export_failed" });
+  }
+}
+
+function vpnConfigureExecution(runtime, target, connection, exported, replayed) {
+  const state = record(connection.lifecycle);
+  const stateClass = String(state.class);
+  const ready = stateClass === "ready";
+  const failed = stateClass === "failed";
+  const activationCommand = exported.path
+    ? `sudo wg-quick up ${shellQuote(exported.path)}`
+    : "sudo wg-quick up <saved-configuration-path>";
+  const action = ready
+    ? {
+        command: activationCommand,
+        description: "Activate the completed local WireGuard configuration before connecting.",
+        type: "command",
+      }
+    : {
+        command: `ornn vpn-connections configure ${target} --guided`,
+        description: failed
+          ? "Retry applying this exact VPN peer with its original private key."
+          : "Reapply this pending VPN peer after gateway readiness is restored.",
+        type: "command",
+      };
+  return runtime.result({
+    action,
+    data: { export: exported, replayed, vpn_connection: connection },
+    exitCode: ready ? 3 : failed ? 4 : 3,
+    outcome: ready
+      ? { class: "action_required", phase: "local_vpn_activation_required" }
+      : { class: String(state.class), phase: String(state.phase) },
+    presentation: {
+      lines: [
+        ready
+          ? replayed
+            ? "VPN configuration exported again; local tunnel activation is still required."
+            : "VPN peer is active and the complete local configuration was exported."
+          : failed
+            ? "VPN connection was saved, but the gateway rejected or could not apply it."
+            : "VPN connection was saved and is waiting for gateway application.",
+        ...vpnLines(connection),
+        `Configuration fingerprint: ${exported.fingerprint}`,
+        ...(exported.path ? [`Configuration written to ${exported.path} (${exported.mode}).`] : []),
+      ],
+      next: action.command,
+    },
+    resume: ready
+      ? { kind: "connect", ref: target }
+      : { kind: "vpn_connection", ref: String(connection.id) },
+  });
+}
+
+async function configureVpnConnection(context, input) {
+  const runtime = interaction(context);
+  const usage =
+    "Usage: ornn vpn-connections configure <canonical-reservation-id> --name <name> --private-key <path> (--print | --output <path>)";
+  const [rawTarget] = exactPositionals(runtime, input.$positionals, 1, usage);
+  const target = requireCanonicalTarget(runtime, rawTarget);
+  if (input.guided === true && !runtime.machine) {
+    input.name ??= await runtime.ask({ label: "VPN connection name" });
+    input.privateKey ??= await runtime.ask({ label: "WireGuard private-key path" });
+    if (input.print !== true && !text(input.output)) {
+      input.output = await runtime.ask({ label: "VPN configuration output path" });
+    }
+  }
+  const name = requiredOption(runtime, input.name, "--name", usage)
+    .normalize("NFKC")
+    .trim()
+    .replace(/\s+/g, " ");
+  const privateKeyPath = requiredOption(runtime, input.privateKey, "--private-key", usage);
+  validateSecretExport(runtime, input);
+  await prepareVpnExport(runtime, input);
+  let publicKey = "";
+  try {
+    publicKey = await runtime.wireGuardPublicKeyFromFile(privateKeyPath);
+  } catch (error) {
+    const code = error && typeof error === "object" && "code" in error ? text(error.code) : null;
+    const message =
+      error instanceof Error && error.message
+        ? error.message
+        : "Could not read the WireGuard private key.";
+    runtime.error(message, { code: code ?? "invalid_wireguard_private_key", field: "privateKey" });
+  }
+  const idempotencyKey = requireMutationKey(runtime, input);
+  const existing = await listVpnPayloads(context);
+  const sameKey = existing.find((payload) => text(vpnPeer(payload).public_key) === publicKey);
+  let effectiveName = name;
+  if (sameKey) {
+    const existingName = text(vpnPeer(sameKey).label) ?? "VPN connection";
+    effectiveName = existingName;
+    if (normalizedName(existingName) !== normalizedName(name)) {
+      runtime.usage(
+        "This public key already identifies a VPN connection with a different name. Use the original effective input or a new key after review.",
+        { code: "vpn_connection_replay_conflict", field: "name" }
+      );
+    }
+  } else if (
+    existing.some(
+      (payload) =>
+        normalizedName(text(vpnPeer(payload).label) ?? "VPN connection") === normalizedName(name)
+    )
+  ) {
+    runtime.usage(`A VPN connection named "${name}" already exists with different key material.`, {
+      code: "vpn_connection_name_conflict",
+      field: "name",
+    });
+  }
+  if (sameKey && lifecycle(text(vpnPeer(sameKey).status)).class === "ready") {
+    const exported = await exportVpnConfig(
+      runtime,
+      input,
+      sameKey.config,
+      privateKeyPath,
+      publicKey
+    );
+    return vpnConfigureExecution(
+      runtime,
+      target,
+      projectVpnConnection(sameKey, target),
+      exported,
+      true
+    );
+  }
+  if (
+    !(await runtime.review({
+      title: sameKey ? "Retry VPN connection" : "Configure VPN connection",
+      terms: [
+        { label: "Private target", value: target },
+        { label: "VPN connection", value: name },
+        { label: "WireGuard public key", value: publicKey },
+        {
+          label: "Configuration destination",
+          value: input.print ? "Terminal (explicit --print)" : String(input.output),
+        },
+      ],
+    }))
+  )
+    return declined(runtime);
+  const applied = record(
+    await createNetworkPeer(
+      context.fetch,
+      "shared",
+      { label: effectiveName, public_key: publicKey },
+      {
+        headers: mutationHeaders(idempotencyKey),
+      }
+    )
+  );
+  const exported = await exportVpnConfig(runtime, input, applied.config, privateKeyPath, publicKey);
+  const connection = projectVpnConnection(applied, target);
+  return vpnConfigureExecution(runtime, target, connection, exported, Boolean(sameKey));
+}
+
+async function disconnectVpnConnection(context, input) {
+  const runtime = interaction(context);
+  const [rawTarget, reference] = exactPositionals(
+    runtime,
+    input.$positionals,
+    2,
+    "Usage: ornn vpn-connections disconnect <canonical-reservation-id> <exact-name-or-id>"
+  );
+  const target = requireCanonicalTarget(runtime, rawTarget);
+  const idempotencyKey = requireMutationKey(runtime, input);
+  const matches = (await listVpnPayloads(context)).filter((payload) => {
+    const peer = vpnPeer(payload);
+    return CANONICAL_ID.test(reference)
+      ? text(peer.id) === reference
+      : normalizedName(text(peer.label) ?? "VPN connection") === normalizedName(reference);
+  });
+  if (matches.length === 0)
+    runtime.error(`VPN connection not found: ${reference}.`, { code: "vpn_connection_not_found" });
+  if (matches.length > 1) {
+    runtime.usage(
+      `More than one VPN connection has the exact name "${reference}"; use a canonical identifier.`,
+      {
+        code: "vpn_connection_ambiguous",
+        field: "connection",
+      }
+    );
+  }
+  const connection = projectVpnConnection(matches[0], target);
+  if (
+    !(await runtime.review({
+      title: "Disconnect VPN connection",
+      terms: [
+        { label: "Private target", value: target },
+        { label: "VPN connection", value: `${String(connection.name)} (${String(connection.id)})` },
+        {
+          label: "Consequence",
+          value: "Private access through this VPN connection ends; the private network remains.",
+        },
+      ],
+    }))
+  )
+    return declined(runtime);
+  await deleteNetworkPeer(context.fetch, "shared", String(connection.id), {
+    headers: mutationHeaders(idempotencyKey),
+  });
+  return runtime.result({
+    data: { disconnected: true, vpn_connection: connection },
+    outcome: { class: "ended", phase: "disconnected" },
+    presentation: {
+      lines: [`VPN connection disconnected: ${String(connection.name)} (${String(connection.id)})`],
+    },
+  });
+}
+
+function normalizedConnectAccessMode(value) {
+  const mode = text(value)?.toLowerCase();
+  return mode === "virtual-machine" ? "vm" : (mode ?? null);
+}
+
+function validateKnownConnectMode(runtime, input, mode) {
+  if (mode === "vm" || mode === "bare-metal" || mode === "slurm") {
+    if (input.output || input.overwrite) {
+      runtime.usage(
+        `${mode === "slurm" ? "Slurm" : mode === "vm" ? "VM" : "Bare Metal"} connect uses native SSH and does not write an output file.`,
+        {
+          code: mode === "slurm" ? "slurm_output_unsupported" : "direct_machine_output_unsupported",
+          field: input.output ? "output" : "overwrite",
+        }
+      );
+    }
+    return;
+  }
+  if (mode === "kubernetes" && (input.identityFile || input.user || input.print)) {
+    runtime.usage(
+      "Kubernetes connect writes a kubeconfig and does not accept SSH identity, user, or print options.",
+      {
+        code: input.print ? "kubeconfig_output_required" : "kubernetes_ssh_options_unsupported",
+        field: input.identityFile ? "identityFile" : input.user ? "user" : "output",
+      }
+    );
+  }
+}
+
+function blockedPrivateTransport(runtime, lifecycleValue, action, data, reservationId) {
+  const state = record(lifecycleValue);
+  const outcome = {
+    class: text(state.class) ?? "pending",
+    phase: text(state.phase) ?? "configuring",
+  };
+  return runtime.result({
+    action,
+    data,
+    exitCode: ["failed", "ended"].includes(outcome.class) ? 1 : 3,
+    outcome,
+    resume: { kind: "connect", ref: reservationId },
+  });
+}
+
+function compareVpnConnections(left, right) {
+  return (
+    (text(left.created_at) ?? "").localeCompare(text(right.created_at) ?? "") ||
+    (text(left.id) ?? "").localeCompare(text(right.id) ?? "") ||
+    normalizedName(text(left.name) ?? "").localeCompare(normalizedName(text(right.name) ?? ""))
+  );
+}
+
+async function connectPrivateTarget(context, input) {
+  const runtime = interaction(context);
+  const values = input.$positionals ?? [];
+  if (values.length > 1) {
+    runtime.usage("Usage: ornn connect [<exact-hostname-or-canonical-machine-id>]", {
+      code: "usage_error",
+    });
+  }
+  const rawTarget = text(values[0]);
+  let resolved = null;
+  let target = rawTarget;
+  if (runtime.resolveConnectTarget) {
+    resolved = await runtime.resolveConnectTarget({
+      context,
+      input,
+      interaction: runtime,
+      reference: rawTarget,
+    });
+    if (resolved) {
+      validateKnownConnectMode(runtime, input, normalizedConnectAccessMode(resolved.mode));
+    }
+    if (resolved && resolved.privateTransportRequired !== true && runtime.continueConnect) {
+      const direct = await runtime.continueConnect(resolved);
+      if (direct) return runtime.result(direct);
+    }
+    if (resolved) target = resolved.reservationId;
+  }
+  if (!resolved && rawTarget && CANONICAL_ID.test(rawTarget)) {
+    try {
+      const reservation = await getReservation(context.fetch, rawTarget);
+      const reservationId = text(reservation.reservationId);
+      if (reservationId && reservationId !== rawTarget) {
+        runtime.error("The gateway returned a different capacity reservation.", {
+          code: "reservation_correlation_changed",
+        });
+      }
+      const status = text(reservation.status)?.toLowerCase() ?? "unknown";
+      const mode = normalizedConnectAccessMode(reservation.provisioningType);
+      if (status !== "active") {
+        const state = reservationTargetLifecycle(status);
+        const waiting = state.class === "pending" || state.class === "working";
+        return runtime.result({
+          action: waiting
+            ? {
+                command: `ornn reservations show ${reservationId ?? rawTarget}`,
+                description:
+                  "Wait for the capacity reservation to become active before launching native compute.",
+                type: "command",
+              }
+            : null,
+          data: {
+            capacity_reservation: {
+              id: reservationId ?? rawTarget,
+              access_mode: mode,
+              lifecycle: state,
+            },
+          },
+          exitCode: waiting ? 3 : 1,
+          outcome: state,
+          presentation: {
+            lines: [
+              waiting
+                ? `Capacity reservation ${reservationId ?? rawTarget} is not active yet; it has no native-access target.`
+                : `Capacity reservation ${reservationId ?? rawTarget} is ${state.phase}; it has no launchable native-access target.`,
+            ],
+          },
+          resume: waiting ? { kind: "reservation", ref: reservationId ?? rawTarget } : null,
+        });
+      }
+      validateKnownConnectMode(runtime, input, mode);
+      return runtime.actionRequired({
+        action: {
+          command: "ornn launch",
+          description:
+            "Launch compute for this capacity reservation before requesting native access.",
+          type: "command",
+        },
+        data: {
+          capacity_reservation: {
+            id: reservationId ?? rawTarget,
+            access_mode: mode,
+          },
+        },
+        resume: { kind: "reservation", ref: reservationId ?? rawTarget },
+      });
+    } catch (error) {
+      if (![400, 404, 422].includes(responseStatus(error) ?? 0)) throw error;
+    }
+  }
+  const privateTarget = target ?? "";
+  if (!privateTarget || !CANONICAL_ID.test(privateTarget)) {
+    runtime.usage(
+      "Connect requires an exact unique hostname, canonical machine ID, or eligible guided choice.",
+      {
+        code: "invalid_reference",
+        field: "machine",
+      }
+    );
+  }
+
+  // A UUID and an organization network do not prove that this target exists.
+  // Only a resolved native target may continue into private transport setup.
+  if (!resolved) {
+    runtime.error("No accessible machine, cluster, or capacity reservation matches this target.", {
+      code: "connect_target_not_found",
+    });
+  }
+
+  const shared = record(await getNetwork(context.fetch, "shared"));
+  const privateNetwork = projectNetwork({
+    ...record(shared.network),
+    id: "shared",
+    name: "Organization private network",
+  });
+  const networkState = record(privateNetwork.lifecycle);
+  if (networkState.class !== "ready") {
+    const recoverable = ["failed", "ended"].includes(String(networkState.class));
+    return blockedPrivateTransport(
+      runtime,
+      networkState,
+      {
+        command: `ornn vpn-connections list ${privateTarget}`,
+        description: recoverable
+          ? "Inspect organization VPN connectivity before retrying."
+          : "Wait for organization networking to become ready, then retry connect.",
+        type: "command",
+      },
+      {
+        private_network: privateNetwork,
+        private_target: { reservation_id: privateTarget },
+        vpn_connection: null,
+      },
+      privateTarget
+    );
+  }
+  const connections = (await listVpnPayloads(context))
+    .map((payload) => projectVpnConnection(payload, privateTarget))
+    .sort(compareVpnConnections);
+  if (connections.length === 0) {
+    return runtime.actionRequired({
+      action: {
+        command: `ornn vpn-connections configure ${privateTarget} --guided`,
+        description:
+          "Provide one VPN peer and explicit configuration destination, then retry connect.",
+        type: "command",
+      },
+      data: {
+        private_network: privateNetwork,
+        private_target: { reservation_id: privateTarget },
+        vpn_connection: null,
+      },
+      resume: { kind: "connect", ref: privateTarget },
+    });
+  }
+  const readyConnections = connections.filter(
+    (connection) => record(connection.lifecycle).class === "ready"
+  );
+  if (readyConnections.length === 0) {
+    const connection =
+      connections.find((candidate) =>
+        ["pending", "working"].includes(String(record(candidate.lifecycle).class))
+      ) ??
+      connections.find((candidate) => record(candidate.lifecycle).class === "failed") ??
+      connections[0];
+    const state = record(connection.lifecycle);
+    const stateClass = String(state.class);
+    const id = text(connection.id);
+    const failed = stateClass === "failed";
+    const ended = stateClass === "ended";
+    const action =
+      failed && id
+        ? {
+            command: `ornn vpn-connections disconnect ${privateTarget} ${id}`,
+            description: "Remove the failed VPN connection before configuring a replacement.",
+            type: "command",
+          }
+        : ended
+          ? {
+              command: `ornn vpn-connections configure ${privateTarget} --guided`,
+              description: "Configure a new VPN connection, then retry connect.",
+              type: "command",
+            }
+          : {
+              command: `ornn vpn-connections configure ${privateTarget} --guided`,
+              description: "Reapply the pending VPN connection, then retry connect.",
+              type: "command",
+            };
+    return blockedPrivateTransport(
+      runtime,
+      state,
+      action,
+      {
+        private_network: privateNetwork,
+        private_target: { reservation_id: privateTarget },
+        vpn_connection: connection,
+      },
+      privateTarget
+    );
+  }
+  const connection =
+    readyConnections.find((candidate) => {
+      const address = text(candidate.assigned_address);
+      return Boolean(address && runtime.hasLocalNetworkAddress?.(address) === true);
+    }) ?? readyConnections[0];
+  const assignedAddress = text(connection.assigned_address);
+  if (!assignedAddress || runtime.hasLocalNetworkAddress?.(assignedAddress) !== true) {
+    return runtime.actionRequired({
+      action: {
+        command: `ornn vpn-connections configure ${privateTarget} --guided`,
+        description:
+          "Export a complete WireGuard configuration, activate it locally, then retry connect.",
+        type: "command",
+      },
+      data: {
+        private_network: privateNetwork,
+        private_target: { reservation_id: privateTarget },
+        vpn_connection: connection,
+      },
+      resume: { kind: "connect", ref: privateTarget },
+    });
+  }
+  if (runtime.continueConnect) {
+    const continuation = await runtime.continueConnect({
+      ...(resolved ?? {}),
+      privateNetwork,
+      reservationId: privateTarget,
+      vpnConnection: connection,
+    });
+    if (continuation) return runtime.result(continuation);
+  }
+  return runtime.result({
+    data: {
+      private_network: privateNetwork,
+      private_target: { reservation_id: privateTarget },
+      vpn_connection: connection,
+    },
+    outcome: { class: "ready", phase: "private_transport_ready" },
+    presentation: {
+      lines: ["VPN connection is ready for private access.", ...vpnLines(connection)],
+    },
+  });
+}
+
+export function executeNetworkCommand(command, input, context) {
+  switch (command) {
+    case "private-networks list":
+      return listPrivateNetworks(context, input);
+    case "private-networks show":
+      return showPrivateNetwork(context, input);
+    case "private-networks create":
+      return createPrivateNetwork(context, input);
+    case "private-networks update":
+      return updatePrivateNetwork(context, input);
+    case "private-networks delete":
+      return deletePrivateNetwork(context, input);
+    case "vpn-connections list":
+      return listVpnConnections(context, input);
+    case "vpn-connections configure":
+      return configureVpnConnection(context, input);
+    case "vpn-connections disconnect":
+      return disconnectVpnConnection(context, input);
+    case "connect":
+      return connectPrivateTarget(context, input);
+    default:
+      throw new Error(`Unsupported network command: ${command}`);
+  }
+}