@ornncompute/cli 0.2.24 → 1.0.34

package/src/launch-mode-handlers.mjs

@@ -0,0 +1,119 @@
+const MODE_LABELS = {
+  "bare-metal": "Bare Metal",
+  kubernetes: "Kubernetes",
+  slurm: "Slurm",
+  vm: "VM",
+};
+
+const COMMON_OPTIONS = [
+  "$positionals",
+  "guided",
+  "idempotencyKey",
+  "mode",
+  "noWait",
+  "organization",
+  "reservation",
+  "timeout",
+  "wait",
+  "yes",
+];
+const KEY_OPTIONS = ["key", "keyId", "label", "publicKey", "publicKeyFile"];
+const MODE_OPTIONS = new Map([
+  ["vm", new Set([...COMMON_OPTIONS, ...KEY_OPTIONS, "username"])],
+  [
+    "bare-metal",
+    new Set([
+      ...COMMON_OPTIONS,
+      ...KEY_OPTIONS,
+      "mountAccess",
+      "network",
+      "resume",
+      "username",
+      "volume",
+    ]),
+  ],
+  ["kubernetes", new Set([...COMMON_OPTIONS, "machine", "machines", "network", "nodes"])],
+  [
+    "slurm",
+    new Set([...COMMON_OPTIONS, ...KEY_OPTIONS, "machine", "machines", "network", "nodes"]),
+  ],
+]);
+const OPTION_FLAGS = {
+  idempotencyKey: "--idempotency-key",
+  keyId: "--key-id",
+  mountAccess: "--mount-access",
+  noWait: "--no-wait",
+  publicKey: "--public-key",
+  publicKeyFile: "--public-key-file",
+};
+
+function rejectUnsupportedModeOptions(state, mode) {
+  const allowed = MODE_OPTIONS.get(mode);
+  if (!allowed) return;
+  const unsupported = Object.entries(state.input).find(
+    ([key, value]) => value !== undefined && !allowed.has(key)
+  );
+  if (!unsupported) return;
+  const [field] = unsupported;
+  const flag =
+    OPTION_FLAGS[field] ?? `--${field.replace(/[A-Z]/g, (value) => `-${value.toLowerCase()}`)}`;
+  state.interaction.usage(`${MODE_LABELS[mode]} launch does not accept ${flag}.`, {
+    code: "unsupported_launch_option",
+    field,
+  });
+}
+
+/**
+ * The single `ornn launch` extension seam. Mode modules export a handler with:
+ *
+ *   { mode, launch({ mode, input, context, interaction }) }
+ *
+ * A handler may supply `matches(state)` when one catalog mode needs more than
+ * an exact string match. The dispatcher owns explicit mode selection and never
+ * falls back from an unsupported mode to another lifecycle.
+ */
+export async function dispatchLaunchWithHandlers(state, handlers = []) {
+  const valid = handlers.map((handler) => {
+    if (!handler || typeof handler.mode !== "string" || typeof handler.launch !== "function") {
+      throw new TypeError("Launch mode handlers require mode and launch(state).");
+    }
+    return handler;
+  });
+  const modes = [...new Set(valid.map((handler) => handler.mode))];
+  if (modes.length !== valid.length) {
+    throw new TypeError("Launch mode handlers must own unique modes.");
+  }
+  let mode = typeof state.input.mode === "string" ? state.input.mode.trim().toLowerCase() : "";
+  if (!mode) {
+    if (!state.interaction.eligibleHuman || state.interaction.machine) {
+      state.interaction.usage("--mode is required for launch automation.", {
+        code: "access_mode_required",
+        field: "mode",
+      });
+    }
+    mode = await state.interaction.ask({
+      label: "Access mode",
+      choices: modes.map((value) => ({ label: MODE_LABELS[value] ?? value, value })),
+    });
+    if (!mode) {
+      state.interaction.usage("Choose an explicit access mode before launch.", {
+        code: "access_mode_required",
+        field: "mode",
+      });
+    }
+  }
+  rejectUnsupportedModeOptions(state, mode);
+
+  const withMode = { ...state, mode };
+  for (const handler of valid) {
+    const matches =
+      typeof handler.matches === "function"
+        ? await handler.matches(withMode)
+        : handler.mode === mode;
+    if (matches) return handler.launch(withMode);
+  }
+  state.interaction.usage(
+    `Unsupported launch mode: ${mode}. Choose ${modes.join(", ") || "a registered mode"}.`,
+    { code: "unsupported_access_mode", field: "mode" }
+  );
+}

package/src/machine-reference.mjs

@@ -0,0 +1,285 @@
+import { gpuLabeler } from "./gpu-catalog.mjs";
+
+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 PAGE_SIZE = 500;
+const MAX_RESERVATION_PAGES = 20;
+const TERMINAL_MACHINE_STATES = new Set([
+  "canceled",
+  "cancelled",
+  "deleted",
+  "ended",
+  "failed",
+  "released",
+  "terminated",
+]);
+
+function record(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function text(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function rows(payload, field) {
+  if (Array.isArray(payload)) return payload;
+  const value =
+    field === "machines"
+      ? (record(payload).nodes ?? record(payload).machines)
+      : record(payload)[field];
+  return Array.isArray(value) ? value : null;
+}
+
+function reservationId(value) {
+  const source = record(value);
+  return (
+    text(source.id) ??
+    text(source.ref) ??
+    text(source.reservation_id) ??
+    text(source.commerce_reservation_id)
+  );
+}
+
+function reservationMode(value) {
+  const source = record(value);
+  const mode = text(source.access_mode) ?? text(source.accessMode);
+  return mode?.toLowerCase() === "virtual-machine" ? "vm" : (mode?.toLowerCase() ?? null);
+}
+
+function reservationModeLabel(value) {
+  switch (reservationMode(value)) {
+    case "vm":
+      return "VM";
+    case "bare-metal":
+      return "Bare Metal";
+    case "kubernetes":
+      return "Kubernetes";
+    case "slurm":
+      return "Slurm";
+    default:
+      return null;
+  }
+}
+
+export function reservationChoiceLabel(value, gpuLabel) {
+  const reservation = record(value);
+  const gpu = text(reservation.gpu_type);
+  const hardware = gpu ? gpuLabel(gpu) : (text(reservation.hardware) ?? "GPU capacity");
+  const quantity = Number(reservation.node_count ?? reservation.machine_count ?? 1);
+  const machines = Number.isInteger(quantity) && quantity > 0 ? quantity : 1;
+  const location =
+    text(reservation.site_nickname) ??
+    text(reservation.facility) ??
+    text(reservation.location) ??
+    text(reservation.region) ??
+    "location unreported";
+  const start = text(reservation.start_at) ?? text(reservation.start_date);
+  const end = text(reservation.end_at) ?? text(reservation.end_date);
+  const createdAt = text(reservation.created_at);
+  return [
+    `${hardware}, ${machines} machine${machines === 1 ? "" : "s"}, ${location}`,
+    reservationModeLabel(reservation),
+    start && end ? `${start} to ${end}` : null,
+    createdAt ? `reserved ${createdAt}` : null,
+  ]
+    .filter(Boolean)
+    .join(" · ");
+}
+
+export async function reservationLabeler(fetch) {
+  const gpuLabel = await gpuLabeler(fetch);
+  return (reservation) => reservationChoiceLabel(reservation, gpuLabel);
+}
+
+function isActiveDirectReservation(value) {
+  const source = record(value);
+  const status = (text(source.status) ?? text(source.state) ?? "").toLowerCase();
+  const mode = reservationMode(source);
+  return status === "active" && (!mode || mode === "vm" || mode === "bare-metal");
+}
+
+export function canonicalMachineId(value) {
+  const source = record(value);
+  return (
+    text(source.id) ?? text(source.machine_id) ?? text(source.instance_id) ?? text(source.node_id)
+  );
+}
+
+export function machineHostname(value) {
+  return text(record(value).hostname);
+}
+
+function machineState(value) {
+  const source = record(value);
+  return (text(source.state) ?? text(source.status) ?? "unknown").toLowerCase();
+}
+
+export function isCanonicalMachineId(value) {
+  return CANONICAL_ID.test(text(value) ?? "");
+}
+
+export function isReferenceMiss(error) {
+  return error?.status === 404;
+}
+
+function invalidGateway(interaction, message) {
+  interaction.error(message, {
+    code: "invalid_gateway_response",
+    exitCode: 6,
+    retryable: true,
+  });
+}
+
+export async function listActiveDirectReservations(context, interaction) {
+  const reservations = [];
+  const seen = new Set();
+  let cursor = null;
+  for (let page = 0; page < MAX_RESERVATION_PAGES; page += 1) {
+    const query = new URLSearchParams({ limit: String(PAGE_SIZE), status: "active" });
+    if (cursor) query.set("cursor", cursor);
+    const payload = await context.fetch(`/v1/workflows/commerce/reservations?${query}`, {
+      method: "GET",
+    });
+    const pageRows = rows(payload, "reservations");
+    if (!pageRows)
+      invalidGateway(interaction, "The gateway returned an invalid capacity-reservation page.");
+    reservations.push(...pageRows.map(record).filter(isActiveDirectReservation));
+
+    const source = record(payload);
+    const next = text(source.next_cursor) ?? text(source.nextCursor);
+    if (!next || Array.isArray(payload)) return reservations;
+    if (seen.has(next)) {
+      invalidGateway(interaction, "Capacity-reservation pagination repeated a cursor.");
+    }
+    seen.add(next);
+    cursor = next;
+  }
+  interaction.error("Machine resolution exceeded its bounded capacity-reservation search.", {
+    code: "resource_search_incomplete",
+    exitCode: 6,
+    retryable: true,
+  });
+}
+
+export async function listOwnedActiveMachines(context, interaction) {
+  const reservations = await listActiveDirectReservations(context, interaction);
+  const pages = await Promise.all(
+    reservations.map(async (reservation) => {
+      const ref = reservationId(reservation);
+      if (!isCanonicalMachineId(ref)) {
+        invalidGateway(
+          interaction,
+          "The gateway returned a capacity reservation without a canonical identifier."
+        );
+      }
+      const payload = await context.fetch(
+        `/v1/workflows/compute/nodes/reservations/${encodeURIComponent(ref)}/machines`,
+        { method: "GET" }
+      );
+      const machineRows = rows(payload, "machines");
+      if (!machineRows)
+        invalidGateway(interaction, "The gateway returned an invalid machine collection.");
+      return machineRows
+        .map(record)
+        .filter((machine) => !TERMINAL_MACHINE_STATES.has(machineState(machine)))
+        .map((machine) => ({
+          ...machine,
+          reservation_id:
+            text(machine.reservation_id) ?? text(machine.commerce_reservation_id) ?? ref,
+        }));
+    })
+  );
+
+  const machines = new Map();
+  for (const machine of pages.flat()) {
+    const id = canonicalMachineId(machine);
+    if (!isCanonicalMachineId(id)) {
+      invalidGateway(interaction, "The gateway returned a machine without a canonical identifier.");
+    }
+    if (!machines.has(id)) machines.set(id, machine);
+  }
+  return [...machines.values()].sort(
+    (left, right) =>
+      (machineHostname(left) ?? "").localeCompare(machineHostname(right) ?? "") ||
+      canonicalMachineId(left).localeCompare(canonicalMachineId(right))
+  );
+}
+
+async function fetchCanonicalMachine(reference, context, interaction, { allowMiss = false } = {}) {
+  try {
+    const machine = record(
+      await context.fetch(`/v1/workflows/compute/nodes/${encodeURIComponent(reference)}`, {
+        method: "GET",
+      })
+    );
+    if (canonicalMachineId(machine)?.toLowerCase() !== reference.toLowerCase()) {
+      invalidGateway(
+        interaction,
+        "The gateway returned a machine with a mismatched canonical identifier."
+      );
+    }
+    return machine;
+  } catch (error) {
+    if (!isReferenceMiss(error)) throw error;
+    if (allowMiss) return null;
+    interaction.error(`Machine not found: ${reference}.`, { code: "machine_not_found" });
+  }
+}
+
+export async function resolveMachineReference(
+  reference,
+  context,
+  interaction,
+  { allowMiss = false } = {}
+) {
+  const requested = text(reference);
+  if (requested && isCanonicalMachineId(requested)) {
+    return fetchCanonicalMachine(requested, context, interaction, { allowMiss });
+  }
+
+  const machines = await listOwnedActiveMachines(context, interaction);
+  let selected;
+  if (requested) {
+    const normalized = requested.toLowerCase();
+    const matches = machines.filter(
+      (machine) => machineHostname(machine)?.toLowerCase() === normalized
+    );
+    if (matches.length > 1) {
+      interaction.usage(
+        `More than one active machine has hostname "${requested}". Use a canonical machine identifier.`,
+        { code: "machine_hostname_ambiguous", field: "machine" }
+      );
+    }
+    selected = matches[0];
+  } else {
+    if (!interaction.eligibleHuman || interaction.machine) {
+      if (allowMiss) return null;
+      interaction.usage("A machine reference is required outside an eligible terminal.", {
+        code: "missing_input",
+        field: "machine",
+      });
+    }
+    if (machines.length === 1) {
+      [selected] = machines;
+    } else if (machines.length > 1) {
+      const answer = await interaction.ask({
+        label: "Machine",
+        choices: machines.map((machine) => ({
+          label: `${machineHostname(machine) ?? "Unnamed machine"} (${machineState(machine)})`,
+          value: canonicalMachineId(machine),
+        })),
+      });
+      selected = machines.find((machine) => canonicalMachineId(machine) === answer);
+      if (!selected) interaction.usage("Choose one exact machine.", { code: "missing_input" });
+    }
+  }
+
+  if (!selected) {
+    if (allowMiss) return null;
+    interaction.error(
+      requested ? `Machine not found: ${requested}.` : "No active direct machine is available.",
+      { code: "machine_not_found" }
+    );
+  }
+  return fetchCanonicalMachine(canonicalMachineId(selected), context, interaction);
+}