@allocator-one/harness-cli 1.16.0 → 1.17.0

package/dist/chunk-W7BVOQQG.js

@@ -0,0 +1,1448 @@
+#!/usr/bin/env node
+import {
+  browserAvailable,
+  loopbackCode
+} from "./chunk-WSDFLMO6.js";
+import {
+  CommandError,
+  HttpError,
+  LocalError,
+  MalformedResponseError,
+  TransportError,
+  UsageError,
+  clean,
+  cleanMultiline,
+  deleteCredentials,
+  readCredentials,
+  resolveCacheHome,
+  validateBaseUrl,
+  writeCredentials
+} from "./chunk-BHBEIT5I.js";
+import {
+  CLI_VERSION
+} from "./chunk-5THYIKLW.js";
+
+// src/infraone/config.ts
+import { createHash } from "crypto";
+import { homedir } from "os";
+import { isAbsolute, join } from "path";
+var DEFAULT_API_URL = "https://api.infra.one/v1";
+function credentialsPath(env = process.env) {
+  const xdg = env["XDG_CONFIG_HOME"];
+  const base = xdg !== void 0 && xdg !== "" && isAbsolute(xdg) ? xdg : join(homedir(), ".config");
+  return join(base, "infraone", "credentials.json");
+}
+function resolveConfig(env = process.env) {
+  const path = credentialsPath(env);
+  const stored = readCredentials(path);
+  const envToken = nonBlank(env["INFRAONE_TOKEN"])?.trim() ?? null;
+  const apiUrl = trimSlash(nonBlank(env["INFRAONE_API_URL"]) ?? (envToken === null ? stored?.url : void 0) ?? DEFAULT_API_URL);
+  const api = checkUrl(apiUrl, "INFRAONE_API_URL");
+  if (!api.ok) return api;
+  const explicitLogin = nonBlank(env["INFRAONE_LOGIN_URL"]);
+  if (explicitLogin !== null) {
+    const login2 = checkUrl(explicitLogin, "INFRAONE_LOGIN_URL");
+    if (!login2.ok) return login2;
+  }
+  const loginUrl = explicitLogin === null ? loginOrigin(apiUrl) : new URL(explicitLogin).origin;
+  const storedToken = stored !== null && sameBase(stored.url, apiUrl) ? stored.token : null;
+  const token = envToken ?? storedToken;
+  return {
+    ok: true,
+    config: {
+      apiUrl,
+      loginUrl,
+      token,
+      tokenSource: envToken !== null ? "environment" : storedToken !== null ? "stored login" : null,
+      credentialsPath: path,
+      cacheDir: join(resolveCacheHome(env), "infraone")
+    }
+  };
+}
+function loginOrigin(apiUrl) {
+  const url = new URL(apiUrl);
+  if (url.hostname.startsWith("api.")) url.hostname = `venture.${url.hostname.slice("api.".length)}`;
+  return url.origin;
+}
+function apiUrlFor(apiUrl, path) {
+  const base = trimSlash(apiUrl);
+  const versioned = /\/v\d+$/.test(base) ? path.replace(/^\/v\d+(?=\/|$)/, "") : path;
+  return new URL(base + versioned);
+}
+function baseKey(apiUrl) {
+  return createHash("sha256").update(canonical(apiUrl)).digest("hex").slice(0, 16);
+}
+function checkUrl(url, variable) {
+  const checked = validateBaseUrl(url);
+  if (checked.ok) return checked;
+  return {
+    ok: false,
+    message: checked.message.replaceAll("HARNESS_API_URL", variable).replaceAll("HARNESS_API_TOKEN", "INFRAONE_TOKEN")
+  };
+}
+function sameBase(left, right) {
+  return canonical(left) === canonical(right);
+}
+function canonical(url) {
+  try {
+    const parsed = new URL(url);
+    return `${parsed.protocol}//${parsed.host.toLowerCase()}${parsed.pathname.replace(/\/+$/, "")}`;
+  } catch {
+    return url;
+  }
+}
+function trimSlash(url) {
+  return url.replace(/\/+$/, "");
+}
+function nonBlank(value) {
+  return value === void 0 || value.trim() === "" ? null : value;
+}
+
+// src/infraone/client.ts
+var RECEIVE_TIMEOUT_MS = 3e4;
+var SPEC_FINGERPRINT_HEADER = "infraone-spec-fingerprint";
+var API_VERSION_HEADER = "infraone-api-version";
+var DEFAULT_MESSAGES = {
+  401: "Not signed in, or the credential has expired or was revoked (run infraone login)",
+  403: "The credential lacks the scope this needs",
+  404: "Not found",
+  409: "Conflict",
+  422: "Validation error",
+  428: "A person must confirm this first",
+  429: "Rate limited \u2014 retry later"
+};
+var InfraoneClient = class {
+  constructor(apiUrl, token, fetchImpl) {
+    this.apiUrl = apiUrl;
+    this.token = token;
+    this.fetchImpl = fetchImpl ?? globalThis.fetch;
+  }
+  apiUrl;
+  token;
+  fetchImpl;
+  /**
+   * The credential header for a URL the API handed out (an upload or
+   * download URL): the bearer only on the API's own origin, never on a
+   * storage host's signed URL.
+   */
+  authorizationFor(url) {
+    if (this.token === null) return {};
+    try {
+      return new URL(url).origin === new URL(this.apiUrl).origin ? { authorization: `Bearer ${this.token}` } : {};
+    } catch {
+      return {};
+    }
+  }
+  async request(method, path, options = {}) {
+    const url = apiUrlFor(this.apiUrl, path);
+    for (const [key, value] of Object.entries(options.query ?? {})) {
+      if (value === void 0) continue;
+      for (const item of Array.isArray(value) ? value : [value]) url.searchParams.append(key, String(item));
+    }
+    const headers = {
+      accept: "application/json",
+      "infraone-client": "cli",
+      "user-agent": `infraone/${CLI_VERSION}`
+    };
+    if (this.token !== null && options.anonymous !== true) headers["authorization"] = `Bearer ${this.token}`;
+    if (options.idempotencyKey !== void 0) headers["idempotency-key"] = options.idempotencyKey;
+    if (options.confirmed === true) headers["infraone-confirm"] = "yes";
+    let body;
+    if (options.body !== void 0) {
+      headers["content-type"] = "application/json";
+      body = JSON.stringify(options.body);
+    }
+    let response;
+    try {
+      response = await this.fetchImpl(url, {
+        method,
+        headers,
+        body,
+        signal: AbortSignal.timeout(options.timeoutMs ?? RECEIVE_TIMEOUT_MS),
+        redirect: "manual"
+      });
+    } catch (error) {
+      throw new TransportError(transportMessage(error), transportCode(error));
+    }
+    let text;
+    try {
+      text = await response.text();
+    } catch (error) {
+      throw new TransportError(transportMessage(error), transportCode(error));
+    }
+    const parsed = parseObject(text);
+    if (!response.ok) {
+      const parsedBody = parsed ?? {};
+      const message = typeof parsedBody["message"] === "string" && parsedBody["message"] !== "" ? parsedBody["message"] : DEFAULT_MESSAGES[response.status] ?? `HTTP ${response.status}`;
+      throw new HttpError(response.status, message, parsedBody, response.headers.get("retry-after"));
+    }
+    if (parsed === null && text !== "") {
+      throw new MalformedResponseError(`the API answered with a non-JSON body (HTTP ${response.status})`);
+    }
+    return {
+      status: response.status,
+      body: parsed ?? {},
+      apiVersion: response.headers.get(API_VERSION_HEADER),
+      fingerprint: response.headers.get(SPEC_FINGERPRINT_HEADER)
+    };
+  }
+};
+function parseObject(text) {
+  if (text === "") return null;
+  try {
+    const value = JSON.parse(text);
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+function transportCode(error) {
+  const cause = error instanceof Error ? error.cause : void 0;
+  if (typeof cause !== "object" || cause === null) return null;
+  const code = cause.code;
+  return typeof code === "string" ? code : null;
+}
+function transportMessage(error) {
+  if (error instanceof Error) {
+    if (error.name === "TimeoutError" || error.name === "AbortError") return "request timed out";
+    const cause = error.cause;
+    if (cause instanceof Error && cause.message !== "") return cause.message;
+    return error.message;
+  }
+  return String(error);
+}
+
+// src/infraone/auth.ts
+var SESSION_PATH = "/v1/session";
+var EXCHANGE_PATH = "/v1/cli/token-exchange";
+function loginPageUrl(config) {
+  return `${config.loginUrl}/cli/login?client=infraone`;
+}
+async function login(config, options = {}) {
+  const notify = options.notify ?? (() => void 0);
+  const canOpen = options.openBrowser !== void 0 || browserAvailable({ env: options.env ?? process.env });
+  if (options.noBrowser === true || !canOpen) {
+    if (options.interactive === false || options.prompt === void 0) {
+      return { ok: false, message: "--no-browser needs a terminal to paste the token into; for scripts, set INFRAONE_TOKEN" };
+    }
+    notify(`Open ${loginPageUrl(config)} in a browser, authorize, and paste the token below.`);
+    const token = (await options.prompt()).trim();
+    if (token === "") return { ok: false, message: "no token entered" };
+    return verifyAndStore(config, token, { minted: false, kind: null }, options);
+  }
+  const callback = await loopbackCode((query) => {
+    query.set("client", "infraone");
+    return `${config.loginUrl}/cli/login?${query.toString()}`;
+  }, {
+    notify,
+    ...options.openBrowser === void 0 ? {} : { openBrowser: options.openBrowser },
+    ...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs }
+  });
+  if (!callback.ok) return callback;
+  try {
+    const exchanged = await exchangeCode(config, callback.code, callback.verifier, options);
+    if (!exchanged.ok) {
+      await callback.respond(400, "Infra One could not exchange the browser authorization. Return to the terminal for details.", "error");
+      return exchanged;
+    }
+    const result = await verifyAndStore(config, exchanged.token, { minted: true, kind: exchanged.kind }, options);
+    await (result.ok ? callback.respond(200, "You can close this browser and return to the terminal.", "success") : callback.respond(400, "Infra One could not verify and store this login. Return to the terminal for details.", "error"));
+    return result;
+  } catch (error) {
+    await callback.respond(500, "Infra One could not finish the login. Return to the terminal for details.", "error");
+    const detail = error instanceof Error ? error.message : String(error);
+    return { ok: false, message: `could not finish the browser login: ${detail}` };
+  } finally {
+    callback.close();
+  }
+}
+async function exchangeCode(config, code, verifier, options) {
+  try {
+    const answer = await new InfraoneClient(config.apiUrl, null, options.fetchImpl).request("POST", EXCHANGE_PATH, {
+      body: { code, code_verifier: verifier },
+      anonymous: true
+    });
+    const data = isRecord(answer.body["data"]) ? answer.body["data"] : answer.body;
+    const token = data["token"];
+    const kind = typeof data["kind"] === "string" ? data["kind"] : null;
+    if (typeof token === "string" && token !== "") return { ok: true, token, kind };
+    return { ok: false, message: "the login-code exchange returned no token \u2014 aborting" };
+  } catch (error) {
+    if (error instanceof HttpError) return { ok: false, message: `the login-code exchange failed: ${error.message}` };
+    if (error instanceof TransportError) {
+      return { ok: false, message: `the login-code exchange failed: cannot reach the API (${error.message})` };
+    }
+    throw error;
+  }
+}
+async function verifyAndStore(config, token, received, options) {
+  const client = new InfraoneClient(config.apiUrl, token, options.fetchImpl);
+  let session;
+  try {
+    session = await describeSession(client);
+  } catch (error) {
+    if (error instanceof HttpError) {
+      const revoked = received.minted && await revokeSession(client);
+      return {
+        ok: false,
+        message: `the received token failed verification (${error.message}, HTTP ${error.status}) \u2014 nothing was stored` + (revoked ? ", and the token was revoked" : "")
+      };
+    }
+    if (error instanceof TransportError) {
+      const revoked = received.minted && await revokeSession(client);
+      return {
+        ok: false,
+        message: `could not verify the token: cannot reach the API (${error.message}) \u2014 nothing was stored` + (revoked ? ", and the token was revoked" : received.minted ? "; it expires on its own in 30 days" : "")
+      };
+    }
+    throw error;
+  }
+  const stored = readCredentials(config.credentialsPath);
+  try {
+    writeCredentials(config.credentialsPath, config.apiUrl, token);
+  } catch (error) {
+    if (received.minted) await revokeSession(client);
+    const detail = error instanceof Error ? error.message : String(error);
+    return {
+      ok: false,
+      message: `could not store credentials at ${config.credentialsPath}: ${detail}` + (received.minted ? "" : " (the pasted token stays valid)")
+    };
+  }
+  if (stored !== null && stored.token !== token) {
+    await revokeSession(new InfraoneClient(stored.url, stored.token, options.fetchImpl));
+  }
+  const kind = session?.kind ?? received.kind;
+  return {
+    ok: true,
+    json: { url: config.apiUrl, credentials: config.credentialsPath, kind, verified: session !== null, org: session?.org ?? null },
+    human: `Logged in to ${config.apiUrl}${orgSuffix(session)} \u2014 stored at ${config.credentialsPath} (valid ~30 days; infraone logout revokes it).
+` + (session === null ? "This server can't describe the credential yet, so it was stored unverified.\n" : "")
+  };
+}
+async function logout(config, options = {}) {
+  const stored = readCredentials(config.credentialsPath);
+  if (stored === null) {
+    const envToken2 = (options.env?.["INFRAONE_TOKEN"] ?? "").trim() !== "";
+    return {
+      ok: false,
+      message: envToken2 ? "no stored login to remove: the INFRAONE_TOKEN in the environment is yours to manage \u2014 unset it" : "no stored login to remove"
+    };
+  }
+  const revoked = await revokeSession(new InfraoneClient(stored.url, stored.token, options.fetchImpl));
+  try {
+    deleteCredentials(config.credentialsPath);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return {
+      ok: false,
+      message: `could not remove ${config.credentialsPath} (${detail}) \u2014 delete it manually.` + (revoked ? " The token itself was revoked." : "")
+    };
+  }
+  const envToken = (options.env?.["INFRAONE_TOKEN"] ?? "").trim() !== "";
+  return {
+    ok: true,
+    json: { logged_out: true, revoked, environment_token: envToken },
+    human: `Logged out of ${stored.url}${revoked ? "" : " (the server did not revoke the token \u2014 it still expires on its own)"}.
+` + (envToken ? "INFRAONE_TOKEN is still set, so commands keep using it: unset it too.\n" : "")
+  };
+}
+async function whoami(config, client) {
+  if (config.token === null) {
+    return { ok: false, message: `not signed in to ${config.apiUrl}: run \`infraone login\`, or set INFRAONE_TOKEN for scripts` };
+  }
+  let session;
+  try {
+    session = await describeSession(client);
+  } catch (error) {
+    if (error instanceof HttpError) {
+      return {
+        ok: false,
+        message: `signed in to ${config.apiUrl} with a ${config.tokenSource} credential, but it failed verification: ${error.message} (HTTP ${error.status})`
+      };
+    }
+    throw error;
+  }
+  const lines = [`API:         ${config.apiUrl}`, `Credential:  ${config.tokenSource}${session?.kind ? `, ${clean(session.kind)}` : ""}`];
+  if (session?.user) lines.push(`User:        ${person(session.user)}`);
+  if (session?.org) lines.push(`Org:         ${orgName(session.org)}`);
+  if (session?.scopes) lines.push(`Scopes:      ${session.scopes.map(clean).join(" ")}`);
+  if (session?.expires_at) lines.push(`Expires:     ${clean(session.expires_at)}`);
+  lines.push(`Verified:    ${session === null ? "no \u2014 this server can't describe credentials yet" : "ok"}`);
+  return {
+    ok: true,
+    json: {
+      url: config.apiUrl,
+      source: config.tokenSource,
+      verified: session !== null,
+      kind: session?.kind ?? null,
+      user: session?.user ?? null,
+      org: session?.org ?? null,
+      scopes: session?.scopes ?? null,
+      expires_at: session?.expires_at ?? null
+    },
+    human: lines.join("\n") + "\n"
+  };
+}
+async function describeSession(client) {
+  try {
+    const answer = await client.request("GET", SESSION_PATH);
+    const data = isRecord(answer.body["data"]) ? answer.body["data"] : {};
+    const text = (value) => typeof value === "string" ? value : null;
+    return {
+      kind: text(data["kind"]),
+      expires_at: text(data["expires_at"]),
+      scopes: Array.isArray(data["scopes"]) ? data["scopes"].filter((scope) => typeof scope === "string") : null,
+      user: isRecord(data["user"]) ? data["user"] : null,
+      org: isRecord(data["org"]) ? data["org"] : null
+    };
+  } catch (error) {
+    if (error instanceof HttpError && (error.status === 404 || error.status === 405)) return null;
+    throw error;
+  }
+}
+async function revokeSession(client) {
+  try {
+    await client.request("DELETE", SESSION_PATH);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function orgSuffix(session) {
+  return session?.org ? `, org ${orgName(session.org)}` : "";
+}
+function orgName(org) {
+  const name = clean(org["name"]);
+  const slug = clean(org["slug"]);
+  return slug === "" || slug === name ? name : `${name} (${slug})`;
+}
+function person(user) {
+  const name = clean(user["name"]);
+  const email = clean(user["email"]);
+  return name === "" ? email : email === "" ? name : `${name} <${email}>`;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/core/transfer.ts
+import { lstat, readdir, realpath as realpath2, stat as stat2 } from "fs/promises";
+import { basename, extname, join as join2, relative, resolve, sep as sep2 } from "path";
+import { randomUUID } from "crypto";
+import { Option } from "commander";
+
+// src/core/transfer-download.ts
+import { randomBytes } from "crypto";
+import { link, open, rename, rm } from "fs/promises";
+
+// src/core/transfer-errors.ts
+var PERMANENT = /^(ENOTFOUND|CERT_|ERR_TLS_|DEPTH_ZERO_SELF_SIGNED_CERT|SELF_SIGNED_CERT_IN_CHAIN|UNABLE_TO_(GET_ISSUER_CERT|VERIFY_LEAF_SIGNATURE))/;
+function failureCode(error) {
+  const cause = error instanceof Error ? error.cause : void 0;
+  const code = typeof cause === "object" && cause !== null ? cause.code : void 0;
+  return typeof code === "string" ? code : null;
+}
+function transient(error) {
+  return !PERMANENT.test(failureCode(error) ?? "");
+}
+function failureMessage(error) {
+  if (!(error instanceof Error)) return redact(String(error));
+  const cause = error.cause;
+  return redact(cause instanceof Error && cause.message !== "" ? `${error.message}: ${cause.message}` : error.message);
+}
+function redact(text) {
+  return text.replace(/\b(https?:\/\/[^\s?#"'<>]*)[?#][^\s"'<>]*/gi, "$1?\u2026");
+}
+
+// src/core/transfer-download.ts
+var DownloadError = class extends CommandError {
+  constructor(message) {
+    super(message);
+    this.name = "DownloadError";
+  }
+};
+var DEFAULT_RETRIES = 8;
+var IDLE_TIMEOUT_MS = 12e4;
+var Interrupted = class extends Error {
+};
+async function downloadFile(url, dest, options = {}) {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  const retries = options.retries ?? DEFAULT_RETRIES;
+  const backoff = options.backoff ?? ((attempt) => Math.min(3e4, 500 * 2 ** (attempt - 1)));
+  const idleMs = options.timeoutMs ?? IDLE_TIMEOUT_MS;
+  const part = `${dest}.${randomBytes(6).toString("hex")}.part`;
+  let current = url;
+  let refreshed = false;
+  let written = 0;
+  let total2 = null;
+  let ranges = false;
+  let validator = null;
+  let failures = 0;
+  let mark = -1;
+  const file = await open(part, "wx", 384);
+  try {
+    for (; ; ) {
+      const controller = new AbortController();
+      let idle = setTimeout(() => controller.abort(), idleMs);
+      try {
+        const resuming = written > 0 && ranges;
+        let response;
+        try {
+          response = await fetchImpl(current, {
+            // Identity: a decoded body matches neither Content-Length nor a byte Range.
+            headers: {
+              "accept-encoding": "identity",
+              ...resuming && validator !== null ? { range: `bytes=${written}-`, "if-range": validator } : {}
+            },
+            signal: controller.signal,
+            // Signed URLs carry no credential, so following a redirect leaks nothing.
+            redirect: "follow"
+          });
+        } catch (error) {
+          if (!transient(error)) throw new DownloadError(`cannot reach the download server: ${failureMessage(error)}`);
+          throw new Interrupted(failureMessage(error));
+        }
+        if ((response.status === 403 || response.status === 410) && options.refresh !== void 0 && !refreshed) {
+          await response.body?.cancel();
+          refreshed = true;
+          current = await options.refresh();
+          continue;
+        }
+        if (response.status === 429 || response.status >= 500) {
+          await response.body?.cancel();
+          throw new Interrupted(`the download server answered HTTP ${response.status}`);
+        }
+        if (response.status === 204) throw new DownloadError("there is nothing to download: it is empty");
+        if (response.status === 416 && resuming) {
+          await response.body?.cancel().catch(() => void 0);
+          written = 0;
+          ranges = false;
+          await file.truncate(0);
+          throw new Interrupted("the resumed range no longer fits the object; starting over");
+        }
+        if (response.status !== 200 && response.status !== 206) {
+          await response.body?.cancel();
+          throw new DownloadError(`the download was refused (HTTP ${response.status})`);
+        }
+        if (response.status === 206) {
+          const range = contentRange(response.headers.get("content-range"));
+          if (!resuming) {
+            await response.body?.cancel().catch(() => void 0);
+            throw new DownloadError("the download server answered a range nobody asked for");
+          }
+          const same = response.headers.get("etag") === validator;
+          if (!same || range === null || range.start !== written || range.end !== (total2 ?? 0) - 1 || range.total !== total2) {
+            await response.body?.cancel().catch(() => void 0);
+            written = 0;
+            ranges = false;
+            await file.truncate(0);
+            throw new Interrupted("the download server answered a different range; starting over");
+          }
+        } else {
+          written = 0;
+          await file.truncate(0);
+          const length = response.headers.get("content-length");
+          total2 = length !== null && /^\d+$/.test(length) ? Number(length) : null;
+          const etag = response.headers.get("etag");
+          validator = etag !== null && !etag.startsWith("W/") ? etag : null;
+          ranges = response.headers.get("accept-ranges")?.toLowerCase() === "bytes" && total2 !== null && validator !== null;
+        }
+        if (response.body === null) throw new Interrupted("the download server sent no body");
+        const reader = response.body.getReader();
+        for (; ; ) {
+          let chunk;
+          try {
+            chunk = await reader.read();
+          } catch (error) {
+            throw new Interrupted(failureMessage(error));
+          }
+          if (chunk.done) break;
+          clearTimeout(idle);
+          idle = setTimeout(() => controller.abort(), idleMs);
+          for (let done = 0; done < chunk.value.length; ) {
+            const { bytesWritten } = await file.write(chunk.value, done, chunk.value.length - done, written + done);
+            done += bytesWritten;
+          }
+          written += chunk.value.length;
+          options.onProgress?.(written, total2);
+        }
+        if (total2 !== null && written !== total2) throw new Interrupted(`the download ended at ${written} of ${total2} bytes`);
+        await file.close();
+        await place(part, dest, options.force === true);
+        return written;
+      } catch (error) {
+        if (!(error instanceof Interrupted)) throw error;
+        if (ranges && written > mark) {
+          failures = 0;
+          mark = written;
+        }
+        failures += 1;
+        if (failures > retries) throw new TransportError(`the download gave up after ${retries} retries: ${error.message}`);
+        await sleep(backoff(failures));
+      } finally {
+        clearTimeout(idle);
+      }
+    }
+  } catch (error) {
+    await file.close().catch(() => void 0);
+    await rm(part, { force: true });
+    throw error;
+  }
+}
+async function place(part, dest, force) {
+  if (force) return rename(part, dest);
+  try {
+    await link(part, dest);
+  } catch (error) {
+    const code = error.code;
+    if (code === "EEXIST") throw new DownloadError(`${dest} appeared while downloading \u2014 pass --force to replace it`);
+    if (code === "EPERM" || code === "ENOTSUP" || code === "EXDEV" || code === "ENOSYS") {
+      throw new DownloadError(
+        `this file system can't move ${dest} into place without risking another file there \u2014 pass --force, or --output on another disk`
+      );
+    }
+    throw error;
+  }
+  await rm(part, { force: true });
+}
+function contentRange(header) {
+  const match = /^bytes (\d+)-(\d+)\/(\d+)$/i.exec(header?.trim() ?? "");
+  return match === null ? null : { start: Number(match[1]), end: Number(match[2]), total: Number(match[3]) };
+}
+function sleep(ms) {
+  return ms <= 0 ? Promise.resolve() : new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+
+// src/core/transfer-upload.ts
+import { constants } from "fs";
+import { open as open2, realpath, stat } from "fs/promises";
+import { sep } from "path";
+var CHUNK_QUANTUM = 256 * 1024;
+var DEFAULT_CHUNK_SIZE = 32 * CHUNK_QUANTUM;
+var UploadError = class extends CommandError {
+  constructor(message) {
+    super(message);
+    this.name = "UploadError";
+  }
+};
+var DEFAULT_RETRIES2 = 8;
+var CHUNK_TIMEOUT_MS = 12e4;
+var SLOW_BYTES_PER_MS = 8;
+function defaultBackoff(attempt) {
+  return Math.min(3e4, 500 * 2 ** (attempt - 1));
+}
+async function uploadFile(path, size, target, options = {}) {
+  const chunkSize = options.chunkSize ?? DEFAULT_CHUNK_SIZE;
+  if (chunkSize <= 0 || chunkSize % CHUNK_QUANTUM !== 0) throw new Error(`chunk size must be a positive multiple of ${CHUNK_QUANTUM}`);
+  const retries = options.retries ?? DEFAULT_RETRIES2;
+  const backoff = options.backoff ?? defaultBackoff;
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  const timeoutFor = (bytes2) => options.timeoutMs ?? CHUNK_TIMEOUT_MS + Math.ceil(bytes2 / SLOW_BYTES_PER_MS);
+  const file = await open2(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0)).catch((error) => {
+    if (error.code === "ELOOP") throw new UploadError(`${path} became a symbolic link \u2014 nothing more was sent`);
+    throw error;
+  });
+  const buffer = Buffer.allocUnsafe(Math.min(chunkSize, Math.max(size, 1)));
+  try {
+    const info = await file.stat();
+    const swapped = options.identity !== void 0 && (info.dev !== options.identity.dev || info.ino !== options.identity.ino);
+    if (!info.isFile() || info.size !== size || swapped) {
+      throw new UploadError(`${path} changed since it was listed \u2014 nothing more was sent`);
+    }
+    if (options.within !== void 0) {
+      const real = await realpath(path).catch(() => "");
+      const now = real === "" ? null : await stat(real).catch(() => null);
+      if (!real.startsWith(options.within + sep) || now?.dev !== info.dev || now?.ino !== info.ino) {
+        throw new UploadError(`${path} no longer lies inside the folder being uploaded \u2014 nothing more was sent`);
+      }
+    }
+    const unchanged = async () => {
+      const after = await file.stat();
+      if (after.size !== info.size || after.mtimeMs !== info.mtimeMs || after.ctimeMs !== info.ctimeMs) {
+        throw new UploadError(`${path} was changed while it was being uploaded \u2014 the upload was not finished`);
+      }
+    };
+    let offset = 0;
+    let failures = 0;
+    let best = 0;
+    let resync = false;
+    for (; ; ) {
+      try {
+        if (resync) {
+          const status2 = await put(fetchImpl, target, null, `bytes */${size}`, timeoutFor(0));
+          if (status2.done) return await unchanged();
+          offset = status2.next;
+          resync = false;
+          if (offset > best) {
+            best = offset;
+            failures = 0;
+          }
+        }
+        if (offset >= size && size > 0) {
+          resync = true;
+          throw new TransportError("the upload ended without the server confirming it");
+        }
+        const length = Math.min(chunkSize, size - offset);
+        const bytes2 = length === 0 ? Buffer.alloc(0) : await readExactly(file, buffer, length, offset, path);
+        const range = size === 0 ? `bytes */0` : `bytes ${offset}-${offset + length - 1}/${size}`;
+        const status = await put(fetchImpl, target, bytes2, range, timeoutFor(length));
+        if (status.done) {
+          options.onProgress?.(size, size);
+          return await unchanged();
+        }
+        if (status.next < offset || status.next > offset + length) {
+          throw new UploadError(`the server reported ${status.next} bytes stored after a chunk ending at ${offset + length}`);
+        }
+        if (status.next === offset) throw new RetryableStatus(308);
+        offset = status.next;
+        if (offset > best) {
+          best = offset;
+          failures = 0;
+        }
+        options.onProgress?.(offset, size);
+      } catch (error) {
+        if (!retryable(error)) throw error;
+        failures += 1;
+        if (failures > retries) {
+          const detail = failureMessage(error);
+          throw new UploadError(`gave up after ${retries} retries: ${detail}`);
+        }
+        resync = true;
+        await sleep2(backoff(failures));
+      }
+    }
+  } finally {
+    await file.close();
+  }
+}
+var RetryableStatus = class extends Error {
+  constructor(status) {
+    super(`the upload server answered HTTP ${status}`);
+    this.status = status;
+  }
+  status;
+};
+async function put(fetchImpl, target, body, contentRange2, timeoutMs) {
+  let response;
+  try {
+    response = await fetchImpl(target.url, {
+      method: "PUT",
+      headers: { ...target.headers, "content-range": contentRange2 },
+      // An empty body still goes as one, so Content-Length is 0.
+      body: body === null ? new Uint8Array(0) : new Uint8Array(body.buffer, body.byteOffset, body.length),
+      signal: AbortSignal.timeout(timeoutMs),
+      redirect: "manual"
+    });
+    await response.body?.cancel();
+  } catch (error) {
+    if (!transient(error)) throw new UploadError(`cannot reach the upload server: ${failureMessage(error)}`);
+    throw new TransportError(failureMessage(error), failureCode(error));
+  }
+  if (response.status === 200 || response.status === 201) return { done: true, next: Number.NaN };
+  if (response.status === 308) return { done: false, next: storedUpTo(response.headers.get("range")) };
+  if (response.status === 429 || response.status >= 500) throw new RetryableStatus(response.status);
+  throw new UploadError(`the upload server refused the bytes (HTTP ${response.status})`);
+}
+function storedUpTo(range) {
+  if (range === null) return 0;
+  const match = /^bytes=0-(\d+)$/i.exec(range.trim());
+  if (match === null) throw new UploadError(`the upload server sent an unreadable Range header: ${range}`);
+  return Number(match[1]) + 1;
+}
+async function readExactly(file, buffer, length, position, path) {
+  let read = 0;
+  while (read < length) {
+    const { bytesRead } = await file.read(buffer, read, length - read, position + read);
+    if (bytesRead === 0) throw new UploadError(`${path} shrank while it was being uploaded`);
+    read += bytesRead;
+  }
+  return buffer.subarray(0, length);
+}
+function retryable(error) {
+  return error instanceof TransportError || error instanceof RetryableStatus;
+}
+function sleep2(ms) {
+  return ms <= 0 ? Promise.resolve() : new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+
+// src/core/transfer.ts
+var FILES_PER_SESSION = 20;
+var FOLDER_FILES_PER_SESSION = 100;
+var POLL_LIMIT_MS = 10 * 6e4;
+var upload = {
+  // The session's create operation; its finalize and chunk operations run as
+  // ordinary requests.
+  handles: (spec) => spec.method === "POST" && spec.bodyFields.some((field) => field.name === "files"),
+  supplies: ["files"],
+  configure(command) {
+    command.argument("<paths...>", "the files and folders to upload (a folder keeps its tree)").addOption(
+      new Option("--on-conflict <how>", "for a name that already exists: keep both, replace it (confirmed), or skip the new file").choices(["keep", "replace", "skip"]).default("keep")
+    ).option("-y, --yes", "confirm --on-conflict replace without the prompt");
+  },
+  async run(context) {
+    const { files, left } = await collectFiles(context.invocation.extra);
+    for (const note of left) context.stderr(`Skipped ${clean(note)}
+`);
+    const onConflict = String(context.invocation.options["onConflict"] ?? "keep");
+    const confirmed = onConflict === "replace" ? await confirmReplace(context) : context.confirmed;
+    const base = context.command.path;
+    const finalize = context.operations.find((operation) => operation.method === "POST" && isChild(base, operation.path, "/finalize"));
+    const show = context.operations.find((operation) => operation.method === "GET" && isChild(base, operation.path, ""));
+    if (finalize === void 0) throw new CommandError("this API has no finalize operation for its upload sessions \u2014 nothing was sent");
+    const batches = batch(files);
+    context.stderr(`Uploading ${files.length} file${files.length === 1 ? "" : "s"} (${bytes(total(files))})\u2026
+`);
+    const results = [];
+    for (const files2 of batches) {
+      try {
+        results.push(await uploadSession(context, files2, { onConflict, confirmed, show: show !== void 0 }));
+      } catch (error) {
+        if (results.length === 0) throw error;
+        const detail = error instanceof Error ? error.message : String(error);
+        const filed = results.map((result) => clean(result["id"])).join(", ");
+        const unsettled = error instanceof Unsettled ? `, and session ${clean(error.sessionId)} may be too` : "";
+        throw new CommandError(
+          `${detail} \u2014 ${results.length} of ${batches.length} uploads were already filed (sessions ${filed})${unsettled}; upload only the files not in those sessions`
+        );
+      }
+    }
+    return results.length === 1 ? results[0] : results;
+  }
+};
+async function uploadSession(context, files, plan) {
+  const created = await context.client.request(context.command.method, context.path, {
+    query: context.invocation.query,
+    body: {
+      ...context.invocation.body ?? {},
+      files: files.map((file) => ({
+        name: file.name,
+        size: file.size,
+        content_type: contentType(file.name),
+        ...file.relativePath === null ? {} : { relative_path: file.relativePath }
+      }))
+    },
+    idempotencyKey: randomUUID()
+  });
+  const session = record(created.body["data"]);
+  const id = typeof session["id"] === "string" ? session["id"] : null;
+  if (id === null || !Array.isArray(session["files"])) throw new CommandError("the API answered the upload session without an id or files");
+  const conflicts = Array.isArray(session["conflicts"]) ? session["conflicts"].length : 0;
+  if (conflicts > 0) {
+    context.stderr(`${conflicts} name${conflicts === 1 ? "" : "s"} already exist${conflicts === 1 ? "s" : ""} there: --on-conflict ${plan.onConflict} decides.
+`);
+  }
+  const remote = session["files"].map(record);
+  const taken = /* @__PURE__ */ new Set();
+  for (const file of files) {
+    const label = file.relativePath ?? file.name;
+    const entry = remote.find(
+      (candidate) => !taken.has(candidate) && candidate["name"] === file.name && (candidate["relative_path"] ?? null) === file.relativePath
+    );
+    if (entry === void 0 || typeof entry["upload_url"] !== "string") throw new CommandError(`the upload session has no upload_url for ${clean(label)}`);
+    taken.add(entry);
+    const url = entry["upload_url"];
+    await uploadFile(file.path, file.size, { url, headers: { "content-type": "application/octet-stream", ...context.client.authorizationFor(url) } }, {
+      onProgress: progress(context, label, file.size),
+      identity: file.identity,
+      ...file.within === null ? {} : { within: file.within }
+    });
+    if (!context.interactive) context.stderr(`Uploaded ${clean(label)} (${bytes(file.size)})
+`);
+  }
+  const sessionPath = `${context.path}/${encodeURIComponent(id)}`;
+  let finalized;
+  try {
+    finalized = await context.client.request("POST", `${sessionPath}/finalize`, {
+      body: { on_conflict: plan.onConflict },
+      idempotencyKey: randomUUID(),
+      confirmed: plan.confirmed
+    });
+  } catch (error) {
+    if (!(error instanceof TransportError) && !(error instanceof HttpError && error.status >= 500)) throw error;
+    throw new Unsettled(
+      id,
+      `the upload's finalize may or may not have taken effect (${error.message}) \u2014 check session ${clean(id)} before uploading these files again`
+    );
+  }
+  const outcome = { ...record(finalized.body["data"]), id };
+  if (!plan.show || outcome["status"] === "nothing_to_upload") return outcome;
+  return { ...outcome, ...await settle(context, sessionPath, id), id };
+}
+var Unsettled = class extends CommandError {
+  constructor(sessionId, message) {
+    super(message);
+    this.sessionId = sessionId;
+  }
+  sessionId;
+};
+async function settle(context, path, id) {
+  const deadline = Date.now() + POLL_LIMIT_MS;
+  let wait = 500;
+  for (; ; ) {
+    let session;
+    try {
+      session = record((await context.client.request("GET", path)).body["data"]);
+    } catch (error) {
+      const passing = error instanceof TransportError || error instanceof HttpError && (error.status === 429 || error.status >= 500);
+      if (!passing || Date.now() > deadline) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Unsettled(id, `the upload was finalized, but its status could not be read (${path}): ${detail} \u2014 do not upload it again`);
+      }
+      await new Promise((resolve2) => setTimeout(resolve2, wait));
+      wait = Math.min(5e3, wait * 2);
+      continue;
+    }
+    const status = session["status"];
+    if (status === "completed") return { status, result: session["result"] ?? null };
+    if (status === "failed") throw new CommandError(`the upload was received but could not be filed (session ${clean(id)})`);
+    if (Date.now() > deadline) {
+      context.stderr(`Still filing the upload; check its status later (session ${clean(session["id"])}).
+`);
+      return { status };
+    }
+    await new Promise((resolve2) => setTimeout(resolve2, wait));
+    wait = Math.min(5e3, wait * 2);
+  }
+}
+function batch(files) {
+  const batches = [];
+  for (const [group, limit] of [
+    [files.filter((file) => file.relativePath === null), FILES_PER_SESSION],
+    [files.filter((file) => file.relativePath !== null), FOLDER_FILES_PER_SESSION]
+  ]) {
+    for (let start = 0; start < group.length; start += limit) batches.push(group.slice(start, start + limit));
+  }
+  return batches;
+}
+function isChild(base, path, suffix) {
+  return path.startsWith(`${base}/`) && new RegExp(`^/\\{[a-z][a-z0-9_]*\\}${suffix}$`).test(path.slice(base.length));
+}
+async function confirmReplace(context) {
+  if (context.invocation.yes || context.confirmed) return true;
+  if (!context.interactive) {
+    throw new UsageError("--on-conflict replace overwrites files and needs your confirmation: run it at a terminal, or pass --yes \u2014 nothing was sent");
+  }
+  const answer = await context.prompt(`Replace files of the same name in ${await context.target()}? [y/N] `);
+  if (!/^y(es)?$/i.test(answer.trim())) throw new LocalError("cancelled \u2014 nothing was sent");
+  return true;
+}
+async function collectFiles(paths) {
+  if (paths.length === 0) throw new UsageError("name at least one file or folder to upload");
+  const files = [];
+  const left = [];
+  for (const given of paths) {
+    const absolute = resolve(given);
+    const info = await lstat(absolute).catch(() => null);
+    if (info === null) throw new UsageError(`${given} does not exist \u2014 nothing was sent`);
+    if (info.isFile()) {
+      if (info.size === 0) left.push(`${given} (empty)`);
+      else files.push({ path: absolute, name: basename(absolute), relativePath: null, size: info.size, identity: { dev: info.dev, ino: info.ino }, within: null });
+    } else if (info.isDirectory()) {
+      const real = await realpath2(absolute);
+      const resolved = await stat2(real);
+      if (!resolved.isDirectory() || resolved.dev !== info.dev || resolved.ino !== info.ino) {
+        throw new UsageError(`${given} changed while it was being read \u2014 nothing was sent`);
+      }
+      await walk(basename(absolute), real, real, files, left);
+    } else {
+      throw new UsageError(`${given} is not a file or folder \u2014 nothing was sent`);
+    }
+  }
+  if (files.length === 0) throw new UsageError("there are no files to upload there \u2014 nothing was sent");
+  for (const file of files) {
+    if (file.within === null) continue;
+    const real = await realpath2(file.path).catch(() => "");
+    const now = real === "" ? null : await stat2(real).catch(() => null);
+    if (!real.startsWith(file.within + sep2) || now?.dev !== file.identity.dev || now?.ino !== file.identity.ino) {
+      throw new UsageError(`${file.relativePath ?? file.name} changed while the folder was being read \u2014 nothing was sent`);
+    }
+  }
+  return { files, left };
+}
+async function walk(name, real, dir, files, left) {
+  const entries = (await readdir(dir, { withFileTypes: true })).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+  for (const entry of entries) {
+    const path = join2(dir, entry.name);
+    const shown = [name, ...relative(real, path).split(sep2)].join("/");
+    if (entry.name.startsWith(".")) {
+      left.push(`${shown} (hidden)`);
+    } else if (entry.isDirectory()) {
+      const info = await lstat(path);
+      if (!info.isDirectory() || !(await realpath2(path)).startsWith(real + sep2)) left.push(`${shown} (outside the folder)`);
+      else await walk(name, real, path, files, left);
+    } else if (entry.isFile()) {
+      const info = await lstat(path);
+      if (!info.isFile()) left.push(`${shown} (not a regular file)`);
+      else if (info.size === 0) left.push(`${shown} (empty)`);
+      else files.push({ path, name: entry.name, relativePath: shown, size: info.size, identity: { dev: info.dev, ino: info.ino }, within: real });
+    } else {
+      left.push(`${shown} (not a regular file)`);
+    }
+  }
+}
+var TYPES = {
+  ".pdf": "application/pdf",
+  ".doc": "application/msword",
+  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  ".xls": "application/vnd.ms-excel",
+  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ".ppt": "application/vnd.ms-powerpoint",
+  ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  ".csv": "text/csv",
+  ".txt": "text/plain",
+  ".md": "text/markdown",
+  ".json": "application/json",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".svg": "image/svg+xml",
+  ".mp4": "video/mp4",
+  ".mov": "video/quicktime",
+  ".zip": "application/zip"
+};
+function contentType(name) {
+  return TYPES[extname(name).toLowerCase()] ?? "application/octet-stream";
+}
+var download = {
+  handles: (spec) => spec.method === "GET",
+  supplies: [],
+  configure(command) {
+    command.option("-o, --output <path>", "where to save the file (default: its name, in the current folder)").option("--force", "replace an existing file at that path");
+  },
+  async run(context) {
+    const ask = async () => {
+      const answer = await context.client.request(context.command.method, context.path, {
+        query: context.invocation.query
+      });
+      const data = record(answer.body["data"]);
+      if (typeof data["url"] !== "string" || data["url"] === "") throw new CommandError("the API answered the download without a url");
+      return { url: data["url"], filename: typeof data["filename"] === "string" ? data["filename"] : "" };
+    };
+    const first = await ask();
+    const dest = await destination(first.filename, context.invocation.options);
+    const size = await downloadFile(first.url, dest, {
+      force: context.invocation.options["force"] === true,
+      refresh: async () => (await ask()).url,
+      onProgress: progress(context, basename(dest), null)
+    });
+    if (!context.interactive) context.stderr(`Saved ${clean(dest)} (${bytes(size)})
+`);
+    return { path: dest, bytes: size };
+  }
+};
+async function destination(filename, options) {
+  const output = typeof options["output"] === "string" ? options["output"] : null;
+  const force = options["force"] === true;
+  let path;
+  if (output !== null) {
+    const info = await stat2(output).catch(() => null);
+    path = resolve(info?.isDirectory() === true ? join2(output, safeName(filename)) : output);
+  } else {
+    path = resolve(safeName(filename));
+  }
+  if (!force && await lstat(path).catch(() => null) !== null) {
+    throw new LocalError(`${path} already exists \u2014 pass --force to replace it, or --output to save elsewhere`);
+  }
+  return path;
+}
+function safeName(filename) {
+  const name = clean(basename(filename.replaceAll("\\", "/"))).trim();
+  if (name === "" || name === "." || name === "..") throw new LocalError("the API gave no usable file name \u2014 pass --output");
+  return name;
+}
+function progress(context, label, size) {
+  if (!context.interactive) return void 0;
+  let last = 0;
+  return (done, total2) => {
+    const now = Date.now();
+    const whole = total2 ?? size;
+    if (now - last < 200 && done !== whole) return;
+    last = now;
+    const share = whole === null || whole === 0 ? "" : ` ${Math.floor(done / whole * 100)}%`;
+    context.stderr(`\r\x1B[2K${clean(label)}${share} ${bytes(done)}${whole === null ? "" : ` of ${bytes(whole)}`}${done === whole ? "\n" : ""}`);
+  };
+}
+function total(files) {
+  return files.reduce((sum, file) => sum + file.size, 0);
+}
+function bytes(count) {
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  let value = count;
+  let unit = 0;
+  while (value >= 1e3 && unit < units.length - 1) {
+    value /= 1e3;
+    unit += 1;
+  }
+  return `${unit === 0 ? value : value.toFixed(1)} ${units[unit]}`;
+}
+function record(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+}
+
+// src/infraone/transfer.ts
+var KINDS = { upload, download };
+function transferFor(spec) {
+  if (spec.transfer === null) return null;
+  const kind = Object.hasOwn(KINDS, spec.transfer) ? KINDS[spec.transfer] : UNKNOWN;
+  return kind.handles(spec) ? kind : null;
+}
+var UNKNOWN = {
+  handles: () => true,
+  supplies: [],
+  configure: () => void 0,
+  run: async (context) => {
+    throw new LocalError(`this version of infraone cannot ${context.command.transfer} files \u2014 nothing was sent`);
+  }
+};
+
+// src/infraone/generator.ts
+import { InvalidArgumentError, Option as Option2 } from "commander";
+var METHODS = ["get", "post", "put", "patch", "delete"];
+var RISKS = ["read", "write", "destructive", "outward"];
+var WORD = /^[a-z][a-z0-9_-]*$/;
+var PATH_PARAM = /\{([a-z][a-z0-9_]*)\}/g;
+var RESERVED = /* @__PURE__ */ new Set(["json", "all", "yes", "help", "version"]);
+function commandSpecs(spec) {
+  const specs = [];
+  for (const [path, item] of Object.entries(spec.paths)) {
+    if (!isRecord2(item)) continue;
+    for (const method of METHODS) {
+      const operation = item[method];
+      if (!isRecord2(operation)) continue;
+      const built = commandSpec(spec, path, method.toUpperCase(), operation);
+      if (built !== null) specs.push(built);
+    }
+  }
+  return specs.sort((left, right) => left.words.join(" ").localeCompare(right.words.join(" ")));
+}
+function commandSpec(spec, path, method, operation) {
+  const command = operation["x-infraone-command"];
+  if (typeof command !== "string") return null;
+  const words = command.trim().split(/\s+/);
+  if (words.length < 2 || !words.every((word) => WORD.test(word))) return null;
+  const parameters = (operation.parameters ?? []).map((parameter) => resolveParameter(spec, parameter)).filter((parameter) => parameter !== null);
+  const pathNames = [...path.matchAll(PATH_PARAM)].map((match) => match[1]);
+  const pathParams = [];
+  for (const name of pathNames) {
+    const parameter = parameters.find((candidate) => candidate.in === "path" && candidate.name === name);
+    pathParams.push({
+      name,
+      location: "path",
+      schema: resolveSchema(spec, parameter?.schema) ?? { type: "string" },
+      required: true,
+      description: parameter?.description ?? ""
+    });
+  }
+  const queryParams = parameters.filter((parameter) => parameter.in === "query").map((parameter) => ({
+    name: parameter.name,
+    location: "query",
+    schema: withItems(spec, resolveSchema(spec, parameter.schema) ?? { type: "string" }),
+    required: parameter.required === true,
+    description: parameter.description ?? ""
+  }));
+  const bodySchema = resolveSchema(spec, operation.requestBody?.content?.["application/json"]?.schema);
+  const required = new Set(bodySchema?.required ?? []);
+  const bodyFields = Object.entries(bodySchema?.properties ?? {}).map(([name, schema]) => {
+    const resolved = withItems(spec, resolveSchema(spec, schema) ?? {});
+    return { name, location: "body", schema: resolved, required: required.has(name), description: resolved.description ?? "" };
+  });
+  const risk = operation["x-infraone-risk"];
+  const names = new Set(queryParams.map((field) => field.name));
+  return {
+    words,
+    method,
+    path,
+    tool: operation["x-infraone-tool"] ?? operation.operationId ?? null,
+    summary: operation.summary ?? "",
+    description: operation.description ?? "",
+    // An operation that does not say what it risks is treated as the
+    // riskiest kind, so it asks before it runs.
+    risk: typeof risk === "string" && RISKS.includes(risk) ? risk : "destructive",
+    scope: operation["x-infraone-scope"] ?? null,
+    transfer: operation["x-infraone-transfer"] ?? null,
+    pathParams,
+    queryParams,
+    bodyFields,
+    hasBody: bodySchema !== null,
+    paged: names.has("cursor") && names.has("limit"),
+    dataSchema: dataSchema(spec, operation, names.has("cursor") && names.has("limit"))
+  };
+}
+function dataSchema(spec, operation, paged) {
+  const ok = operation.responses?.["200"] ?? operation.responses?.["201"];
+  const envelope = resolveSchema(spec, ok?.content?.["application/json"]?.schema);
+  const data = resolveSchema(spec, envelope?.properties?.["data"]);
+  if (data === null) return null;
+  return paged && data.type === "array" ? resolveSchema(spec, data.items) : data;
+}
+function mountCommands(program, specs, action) {
+  const placed = [];
+  const leaves = /* @__PURE__ */ new Set();
+  for (const spec of specs) {
+    let parent = program;
+    let blocked = false;
+    for (const word of spec.words.slice(0, -1)) {
+      const existing = parent.commands.find((command) => command.name() === word);
+      if (existing !== void 0 && leaves.has(existing)) {
+        blocked = true;
+        break;
+      }
+      parent = existing ?? parent.command(word).description(`${word} commands`);
+    }
+    const leafName = spec.words.at(-1);
+    if (blocked || parent.commands.some((command) => command.name() === leafName)) continue;
+    const leaf = buildLeaf(parent.command(leafName), spec, action);
+    leaves.add(leaf);
+    placed.push(spec);
+  }
+  return placed;
+}
+function buildLeaf(command, spec, action) {
+  const summary = clean(spec.summary === "" ? spec.words.join(" ") : spec.summary);
+  command.summary(summary).description(spec.description === "" ? summary : `${summary}
+
+${cleanMultiline(spec.description)}`);
+  for (const field of spec.pathParams) command.argument(`<${field.name}>`, clean(field.description));
+  const transfer = transferFor(spec);
+  transfer?.configure(command);
+  const bound = [];
+  const taken = /* @__PURE__ */ new Set();
+  const supplied = (field) => field.location === "body" && transfer?.supplies.includes(field.name) === true;
+  for (const field of [...spec.queryParams, ...spec.bodyFields].filter((candidate) => !supplied(candidate))) {
+    const base = kebab(field.name);
+    const flag = RESERVED.has(base) || taken.has(base) ? `${field.location}-${base}` : base;
+    if (taken.has(flag)) continue;
+    taken.add(flag);
+    bound.push(...addFieldOption(command, field, flag));
+  }
+  command.option("--json", "print the response's data as JSON");
+  if (spec.paged) command.option("--all", "follow next_cursor and print every page");
+  if ((spec.risk === "destructive" || spec.risk === "outward") && !command.options.some((option) => option.long === "--yes")) {
+    command.option("-y, --yes", `confirm this ${spec.risk} operation without the prompt`);
+  }
+  command.action(async (...args) => {
+    const self = args.at(-1);
+    const options = self.opts();
+    const positional = self.processedArgs;
+    const pathValues = {};
+    spec.pathParams.forEach((field, index) => {
+      pathValues[field.name] = String(positional[index]);
+    });
+    const query = {};
+    const body = {};
+    for (const { field, attribute } of bound) {
+      const value = options[attribute];
+      if (value === void 0) continue;
+      (field.location === "query" ? query : body)[field.name] = value;
+    }
+    await action(spec, {
+      pathValues,
+      query,
+      body: spec.hasBody ? body : void 0,
+      json: options["json"] === true,
+      all: options["all"] === true,
+      yes: options["yes"] === true,
+      extra: positional.slice(spec.pathParams.length).flat().map(String),
+      options
+    });
+  });
+  return command;
+}
+function addFieldOption(command, field, flag) {
+  const schema = field.schema;
+  const description = optionDescription(field);
+  if (schema.type === "boolean") {
+    const on = new Option2(`--${flag}`, description);
+    const off = new Option2(`--no-${flag}`, `send ${field.name} as false`);
+    command.addOption(on).addOption(off);
+    return [{ field, attribute: on.attributeName() }];
+  }
+  const option = new Option2(`--${flag} <${valueName(schema)}>`, description);
+  if (schema.type === "array") {
+    const items = schema.items ?? {};
+    if (items.type === "object" || items.type === "array") {
+      option.argParser((value) => parseJson(value, "array"));
+    } else {
+      option.argParser((value, previous) => [...Array.isArray(previous) ? previous : [], scalar(value, items)]);
+    }
+  } else if (schema.type === "object" || schema.type === void 0) {
+    option.argParser((value) => schema.type === "object" ? parseJson(value, "object") : value);
+  } else if (Array.isArray(schema.enum) && schema.enum.length > 0) {
+    option.choices(schema.enum.map(String)).argParser((value) => enumValue(value, schema));
+  } else {
+    option.argParser((value) => scalar(value, schema));
+  }
+  if (field.required) option.makeOptionMandatory();
+  command.addOption(option);
+  return [{ field, attribute: option.attributeName() }];
+}
+function optionDescription(field) {
+  const parts = [field.description === "" ? field.name.replaceAll("_", " ") : clean(field.description)];
+  const schema = field.schema;
+  if (schema.type === "array") parts.push("(repeatable)");
+  if (schema.default !== void 0) parts.push(`(default: ${clean(JSON.stringify(schema.default))})`);
+  return parts.join(" ");
+}
+function valueName(schema) {
+  if (schema.type === "integer" || schema.type === "number") return "n";
+  if (schema.type === "object" || schema.type === "array" && (schema.items?.type === "object" || schema.items?.type === "array")) {
+    return "json";
+  }
+  return "value";
+}
+function scalar(value, schema) {
+  switch (schema.type) {
+    case "integer": {
+      if (!/^-?\d+$/.test(value)) throw new InvalidArgumentError("expected an integer");
+      return bounded(Number.parseInt(value, 10), schema);
+    }
+    case "number": {
+      const number = Number(value);
+      if (value.trim() === "" || !Number.isFinite(number)) throw new InvalidArgumentError("expected a number");
+      return bounded(number, schema);
+    }
+    case "boolean": {
+      if (value === "true") return true;
+      if (value === "false") return false;
+      throw new InvalidArgumentError("expected true or false");
+    }
+    default:
+      if (Array.isArray(schema.enum) && schema.enum.length > 0) return enumValue(value, schema);
+      return value;
+  }
+}
+function enumValue(value, schema) {
+  const match = (schema.enum ?? []).find((candidate) => String(candidate) === value);
+  if (match === void 0) throw new InvalidArgumentError(`expected one of ${(schema.enum ?? []).map(String).join(", ")}`);
+  return match;
+}
+function bounded(value, schema) {
+  if (schema.minimum !== void 0 && value < schema.minimum) {
+    throw new InvalidArgumentError(`expected at least ${schema.minimum}`);
+  }
+  if (schema.maximum !== void 0 && value > schema.maximum) {
+    throw new InvalidArgumentError(`expected at most ${schema.maximum}`);
+  }
+  return value;
+}
+function parseJson(value, kind) {
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new InvalidArgumentError(`expected a JSON ${kind}`);
+  }
+  if (kind === "array" ? !Array.isArray(parsed) : typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new InvalidArgumentError(`expected a JSON ${kind}`);
+  }
+  return parsed;
+}
+function kebab(name) {
+  return name.replaceAll("_", "-").toLowerCase();
+}
+function resolveParameter(spec, parameter) {
+  if ("$ref" in parameter) {
+    const name = parameter.$ref.replace(/^#\/components\/parameters\//, "");
+    return spec.components?.parameters?.[name] ?? null;
+  }
+  return typeof parameter.name === "string" && typeof parameter.in === "string" ? parameter : null;
+}
+function withItems(spec, schema) {
+  if (schema.type !== "array" || schema.items === void 0) return schema;
+  return { ...schema, items: resolveSchema(spec, schema.items) ?? {} };
+}
+function resolveSchema(spec, schema, depth = 0) {
+  if (schema === void 0 || !isRecord2(schema)) return null;
+  if (typeof schema.$ref === "string") {
+    if (depth > 16) return null;
+    const name = schema.$ref.replace(/^#\/components\/schemas\//, "");
+    return resolveSchema(spec, spec.components?.schemas?.[name], depth + 1);
+  }
+  return schema;
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/infraone/spec.ts
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "fs";
+import { join as join3 } from "path";
+var SPEC_TIMEOUT_MS = 1e4;
+async function loadSpec(config) {
+  const cached = readCached(config);
+  if (cached !== null) return { spec: cached.spec, fingerprint: cached.fingerprint, source: "cache" };
+  return { spec: await bundledSpec(), fingerprint: null, source: "bundled" };
+}
+async function bundledSpec() {
+  const module = await import("./infraone-A3KDADRM.js");
+  const spec = module.default;
+  if (!isSpec(spec)) throw new Error("the bundled spec/infraone.json is not an OpenAPI document");
+  return spec;
+}
+async function fetchSpec(client) {
+  const answer = await client.request("GET", "/v1/openapi.json", { anonymous: true, timeoutMs: SPEC_TIMEOUT_MS });
+  if (!isSpec(answer.body)) throw new Error("the server's spec is not an OpenAPI document");
+  return { spec: answer.body, fingerprint: answer.fingerprint, apiVersion: answer.apiVersion };
+}
+async function refreshSpec(config, client) {
+  try {
+    const fetched = await fetchSpec(client);
+    writeCached(config, { api_url: config.apiUrl, api_version: fetched.apiVersion, fingerprint: fetched.fingerprint, spec: fetched.spec });
+    return { spec: fetched.spec, fingerprint: fetched.fingerprint, source: "server" };
+  } catch {
+    return null;
+  }
+}
+function cachePath(config) {
+  return join3(config.cacheDir, `spec-${baseKey(config.apiUrl)}.json`);
+}
+function readCached(config) {
+  try {
+    const parsed = JSON.parse(readFileSync(cachePath(config), "utf8"));
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const file = parsed;
+    if (file["api_url"] !== config.apiUrl || !isSpec(file["spec"])) return null;
+    return {
+      api_url: config.apiUrl,
+      api_version: typeof file["api_version"] === "string" ? file["api_version"] : null,
+      fingerprint: typeof file["fingerprint"] === "string" ? file["fingerprint"] : null,
+      spec: file["spec"]
+    };
+  } catch {
+    return null;
+  }
+}
+var uniqueCounter = 0;
+function writeCached(config, file) {
+  const path = cachePath(config);
+  const temp = `${path}.${process.pid}.${++uniqueCounter}.tmp`;
+  try {
+    mkdirSync(config.cacheDir, { recursive: true });
+    writeFileSync(temp, JSON.stringify(file));
+    renameSync(temp, path);
+  } catch {
+    rmSync(temp, { force: true });
+  }
+}
+function isSpec(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const paths = value["paths"];
+  return typeof paths === "object" && paths !== null && !Array.isArray(paths);
+}
+
+export {
+  resolveConfig,
+  InfraoneClient,
+  login,
+  logout,
+  whoami,
+  describeSession,
+  collectFiles,
+  transferFor,
+  commandSpecs,
+  mountCommands,
+  loadSpec,
+  refreshSpec
+};