@zocomputer/cli 0.2.1 → 0.3.0

package/dist/main.js

@@ -1,313 +1,8 @@
 #!/usr/bin/env node
-import { readFile, realpath } from "node:fs/promises";
-import { createInterface } from "node:readline/promises";
+import { realpath } from "node:fs/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 a sign-in URL and code, open your browser, and wait for approval.\nNew profiles use production. Browser consent approves workspaces and identities.\n--no-browser prints the URL without opening a browser; approve it on any device.\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",
-};
-function identity(session, workspace) {
-    const { type, id } = workspace.subject;
-    if (type === "user" &&
-        session.approving_subject?.type === "user" &&
-        session.approving_subject.id === id)
-        return "as you";
-    if (type === "service_account")
-        return `as service account ${safeText(id)}`;
-    return `as ${type} ${safeText(id)}`;
-}
-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, userCode, browser }) => stderr.write(`${browser
-                    ? "Opening your browser to sign in. If it doesn't open, visit:"
-                    : "To sign in, visit this URL on any device:"}\n\n  ${url}\n\nCode: ${userCode}. Approve only if your browser shows the same code.\nWaiting for approval… (Ctrl-C to cancel)\n`),
-            });
-            stderr.write(`\nApproved in the browser. 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();
-            // Always list the approved workspaces, so a sign-in someone else
-            // approved shows up as workspaces or identities you don't recognize.
-            session.workspaces.forEach((workspace, index) => stderr.write(`${index + 1}. ${safeText(workspace.name)} (${workspace.workspace_id}), ${identity(session, workspace)}\n`));
-            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) {
-                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"),
-        });
-    }
-}
+import { execute } from "./runner.js";
+export * from "./runner.js";
 if (process.argv[1] &&
     import.meta.url === pathToFileURL(await realpath(process.argv[1])).href)
     process.exitCode = await execute();

package/dist/profiles.d.ts

@@ -1,15 +1,20 @@
+/**
+ * The Zo CLI's OAuth client metadata document, served from www as its own
+ * client ID for both environments; its redirects are the loopback callbacks.
+ */
+export declare const CLIENT_ID = "https://www.zo.computer/oauth/zo-cli-client-metadata.json";
 export declare const environments: {
     readonly production: {
         readonly issuer: "https://auth.zo.computer";
         readonly api: "https://api.zo.computer";
         readonly audience: "https://api.zo.computer/zo-system-api";
-        readonly clientId: "zo-public-cli";
+        readonly clientId: "https://www.zo.computer/oauth/zo-cli-client-metadata.json";
     };
     readonly staging: {
         readonly issuer: "https://auth.zostaging.computer";
         readonly api: "https://api.zostaging.computer";
         readonly audience: "https://api.zostaging.computer/zo-system-api";
-        readonly clientId: "zo-public-cli";
+        readonly clientId: "https://www.zo.computer/oauth/zo-cli-client-metadata.json";
     };
 };
 export type Environment = keyof typeof environments;

package/dist/profiles.js

@@ -1,18 +1,23 @@
 import { join } from "node:path";
 import { CliError, record, throwIfInterrupted } from "./errors.js";
 import { configDirectory, privateDirectory, readPrivate, withLock, writePrivate, } from "./storage.js";
+/**
+ * The Zo CLI's OAuth client metadata document, served from www as its own
+ * client ID for both environments; its redirects are the loopback callbacks.
+ */
+export const CLIENT_ID = "https://www.zo.computer/oauth/zo-cli-client-metadata.json";
 export const environments = {
     production: {
         issuer: "https://auth.zo.computer",
         api: "https://api.zo.computer",
         audience: "https://api.zo.computer/zo-system-api",
-        clientId: "zo-public-cli",
+        clientId: CLIENT_ID,
     },
     staging: {
         issuer: "https://auth.zostaging.computer",
         api: "https://api.zostaging.computer",
         audience: "https://api.zostaging.computer/zo-system-api",
-        clientId: "zo-public-cli",
+        clientId: CLIENT_ID,
     },
 };
 export function profileName(name) {

package/dist/runner.d.ts

@@ -0,0 +1,16 @@
+#!/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 {
+    version?: string;
+    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>;