@ornncompute/cli 0.2.24 → 1.0.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ornncompute/cli",
-  "version": "0.2.24",
+  "version": "1.0.34",
   "description": "Command-line interface for Ornn compute access workflows.",
   "type": "module",
   "bin": {
@@ -27,16 +27,22 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "test": "node --test",
-    "prepack": "node scripts/vendor-capabilities.mjs"
+    "acceptance:packaged": "node scripts/packaged-vnext-gate.mjs",
+    "evidence:participant": "node scripts/record-participant-evidence.mjs",
+    "prepack": "node scripts/vendor-capabilities.mjs",
+    "pretest": "node scripts/vendor-capabilities.mjs",
+    "smoke:nonproduction": "node scripts/nonproduction-release-smoke.mjs",
+    "test": "node --test 'test/*.test.mjs'"
   },
   "devDependencies": {
     "@ornn/capabilities": "0.1.0"
   },
-  "dependencies": {
-    "update-notifier": "7.3.1"
-  },
   "engines": {
     "node": ">=20"
+  },
+  "dependencies": {
+    "picocolors": "^1.1.1",
+    "zod": "^4.6.5",
+    "update-notifier": "7.3.1"
   }
 }

package/src/admin-capacity-reservations.mjs

@@ -0,0 +1,305 @@
+import { ADMIN_MUTATION_SAFETY, AdminMutationError, runAdminMutation } from "./admin-mutations.mjs";
+import { gpuLabeler } from "./gpu-catalog.mjs";
+
+const UUID = /^[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 DECIMAL = /^\d+(?:\.\d{1,6})?$/;
+
+const USAGE = {
+  "listings.create":
+    "Usage: ornn admin capacity-offers create --gpu GPU --nodes COUNT --gpus-per-node COUNT --site SITE --starts-at TIME --ends-at TIME --price-per-gpu-hour USD [--supplier-price-per-gpu-hour USD] [--down-payment-cents CENTS] [--access-mode bare-metal|virtual-machine] [--yes]",
+  "reservations.create":
+    "Usage: ornn admin reservations create --organization ID --capacity-offer ID --starts-at TIME --ends-at TIME --price-per-gpu-hour USD [--down-payment-cents CENTS] [--yes]",
+};
+const ACCESS_MODES = new Set(["bare-metal", "virtual-machine"]);
+const STAFF_HARDWARE_CATALOG = "/catalog/hardware";
+
+function parseOptions(argv, { values, positionals }, usage) {
+  const options = {};
+  const positionalValues = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (!argument.startsWith("--")) {
+      positionalValues.push(argument);
+      continue;
+    }
+    if (argument === "--yes") {
+      if (options.yes !== undefined)
+        throw new AdminMutationError(`${usage}\n--yes may be supplied only once.`, {
+          field: "yes",
+        });
+      options.yes = true;
+      continue;
+    }
+    const separator = argument.indexOf("=");
+    const name = argument.slice(2, separator === -1 ? undefined : separator);
+    if (!values.includes(name)) throw new AdminMutationError(`${usage}\nUnknown option: --${name}`);
+    const value = separator === -1 ? argv[index + 1] : argument.slice(separator + 1);
+    if (!value || (separator === -1 && value.startsWith("--"))) {
+      throw new AdminMutationError(`${usage}\n--${name} requires a value.`, { field: name });
+    }
+    if (options[name] !== undefined) {
+      throw new AdminMutationError(`${usage}\n--${name} may be supplied only once.`, {
+        field: name,
+      });
+    }
+    options[name] = value;
+    if (separator === -1) index += 1;
+  }
+  if (positionalValues.length !== positionals) throw new AdminMutationError(usage);
+  return { options, positionals: positionalValues };
+}
+
+function required(options, name, usage) {
+  const value = options[name]?.trim();
+  if (!value) throw new AdminMutationError(`${usage}\n--${name} is required.`, { field: name });
+  return value;
+}
+
+function positiveInteger(options, name, usage) {
+  const value = required(options, name, usage);
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 1) {
+    throw new AdminMutationError(`--${name} must be a positive integer.`, { field: name });
+  }
+  return parsed;
+}
+
+function uuid(options, name, usage) {
+  const value = required(options, name, usage);
+  if (!UUID.test(value)) {
+    throw new AdminMutationError(`--${name} must be a canonical UUID.`, { field: name });
+  }
+  return value.toLowerCase();
+}
+
+function timestamp(options, name, usage) {
+  const value = required(options, name, usage);
+  const parsed = Date.parse(value);
+  if (!Number.isFinite(parsed)) {
+    throw new AdminMutationError(`--${name} must be an ISO timestamp.`, { field: name });
+  }
+  return new Date(parsed).toISOString();
+}
+
+function price(options, usage, name = "price-per-gpu-hour") {
+  const value = required(options, name, usage);
+  if (!DECIMAL.test(value)) {
+    throw new AdminMutationError(
+      `--${name} must be zero or a positive decimal with at most 6 decimal places.`,
+      { field: name }
+    );
+  }
+  return value;
+}
+
+function optionalCents(options) {
+  const value = options["down-payment-cents"]?.trim();
+  if (value === undefined) return undefined;
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 0) {
+    throw new AdminMutationError("--down-payment-cents must be a whole number of cents.", {
+      field: "down-payment-cents",
+    });
+  }
+  return parsed;
+}
+
+function assertWindow(start, end) {
+  if (Date.parse(start) >= Date.parse(end)) {
+    throw new AdminMutationError("--ends-at must be later than --starts-at.", { field: "ends-at" });
+  }
+}
+
+function parseCapacityOffer(argv) {
+  const usage = USAGE["listings.create"];
+  const { options } = parseOptions(
+    argv,
+    {
+      positionals: 0,
+      values: [
+        "gpu",
+        "nodes",
+        "gpus-per-node",
+        "site",
+        "starts-at",
+        "ends-at",
+        "price-per-gpu-hour",
+        "supplier-price-per-gpu-hour",
+        "down-payment-cents",
+        "access-mode",
+        "idempotency-key",
+      ],
+    },
+    usage
+  );
+  const startsAt = timestamp(options, "starts-at", usage);
+  const endsAt = timestamp(options, "ends-at", usage);
+  assertWindow(startsAt, endsAt);
+  const accessMode = options["access-mode"]?.trim();
+  if (accessMode !== undefined && !ACCESS_MODES.has(accessMode)) {
+    throw new AdminMutationError("--access-mode must be bare-metal or virtual-machine.", {
+      field: "access-mode",
+    });
+  }
+  const downPaymentCents = optionalCents(options);
+  return {
+    input: {
+      gpu_type: required(options, "gpu", usage),
+      node_count: positiveInteger(options, "nodes", usage),
+      gpus_per_node: positiveInteger(options, "gpus-per-node", usage),
+      site_nickname: required(options, "site", usage),
+      available_start_at: startsAt,
+      available_end_at: endsAt,
+      buy_now_price_per_gpu_hour: Number(price(options, usage)),
+      ...(options["supplier-price-per-gpu-hour"] !== undefined
+        ? {
+            cost_per_gpu_hour: Number(price(options, usage, "supplier-price-per-gpu-hour")),
+          }
+        : {}),
+      ...(downPaymentCents !== undefined ? { down_payment_cents: downPaymentCents } : {}),
+      ...(accessMode ? { access_mode: accessMode } : {}),
+    },
+    mutation: {
+      idempotencyKey: options["idempotency-key"],
+      safety: ADMIN_MUTATION_SAFETY.eligibleHumanOnly,
+      yes: options.yes === true,
+    },
+  };
+}
+
+function parseReservationCreate(argv) {
+  const usage = USAGE["reservations.create"];
+  const { options } = parseOptions(
+    argv,
+    {
+      positionals: 0,
+      values: [
+        "organization",
+        "capacity-offer",
+        "starts-at",
+        "ends-at",
+        "price-per-gpu-hour",
+        "down-payment-cents",
+        "idempotency-key",
+      ],
+    },
+    usage
+  );
+  const startsAt = timestamp(options, "starts-at", usage);
+  const endsAt = timestamp(options, "ends-at", usage);
+  assertWindow(startsAt, endsAt);
+  const downPaymentCents = optionalCents(options);
+  return {
+    input: {
+      organization_id: uuid(options, "organization", usage),
+      listing_id: uuid(options, "capacity-offer", usage),
+      start_at: startsAt,
+      end_at: endsAt,
+      price_per_gpu_hour: price(options, usage),
+      ...(downPaymentCents !== undefined ? { down_payment_cents: downPaymentCents } : {}),
+    },
+    mutation: {
+      idempotencyKey: options["idempotency-key"],
+      safety: ADMIN_MUTATION_SAFETY.eligibleHumanOnly,
+      yes: options.yes === true,
+    },
+  };
+}
+
+function previewPayload(value) {
+  if (value?.ok === false) {
+    throw new AdminMutationError("The capacity offer contains an unknown hardware catalog term.", {
+      code: value.error ?? "unknown_catalog_term",
+    });
+  }
+  if (!value?.payload || typeof value.payload !== "object") {
+    throw new AdminMutationError("Capacity-offer normalization returned no effective terms.", {
+      code: "admin_review_incomplete",
+    });
+  }
+  return value.payload;
+}
+
+function usd(microUsd) {
+  return typeof microUsd === "number" ? (microUsd / 1_000_000).toFixed(6) : undefined;
+}
+
+function capacityOfferReview(payload, input, gpuLabel) {
+  const listing = payload.listing ?? {};
+  return {
+    title: "Create capacity offer",
+    fields: [
+      { label: "GPU", value: gpuLabel(payload.gpu_type ?? listing.gpuSlug) },
+      { label: "Nodes to attach", value: payload.node_count ?? input.node_count },
+      { label: "GPUs per node", value: listing.gpusPerNode ?? input.gpus_per_node },
+      { label: "Site", value: payload.site_nickname ?? input.site_nickname },
+      { label: "Access mode", value: listing.accessMode },
+      { label: "Starts at", value: listing.startsAt ?? input.available_start_at },
+      { label: "Ends at", value: listing.endsAt ?? input.available_end_at },
+      { label: "Price per GPU-hour (USD)", value: input.buy_now_price_per_gpu_hour },
+      {
+        label: "Supplier price per GPU-hour (USD)",
+        value: usd(listing.supplierPricePerGpuHourMicroUsd),
+      },
+      { label: "Spread per GPU-hour (USD)", value: usd(listing.spreadPerGpuHourMicroUsd) },
+      { label: "Down payment (cents)", value: listing.downPaymentCents },
+    ],
+    consequence:
+      "Publishes a primary listing with these terms; attach its nodes before it reaches the market.",
+  };
+}
+
+function reservationCreateReview(input) {
+  return {
+    title: "Create capacity reservation",
+    fields: [
+      { label: "Organization", value: input.organization_id },
+      { label: "Capacity offer", value: input.listing_id },
+      { label: "Starts at", value: input.start_at },
+      { label: "Ends at", value: input.end_at },
+      { label: "Price per GPU-hour (USD)", value: input.price_per_gpu_hour },
+      ...(input.down_payment_cents !== undefined
+        ? [{ label: "Down payment (cents)", value: input.down_payment_cents }]
+        : []),
+    ],
+    consequence:
+      "Creates a schedule reservation on the listing's nodes with the reviewed dates and price.",
+  };
+}
+
+async function runCapacityOffer({ execute, fetch, input, mutation, runtime }) {
+  return runAdminMutation({
+    ...runtime,
+    ...mutation,
+    prepare: async () => {
+      const payload = previewPayload(await execute(input));
+      const gpuLabel = await gpuLabeler(fetch, STAFF_HARDWARE_CATALOG);
+      return { review: capacityOfferReview(payload, input, gpuLabel), value: input };
+    },
+    execute: (value) => execute(value, { confirmed: true }),
+  });
+}
+
+async function runReservationCreate({ execute, input, mutation, runtime }) {
+  return runAdminMutation({
+    ...runtime,
+    ...mutation,
+    prepare: async () => ({ review: reservationCreateReview(input), value: input }),
+    execute: (value) => execute(value, { confirmed: true }),
+  });
+}
+
+export const adminCapacityReservationHandlers = [
+  {
+    capabilityId: "listings.create",
+    parse: parseCapacityOffer,
+    run: runCapacityOffer,
+    safety: ADMIN_MUTATION_SAFETY.eligibleHumanOnly,
+  },
+  {
+    capabilityId: "reservations.create",
+    parse: parseReservationCreate,
+    run: runReservationCreate,
+    safety: ADMIN_MUTATION_SAFETY.eligibleHumanOnly,
+  },
+];

package/src/admin-command-handlers.mjs

@@ -0,0 +1,57 @@
+import { adminCapacityReservationHandlers } from "./admin-capacity-reservations.mjs";
+import { adminEnrollmentHandlers } from "./admin-enrollment.mjs";
+import { adminNodeDiagnosticsHandlers } from "./admin-node-diagnostics.mjs";
+import { adminNodeLifecycleHandlers } from "./admin-node-lifecycle.mjs";
+import { ADMIN_MUTATION_SAFETY, assertAdminMutationContext } from "./admin-mutations.mjs";
+
+const handlers = [
+  ...adminCapacityReservationHandlers,
+  ...adminEnrollmentHandlers,
+  ...adminNodeDiagnosticsHandlers,
+  ...adminNodeLifecycleHandlers,
+];
+
+export function adminCommandHandler(capability) {
+  return handlers.find((handler) => handler.capabilityId === capability.id) ?? null;
+}
+
+function commandParts(capability) {
+  return capability.cli?.vnext?.command ?? capability.cli?.command ?? [];
+}
+function matchedAdminCapability(catalog, argv) {
+  return catalog.find((candidate) => {
+    if (candidate.cli?.vnext?.audience !== "admin") return false;
+    const command = commandParts(candidate).slice(1);
+    return command.length <= argv.length && command.every((part, index) => argv[index] === part);
+  });
+}
+
+export function adminCommandName(catalog, argv) {
+  const capability = matchedAdminCapability(catalog, argv);
+  return capability ? commandParts(capability).join(" ") : null;
+}
+
+/** Parses supported mutation semantics and rejects unsafe contexts before auth preflight I/O. */
+export function preflightAdminCommand(catalog, argv, runtime) {
+  if (argv[0] === "help" || argv.includes("--help") || argv.includes("-h")) return null;
+  const capability = matchedAdminCapability(catalog, argv);
+  if (!capability) return null;
+  const handler = adminCommandHandler(capability);
+  if (!handler) return null;
+  if (handler.safety === ADMIN_MUTATION_SAFETY.eligibleHumanOnly) {
+    assertAdminMutationContext({ ...runtime, safety: handler.safety });
+  }
+  const command = commandParts(capability);
+  const parsed = handler.parse(argv.slice(command.length - 1), capability);
+  if (handler.safety) {
+    assertAdminMutationContext({
+      ...runtime,
+      idempotencyKey: parsed.mutation?.idempotencyKey,
+      safety: handler.safety,
+      yes: parsed.mutation?.yes,
+    });
+  }
+  return { capabilityId: capability.id, command: command.join(" "), parsed };
+}
+
+export const adminCommandHandlers = handlers;