@zocomputer/cli 0.0.0-stage → 0.1.1

package/dist/http.d.ts

@@ -0,0 +1,11 @@
+import { SystemAPIError } from "@zocomputer/system-api";
+import { CliError } from "./errors.ts";
+export declare function systemApiFailure(response: Response, raw: string | Uint8Array, operation: string): SystemAPIError;
+export declare class RequestFailure extends CliError {
+    readonly ambiguous: boolean;
+    constructor(ambiguous: boolean, code?: string, exitCode?: number);
+}
+export declare function requestJson(url: string, init?: RequestInit, fetcher?: typeof fetch, options?: {
+    timeoutMs?: number;
+    systemApi?: boolean;
+}): Promise<unknown>;

package/dist/http.js

@@ -0,0 +1,124 @@
+import { SystemAPIError } from "@zocomputer/system-api";
+import { loadsJson } from "@zocomputer/system-api/json";
+import { CliError, record, throwIfInterrupted } from "./errors.js";
+export function systemApiFailure(response, raw, operation) {
+    let body;
+    try {
+        body = loadsJson(raw);
+    }
+    catch {
+        /* Non-JSON upstream failures carry no safe details. */
+    }
+    const error = record(body) && record(body.error) ? body.error : undefined;
+    const valid = error &&
+        typeof error.code === "string" &&
+        /^[a-z][a-z0-9_]*$/.test(error.code) &&
+        typeof error.message === "string";
+    const retryHeader = response.headers.get("retry-after")?.trim();
+    let retryAfterSeconds;
+    if (retryHeader) {
+        const seconds = /^\d+$/.test(retryHeader)
+            ? Number(retryHeader)
+            : Math.ceil((Date.parse(retryHeader) - Date.now()) / 1000);
+        if (!Number.isNaN(seconds))
+            retryAfterSeconds = Math.max(0, Math.min(seconds, 86_400));
+    }
+    const outcome = valid && record(error.details) ? error.details.outcome : undefined;
+    return new SystemAPIError({
+        code: valid
+            ? error.code
+            : response.status === 401
+                ? "unauthenticated"
+                : response.status === 403
+                    ? "permission_denied"
+                    : "invalid_response",
+        message: valid
+            ? error.message
+            : `${operation} failed with HTTP ${response.status}.`,
+        ...(record(body) && typeof body.request_id === "string"
+            ? { requestId: body.request_id }
+            : {}),
+        ...(valid ? { details: error.details } : {}),
+        ...(retryAfterSeconds !== undefined ? { retryAfterSeconds } : {}),
+        httpStatus: response.status,
+        outcome: outcome === "unknown" ? "unknown" : "not_started",
+    });
+}
+export class RequestFailure extends CliError {
+    ambiguous;
+    constructor(ambiguous, code = "transport_error", exitCode = 5) {
+        super(code === "invalid_grant"
+            ? "Your sign-in ended. Run zo login."
+            : "The authentication request failed. Try again or run zo login.", exitCode, code);
+        this.ambiguous = ambiguous;
+    }
+}
+export async function requestJson(url, init = {}, fetcher = fetch, options = {}) {
+    throwIfInterrupted(init.signal);
+    const timeout = AbortSignal.timeout(options.timeoutMs ?? 8_000);
+    const signal = init.signal
+        ? AbortSignal.any([init.signal, timeout])
+        : timeout;
+    let response;
+    try {
+        response = await fetcher(url, {
+            ...init,
+            redirect: "error",
+            signal,
+        });
+    }
+    catch {
+        throwIfInterrupted(init.signal);
+        throw new RequestFailure(true);
+    }
+    let raw;
+    try {
+        if (!response.body)
+            throw new RequestFailure(false, "invalid_response");
+        const reader = response.body.getReader();
+        const chunks = [];
+        let size = 0;
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            size += value.length;
+            if (size > 1_048_576) {
+                // Cleanup failure cannot make a known oversized response retryable.
+                await reader.cancel().catch(() => { });
+                throw new RequestFailure(false, "invalid_response");
+            }
+            chunks.push(value);
+        }
+        raw = Buffer.concat(chunks).toString("utf8");
+    }
+    catch (error) {
+        throwIfInterrupted(init.signal);
+        if (error instanceof RequestFailure)
+            throw error;
+        throw new RequestFailure(true, "invalid_response");
+    }
+    throwIfInterrupted(init.signal);
+    if (!response.ok && options.systemApi)
+        throw systemApiFailure(response, raw, "Session discovery");
+    let body;
+    try {
+        body = JSON.parse(raw);
+    }
+    catch {
+        throw new RequestFailure(false, "invalid_response");
+    }
+    if (!response.ok) {
+        const code = record(body) &&
+            typeof body.error === "string" &&
+            /^[a-z_]+$/.test(body.error)
+            ? body.error
+            : "authentication_failed";
+        throw new RequestFailure(response.status >= 500 || response.status === 429, code, response.status === 401 || code === "invalid_grant"
+            ? 3
+            : response.status === 403
+                ? 4
+                : 5);
+    }
+    return body;
+}

package/dist/login.d.ts

@@ -0,0 +1,14 @@
+export interface LoginOptions {
+    noBrowser?: boolean;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    announce?: (url: string) => void;
+    openBrowser?: (url: string) => Promise<void>;
+}
+export interface LoginCode {
+    code: string;
+    verifier: string;
+    redirectUri: string;
+}
+export declare function openBrowser(url: string): Promise<void>;
+export declare function loginCode(issuer: string, audience: string, clientId: string, options?: LoginOptions): Promise<LoginCode>;

package/dist/login.js

@@ -0,0 +1,102 @@
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+import { CliError } from "./errors.js";
+export async function openBrowser(url) {
+    await new Promise((resolve, reject) => {
+        const child = spawn(process.platform === "darwin" ? "open" : "xdg-open", [url], { stdio: "ignore", detached: true });
+        child.unref();
+        child.once("error", () => reject(new CliError("Could not open a browser. Retry with --no-browser.")));
+        child.once("exit", (status) => status === 0
+            ? resolve()
+            : reject(new CliError("Could not open a browser. Retry with --no-browser.")));
+    });
+}
+export async function loginCode(issuer, audience, clientId, options = {}) {
+    const state = randomBytes(32).toString("base64url");
+    const verifier = randomBytes(32).toString("base64url");
+    let complete = () => { };
+    let fail = () => { };
+    const received = new Promise((resolve, reject) => {
+        complete = resolve;
+        fail = reject;
+    });
+    // The callback may arrive while the browser opener is still running.
+    void received.catch(() => { });
+    let accepted = false;
+    const server = createServer((request, response) => {
+        let url;
+        try {
+            url = new URL(request.url ?? "/", "http://127.0.0.1");
+        }
+        catch {
+            response.writeHead(400).end("Invalid callback.");
+            return;
+        }
+        const params = url.searchParams;
+        const keys = [...params.keys()];
+        const valid = !accepted &&
+            request.method === "GET" &&
+            url.pathname === "/callback" &&
+            keys.length === new Set(keys).size &&
+            params.get("state") === state &&
+            params.get("iss") === issuer &&
+            params.has("code") !== params.has("error");
+        response.setHeader("Content-Type", "text/plain; charset=utf-8");
+        response.setHeader("Cache-Control", "no-store");
+        if (!valid) {
+            response.writeHead(400).end("Invalid callback.");
+            return;
+        }
+        accepted = true;
+        response.end("You may close this window and return to Zo.");
+        if (params.has("error"))
+            fail(new CliError("Authorization was denied. Run zo login to try again.", 4, "access_denied"));
+        else {
+            const code = params.get("code");
+            if (code)
+                complete(code);
+            else
+                fail(new CliError("Authorization returned an empty code.", 3, "invalid_response"));
+        }
+    });
+    server.requestTimeout = 5_000;
+    server.headersTimeout = 5_000;
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", resolve);
+    });
+    const address = server.address();
+    if (!address || typeof address === "string")
+        throw new CliError("Could not bind the login callback.");
+    const redirectUri = `http://127.0.0.1:${address.port}/callback`;
+    const authorize = new URL("/zo-system-api/oauth/authorize", issuer);
+    authorize.search = new URLSearchParams({
+        response_type: "code",
+        client_id: clientId,
+        redirect_uri: redirectUri,
+        resource: audience,
+        code_challenge: createHash("sha256").update(verifier).digest("base64url"),
+        code_challenge_method: "S256",
+        state,
+    }).toString();
+    const timer = setTimeout(() => fail(new CliError("Login timed out. Run zo login to try again.", 3, "login_timeout")), options.timeoutMs ?? 300_000);
+    const abort = () => fail(new CliError("Login interrupted.", 130, "interrupted"));
+    options.signal?.addEventListener("abort", abort, { once: true });
+    try {
+        if (options.signal?.aborted)
+            abort();
+        else {
+            options.announce?.(authorize.href);
+            if (!options.noBrowser)
+                void (options.openBrowser ?? openBrowser)(authorize.href).catch(fail);
+        }
+        return { code: await received, verifier, redirectUri };
+    }
+    finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", abort);
+        server.closeAllConnections();
+        await new Promise((resolve) => server.close(() => resolve()));
+    }
+}

package/dist/main.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { Profiles } from "./profiles.ts";
+import type { InvocationContext } from "./catalog.ts";
+import type { OutputOptions } from "./output.ts";
+import type { RpcOptions } from "./rpc.ts";
+export { parseGlobals } from "./argv.ts";
+export interface RunOptions extends OutputOptions {
+    profiles?: Profiles;
+    env?: NodeJS.ProcessEnv;
+    fetch?: InvocationContext["fetch"];
+    stdin?: RpcOptions["stdin"];
+    signal?: AbortSignal;
+}
+export declare function run(argv?: string[], runtime?: RunOptions): Promise<void>;
+export declare function execute(argv?: string[], runtime?: RunOptions): Promise<number>;

package/dist/main.js

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+import { readFile, realpath } from "node:fs/promises";
+import { createInterface } from "node:readline/promises";
+import { pathToFileURL } from "node:url";
+import { AuthClient } from "./auth.js";
+import { commandOptions, parseGlobals } from "./argv.js";
+import { authorizedWorkspace, contextStatus, useContext } from "./context.js";
+import { CliError, record, safeText, throwIfInterrupted } from "./errors.js";
+import { Profiles, selectedWorkspace } from "./profiles.js";
+export { parseGlobals } from "./argv.js";
+const help = `Zo public command line client
+
+Usage: zo <command> [--profile <name>] [--workspace <id>] [--json]
+
+  login / logout       Sign in through your browser or revoke the sign-in
+  auth status / token  Inspect your identity or explicitly print an access token
+  context list/use/show Select an authorized workspace
+  actions list/describe Discover live action contracts
+  rpc <action>         Invoke any callable action from JSON
+  <resource> <action>  Invoke an installed built-in command
+  completion <shell>  Print bash, zsh or fish completion (offline)
+  --version            Show the installed CLI version
+
+Run zo <command> --help for options; for example, zo machine list --help.
+Use --profile to keep separate sign-ins. New profiles use production.
+ZO_SYSTEM_API_ACCESS_TOKEN overrides saved credentials; ZO_WORKSPACE_ID selects a workspace.
+`;
+const localHelp = {
+    login: "Usage: zo login [--profile <name>] [--workspace <id>] [--no-browser]\nPrint the sign-in URL, open your browser, and wait for approval.\nNew profiles use production. Browser consent approves workspaces and identities.\n--no-browser skips opening the browser and still waits for the localhost callback.\nInternal testing: --environment staging explicitly binds a separate profile to staging.\n",
+    logout: "Usage: zo logout [--profile <name>] [--local-only]\nRevoke the saved sign-in and pending replaced sign-ins. --local-only removes local credentials without revoking server access.\n",
+    auth: "Usage: zo auth status | token [--headers]\nStatus shows the current identity; token explicitly prints an access token.\n",
+    "auth status": "Usage: zo auth status [--profile <name>] [--workspace <id>] [--json]\nShow the approving person, sign-in expiry and effective identity in the selected workspace.\n",
+    "auth token": "Usage: zo auth token [--profile <name>] [--headers]\nExplicitly print a short-lived access token; --headers prints Authorization JSON.\n",
+    context: "Usage: zo context list | use <workspace-id> | show\nWorkspace selection does not change permissions.\n",
+    "context list": "Usage: zo context list [--profile <name>] [--json]\nList currently authorized workspaces and effective identities.\n",
+    "context use": "Usage: zo context use <workspace-id> [--profile <name>]\nValidate access and save the workspace as this profile's default.\n",
+    "context show": "Usage: zo context show [--profile <name>] [--workspace <id>] [--json]\nShow and validate the selected workspace and identity.\n",
+    actions: "Usage: zo actions list | describe <action> [--version <integer>] [--catalog scoped|all]\nRead the live catalog. --catalog all includes definitions beyond current availability.\n",
+    "actions list": "Usage: zo actions list [--catalog scoped|all] [--profile <name>] [--workspace <id>] [--json]\nList callable contracts from the live catalog; --catalog all includes definitions.\n",
+    "actions describe": "Usage: zo actions describe <action> [--version <integer>] [--catalog scoped|all] [--json]\nShow live input, output and query schemas. Omit --version to inspect every published version.\n",
+    rpc: "Usage: zo rpc <action> [--input <json> | --input-file <path|->] [--version <integer>]\n  --query <json>            Declared list-query options; one page per call\n  --idempotency-key <key>   Envelope key where the action supports it\n  --preview                Print the request without invoking\n  --envelope               Print the complete success envelope\n  --json                   Print exact result JSON\n  --profile <name> --workspace <id>\nThe live catalog supplies the default version. RPC preserves supplied inputs. Invocations are never retried.\n",
+    completion: "Usage: zo completion bash|zsh|fish\nPrint completion from installed metadata without credentials or network requests.\n",
+};
+async function showHelp(args, stdout) {
+    if (!args.length) {
+        stdout.write(help);
+        return;
+    }
+    const path = args.slice(0, args.findIndex((arg) => arg.startsWith("--")) === -1
+        ? undefined
+        : args.findIndex((arg) => arg.startsWith("--")));
+    const key = path
+        .slice(0, ["auth", "context", "actions"].includes(path[0] ?? "") ? 2 : 1)
+        .join(" ");
+    if (Object.hasOwn(localHelp, key)) {
+        stdout.write(localHelp[key] ?? "");
+        return;
+    }
+    stdout.write((await import("./commands.js")).builtinHelp(path));
+}
+export async function run(argv = process.argv.slice(2), runtime = {}) {
+    const { args, options } = parseGlobals(argv);
+    const stdout = runtime.stdout ?? process.stdout;
+    const stderr = runtime.stderr ?? process.stderr;
+    const output = {
+        stdout,
+        stderr,
+        json: options.json,
+        envelope: options.envelope,
+    };
+    const env = runtime.env ?? process.env;
+    if (options.help || !args.length) {
+        await showHelp(args, stdout);
+        return;
+    }
+    if (args[0] === "--version") {
+        if (args.length !== 1)
+            throw new CliError("Usage: zo --version");
+        const manifest = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+        if (!record(manifest) || typeof manifest.version !== "string")
+            throw new CliError("The installed package has no version.", 5);
+        stdout.write(`${manifest.version}\n`);
+        return;
+    }
+    if (args[0] === "completion") {
+        if (args.length !== 2 || !args[1])
+            throw new CliError(localHelp.completion ?? "Invalid completion command.");
+        stdout.write((await import("./commands.js")).completionScript(args[1]));
+        return;
+    }
+    const local = ["login", "logout", "auth", "context"].includes(args[0] ?? "");
+    if (options.envelope && local)
+        throw new CliError("--envelope is only supported for action invocation.");
+    const controller = new AbortController();
+    const interrupt = () => controller.abort();
+    process.once("SIGINT", interrupt);
+    const signal = runtime.signal
+        ? AbortSignal.any([controller.signal, runtime.signal])
+        : controller.signal;
+    try {
+        throwIfInterrupted(signal);
+        const profiles = runtime.profiles ?? new Profiles();
+        const { writeJson } = await import("./output.js");
+        const writeLocalJson = (value) => {
+            throwIfInterrupted(signal);
+            writeJson(value, output);
+        };
+        if (args[0] === "login") {
+            const parsed = commandOptions(args.slice(1), ["environment"], ["no-browser"]);
+            const requested = parsed.values.get("environment");
+            if (requested !== undefined &&
+                requested !== "production" &&
+                requested !== "staging")
+                throw new CliError("--environment must be production or staging.");
+            const profile = await profiles.create(options.profile, requested, signal);
+            const auth = new AuthClient(profile, profiles.directory, {
+                env,
+                fetch: runtime.fetch,
+                signal,
+            });
+            const login = await auth.login({
+                noBrowser: parsed.flags.has("no-browser"),
+                signal,
+                announce: (url) => {
+                    const message = `Open this URL to sign in:\n${url}\n`;
+                    const dim = stderr.isTTY &&
+                        !options.json &&
+                        env.NO_COLOR === undefined &&
+                        env.TERM !== "dumb";
+                    stderr.write(dim ? `\u001b[2m${message}\u001b[22m` : message);
+                },
+            });
+            stderr.write(`Sign-in saved for profile ${profile.name}.\n`);
+            if (login.cleanupPending)
+                stderr.write("A previous sign-in could not be revoked. Cleanup remains saved for the next login; the current sign-in is active. You can revoke the previous sign-in in Authorized apps.\n");
+            const session = await auth.session();
+            const desired = options.workspace ?? env.ZO_WORKSPACE_ID ?? profile.workspaceId;
+            let chosen;
+            if (options.workspace !== undefined)
+                chosen = authorizedWorkspace(session, options.workspace).workspace_id;
+            else if (desired !== undefined) {
+                chosen = session.workspaces.find((workspace) => workspace.workspace_id === desired)?.workspace_id;
+                if (!chosen)
+                    stderr.write(env.ZO_WORKSPACE_ID !== undefined
+                        ? "ZO_WORKSPACE_ID is not authorized by the new sign-in. Choose a workspace, then update or unset ZO_WORKSPACE_ID (or use --workspace) before invoking.\n"
+                        : "The saved workspace is not authorized by the new sign-in. Choose a workspace explicitly; the previous selection is unchanged.\n");
+            }
+            else if (session.workspaces.length === 1)
+                chosen = session.workspaces[0]?.workspace_id;
+            if (!chosen &&
+                !runtime.stdin &&
+                process.stdin.isTTY &&
+                stderr.isTTY &&
+                session.workspaces.length > 0) {
+                session.workspaces.forEach((workspace, index) => stderr.write(`${index + 1}. ${safeText(workspace.name)} (${workspace.workspace_id})\n`));
+                const input = createInterface({
+                    input: process.stdin,
+                    output: process.stderr,
+                });
+                try {
+                    const answer = await input.question("Choose a workspace number: ", {
+                        signal,
+                    });
+                    if (/^[1-9][0-9]*$/.test(answer))
+                        chosen = session.workspaces[Number(answer) - 1]?.workspace_id;
+                }
+                finally {
+                    input.close();
+                }
+            }
+            if (!chosen) {
+                stderr.write("Select an authorized workspace with zo context use <workspace-id>.\n");
+                writeLocalJson({
+                    profile: profile.name,
+                    signed_in: true,
+                    workspace_id: null,
+                    selection_required: true,
+                });
+                return;
+            }
+            await profiles.select(profile, chosen, signal);
+            writeLocalJson({ profile: profile.name, workspace_id: chosen });
+            return;
+        }
+        const profile = await profiles.resolve(options.profile);
+        throwIfInterrupted(signal);
+        const auth = new AuthClient(profile, profiles.directory, {
+            env,
+            fetch: runtime.fetch,
+            signal,
+        });
+        if (args[0] === "logout") {
+            const parsed = commandOptions(args.slice(1), [], ["local-only"]);
+            const localOnly = parsed.flags.has("local-only");
+            await auth.logout(localOnly);
+            throwIfInterrupted(signal);
+            stderr.write(localOnly
+                ? "Local credentials removed. Server access was not revoked.\n"
+                : "Signed out; saved sign-ins revoked.\n");
+            return;
+        }
+        if (args[0] === "auth" && args[1] === "token") {
+            const parsed = commandOptions(args.slice(2), [], ["headers"]);
+            const token = await auth.accessToken();
+            throwIfInterrupted(signal);
+            if (parsed.flags.has("headers"))
+                writeLocalJson({ Authorization: `Bearer ${token}` });
+            else
+                stdout.write(`${token}\n`);
+            return;
+        }
+        if ((args[0] === "auth" && args[1] === "status") ||
+            (args[0] === "context" && args[1] === "show")) {
+            commandOptions(args.slice(2), []);
+            writeLocalJson(await contextStatus(profile, auth, options.workspace, env));
+            return;
+        }
+        if (args[0] === "context" && args[1] === "list") {
+            commandOptions(args.slice(2), []);
+            writeLocalJson((await auth.session()).workspaces);
+            return;
+        }
+        if (args[0] === "context" && args[1] === "use") {
+            if (args.length !== 3 || !args[2])
+                throw new CliError("Usage: zo context use <workspace-id>");
+            writeLocalJson(await useContext(profiles, profile, auth, args[2], signal));
+            return;
+        }
+        if (local)
+            throw new CliError("Unknown command. Run zo --help.");
+        const context = {
+            workspaceId: selectedWorkspace(profile, options.workspace, env),
+            apiOrigin: auth.binding.api,
+            accessToken: () => auth.accessToken(),
+            signal,
+            ...(runtime.fetch ? { fetch: runtime.fetch } : {}),
+        };
+        if (args[0] === "rpc") {
+            const action = args[1];
+            if (!action || action.startsWith("--"))
+                throw new CliError("Usage: zo rpc <action> [options]");
+            const parsed = commandOptions(args.slice(2), ["input", "input-file", "version", "query", "idempotency-key"], ["preview"]);
+            const { parseVersion } = await import("./catalog.js");
+            const version = parsed.values.get("version");
+            const result = await (await import("./rpc.js")).runRpc(context, {
+                action,
+                input: parsed.values.get("input"),
+                inputFile: parsed.values.get("input-file"),
+                query: parsed.values.get("query"),
+                version: version === undefined ? undefined : parseVersion(version),
+                idempotencyKey: parsed.values.get("idempotency-key"),
+                preview: parsed.flags.has("preview"),
+                stdin: runtime.stdin,
+            });
+            (await import("./output.js")).writeRpcResult(result, output);
+            return;
+        }
+        if (args[0] === "actions") {
+            const describe = args[1] === "describe";
+            if (args[1] !== "list" && !describe)
+                throw new CliError("Usage: zo actions list | describe <action>");
+            const action = describe ? args[2] : undefined;
+            if (describe && (!action || action.startsWith("--")))
+                throw new CliError("Usage: zo actions describe <action>");
+            if (options.envelope)
+                throw new CliError("--envelope is only supported for action invocation.");
+            const parsed = commandOptions(args.slice(describe ? 3 : 2), describe ? ["catalog", "version"] : ["catalog"]);
+            const mode = parsed.values.get("catalog") ?? "scoped";
+            if (mode !== "scoped" && mode !== "all")
+                throw new CliError("--catalog must be scoped or all.");
+            const { loadCatalog, listActions, describeAction, parseVersion } = await import("./catalog.js");
+            const version = parsed.values.get("version");
+            const parsedVersion = version === undefined ? undefined : parseVersion(version);
+            const { catalog } = await loadCatalog(context, { catalog: mode });
+            writeJson(action
+                ? describeAction(catalog, action, parsedVersion)
+                : listActions(catalog), output);
+            return;
+        }
+        const { matchBuiltinCommand, runBuiltin } = await import("./commands.js");
+        const command = matchBuiltinCommand(args);
+        if (!command)
+            throw new CliError("Unknown command. Run zo --help.");
+        const result = await runBuiltin(context, command.action, command.args, runtime.stdin);
+        (await import("./presentation.js")).writeBuiltinResult(command.action, result, { ...output, workspaceId: context.workspaceId });
+    }
+    finally {
+        process.removeListener("SIGINT", interrupt);
+    }
+}
+export async function execute(argv = process.argv.slice(2), runtime = {}) {
+    try {
+        await run(argv, runtime);
+        return 0;
+    }
+    catch (error) {
+        const { writeError } = await import("./output.js");
+        return writeError(error, {
+            ...runtime,
+            json: argv.some((arg) => arg === "--json"),
+        });
+    }
+}
+if (process.argv[1] &&
+    import.meta.url === pathToFileURL(await realpath(process.argv[1])).href)
+    process.exitCode = await execute();

package/dist/output.d.ts

@@ -0,0 +1,21 @@
+import { type JsonObject } from "@zocomputer/system-api/json";
+import type { RpcResult } from "./rpc.ts";
+export interface OutputOptions {
+    json?: boolean;
+    envelope?: boolean;
+    stdout?: {
+        write(text: string): unknown;
+        isTTY?: boolean;
+    };
+    stderr?: {
+        write(text: string): unknown;
+        isTTY?: boolean;
+    };
+}
+export declare function writeJsonText(text: string, options?: OutputOptions): void;
+export declare function writeJson(value: unknown, options?: OutputOptions): void;
+export declare function writeRpcResult(result: RpcResult, options?: OutputOptions): void;
+/** Mirror the public error detail fields in hostagent.system_api.errors. */
+export declare function safeDetails(code: string, details: unknown): JsonObject;
+export declare function exitCode(error: unknown): number;
+export declare function writeError(error: unknown, options?: OutputOptions): number;