@zocomputer/cli 0.4.0 → 0.4.1

package/dist/render.js

@@ -0,0 +1,145 @@
+import { dumpsJson, JsonNumber, } from "@zocomputer/system-api/json";
+import { safeText } from "./errors.js";
+/** Ends a table: it shows a few columns of each row. */
+export const completeResultHint = "Use --json for the complete result.";
+/** Ends a key/value view, which leaves nothing out. */
+export const jsonHint = "Use --json for JSON.";
+// Results nested deeper than this are easier to read as JSON.
+const MAX_DEPTH = 4;
+// A nested object with at most this many plain values fits one table cell.
+const CELL_FIELDS = 4;
+export function jsonObject(value) {
+    return value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        !(value instanceof JsonNumber)
+        ? value
+        : undefined;
+}
+export function isScalar(value) {
+    return (value === undefined ||
+        value === null ||
+        typeof value !== "object" ||
+        value instanceof JsonNumber);
+}
+/** Plain, or a small object of plain values such as `{type, id}`. */
+export function fitsCell(value) {
+    if (isScalar(value))
+        return true;
+    const values = Object.values(jsonObject(value) ?? {});
+    return (values.length > 0 && values.length <= CELL_FIELDS && values.every(isScalar));
+}
+/** One value as escaped single-line text. */
+export function cell(value) {
+    if (value === undefined || value === null)
+        return "-";
+    const nested = jsonObject(value);
+    if (nested && fitsCell(value))
+        return (Object.values(nested)
+            .filter((entry) => entry !== null)
+            .map(cell)
+            .join(" ") || "-");
+    return safeText(typeof value === "string"
+        ? value
+        : value instanceof JsonNumber
+            ? value.text
+            : dumpsJson(value));
+}
+const length = (text) => Array.from(text).length;
+function clip(text, width) {
+    const characters = Array.from(text);
+    return characters.length <= width
+        ? text
+        : `${characters.slice(0, Math.max(1, width) - 1).join("")}…`;
+}
+/**
+ * Lines of an aligned table no wider than `width`: a header, then one line a
+ * row. Cells must already be escaped. A narrow terminal drops trailing columns
+ * and shortens the widest ones.
+ */
+export function tableLines(headers, rows, width, style) {
+    const total = Math.max(20, Math.floor(width));
+    const visible = headers.slice(0, Math.max(1, Math.floor((total + 2) / 12)));
+    const room = total - (visible.length - 1) * 2;
+    const share = Math.floor(room / visible.length);
+    const natural = visible.map((header, index) => Math.max(length(header), ...rows.map((row) => length(row[index] ?? ""))));
+    const widths = natural.map((size) => Math.min(size, share));
+    // Columns narrower than their share leave room for the ones that need more.
+    let spare = room - widths.reduce((sum, size) => sum + size, 0);
+    natural.forEach((size, index) => {
+        const extra = Math.min(spare, size - (widths[index] ?? size));
+        widths[index] = (widths[index] ?? size) + extra;
+        spare -= extra;
+    });
+    const line = (row) => visible
+        .map((_, index) => clip(row[index] ?? "", widths[index] ?? share).padEnd(widths[index] ?? share))
+        .join("  ")
+        .trimEnd();
+    return [style.bold(line(visible)), ...rows.map(line)];
+}
+const oneLine = (value) => isScalar(value) && !(typeof value === "string" && value.includes("\n"));
+/**
+ * What goes under a key instead of beside it: the lines of a nested object, a
+ * list of objects or text with line breaks. Undefined for a shape this layout
+ * can't hold.
+ */
+function linesUnder(entry, indent, style, depth) {
+    if (typeof entry === "string")
+        // The bar is something a field never has, so a name with a line break
+        // in it cannot pass for one.
+        return entry
+            .replaceAll("\r\n", "\n")
+            .replace(/\n$/, "")
+            .split("\n")
+            .map((line) => `${indent}  ${style.dim("│")} ${safeText(line.replaceAll("\t", "    "))}`);
+    const nested = jsonObject(entry);
+    if (nested)
+        return detailLines(nested, style, depth + 1);
+    if (!Array.isArray(entry))
+        return undefined;
+    const lines = [];
+    for (const item of entry) {
+        const object = jsonObject(item);
+        const below = object && detailLines(object, style, depth + 2);
+        if (!below)
+            return undefined;
+        // Each object starts at a dash, one level in from the key.
+        const [first = `${indent}    {}`, ...rest] = below;
+        lines.push(`${indent}  - ${first.slice(indent.length + 4)}`, ...rest);
+    }
+    return lines;
+}
+/**
+ * Lines of an aligned key/value view of one object, with nothing left out or
+ * shortened: a person may not be able to run the command again to see the
+ * rest. Nested objects, lists of objects and text with line breaks are
+ * indented under their key. Returns undefined for a shape this layout can't
+ * hold (lists of lists, mixed lists, deep nesting); the caller prints JSON.
+ */
+export function detailLines(value, style, depth = 0) {
+    if (depth > MAX_DEPTH)
+        return undefined;
+    const indent = "  ".repeat(depth);
+    const entries = [];
+    for (const [name, entry] of Object.entries(value)) {
+        const key = safeText(name);
+        if (oneLine(entry))
+            entries.push({ key, beside: entry === "" ? '""' : cell(entry) });
+        else if (Array.isArray(entry) && entry.every(oneLine))
+            entries.push({
+                key,
+                beside: entry.length ? entry.map(cell).join(", ") : "[]",
+            });
+        else {
+            const below = linesUnder(entry, indent, style, depth);
+            if (!below)
+                return undefined;
+            entries.push(below.length ? { key, below } : { key, beside: "{}" });
+        }
+    }
+    // A very long key stands out of the column instead of widening it.
+    const width = Math.min(32, Math.max(0, ...entries.flatMap(({ key, below }) => (below ? [] : [length(key)]))));
+    return entries.flatMap(({ key, beside, below }) => below
+        ? [`${indent}${style.dim(key)}`, ...below]
+        : [`${indent}${style.dim(key.padEnd(width))}  ${beside}`]);
+}

package/dist/runner.d.ts

@@ -7,7 +7,6 @@ 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;

package/dist/runner.js

@@ -5,26 +5,10 @@ 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 { rootHelp } from "./help.js";
 import { Profiles, selectedWorkspace } from "./profiles.js";
+import { spinner, styleFor, terminalWidth } from "./style.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)
-  update               Install the latest standalone release
-  --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>] [--device]\nOpen your browser to sign in and wait for approval.\nNew profiles use production. Browser consent approves workspaces and identities.\n--device prints a URL and code to approve on any device; login does the same when this machine can't open a browser.\nInternal testing: --environment staging explicitly binds a separate profile to staging.\n",
     logout: "Usage: zo logout [--profile <name>]\nRevoke the saved sign-in and pending replaced sign-ins, then remove them from this computer. If revocation fails, logout says why and removes them anyway.\n",
@@ -44,9 +28,13 @@ const localHelp = {
 };
 // Printed after login so a first-time caller, person or agent, knows the next
 // command and that one sign-in serves the CLI, HTTP and MCP alike.
-const nextSteps = "Calls act as the identity shown for each workspace, with its current permissions.\n" +
-    "Next: zo workspace get for a first call, then zo actions list to see what you can call.\n" +
-    "For HTTP or MCP, zo auth token --headers prints an Authorization header for this sign-in.\n";
+const nextSteps = (style) => `\n${style.bold("Next")}\n` +
+    "  zo workspace get         Make a first call\n" +
+    "  zo actions list          See what you can call\n" +
+    "  zo auth token --headers  Print an Authorization header for HTTP or MCP\n";
+function subjectText({ type, id }) {
+    return `${type.replaceAll("_", " ")} ${safeText(id)}`;
+}
 function identity(session, workspace) {
     const { type, id } = workspace.subject;
     if (type === "user" &&
@@ -57,9 +45,11 @@ function identity(session, workspace) {
         return `as service account ${safeText(id)}`;
     return `as ${type} ${safeText(id)}`;
 }
-async function showHelp(args, stdout) {
+async function showHelp(args, stdout, env) {
+    // Help is one text for people and agents; a terminal only adds emphasis.
+    const style = styleFor(stdout, env);
     if (!args.length) {
-        stdout.write(help);
+        stdout.write(rootHelp(style, (await import("./commands.js")).resourceNames()));
         return;
     }
     const path = args.slice(0, args.findIndex((arg) => arg.startsWith("--")) === -1
@@ -68,25 +58,25 @@ async function showHelp(args, stdout) {
     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));
+    const text = Object.hasOwn(localHelp, key)
+        ? (localHelp[key] ?? "")
+        : (await import("./commands.js")).builtinHelp(path);
+    stdout.write(text.replace(/^Usage:/, style.bold("Usage:")));
 }
 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 env = runtime.env ?? process.env;
     const output = {
         stdout,
         stderr,
         json: options.json,
         envelope: options.envelope,
+        env,
     };
-    const env = runtime.env ?? process.env;
     if (options.help || !args.length) {
-        await showHelp(args, stdout);
+        await showHelp(args, stdout, env);
         return;
     }
     if (args[0] === "--version") {
@@ -119,16 +109,37 @@ export async function run(argv = process.argv.slice(2), runtime = {}) {
         : controller.signal;
     try {
         throwIfInterrupted(signal);
+        // A built-in command that doesn't exist is reported before anything reads
+        // a profile, so the answer isn't "select a workspace".
+        const invocation = !local && args[0] !== "rpc" && args[0] !== "actions";
+        const command = invocation
+            ? (await import("./commands.js")).matchBuiltinCommand(args)
+            : undefined;
+        if (invocation && !command)
+            throw (await import("./commands.js")).unknownCommand(args);
         const profiles = runtime.profiles ?? new Profiles();
-        const { writeJson } = await import("./output.js");
+        const { toJson, writeJson } = await import("./output.js");
         const writeLocalJson = (value) => {
             throwIfInterrupted(signal);
             writeJson(value, output);
         };
+        // A local command's result is JSON for a script and `text` for a person
+        // at a terminal. A command that already reported on stderr passes none.
+        const human = stdout.isTTY === true && !options.json;
+        const render = human ? await import("./render.js") : undefined;
+        const page = styleFor(stdout, env);
+        const notice = styleFor(stderr, env);
+        const writeLocal = (value, text) => {
+            throwIfInterrupted(signal);
+            if (!human)
+                writeJson(value, output);
+            else if (text)
+                stdout.write(text);
+        };
         if (args[0] === "update") {
             commandOptions(args.slice(1), []);
             const { update } = await import("./update.js");
-            writeLocalJson(await update({
+            writeLocal(await update({
                 version: runtime.version,
                 env,
                 fetch: runtime.fetch,
@@ -150,20 +161,32 @@ export async function run(argv = process.argv.slice(2), runtime = {}) {
                 fetch: runtime.fetch,
                 signal,
             });
-            const login = await auth.login({
+            // The status lines are one wording for whoever reads stderr. A terminal
+            // adds color, the success mark and a spinner; anything else gets the
+            // same lines plain, with one static line for the wait.
+            let waiting = { stop() { } };
+            const login = await auth
+                .login({
                 device: parsed.flags.has("device"),
                 signal,
-                announce: (prompt) => stderr.write(prompt.flow === "browser"
-                    ? `Opening your browser to sign in. If it doesn't open, visit this URL on this computer:\n\n  ${prompt.url}\n\nWaiting for approval… (Ctrl-C to cancel)\n`
-                    : `To sign in, visit this URL on any device:\n\n  ${prompt.url}\n\nCode: ${prompt.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`);
+                announce: (prompt) => {
+                    stderr.write(prompt.flow === "browser"
+                        ? `Opening your browser to sign in.\nIf it doesn't open, visit this URL on this computer:\n  ${notice.dim(prompt.url)}\n\n`
+                        : `To sign in, visit this URL on any device:\n  ${notice.dim(prompt.url)}\nCode: ${notice.bold(prompt.userCode)}. Approve only if your browser shows the same code.\n\n`);
+                    waiting = spinner(stderr, "Waiting for approval… (Ctrl-C to cancel)", env);
+                },
+            })
+                // Approval, refusal, a timeout and Ctrl-C all end the wait.
+                .finally(() => waiting.stop());
+            stderr.write(`${notice.ok(`Approved. 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`));
+            session.workspaces.forEach((workspace, index) => stderr.write(`  ${index + 1}. ${safeText(workspace.name)} (${workspace.workspace_id}), ${identity(session, workspace)}\n`));
+            if (session.workspaces.length)
+                stderr.write(`  ${notice.dim("Calls use each workspace's identity and its current permissions.")}\n`);
             const desired = options.workspace ?? env.ZO_WORKSPACE_ID ?? profile.workspaceId;
             let chosen;
             if (options.workspace !== undefined)
@@ -199,8 +222,8 @@ export async function run(argv = process.argv.slice(2), runtime = {}) {
             }
             if (!chosen) {
                 stderr.write("Select an authorized workspace with zo context use <workspace-id>.\n" +
-                    nextSteps);
-                writeLocalJson({
+                    nextSteps(notice));
+                writeLocal({
                     profile: profile.name,
                     signed_in: true,
                     workspace_id: null,
@@ -209,8 +232,9 @@ export async function run(argv = process.argv.slice(2), runtime = {}) {
                 return;
             }
             await profiles.select(profile, chosen, signal);
-            stderr.write(nextSteps);
-            writeLocalJson({ profile: profile.name, workspace_id: chosen });
+            const name = session.workspaces.find((workspace) => workspace.workspace_id === chosen)?.name;
+            stderr.write(`Using workspace ${safeText(name ?? "")} (${chosen}).\n${nextSteps(notice)}`);
+            writeLocal({ profile: profile.name, workspace_id: chosen });
             return;
         }
         const profile = await profiles.resolve(options.profile);
@@ -225,8 +249,8 @@ export async function run(argv = process.argv.slice(2), runtime = {}) {
             const { warning } = await auth.logout();
             throwIfInterrupted(signal);
             stderr.write(warning === undefined
-                ? "Signed out; saved sign-ins revoked.\n"
-                : `Warning: ${warning}\nSigned out of this computer.\n`);
+                ? `${notice.ok("Signed out; saved sign-ins revoked.")}\n`
+                : `${notice.yellow("Warning:")} ${warning}\nSigned out of this computer.\n`);
             return;
         }
         if (args[0] === "auth" && args[1] === "token") {
@@ -242,22 +266,39 @@ export async function run(argv = process.argv.slice(2), runtime = {}) {
         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));
+            const status = await contextStatus(profile, auth, options.workspace, env);
+            const view = render?.detailLines(render.jsonObject(toJson(status)) ?? {}, page);
+            writeLocal(status, view && `${view.join("\n")}\n`);
             return;
         }
         if (args[0] === "context" && args[1] === "list") {
             commandOptions(args.slice(2), []);
-            writeLocalJson((await auth.session()).workspaces);
+            const { workspaces } = await auth.session();
+            const selected = options.workspace ?? env.ZO_WORKSPACE_ID ?? profile.workspaceId;
+            // The mark shares the first column: a column of its own is the first
+            // one a narrow terminal would give up.
+            const lines = render?.tableLines(["  WORKSPACE_ID", "NAME", "IDENTITY"], workspaces.map((workspace) => [
+                `${workspace.workspace_id === selected ? "*" : " "} ${workspace.workspace_id}`,
+                safeText(workspace.name),
+                subjectText(workspace.subject),
+            ]), terminalWidth(stdout), page);
+            lines?.push(!workspaces.length
+                ? "No authorized workspaces. Run zo login to approve one."
+                : workspaces.some((workspace) => workspace.workspace_id === selected)
+                    ? page.dim("* The selected workspace.")
+                    : "None of these is selected. Choose one with zo context use <workspace-id>.");
+            writeLocal(workspaces, lines && `${lines.join("\n")}\n`);
             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));
+            const selected = await useContext(profiles, profile, auth, args[2], signal);
+            writeLocal(selected, `${page.ok(`Using workspace ${safeText(selected.name)} (${selected.workspace_id}) as ${subjectText(selected.subject)}.`)}\n`);
             return;
         }
         if (local)
-            throw new CliError("Unknown command. Run zo --help.");
+            throw (await import("./commands.js")).unknownCommand(args);
         const context = {
             workspaceId: selectedWorkspace(profile, options.workspace, env),
             apiOrigin: auth.binding.api,
@@ -302,15 +343,27 @@ export async function run(argv = process.argv.slice(2), runtime = {}) {
             const version = parsed.values.get("version");
             const parsedVersion = version === undefined ? undefined : parseVersion(version);
             const { catalog } = await loadCatalog(context, { catalog: mode });
+            if (render && !action) {
+                const lines = render.tableLines(["ACTION", "DEFAULT", "VERSIONS", "DESCRIPTION"], catalog.operations.map((operation) => [
+                    safeText(operation.action),
+                    String(operation.defaultVersion ?? "-"),
+                    operation.versions.map((entry) => entry.version).join(", "),
+                    safeText((operation.versions.find((entry) => entry.version === operation.defaultVersion) ?? operation.versions.at(-1))?.description ?? ""),
+                ]), terminalWidth(stdout, 100), page);
+                if (!catalog.operations.length)
+                    lines.push("No results.");
+                lines.push(page.dim(render.completeResultHint));
+                stdout.write(`${lines.join("\n")}\n`);
+                return;
+            }
             writeJson(action
                 ? describeAction(catalog, action, parsedVersion)
                 : listActions(catalog), output);
             return;
         }
-        const { matchBuiltinCommand, runBuiltin } = await import("./commands.js");
-        const command = matchBuiltinCommand(args);
+        const { runBuiltin, unknownCommand } = await import("./commands.js");
         if (!command)
-            throw new CliError("Unknown command. Run zo --help.");
+            throw unknownCommand(args);
         const result = await runBuiltin(context, command.action, command.args, runtime.stdin);
         (await import("./presentation.js")).writeBuiltinResult(command.action, result, { ...output, workspaceId: context.workspaceId });
     }

package/dist/storage.d.ts

@@ -1,7 +1,7 @@
 import { CliError } from "./errors.ts";
 export declare function configDirectory(env?: NodeJS.ProcessEnv): string;
 export declare function privateDirectory(path: string): Promise<void>;
-export declare function readPrivate(path: string): Promise<unknown | undefined>;
+export declare function readPrivate(path: string, maxBytes?: number): Promise<unknown | undefined>;
 export declare class PrivateWriteDurabilityError extends CliError {
     constructor();
 }

package/dist/storage.js

@@ -48,7 +48,7 @@ async function checkedFile(path) {
     }
     return file;
 }
-export async function readPrivate(path) {
+export async function readPrivate(path, maxBytes = 1_048_576) {
     let file;
     try {
         file = await checkedFile(path);
@@ -59,7 +59,7 @@ export async function readPrivate(path) {
         throw error;
     }
     try {
-        if ((await file.stat()).size > 1_048_576)
+        if ((await file.stat()).size > maxBytes)
             throw new CliError("Local configuration is too large.", 2, "invalid_local_data");
         return JSON.parse(await file.readFile("utf8"));
     }

package/dist/style.d.ts

@@ -0,0 +1,40 @@
+/** What the CLI reads from an output stream; injected test streams have only this. */
+export interface Terminal {
+    write(text: string): unknown;
+    isTTY?: boolean;
+    columns?: number;
+}
+export interface Style {
+    /** The stream is a terminal, so it gets the layout written for people. */
+    readonly human: boolean;
+    /** Escape sequences may be written: a terminal with NO_COLOR unset. */
+    readonly color: boolean;
+    bold(text: string): string;
+    dim(text: string): string;
+    red(text: string): string;
+    green(text: string): string;
+    yellow(text: string): string;
+    cyan(text: string): string;
+    /** A line reporting success; a terminal marks it. */
+    ok(text: string): string;
+}
+/**
+ * Styles for one stream. Text passed in must already be safe to print: these
+ * functions only add escape sequences around it.
+ */
+export declare function styleFor(stream: Pick<Terminal, "isTTY"> | undefined, env?: NodeJS.ProcessEnv): Style;
+export declare function terminalWidth(stream: Pick<Terminal, "columns"> | undefined, fallback?: number): number;
+/**
+ * Returns the cursor to the start of its line and blanks what was there (a
+ * spinner frame, the terminal's echoed ^C) without an escape sequence, so it
+ * also works where color is off.
+ */
+export declare function blankLine(stream: Pick<Terminal, "columns">): string;
+/**
+ * Says the CLI is waiting. A terminal gets one animated line, erased when
+ * stopped. Anything else gets the text once on a line that stays: a log or
+ * an agent reading it has nothing to redraw.
+ */
+export declare function spinner(stream: Terminal, text: string, env?: NodeJS.ProcessEnv): {
+    stop(): void;
+};

package/dist/style.js

@@ -0,0 +1,74 @@
+import { styleText } from "node:util";
+/**
+ * Styles for one stream. Text passed in must already be safe to print: these
+ * functions only add escape sequences around it.
+ */
+export function styleFor(stream, env = process.env) {
+    const human = stream?.isTTY === true;
+    // https://no-color.org: any non-empty value turns color off.
+    const color = human && !env.NO_COLOR;
+    // styleText's own stream check throws on anything but a real stream and
+    // reads process.env, while the CLI is handed its streams and environment.
+    // The decision is made here and styleText only supplies the codes.
+    const paint = (format) => (text) => color ? styleText(format, text, { validateStream: false }) : text;
+    const green = paint("green");
+    return {
+        human,
+        color,
+        bold: paint("bold"),
+        dim: paint("dim"),
+        red: paint("red"),
+        green,
+        yellow: paint("yellow"),
+        cyan: paint("cyan"),
+        ok: (text) => (human ? `${green("✓")} ${text}` : text),
+    };
+}
+export function terminalWidth(stream, fallback = 80) {
+    const columns = stream?.columns;
+    return typeof columns === "number" && columns > 0 ? columns : fallback;
+}
+/**
+ * Returns the cursor to the start of its line and blanks what was there (a
+ * spinner frame, the terminal's echoed ^C) without an escape sequence, so it
+ * also works where color is off.
+ */
+export function blankLine(stream) {
+    return `\r${" ".repeat(terminalWidth(stream) - 1)}\r`;
+}
+const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+/**
+ * Says the CLI is waiting. A terminal gets one animated line, erased when
+ * stopped. Anything else gets the text once on a line that stays: a log or
+ * an agent reading it has nothing to redraw.
+ */
+export function spinner(stream, text, env = process.env) {
+    const style = styleFor(stream, env);
+    if (!style.human) {
+        stream.write(`${text}\n`);
+        return { stop() { } };
+    }
+    // A frame wider than the terminal wraps, and every redraw would then
+    // scroll it by a line.
+    const room = terminalWidth(stream) - 3;
+    const characters = Array.from(text);
+    const label = characters.length > room
+        ? `${characters.slice(0, Math.max(0, room - 1)).join("")}…`
+        : text;
+    let frame = 0;
+    const draw = () => stream.write(`\r${style.cyan(frames[frame++ % frames.length] ?? "")} ${label}`);
+    draw();
+    const timer = setInterval(draw, 80);
+    // The wait it decorates keeps the process alive; the animation must not.
+    timer.unref();
+    let stopped = false;
+    return {
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            clearInterval(timer);
+            stream.write(blankLine(stream));
+        },
+    };
+}

package/dist/suggest.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The candidate a mistyped word most likely meant: the nearest within one
+ * edit per three letters, else the shortest one the word begins.
+ */
+export declare function closest(word: string, candidates: readonly string[]): string | undefined;

package/dist/suggest.js

@@ -0,0 +1,42 @@
+/** Edits that turn one word into another: insert, delete, replace, or swap two neighbors. */
+function editDistance(left, right) {
+    let previous = [];
+    let current = Array.from({ length: right.length + 1 }, (_, index) => index);
+    for (let row = 1; row <= left.length; row++) {
+        const next = [row];
+        for (let column = 1; column <= right.length; column++) {
+            const same = left[row - 1] === right[column - 1];
+            let cost = Math.min((current[column] ?? 0) + 1, (next[column - 1] ?? 0) + 1, (current[column - 1] ?? 0) + (same ? 0 : 1));
+            if (row > 1 &&
+                column > 1 &&
+                left[row - 1] === right[column - 2] &&
+                left[row - 2] === right[column - 1])
+                cost = Math.min(cost, (previous[column - 2] ?? 0) + 1);
+            next.push(cost);
+        }
+        previous = current;
+        current = next;
+    }
+    return current[right.length] ?? 0;
+}
+/**
+ * The candidate a mistyped word most likely meant: the nearest within one
+ * edit per three letters, else the shortest one the word begins.
+ */
+export function closest(word, candidates) {
+    const typed = word.toLowerCase();
+    let best;
+    let bestDistance = Math.max(1, Math.floor(typed.length / 3)) + 1;
+    for (const candidate of candidates) {
+        const distance = editDistance(typed, candidate);
+        if (distance < bestDistance) {
+            best = candidate;
+            bestDistance = distance;
+        }
+    }
+    if (best !== undefined || typed.length < 3)
+        return best;
+    return candidates
+        .filter((candidate) => candidate.startsWith(typed))
+        .sort((left, right) => left.length - right.length)[0];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zocomputer/cli",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "description": "Public Zo command line client",
   "bin": {
@@ -14,7 +14,7 @@
     "node": "^22.23.4 || ^24.22.1 || ^26.13.0"
   },
   "dependencies": {
-    "@zocomputer/system-api": "0.3.0"
+    "@zocomputer/system-api": "0.3.1"
   },
   "publishConfig": {
     "access": "public",