@ornncompute/cli 0.2.24 → 1.0.25

package/src/interaction-runtime.mjs

@@ -0,0 +1,310 @@
+import { randomUUID } from "node:crypto";
+import { createInterface } from "node:readline/promises";
+
+import { resolveAuthBaseUrl } from "./device-auth.mjs";
+
+const BOOLEAN_OPTIONS = new Set([
+  "all-nodes",
+  "erase-local-data",
+  "force",
+  "follow",
+  "major",
+  "guided",
+  "no-browser",
+  "no-wait",
+  "overwrite",
+  "print",
+  "read-only",
+  "read-write",
+  "recursive",
+  "wait",
+  "yes",
+]);
+
+const OPTIONAL_VALUE_OPTIONS = new Set(["resume"]);
+
+function optionName(raw) {
+  return raw.replace(/-([a-z0-9])/g, (_, character) => character.toUpperCase());
+}
+
+export class InteractionError extends Error {
+  constructor(
+    message,
+    {
+      action = null,
+      code = "command_failed",
+      exitCode = 1,
+      field,
+      outcomeClass = "failed",
+      retryable = false,
+    } = {}
+  ) {
+    super(message);
+    this.name = "InteractionError";
+    this.action = action;
+    this.code = code;
+    this.exitCode = exitCode;
+    this.field = field;
+    this.outcomeClass = outcomeClass;
+    this.retryable = retryable;
+  }
+}
+
+export function isRecoverableWaitFailure(error) {
+  const status = Number(error?.status);
+  if (status === 401 || status === 403 || (Number.isFinite(status) && status >= 500)) {
+    return true;
+  }
+  if (error?.retryable === true) return true;
+  const code = typeof error?.code === "string" ? error.code : "";
+  if (/^E(?:AI_|CONN|HOST|NET|PIPE|TIMEDOUT)/.test(code)) return true;
+  return (
+    error instanceof TypeError &&
+    /fetch|network|socket|connection|timed? ?out|lost response/i.test(error.message)
+  );
+}
+
+export function parseSemanticArguments(argv) {
+  const parsed = { $positionals: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--" || /^-[^-]/.test(argument)) {
+      throw new InteractionError(`Unsupported option: ${argument}.`, {
+        code: "usage_error",
+        exitCode: 2,
+      });
+    }
+    if (!argument.startsWith("--")) {
+      parsed.$positionals.push(argument);
+      continue;
+    }
+
+    const equals = argument.indexOf("=");
+    const rawName = argument.slice(2, equals === -1 ? undefined : equals);
+    if (!rawName) {
+      throw new InteractionError("An option name is required after --.", {
+        code: "usage_error",
+        exitCode: 2,
+      });
+    }
+    const name = optionName(rawName);
+    if (Object.hasOwn(parsed, name)) {
+      throw new InteractionError(`--${rawName} may be supplied only once.`, {
+        code: "usage_error",
+        exitCode: 2,
+        field: name,
+      });
+    }
+
+    if (OPTIONAL_VALUE_OPTIONS.has(rawName)) {
+      const value = equals === -1 ? argv[index + 1] : argument.slice(equals + 1);
+      if (equals !== -1 && value === "") {
+        throw new InteractionError(`--${rawName} requires a value after =.`, {
+          code: "usage_error",
+          exitCode: 2,
+          field: name,
+        });
+      }
+      if (equals === -1 && (value === undefined || value.startsWith("-"))) {
+        parsed[name] = true;
+      } else {
+        if (equals === -1) index += 1;
+        parsed[name] = value;
+      }
+      continue;
+    }
+
+    if (BOOLEAN_OPTIONS.has(rawName)) {
+      if (equals !== -1) {
+        throw new InteractionError(`--${rawName} does not accept a value.`, {
+          code: "usage_error",
+          exitCode: 2,
+          field: name,
+        });
+      }
+      parsed[name] = true;
+      continue;
+    }
+
+    const value = equals === -1 ? argv[index + 1] : argument.slice(equals + 1);
+    if (value === undefined || (equals === -1 && value.startsWith("-")) || value === "") {
+      throw new InteractionError(`--${rawName} requires a value.`, {
+        code: "usage_error",
+        exitCode: 2,
+        field: name,
+      });
+    }
+    if (equals === -1) index += 1;
+    parsed[name] = value;
+  }
+  return parsed;
+}
+
+function execution({
+  action = null,
+  data = null,
+  errors = [],
+  exitCode = 0,
+  outcome = { class: "ready", phase: "complete" },
+  page = null,
+  progress = [],
+  presentation = null,
+  resume = null,
+} = {}) {
+  return {
+    __ornnCliExecution: true,
+    action,
+    data,
+    errors,
+    exitCode,
+    outcome,
+    page,
+    progress,
+    presentation,
+    resume,
+  };
+}
+
+export function isInteractionExecution(value) {
+  return value?.__ornnCliExecution === true;
+}
+
+export function createInteractionRuntime({
+  eligibleHuman,
+  extensions = {},
+  format,
+  formatProvided = false,
+  io,
+  options,
+}) {
+  const machine = format === "json" || format === "ndjson";
+  const redirected = !eligibleHuman;
+  const stdin = io.stdin ?? process.stdin;
+  const stderr = io.stderr ?? process.stderr;
+  const sleep = io.sleep;
+  const now = io.now ?? (() => Date.now());
+  const progressIntervalMs = io.progressIntervalMs ?? 10_000;
+  let reader;
+
+  function readline() {
+    reader ??= createInterface({ input: stdin, output: stderr, terminal: false });
+    return reader;
+  }
+
+  function usage(message, { code = "usage_error", field } = {}) {
+    throw new InteractionError(message, { code, exitCode: 2, field });
+  }
+
+  function error(message, init = {}) {
+    throw new InteractionError(message, init);
+  }
+
+  async function ask({ choices = [], label }) {
+    if (!eligibleHuman || machine) {
+      usage(`${label} must be supplied explicitly outside an interactive terminal.`, {
+        code: "missing_input",
+      });
+    }
+    for (const [index, choice] of choices.entries()) {
+      stderr.write(`  ${index + 1}) ${choice.label}\n`);
+    }
+    let answer;
+    try {
+      answer = await readline().question(`${label}: `);
+    } catch (caught) {
+      if (caught?.code === "ERR_USE_AFTER_CLOSE") return null;
+      throw caught;
+    }
+    if (!answer) return null;
+    if (choices.length) {
+      const numeric = Number(answer);
+      if (Number.isInteger(numeric) && numeric >= 1 && numeric <= choices.length) {
+        return choices[numeric - 1].value;
+      }
+      const exact = choices.filter(
+        (choice) => choice.label.toLowerCase() === answer.toLowerCase() || choice.value === answer
+      );
+      if (exact.length === 1) return exact[0].value;
+      usage(`Choose one exact ${label.toLowerCase()} value.`, { code: "ambiguous_input" });
+    }
+    return answer;
+  }
+
+  async function review({ prompt = "Continue?", requireLive = false, terms, title }) {
+    if (machine) {
+      if (!requireLive && options.yes === true) return true;
+      usage(
+        requireLive
+          ? "This operation is supported only in an eligible interactive terminal."
+          : "Consent is required. Review the terms and supply --yes to continue.",
+        {
+          code: requireLive ? "unsupported_in_machine_mode" : "consent_required",
+          ...(!requireLive ? { field: "yes" } : {}),
+        }
+      );
+    }
+    if (requireLive && !eligibleHuman) {
+      usage("This operation is supported only in an eligible interactive terminal.", {
+        code: "unsupported_in_machine_mode",
+      });
+    }
+    stderr.write(`${title}\n`);
+    for (const term of terms) stderr.write(`  ${term.label}: ${term.value}\n`);
+
+    if (!requireLive && options.yes === true) return true;
+    if (!eligibleHuman) {
+      usage("Consent is required. Review the terms and supply --yes to continue.", {
+        code: "consent_required",
+        field: "yes",
+      });
+    }
+    let answer;
+    try {
+      answer = await readline().question(`${prompt} [y/N] `);
+    } catch (caught) {
+      if (caught?.code === "ERR_USE_AFTER_CLOSE") return false;
+      throw caught;
+    }
+    return /^(y|yes)$/i.test(String(answer ?? "").trim());
+  }
+
+  function webUrl(path) {
+    return new URL(path, `${resolveAuthBaseUrl({ env: io.env })}/`).toString();
+  }
+
+  const interaction = {
+    actionRequired: ({ action, data, resume }) =>
+      execution({
+        action,
+        data,
+        exitCode: 3,
+        outcome: { class: "action_required", phase: action.kind ?? "external_action" },
+        resume,
+      }),
+    ask,
+    close() {
+      reader?.close();
+    },
+    inform(lines) {
+      if (!eligibleHuman || machine) return;
+      for (const line of lines) stderr.write(`${line}\n`);
+    },
+    eligibleHuman,
+    error,
+    idempotencyKey(supplied) {
+      const stable = typeof supplied === "string" ? supplied.trim() : "";
+      return stable || `ornn-${randomUUID()}`;
+    },
+    format,
+    formatProvided,
+    machine,
+    options,
+    redirected,
+    result: execution,
+    review,
+    usage,
+    webUrl,
+  };
+  Object.assign(interaction, extensions);
+  return interaction;
+}