@zocomputer/cli 0.3.0 → 0.4.0

package/README.md

@@ -16,9 +16,9 @@ curl -fsSL https://zo.computer/install.sh | sh
 Then open a new terminal and run `zo --version`. It includes Node, verifies the archive, and keeps versions under
 `${XDG_DATA_HOME:-$HOME/.local/share}/zo/cli/` with a managed `~/.local/bin/zo`
 symlink, and adds `~/.local/bin` to your shell's PATH configuration unless it's
-already on PATH. Re-run it to upgrade; `--version`, `--bin-dir`, and `--no-modify-path`
-control pinned installs, command placement and shell setup. Existing sign-ins
-are preserved. The [CLI guide](../../src/hostagent/system_api/docs/guides/cli.md)
+already on PATH. Run `zo update` to upgrade, or re-run the installer; `--version`,
+`--bin-dir`, and `--no-modify-path` control pinned installs, command placement
+and shell setup. Existing sign-ins are preserved. The [CLI guide](../../src/hostagent/system_api/docs/guides/cli.md)
 covers supported systems, PATH collisions, rollback and removal.
 
 Install the latest published version from npm:
@@ -29,9 +29,9 @@ zo --version
 zo login
 ```
 
-Run the same install command again to upgrade. The CLI
-installs its matching public SDK dependency. It performs no update check when
-you run a command.
+Run the same install command again to upgrade; `zo update` refuses an npm
+installation and names this command. The CLI installs its matching public SDK
+dependency. It performs no update check when you run a command.
 
 To try the CLI without installing it globally:
 

package/dist/commands.js

@@ -97,6 +97,7 @@ export function completionScript(shell) {
             "actions",
             "rpc",
             "completion",
+            "update",
             "status",
             "token",
             "list",

package/dist/generated/commands.js

@@ -1,6 +1,6 @@
 // Generated by scripts/generate-commands.mjs. Do not edit.
 export const commandManifest = {
-    schemaDigest: "sha256:72a660c4863ad100211dacc6ed13014d46a5311230b0e648e2870e2d4c3f0be4",
+    schemaDigest: "sha256:f3723f93d9d519ebe2517e16cb3db50c99b38e60b9705187006ada3eaeb4e391",
     commands: [
         {
             action: "zo.activity.list",
@@ -968,6 +968,19 @@ export const commandManifest = {
                 },
             ],
         },
+        {
+            action: "zo.model.list",
+            path: ["model", "list"],
+            versions: [
+                {
+                    version: 1,
+                    description: "List the models this workspace can call, each with its ID, capabilities, accepted file types, reasoning levels, limits and current prices.",
+                    inputJson: '{"additionalProperties":false,"properties":{"workspace_id":{"maxLength":200,"minLength":1,"title":"Workspace Id","type":"string"}},"required":["workspace_id"],"title":"ModelListInput","type":"object"}',
+                    queryJson: '{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"default":100,"description":"Rows per page, at most 200; a larger value is reduced to it."},"cursor":{"type":"string","minLength":1,"maxLength":5504,"description":"The previous page\'s next_cursor, sent with the same sort, filter and search."},"sort":{"type":"string","enum":["id.asc"],"default":"id.asc"},"filter":{"additionalProperties":false,"properties":{"capability":{"anyOf":[{"enum":["text","structured_output","embedding","rerank","image","speech","transcription","video"],"type":"string"},{"type":"null"}],"default":null,"description":"Only models with this capability.","title":"Capability"}},"type":"object","required":[],"default":{}}},"required":[]}',
+                    resultKind: "inline",
+                },
+            ],
+        },
         {
             action: "zo.oauth_app.create",
             path: ["oauth-app", "create"],

package/dist/output.js

@@ -55,7 +55,7 @@ export function writeRpcResult(result, options = {}) {
 }
 const detailFields = {
     invalid_envelope: ["reason"],
-    conflict: ["reason", "pointer"],
+    conflict: ["reason", "pointer", "route_ids", "total"],
     quota_exceeded: ["reason"],
     invalid_input: ["violations"],
     invalid_query: ["violations"],
@@ -120,7 +120,9 @@ export function safeDetails(code, details) {
                     return integer === undefined ? [] : [integer];
                 });
             }
-            else if (field === "function_ids" || field === "subscription_ids")
+            else if (field === "function_ids" ||
+                field === "subscription_ids" ||
+                field === "route_ids")
                 projected[field] = value.filter((item) => boundedString(item));
         }
     }

package/dist/rpc.js

@@ -154,7 +154,7 @@ export async function runRpc(context, options, loadedCatalog) {
         });
     if (options.preview)
         return { kind: "preview", workspaceId: context.workspaceId, requestJson };
-    // Snapshot calls may run for 210 seconds; leave time to receive that result.
+    // A call may run for 210 seconds; leave time to receive its result.
     const timeout = AbortSignal.timeout(240_000);
     const signal = context.signal
         ? AbortSignal.any([context.signal, timeout])

package/dist/runner.js

@@ -18,6 +18,7 @@ Usage: zo <command> [--profile <name>] [--workspace <id>] [--json]
   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.
@@ -39,6 +40,7 @@ const localHelp = {
     "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",
+    update: "Usage: zo update [--json]\nDownload the latest standalone release, verify it and switch the zo command to it. Sign-ins are kept.\nDoes nothing when this version is already the latest. An npm installation upgrades with npm install --global @zocomputer/cli@latest.\n",
 };
 // 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.
@@ -106,7 +108,7 @@ export async function run(argv = process.argv.slice(2), runtime = {}) {
         stdout.write((await import("./commands.js")).completionScript(args[1]));
         return;
     }
-    const local = ["login", "logout", "auth", "context"].includes(args[0] ?? "");
+    const local = ["login", "logout", "auth", "context", "update"].includes(args[0] ?? "");
     if (options.envelope && local)
         throw new CliError("--envelope is only supported for action invocation.");
     const controller = new AbortController();
@@ -123,6 +125,18 @@ export async function run(argv = process.argv.slice(2), runtime = {}) {
             throwIfInterrupted(signal);
             writeJson(value, output);
         };
+        if (args[0] === "update") {
+            commandOptions(args.slice(1), []);
+            const { update } = await import("./update.js");
+            writeLocalJson(await update({
+                version: runtime.version,
+                env,
+                fetch: runtime.fetch,
+                signal,
+                stderr,
+            }));
+            return;
+        }
         if (args[0] === "login") {
             const parsed = commandOptions(args.slice(1), ["environment"], ["device"]);
             const requested = parsed.values.get("environment");

package/dist/update.d.ts

@@ -0,0 +1,21 @@
+import type { FetchLike } from "@zocomputer/system-api";
+export interface UpdateOptions {
+    /** The standalone executable's version. npm installations have none. */
+    version?: string;
+    execPath?: string;
+    env?: NodeJS.ProcessEnv;
+    fetch?: FetchLike;
+    signal?: AbortSignal;
+    stderr?: {
+        write(text: string): unknown;
+    };
+    /** Runs the release installer and resolves with its exit status. */
+    runInstaller?: (script: Buffer, args: string[]) => Promise<number>;
+}
+export interface UpdateResult {
+    /** The version the zo command runs after this update. */
+    version: string;
+    latest_version: string;
+    updated: boolean;
+}
+export declare function update(options?: UpdateOptions): Promise<UpdateResult>;

package/dist/update.js

@@ -0,0 +1,195 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFile, readlink, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { delimiter, dirname, isAbsolute, join } from "node:path";
+import { CliError, record, safeText, throwIfInterrupted } from "./errors.js";
+const releases = "https://github.com/zocomputer/zo-cli/releases";
+const installCommand = "curl -fsSL https://zo.computer/install.sh | sh";
+const versionPattern = /^(\d+)\.(\d+)\.(\d+)(-[A-Za-z0-9][A-Za-z0-9.-]*)?$/;
+// The installer links <data home>/zo/cli/releases/<version>/<target>/zo.
+const managedPath = /^(\/.*\/zo\/cli)\/releases\/[^/]+\/[^/]+\/zo$/;
+function unreachable() {
+    return new CliError("Could not download the latest Zo CLI release. Check your connection and try again.", 5, "transport_error");
+}
+/** Follows redirects by hand so a release can never be fetched over plain HTTP. */
+async function download(url, fetcher, signal) {
+    const timeout = AbortSignal.timeout(60_000);
+    const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
+    try {
+        let target = url;
+        for (let hop = 0; hop < 5; hop++) {
+            const response = await fetcher(target, {
+                redirect: "manual",
+                signal: combined,
+            });
+            const location = response.headers.get("location");
+            if (response.status >= 300 && response.status < 400 && location) {
+                await response.body?.cancel();
+                target = new URL(location, target).href;
+                if (!target.startsWith("https://"))
+                    break;
+                continue;
+            }
+            if (!response.ok || !response.body)
+                break;
+            // The manifest and installer are a few kilobytes; refuse anything else.
+            const reader = response.body.getReader();
+            const chunks = [];
+            for (let size = 0;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    return Buffer.concat(chunks);
+                size += value.length;
+                if (size > 1_048_576) {
+                    await reader.cancel().catch(() => { });
+                    break;
+                }
+                chunks.push(value);
+            }
+            break;
+        }
+    }
+    catch {
+        throwIfInterrupted(signal);
+    }
+    throw unreachable();
+}
+function isNewer(candidate, current) {
+    const next = versionPattern.exec(candidate);
+    const now = versionPattern.exec(current);
+    if (!next || !now)
+        return false;
+    for (const index of [1, 2, 3]) {
+        const difference = Number(next[index]) - Number(now[index]);
+        if (difference !== 0)
+            return difference > 0;
+    }
+    // 0.4.0 follows 0.4.0-rc.1; the latest release is never a prerelease.
+    return now[4] !== undefined && next[4] === undefined;
+}
+/** Finds the installer's link on PATH, else in the installer's default directory. */
+async function managedCommand(executable, env) {
+    const directories = (env.PATH ?? "").split(delimiter);
+    directories.push(join(env.HOME ?? homedir(), ".local/bin"));
+    let shadowedBy;
+    for (const directory of directories) {
+        if (!isAbsolute(directory))
+            continue;
+        const command = join(directory, "zo");
+        const resolved = await realpath(command).catch(() => undefined);
+        if (resolved === undefined)
+            continue;
+        if (resolved !== executable) {
+            shadowedBy ??= command;
+            continue;
+        }
+        // The installer replaces only a link it wrote, so an alias that points at
+        // that link is passed over for the link itself.
+        const root = managedPath.exec(await readlink(command).catch(() => ""))?.[1];
+        if (root)
+            return { directory, root, shadowedBy };
+    }
+    return undefined;
+}
+function shell(env, signal, stderr) {
+    return (script, args) => new Promise((resolve, reject) => {
+        // The installer reads itself from stdin, as it does under `curl | sh`.
+        // It gets its own process group so an interrupt also stops its download;
+        // a shell alone would wait for curl before running its trap.
+        const child = spawn("/bin/sh", ["-s", "--", ...args], {
+            env,
+            detached: true,
+            stdio: ["pipe", "ignore", "pipe"],
+        });
+        const stop = () => {
+            try {
+                if (child.pid !== undefined)
+                    process.kill(-child.pid, "SIGTERM");
+            }
+            catch {
+                /* The installer already exited. */
+            }
+        };
+        signal?.addEventListener("abort", stop, { once: true });
+        if (signal?.aborted)
+            stop();
+        child.on("error", reject);
+        child.on("close", (code) => {
+            signal?.removeEventListener("abort", stop);
+            resolve(code ?? 1);
+        });
+        child.stderr.on("data", (chunk) => stderr.write(String(chunk)));
+        // A shell that exits early closes the pipe; its status reports why.
+        child.stdin.on("error", () => { });
+        child.stdin.end(script);
+    });
+}
+export async function update(options = {}) {
+    const env = options.env ?? process.env;
+    const stderr = options.stderr ?? process.stderr;
+    const current = options.version;
+    if (current === undefined)
+        throw new CliError("zo update replaces the standalone executable. This zo was installed with npm; run npm install --global @zocomputer/cli@latest instead.", 2, "unsupported_installation");
+    const unmanaged = (reason) => new CliError(`${reason} Install the latest release with: ${installCommand}`, 2, "unsupported_installation");
+    const executable = await realpath(options.execPath ?? process.execPath);
+    const command = await managedCommand(executable, env);
+    if (managedPath.test(executable) && !command)
+        throw unmanaged("No zo command on your PATH links to this executable.");
+    const marker = command
+        ? await readFile(join(command.root, ".installer-v1"), "utf8").catch(() => "")
+        : "";
+    if (!command || marker.trim() !== "zo-cli-installer-v1")
+        throw unmanaged("This zo was not installed by the standalone installer, so it cannot update itself.");
+    const fetcher = options.fetch ?? fetch;
+    let manifest;
+    try {
+        manifest = JSON.parse((await download(`${releases}/latest/download/release.json`, fetcher, options.signal)).toString("utf8"));
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+    }
+    const invalid = new CliError("The latest Zo CLI release could not be verified. Nothing was changed.", 5, "invalid_response");
+    if (!record(manifest) ||
+        manifest.schema_version !== 1 ||
+        typeof manifest.cli_version !== "string" ||
+        !versionPattern.test(manifest.cli_version) ||
+        typeof manifest.installer_sha256 !== "string")
+        throw invalid;
+    const latest = manifest.cli_version;
+    if (!isNewer(latest, current)) {
+        stderr.write(latest === current
+            ? `zo ${current} is the latest version.\n`
+            : `zo ${current} is newer than the latest release, ${latest}. Nothing to update; to install ${latest}, run: ${installCommand}\n`);
+        return { version: current, latest_version: latest, updated: false };
+    }
+    // Each release publishes the installer pinned to its own version.
+    const installer = await download(`${releases}/download/v${latest}/install.sh`, fetcher, options.signal);
+    if (createHash("sha256").update(installer).digest("hex") !==
+        manifest.installer_sha256)
+        throw invalid;
+    stderr.write(`Updating zo ${current} to ${latest}…\n`);
+    // The installer derives its root from XDG_DATA_HOME, which may have changed
+    // since installation; the link records the root it must keep using.
+    const run = options.runInstaller ??
+        shell({ ...env, XDG_DATA_HOME: dirname(dirname(command.root)) }, options.signal, stderr);
+    let status;
+    try {
+        status = await run(installer, [
+            "--bin-dir",
+            command.directory,
+            "--no-modify-path",
+        ]);
+    }
+    catch {
+        status = 1;
+    }
+    throwIfInterrupted(options.signal);
+    if (status !== 0)
+        throw new CliError(`The update did not finish. zo ${current} is still installed.`, 5, "update_failed");
+    stderr.write(`Updated zo to ${latest}. Sign-ins are unchanged.\n`);
+    if (command.shadowedBy)
+        stderr.write(`Another zo at ${safeText(command.shadowedBy)} comes first on your PATH and was not updated.\n`);
+    return { version: latest, latest_version: latest, updated: true };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zocomputer/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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.2.0"
+    "@zocomputer/system-api": "0.3.0"
   },
   "publishConfig": {
     "access": "public",