@ornncompute/cli 0.2.23 → 1.0.25

package/src/admin-shell.mjs

@@ -0,0 +1,322 @@
+import { adminCommandHandler } from "./admin-command-handlers.mjs";
+
+const DEFAULT_PAGE_LIMIT = 50;
+const MAX_PAGE_LIMIT = 500;
+
+export class AdminUsageError extends Error {
+  constructor(message, { code = "usage_error", field } = {}) {
+    super(message);
+    this.name = "AdminUsageError";
+    this.code = code;
+    this.field = field;
+  }
+}
+
+function vnextCommand(capability) {
+  return capability.cli?.vnext?.command ?? capability.cli?.command ?? [];
+}
+
+function adminCommands(catalog) {
+  return catalog
+    .filter((capability) => capability.cli?.vnext?.audience === "admin")
+    .sort((left, right) =>
+      vnextCommand(left).join(" ").localeCompare(vnextCommand(right).join(" "))
+    );
+}
+
+function commandMatch(catalog, argv) {
+  return adminCommands(catalog)
+    .filter((capability) => vnextCommand(capability).every((part, index) => argv[index] === part))
+    .sort((left, right) => vnextCommand(right).length - vnextCommand(left).length)[0];
+}
+
+export function adminCommandData(capability) {
+  const help = capability.cli.vnext;
+  return {
+    command: vnextCommand(capability).join(" "),
+    outcome: help.outcome,
+    human: help.human,
+    automation: help.automation,
+    accepted_references: help.acceptedReferences ?? [],
+    review: help.review ?? null,
+    resumable_states: help.resumableStates ?? [],
+    related: help.related ?? [],
+  };
+}
+
+export function adminRootData(catalog, roots, selectedRoot) {
+  const commands = adminCommands(catalog);
+  return {
+    roots: roots
+      .filter((root) => selectedRoot === undefined || root.name === selectedRoot)
+      .map((root) => ({
+        name: root.name,
+        commands: commands
+          .filter((capability) => vnextCommand(capability)[1] === root.name)
+          .map(adminCommandData),
+      })),
+  };
+}
+
+export function resolveAdminRequest(catalog, roots, argv) {
+  if (
+    argv.length === 0 ||
+    (argv.length === 1 && (argv[0] === "--help" || argv[0] === "-h" || argv[0] === "help"))
+  ) {
+    return { kind: "root", command: "admin" };
+  }
+
+  if (argv[0] === "help") {
+    const targetArgv = ["admin", ...argv.slice(1)];
+    const target = commandMatch(catalog, targetArgv);
+    if (target && targetArgv.length === vnextCommand(target).length) {
+      return {
+        kind: "help",
+        command: `help ${vnextCommand(target).join(" ")}`,
+        capability: target,
+      };
+    }
+    if (argv.length === 2) {
+      const root = roots.find((candidate) => candidate.name === argv[1]);
+      if (root) return { kind: "root", command: `admin ${root.name}`, root: root.name };
+    }
+    throw new AdminUsageError(
+      "The requested admin command is unavailable for the current authorization.",
+      {
+        code: "admin_command_unavailable",
+      }
+    );
+  }
+
+  if (argv.length === 1) {
+    const root = roots.find((candidate) => candidate.name === argv[0]);
+    if (root) return { kind: "root", command: `admin ${root.name}`, root: root.name };
+  }
+
+  const capability = commandMatch(catalog, ["admin", ...argv]);
+  if (!capability) {
+    throw new AdminUsageError(
+      "The requested admin command is unavailable for the current authorization.",
+      {
+        code: "admin_command_unavailable",
+      }
+    );
+  }
+  const command = vnextCommand(capability).join(" ");
+  const rest = argv.slice(vnextCommand(capability).length - 1);
+  if (rest.includes("--help") || rest.includes("-h")) {
+    if (rest.length !== 1) throw new AdminUsageError(`Usage: ${capability.cli.vnext.human}`);
+    return { kind: "help", command: `help ${command}`, capability };
+  }
+  const handler = adminCommandHandler(capability);
+  return {
+    kind: "command",
+    command,
+    capability,
+    handler,
+    ...(handler ? handler.parse(rest, capability) : parseAdminInput(capability, rest)),
+  };
+}
+
+function parseOptions(argv, allowed, usage) {
+  const options = {};
+  const positionals = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (!argument.startsWith("--")) {
+      positionals.push(argument);
+      continue;
+    }
+    const separator = argument.indexOf("=");
+    const name = argument.slice(2, separator === -1 ? undefined : separator);
+    if (!allowed.includes(name)) throw new AdminUsageError(`${usage}\nUnknown option: --${name}`);
+    const value = separator === -1 ? argv[index + 1] : argument.slice(separator + 1);
+    if (!value || (separator === -1 && value.startsWith("--"))) {
+      throw new AdminUsageError(`${usage}\n--${name} requires a value.`, { field: name });
+    }
+    if (options[name] !== undefined) {
+      throw new AdminUsageError(`${usage}\n--${name} may be supplied only once.`, { field: name });
+    }
+    options[name] = value;
+    if (separator === -1) index += 1;
+  }
+  return { options, positionals };
+}
+
+function positiveInteger(value, name, maximum) {
+  if (value === undefined) return undefined;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > maximum) {
+    throw new AdminUsageError(`--${name} must be an integer from 1 to ${maximum}.`, {
+      field: name,
+    });
+  }
+  return parsed;
+}
+
+function parseAdminInput(capability, argv) {
+  const command = vnextCommand(capability).join(" ");
+  const help = capability.cli.vnext;
+  const usage = `Usage: ${help.human}`;
+  const allowed = [...help.human.matchAll(/--([a-z0-9-]+)/g)].map((match) => match[1]);
+  const { options, positionals } = parseOptions(argv, allowed, usage);
+  const nodeCommand = (help.acceptedReferences ?? []).includes("canonical node ID");
+  if ((nodeCommand && positionals.length !== 1) || (!nodeCommand && positionals.length !== 0)) {
+    throw new AdminUsageError(usage);
+  }
+
+  const limit = positiveInteger(options.limit, "limit", MAX_PAGE_LIMIT) ?? DEFAULT_PAGE_LIMIT;
+  const input = {};
+  if (nodeCommand) input.node_id = positionals[0];
+  if (options.operator) input.operator = options.operator;
+  if (options.facility) input.facility_id = options.facility;
+  if (options.status) input.status = options.status;
+  if (options.email) input.email = options.email;
+  if (options.organization) input.organization = options.organization;
+  if (options.name) input.name = options.name;
+  if (options.span) input.span = options.span;
+  if (options.start) input.start = options.start;
+  if (options.end) input.end = options.end;
+  if (options.before) input.before = options.before;
+  if (options.stream) input.stream = options.stream;
+  if (options.cursor && command === "admin nodes logs") input.cursor = options.cursor;
+  if (command === "admin users search") input.max = 1000;
+  const maxPoints = positiveInteger(options["max-points"], "max-points", 500);
+  if (maxPoints !== undefined) input.max_points = maxPoints;
+  const count = positiveInteger(options.count, "count", 500);
+  if (count !== undefined) input.count = count;
+
+  return {
+    input,
+    pagination: {
+      cursor: options.cursor,
+      limit: command === "admin nodes logs" ? (count ?? 200) : limit,
+    },
+  };
+}
+
+function collectionKey(capability) {
+  const [, root, leaf] = vnextCommand(capability);
+  if (root === "enrollment-tokens") return "enrollment_tokens";
+  if (root === "nodes" && leaf === "logs") return "logs";
+  return ["facilities", "nodes", "operators", "reservations", "users"].includes(root) ? root : null;
+}
+
+function isSensitiveAdminField(key) {
+  const normalized = key.replaceAll(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+  return (
+    normalized === "authorization" ||
+    normalized === "session" ||
+    normalized === "token" ||
+    normalized.endsWith("_session") ||
+    normalized.endsWith("_token") ||
+    normalized.includes("access_token") ||
+    normalized.includes("api_key") ||
+    normalized.includes("credential") ||
+    normalized.includes("password") ||
+    normalized.includes("plaintext") ||
+    normalized.includes("private_key") ||
+    normalized.includes("secret")
+  );
+}
+
+function sanitizeAdminValue(value) {
+  if (Array.isArray(value)) return value.map(sanitizeAdminValue);
+  if (!value || typeof value !== "object") return value;
+  const safe = {};
+  for (const [key, child] of Object.entries(value)) {
+    if (isSensitiveAdminField(key)) continue;
+    safe[key] = sanitizeAdminValue(child);
+  }
+  return safe;
+}
+
+function collectionRows(payload, key) {
+  if (Array.isArray(payload)) return payload;
+  if (!payload || typeof payload !== "object") return [];
+  for (const candidate of [key, "items", "results", "data", "entries", "events", "records"]) {
+    if (Array.isArray(payload[candidate])) return payload[candidate];
+  }
+  return [];
+}
+
+function encodeCursor(command, offset) {
+  return Buffer.from(JSON.stringify({ command, offset }), "utf8").toString("base64url");
+}
+
+function decodeCursor(command, cursor) {
+  if (!cursor) return 0;
+  try {
+    const decoded = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+    if (decoded.command === command && Number.isInteger(decoded.offset) && decoded.offset >= 0) {
+      return decoded.offset;
+    }
+    if (decoded.command !== undefined || decoded.offset !== undefined) {
+      throw new AdminUsageError("The pagination cursor belongs to a different admin command.", {
+        code: "invalid_cursor",
+        field: "cursor",
+      });
+    }
+  } catch (error) {
+    if (error instanceof AdminUsageError) throw error;
+  }
+  return 0;
+}
+
+export function finalizeAdminResult(capability, payload, pagination) {
+  if (!pagination) return { data: sanitizeAdminValue(payload), page: null };
+  const command = vnextCommand(capability).join(" ");
+  const key = collectionKey(capability);
+  if (!key) return { data: sanitizeAdminValue(payload), page: null };
+  const rows = collectionRows(payload, key);
+  const offset = decodeCursor(command, pagination.cursor);
+  const selected = rows.slice(offset, offset + pagination.limit).map(sanitizeAdminValue);
+  const ownerNextCursor =
+    payload && !Array.isArray(payload)
+      ? (payload.next_cursor ?? payload.nextCursor ?? payload.page?.next_cursor ?? null)
+      : null;
+  const nextCursor =
+    offset + selected.length < rows.length
+      ? encodeCursor(command, offset + selected.length)
+      : (ownerNextCursor ?? null);
+  return {
+    data: { [key]: selected },
+    page: {
+      limit: pagination.limit,
+      returned: selected.length,
+      next_cursor: nextCursor,
+    },
+  };
+}
+
+export function writeAdminRootHuman(stdout, data) {
+  stdout.write("Ornn admin\n\nAuthorized resources:\n");
+  for (const root of data.roots) {
+    stdout.write(`  ${root.name}\n`);
+    for (const command of root.commands)
+      stdout.write(`    ${command.command}  ${command.outcome}\n`);
+  }
+}
+
+export function writeAdminHelpHuman(stdout, capability) {
+  const data = adminCommandData(capability);
+  stdout.write(`${data.command}\n\nOutcome: ${data.outcome}\n\n`);
+  stdout.write(`Usage:\n  ${data.human}\n\nAutomation:\n  ${data.automation}\n`);
+}
+
+export function writeAdminResultHuman(stdout, command, result) {
+  const key = result.page ? Object.keys(result.data)[0] : null;
+  if (!key) {
+    stdout.write(`${JSON.stringify(result.data, null, 2)}\n`);
+    return;
+  }
+  const rows = result.data[key];
+  if (rows.length === 0) {
+    stdout.write(`No ${key.replaceAll("_", " ")} found.\n`);
+  } else {
+    for (const row of rows) stdout.write(`${JSON.stringify(row)}\n`);
+  }
+  if (result.page.next_cursor) {
+    stdout.write(`Next: ornn ${command} --cursor ${result.page.next_cursor}\n`);
+  }
+}

package/src/api-client.mjs

@@ -1,6 +1,15 @@
-import { clearAuthSession, configuredApiBaseUrl, loadAuthSession } from "./auth-store.mjs";
+import { createRequire } from "node:module";
+
+import {
+  clearAuthCredentials,
+  configuredApiBaseUrl,
+  configuredInstallerBaseUrl,
+  loadAuthSession,
+} from "./auth-store.mjs";
 import { resolveAuthBaseUrl } from "./device-auth.mjs";
 
+const { version: CLI_VERSION } = createRequire(import.meta.url)("../package.json");
+
 export class CliApiError extends Error {
   constructor(message, { status, detail, genericFallback = false } = {}) {
     super(message);
@@ -52,10 +61,7 @@ function gatewayOriginForAuthOrigin(value, sourceName) {
   if (url.hostname === "compute.ornn.com") {
     return "https://api.ornn.com";
   }
-  if (
-    url.hostname === "staging.compute.ornn.com" ||
-    url.hostname === "staging.fabric.ornn.com"
-  ) {
+  if (url.hostname === "staging.compute.ornn.com" || url.hostname === "staging.fabric.ornn.com") {
     return "https://staging.api.ornn.com";
   }
   const dynamicMatch = url.hostname.match(/^([a-z0-9-]+)\.fabric\.ornn\.com$/i);
@@ -72,16 +78,32 @@ export async function loadRequiredSession({ env = process.env } = {}) {
   }
   return session;
 }
+export function userCredentialHeaders(session) {
+  if (!session?.accessToken) return {};
+  const headers = {
+    Authorization: `Bearer ${session.accessToken}`,
+    // This marker and the organization selector grant nothing by themselves.
+    // The gateway re-resolves the bearer and replaces them with trusted scope.
+    "X-Ornn-Credential-Type": "user",
+    "X-Ornn-CLI-Version": CLI_VERSION,
+  };
+  if (typeof session.selectedOrganizationId === "string" && session.selectedOrganizationId.trim()) {
+    headers["X-Organization-Id"] = session.selectedOrganizationId.trim();
+  }
+  return headers;
+}
 
 export async function cliRequest({
   authRequired = true,
   body,
   endpoint,
+  headers: extraHeaders = {},
   env = process.env,
   fetchImpl = fetch,
   method = "GET",
   raw = false,
   session,
+  signal,
   timeoutMs,
 } = {}) {
   const authSession = session ?? (authRequired ? await loadRequiredSession({ env }) : null);
@@ -89,15 +111,24 @@ export async function cliRequest({
   const url = new URL(endpoint, `${baseUrl}/`);
   const headers = {
     Accept: raw ? "*/*" : "application/json",
+    ...extraHeaders,
   };
-
-  if (authSession?.accessToken) {
-    headers.Authorization = `Bearer ${authSession.accessToken}`;
-    // Explicitly select the gateway's user-credential resolver. This marker
-    // grants nothing by itself; the gateway still has to resolve the bearer
-    // through authorization and derive the caller's organization server-side.
-    headers["X-Ornn-Credential-Type"] = "user";
+  for (const name of Object.keys(headers)) {
+    if (
+      [
+        "authorization",
+        "x-auth-tenant-id",
+        "x-auth-user-id",
+        "x-organization-id",
+        "x-ornn-credential-type",
+        "x-ornn-cli-version",
+        "x-tenant-id",
+      ].includes(name.toLowerCase())
+    ) {
+      delete headers[name];
+    }
   }
+  Object.assign(headers, userCredentialHeaders(authSession));
 
   let requestBody;
   if (body !== undefined) {
@@ -107,33 +138,43 @@ export async function cliRequest({
 
   let response;
   try {
+    const requestSignal = signal ?? (timeoutMs ? AbortSignal.timeout(timeoutMs) : undefined);
     response = await fetchImpl(url, {
       body: requestBody,
       headers,
       method,
-      ...(timeoutMs ? { signal: AbortSignal.timeout(timeoutMs) } : {}),
+      ...(requestSignal ? { signal: requestSignal } : {}),
     });
   } catch (error) {
     // Detect the timeout/abort case before the generic network-failure wrapping
     // below, so a wedged compute call (e.g. status blocked behind an
     // unresponsive FUSE mount) reports a customer-facing timeout instead of an
     // opaque "Could not reach Ornn" message.
+    if (signal?.aborted && (error?.name === "TimeoutError" || error?.name === "AbortError")) {
+      throw error;
+    }
     if (timeoutMs && (error?.name === "TimeoutError" || error?.name === "AbortError")) {
       throw new CliApiError(
-        `Ornn did not respond within ${Math.round(timeoutMs / 1000)} seconds. The service or a node mount may be unresponsive; try again shortly.`,
+        `Ornn did not respond within ${Math.round(timeoutMs / 1000)} seconds. The service or a node mount may be unresponsive; try again shortly.`
       );
     }
     const message = error instanceof Error ? error.message : String(error);
     throw new CliApiError(
-      `Could not reach Ornn at ${baseUrl} (${message}). Check your network connection and that ${baseUrl} is the correct Ornn API endpoint, then try again.`,
+      `Could not reach Ornn at ${baseUrl} (${message}). Check your network connection and that ${baseUrl} is the correct Ornn API endpoint, then try again.`
     );
   }
 
   if (raw) {
     const text = await response.text();
     if (!response.ok) {
-      await handleAuthExpiry({ env, response, hadToken: Boolean(authSession?.accessToken) });
-      throw new CliApiError(text || response.statusText, {
+      await handleAuthExpiry({ env, response, accessToken: authSession?.accessToken });
+      const message =
+        text ||
+        response.statusText ||
+        (response.status === 403
+          ? "Your account is not authorized for this command."
+          : `Ornn request failed with HTTP ${response.status}.`);
+      throw new CliApiError(message, {
         status: response.status,
         genericFallback: true,
       });
@@ -146,8 +187,8 @@ export async function cliRequest({
     // Always throws: handles the 401/expired-session case (clearing the
     // stored token) and the generic detail-surfacing case.
     await raiseForFailedResponse({
+      accessToken: authSession?.accessToken,
       env,
-      hadToken: Boolean(authSession?.accessToken),
       response,
       text,
       url: url.toString(),
@@ -172,17 +213,17 @@ export async function cliRequest({
  *   status text) when the body has no usable detail.
  */
 export async function raiseForFailedResponse({
+  accessToken,
   env = process.env,
   fallbackMessage,
   formatMessage = (message) => message,
-  hadToken,
   response,
   text,
   url,
 } = {}) {
   // Clear a dead token before parsing, so a 401 with a non-JSON body
   // (e.g. a gateway/WAF error page) still triggers the re-login flow.
-  await handleAuthExpiry({ env, response, hadToken });
+  await handleAuthExpiry({ accessToken, env, response });
   const data = text ? parseJson(text, url, response) : null;
   const detail = data?.detail ?? data?.error ?? response.statusText;
   const detailText = detailMessage(detail);
@@ -203,26 +244,32 @@ export async function raiseForFailedResponse({
 }
 
 export function resolveInstallerBaseUrl({ env = process.env } = {}) {
-  const explicit = env.ORNN_INSTALLER_URL?.trim() || env.NEXT_PUBLIC_INSTALLER_URL?.trim();
-  if (!explicit) {
+  const [value, source] = env.ORNN_INSTALLER_URL?.trim()
+    ? [env.ORNN_INSTALLER_URL, "ORNN_INSTALLER_URL"]
+    : env.NEXT_PUBLIC_INSTALLER_URL?.trim()
+      ? [env.NEXT_PUBLIC_INSTALLER_URL, "NEXT_PUBLIC_INSTALLER_URL"]
+      : [configuredInstallerBaseUrl(env), "configured installerBaseUrl"];
+  if (!value?.trim()) {
     return null;
   }
-  return requireValidBaseUrl(explicit, "ORNN_INSTALLER_URL", { allowPath: true });
+  return requireValidBaseUrl(value.trim(), source, { allowPath: true });
 }
 
 function operatorProxyEndpoint(endpoint) {
-  return normalizeComputePath(endpoint);
+  return `/v1/staff${normalizeComputePath(endpoint)}`;
 }
 
 // Staff path: CLI bearer → gateway /v1/orchestrator/ → the owning service.
 // The gateway resolves the bearer and applies staff policy; the CLI never ships
-// a reviewer or service secret.
+// a review secret or service secret.
 export async function operatorRequest({
   body,
   endpoint,
+  headers,
   env = process.env,
   fetchImpl = fetch,
   method = "GET",
+  signal,
 } = {}) {
   const session = await loadAuthSession({ env });
   if (!session?.accessToken) {
@@ -235,12 +282,18 @@ export async function operatorRequest({
     body,
     endpoint: operatorProxyEndpoint(endpoint),
     env,
+    headers,
     fetchImpl,
     method,
+    signal,
     authRequired: true,
   });
 }
 
+export function computeEndpoint(path) {
+  return `/v1/workflows/compute${normalizeComputePath(path)}`;
+}
+
 export function normalizeComputePath(path) {
   if (!path || typeof path !== "string") {
     throw new CliApiError("API path is required.");
@@ -291,11 +344,11 @@ function parseJson(text, url, response) {
   }
 }
 
-async function handleAuthExpiry({ env, response, hadToken }) {
-  if (response.status !== 401 || !hadToken) {
+async function handleAuthExpiry({ accessToken, env, response }) {
+  if (response.status !== 401 || !accessToken) {
     return;
   }
-  await clearAuthSession({ env });
+  await clearAuthCredentials({ env, expectedAccessToken: accessToken });
   throw new CliApiError(
     "Your Ornn session has expired or was revoked. Run `ornn login` to sign in again.",
     {

package/src/atomic-output.mjs

@@ -0,0 +1,112 @@
+import { constants } from "node:fs";
+import { chmod, link, lstat, open, rename, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { Readable } from "node:stream";
+import { randomUUID } from "node:crypto";
+
+export class AtomicOutputExistsError extends Error {
+  constructor(path) {
+    super(`Refusing to replace existing file: ${path}`);
+    this.name = "AtomicOutputExistsError";
+    this.code = "destination_exists";
+    this.path = path;
+  }
+}
+
+async function destinationExists(path) {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+export async function assertAtomicOutputAvailable(destination, { overwrite = false } = {}) {
+  if (typeof destination !== "string" || !destination.trim()) {
+    throw new TypeError("An output path is required.");
+  }
+  if (!overwrite && (await destinationExists(destination))) {
+    throw new AtomicOutputExistsError(destination);
+  }
+}
+
+function nodeReadable(content) {
+  if (content && typeof content.getReader === "function") return Readable.fromWeb(content);
+  if (content && typeof content.pipe === "function") return content;
+  return null;
+}
+async function writeReadable(handle, readable) {
+  for await (const chunk of readable) {
+    const bytes =
+      typeof chunk === "string"
+        ? Buffer.from(chunk)
+        : chunk instanceof Uint8Array || chunk instanceof DataView
+          ? Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength)
+          : null;
+    if (!bytes) throw new TypeError("Readable atomic output chunks must be bytes or text.");
+    let offset = 0;
+    while (offset < bytes.byteLength) {
+      const result = await handle.write(bytes, offset, bytes.byteLength - offset);
+      if (result.bytesWritten === 0) throw new Error("Atomic output write made no progress.");
+      offset += result.bytesWritten;
+    }
+  }
+}
+
+/**
+ * Writes bytes through a unique same-directory temporary file and publishes
+ * them atomically. Without overwrite, hard-link publication provides an atomic
+ * no-replace operation; replacement uses an atomic rename.
+ */
+export async function writeAtomicOutput(
+  destination,
+  content,
+  { mode = 0o644, overwrite = false } = {}
+) {
+  await assertAtomicOutputAvailable(destination, { overwrite });
+  if (!Number.isInteger(mode) || mode < 0 || mode > 0o777) {
+    throw new TypeError("Output mode must be an integer between 0000 and 0777.");
+  }
+
+  const directory = dirname(destination);
+  const temporary = join(directory, `.${process.pid}.${randomUUID()}.ornn-partial`);
+  let handle;
+  try {
+    handle = await open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, mode);
+    const readable = nodeReadable(content);
+    if (readable) {
+      await writeReadable(handle, readable);
+    } else if (
+      typeof content === "string" ||
+      content instanceof Uint8Array ||
+      content instanceof DataView
+    ) {
+      await handle.writeFile(content);
+    } else {
+      throw new TypeError("Atomic output content must be bytes, text, or a readable stream.");
+    }
+    await handle.sync();
+    await handle.close();
+    handle = undefined;
+    await chmod(temporary, mode);
+
+    if (overwrite) {
+      await rename(temporary, destination);
+    } else {
+      try {
+        await link(temporary, destination);
+      } catch (error) {
+        if (error?.code === "EEXIST") throw new AtomicOutputExistsError(destination);
+        throw error;
+      }
+      await rm(temporary);
+    }
+    return { mode, path: destination };
+  } catch (error) {
+    await handle?.close().catch(() => {});
+    await rm(temporary, { force: true }).catch(() => {});
+    throw error;
+  }
+}