@zocomputer/cli 0.3.0 → 0.4.1

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:
 
@@ -127,6 +127,43 @@ Each poll waits up to 20 seconds. After a timeout or network error the CLI
 retries once at once, inside the issuer's 30-second redemption window, then
 resumes polling every `interval` seconds; `slow_down` and a 429 add 5 seconds.
 
+## Output for terminals and scripts
+
+`zo actions list`, `zo actions describe`, and commands with schema-derived
+flags revalidate a private disk copy of the workspace catalog on each call.
+The server returns `304` when its `ETag` still matches; the CLI then uses the
+saved copy. A permission error is never served from disk.
+
+Results are data. When stdout is piped or redirected, or you pass `--json` or
+`--envelope`, the CLI prints the JSON result for scripts and agents to parse,
+with no color or tables. `rpc`, `--preview`, `actions describe` and
+`auth token --headers` print JSON on a terminal too.
+
+When stdout is a terminal, a list command prints a table, any other action
+prints aligned keys and values, and `login`, `context` and `auth status` print
+text. A table shows a few columns of each row and points to `--json` for the
+rest. A key/value view shows the whole result, since the command may not be
+safe to run twice; a result it can't lay out, such as a query's rows, prints
+as JSON.
+
+Help, status lines and error wording are prose, read by people and agents
+alike. Help is the same text everywhere: `zo` and `zo --help` print the
+commands in groups with every resource name, and a terminal only adds bold.
+`login` prints the same status lines everywhere too; a terminal adds color, a
+success mark and a spinner, and anything else gets one `Waiting for approval…`
+line. A mistyped command names the nearest installed one.
+
+A script can rely on the exit status, the error code and the shape of the
+JSON, and should not match the wording of a message. When stderr is not a
+terminal a failure begins `<code>: <message>`, so the code is there to match.
+On a terminal it reads `Error: <message> (<code>)` with any next step on the
+following line, Ctrl-C prints `Cancelled.`, and `login` shows a spinner while
+it waits for approval. `--json` makes a failure a JSON object either way.
+
+Color needs a terminal and an unset or empty `NO_COLOR`. Names and other text
+from the server are escaped before printing, so they cannot send control
+sequences to your terminal.
+
 ## Tokens and logout
 
 `auth token` explicitly prints a short-lived access token. Add `--headers` to

package/dist/catalog-cache.d.ts

@@ -0,0 +1,7 @@
+export interface CachedCatalogExport {
+    etag: string;
+    catalogDigest: string;
+    body: Uint8Array;
+}
+export declare function readCatalogCache(url: URL, directory?: string): Promise<CachedCatalogExport | undefined>;
+export declare function writeCatalogCache(url: URL, entry: CachedCatalogExport, directory?: string): Promise<void>;

package/dist/catalog-cache.js

@@ -0,0 +1,63 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { configDirectory, privateDirectory, readPrivate, writePrivate, } from "./storage.js";
+const MAX_CACHE_FILE_BYTES = 6 * 1024 * 1024;
+const MAX_CATALOG_BYTES = 4 * 1024 * 1024;
+const STRONG_ETAG = /^"[0-9a-f]{64}"$/;
+const CATALOG_DIGEST = /^sha256:[0-9a-f]{64}$/;
+function cachePath(url, directory) {
+    const key = createHash("sha256").update(url.href).digest("hex");
+    return join(directory, `${key}.json`);
+}
+function bodyEtag(body) {
+    return `"${createHash("sha256").update(body).digest("hex")}"`;
+}
+export async function readCatalogCache(url, directory = join(configDirectory(), "catalog-cache")) {
+    try {
+        const path = cachePath(url, directory);
+        await privateDirectory(directory);
+        const value = await readPrivate(path, MAX_CACHE_FILE_BYTES);
+        if (value === null ||
+            typeof value !== "object" ||
+            Array.isArray(value) ||
+            !Object.hasOwn(value, "body") ||
+            !Object.hasOwn(value, "etag") ||
+            !Object.hasOwn(value, "catalogDigest"))
+            return undefined;
+        const entry = value;
+        if (entry.version !== 1 ||
+            typeof entry.body !== "string" ||
+            typeof entry.etag !== "string" ||
+            typeof entry.catalogDigest !== "string" ||
+            !STRONG_ETAG.test(entry.etag) ||
+            !CATALOG_DIGEST.test(entry.catalogDigest) ||
+            entry.body.length > MAX_CACHE_FILE_BYTES)
+            return undefined;
+        const body = Buffer.from(entry.body, "base64");
+        if (body.length > MAX_CATALOG_BYTES || bodyEtag(body) !== entry.etag)
+            return undefined;
+        return { body, etag: entry.etag, catalogDigest: entry.catalogDigest };
+    }
+    catch {
+        // A damaged or unavailable optional cache must not block live discovery.
+        return undefined;
+    }
+}
+export async function writeCatalogCache(url, entry, directory = join(configDirectory(), "catalog-cache")) {
+    if (!STRONG_ETAG.test(entry.etag) ||
+        !CATALOG_DIGEST.test(entry.catalogDigest) ||
+        entry.body.length > MAX_CATALOG_BYTES ||
+        bodyEtag(entry.body) !== entry.etag)
+        return;
+    try {
+        await writePrivate(cachePath(url, directory), {
+            version: 1,
+            etag: entry.etag,
+            catalogDigest: entry.catalogDigest,
+            body: Buffer.from(entry.body).toString("base64"),
+        });
+    }
+    catch {
+        // The disk copy is an optimization, never the source of authorization.
+    }
+}

package/dist/catalog.d.ts

@@ -7,6 +7,8 @@ export interface InvocationContext {
     accessToken: () => Promise<string>;
     fetch?: FetchLike;
     signal?: AbortSignal;
+    /** Test-only override; production uses the private CLI configuration directory. */
+    catalogCacheDirectory?: string;
 }
 export interface LoadedCatalog {
     authenticatedContext: InvocationContext;

package/dist/catalog.js

@@ -1,7 +1,9 @@
+import { createHash } from "node:crypto";
 import { defineRuntimeCatalog, SystemAPIError, } from "@zocomputer/system-api";
 import { loadNormalizedCatalog, } from "@zocomputer/system-api/catalog";
-import { canonicalNumberFromToken, JsonNumber, } from "@zocomputer/system-api/json";
+import { canonicalNumberFromToken, canonicalJsonBytes, JsonNumber, loadsJson, } from "@zocomputer/system-api/json";
 import { CliError } from "./errors.js";
+import { readCatalogCache, writeCatalogCache } from "./catalog-cache.js";
 import { systemApiFailure } from "./http.js";
 const MAX_CATALOG_BYTES = 4 * 1024 * 1024;
 export function apiBaseUrl(context) {
@@ -45,6 +47,24 @@ async function readCatalog(response) {
     }
     return bytes;
 }
+function verifiedDigest(bytes) {
+    const tree = loadsJson(bytes, { maxNodes: null, maxDepth: 40 });
+    if (tree === null ||
+        typeof tree !== "object" ||
+        Array.isArray(tree) ||
+        tree instanceof JsonNumber)
+        throw invalidCatalog("The service returned an invalid catalog export.");
+    const digest = tree.catalog_digest;
+    if (typeof digest !== "string" || !/^sha256:[0-9a-f]{64}$/.test(digest))
+        throw invalidCatalog("The service returned an invalid catalog digest.");
+    const body = { ...tree };
+    delete body.catalog_digest;
+    delete body.view_revision;
+    const computed = `sha256:${createHash("sha256").update(canonicalJsonBytes(body)).digest("hex")}`;
+    if (computed !== digest)
+        throw invalidCatalog("The service returned an invalid catalog digest.");
+    return digest;
+}
 export async function loadCatalog(context, options = {}) {
     if (!/^wsp_[A-Za-z0-9_-]+$/.test(context.workspaceId))
         throw new CliError("Select a workspace with zo context use <workspace-id> or --workspace.");
@@ -65,16 +85,27 @@ export async function loadCatalog(context, options = {}) {
     const signal = context.signal
         ? AbortSignal.any([context.signal, timeout])
         : timeout;
+    const useCache = context.fetch === undefined || context.catalogCacheDirectory !== undefined;
+    const cached = useCache
+        ? await readCatalogCache(url, context.catalogCacheDirectory)
+        : undefined;
     let response;
     let bytes;
     try {
         response = await (context.fetch ?? fetch)(url, {
-            headers: { authorization: `Bearer ${token}`, accept: "application/json" },
+            headers: {
+                authorization: `Bearer ${token}`,
+                accept: "application/json",
+                ...(cached ? { "If-None-Match": cached.etag } : {}),
+            },
             redirect: "error",
             cache: "no-store",
             signal,
         });
-        bytes = await readCatalog(response);
+        bytes =
+            response.status === 304
+                ? (cached?.body ?? new Uint8Array())
+                : await readCatalog(response);
     }
     catch (error) {
         if (signal.aborted)
@@ -95,8 +126,28 @@ export async function loadCatalog(context, options = {}) {
             outcome: "not_started",
         });
     }
-    if (!response.ok)
+    if (response.status === 304 && !cached)
+        throw invalidCatalog("The service returned 304 without a saved catalog.");
+    if (!response.ok && response.status !== 304)
         throw systemApiFailure(response, bytes, "Catalog discovery");
+    const etag = response.headers.get("etag");
+    if (response.status === 304 && etag !== cached?.etag)
+        throw invalidCatalog("The catalog validator changed without a response body.");
+    if (response.status === 200 &&
+        etag !== null &&
+        etag !== `"${createHash("sha256").update(bytes).digest("hex")}"`)
+        throw invalidCatalog("The service returned an invalid catalog validator.");
+    let digest;
+    if (etag !== null || response.status === 304) {
+        try {
+            digest = verifiedDigest(bytes);
+        }
+        catch {
+            throw invalidCatalog("The service returned an invalid catalog digest.");
+        }
+        if (response.status === 304 && digest !== cached?.catalogDigest)
+            throw invalidCatalog("The saved catalog digest changed.");
+    }
     let catalog;
     try {
         catalog = loadNormalizedCatalog(bytes).catalog;
@@ -108,6 +159,8 @@ export async function loadCatalog(context, options = {}) {
         catalog.selection.catalog !== mode) {
         throw invalidCatalog("The catalog selection does not match the requested workspace and catalog.");
     }
+    if (response.status === 200 && etag && digest)
+        await writeCatalogCache(url, { etag, catalogDigest: digest, body: bytes }, context.catalogCacheDirectory);
     return {
         authenticatedContext: { ...context, accessToken: async () => token },
         catalog,

package/dist/commands.d.ts

@@ -1,5 +1,19 @@
 import { type InvocationContext } from "./catalog.ts";
+import { CliError } from "./errors.ts";
 import { type RpcResult, type RpcOptions } from "./rpc.ts";
+/** The first word of every built-in command, in catalog order. */
+export declare function resourceNames(): string[];
+/**
+ * The error for arguments that name no command. It never repeats what was
+ * typed: it names the installed words that did match, and the nearest
+ * installed word to the first one that did not.
+ */
+export declare function unknownCommand(args: readonly string[], kind?: string): CliError;
+/**
+ * The fields a list action sorts by, from installed metadata. Undefined for
+ * an action that declares no list query, which is how a list is recognized.
+ */
+export declare function listSortFields(action: string): string[] | undefined;
 export declare function matchBuiltinCommand(args: readonly string[]): {
     action: string;
     args: string[];

package/dist/commands.js

@@ -4,6 +4,84 @@ import { CliError, safeText } from "./errors.js";
 import { encodeCommandFlags, inputFlags, parseCommandFlags, reservedOptions, resolvedSchema, scalarType, schemaObject, } from "./flags.js";
 import { commandManifest } from "./generated/commands.js";
 import { inputJson, runRpc } from "./rpc.js";
+import { closest } from "./suggest.js";
+/** Commands the runner implements itself, each with its subcommands. */
+const localCommands = {
+    login: [],
+    logout: [],
+    auth: ["status", "token"],
+    context: ["list", "use", "show"],
+    actions: ["list", "describe"],
+    rpc: [],
+    completion: [],
+    update: [],
+};
+/** The first word of every built-in command, in catalog order. */
+export function resourceNames() {
+    return [
+        ...new Set(commandManifest.commands.flatMap((command) => command.path.slice(0, 1))),
+    ];
+}
+/**
+ * The error for arguments that name no command. It never repeats what was
+ * typed: it names the installed words that did match, and the nearest
+ * installed word to the first one that did not.
+ */
+export function unknownCommand(args, kind = "command") {
+    let paths = [
+        ...Object.entries(localCommands).flatMap(([name, subcommands]) => subcommands.length
+            ? subcommands.map((subcommand) => [name, subcommand])
+            : [[name]]),
+        ...commandManifest.commands.map((command) => command.path),
+    ];
+    let depth = 0;
+    for (; depth < args.length; depth++) {
+        const matching = paths.filter((path) => path[depth] === args[depth]);
+        if (!matching.length)
+            break;
+        paths = matching;
+    }
+    const next = [
+        ...new Set(paths.flatMap((path) => {
+            const word = path[depth];
+            return word === undefined ? [] : [word];
+        })),
+    ];
+    const known = paths[0]?.slice(0, depth) ?? [];
+    const prefix = ["zo", ...known].join(" ");
+    const help = `Run ${prefix} --help.`;
+    const typed = args[depth];
+    if (depth > 0 &&
+        next.length &&
+        (typed === undefined || typed.startsWith("--")))
+        return new CliError(`${prefix} needs a command. ${help}`);
+    const guess = typed === undefined || typed.startsWith("--")
+        ? undefined
+        : closest(typed, next);
+    return new CliError(`Unknown ${depth ? `${known.join(" ")} command` : kind}.${guess ? ` Did you mean ${prefix} ${guess}?` : ""} ${help}`);
+}
+/**
+ * The fields a list action sorts by, from installed metadata. Undefined for
+ * an action that declares no list query, which is how a list is recognized.
+ */
+export function listSortFields(action) {
+    const queries = (commandManifest.commands.find((command) => command.action === action)
+        ?.versions ?? []).flatMap((version) => "queryJson" in version && typeof version.queryJson === "string"
+        ? [version.queryJson]
+        : []);
+    if (!queries.length)
+        return undefined;
+    const fields = new Set();
+    for (const text of queries) {
+        const query = loadsJson(text);
+        const sort = schemaObject(resolvedSchema(query)?.properties)?.sort;
+        const choices = sort === undefined ? undefined : resolvedSchema(sort, query)?.enum;
+        for (const choice of Array.isArray(choices) ? choices : [])
+            if (typeof choice === "string")
+                fields.add(choice.replace(/\.(?:asc|desc)$/, ""));
+    }
+    return [...fields];
+}
 export function matchBuiltinCommand(args) {
     const command = commandManifest.commands.find((command) => command.path.every((segment, index) => args[index] === segment));
     return command
@@ -47,7 +125,7 @@ Async actions return their actual accepted/run/operation state; there is no univ
 export function builtinHelp(path = []) {
     const commands = commandManifest.commands.filter((command) => path.every((segment, index) => command.path[index] === segment));
     if (!commands.length)
-        throw new CliError("Unknown built-in command. Run zo --help.");
+        throw unknownCommand(path, "built-in command");
     const command = commands.find((command) => command.path.length === path.length);
     if (!command)
         return `Built-in commands (installed metadata; availability is checked live)\n\n${commands.map((item) => `  zo ${item.path.join(" ")}`).join("\n")}\n\nRun a command with --help for its schema-derived flags.\n`;
@@ -90,19 +168,10 @@ export function builtinHelp(path = []) {
 export function completionScript(shell) {
     const words = [
         ...new Set([
-            "login",
-            "logout",
-            "auth",
-            "context",
-            "actions",
-            "rpc",
-            "completion",
-            "status",
-            "token",
-            "list",
-            "describe",
-            "use",
-            "show",
+            ...Object.entries(localCommands).flatMap(([name, subcommands]) => [
+                name,
+                ...subcommands,
+            ]),
             ...[...reservedOptions].map((option) => `--${option}`),
             ...commandManifest.commands.flatMap((command) => command.path),
             ...commandManifest.commands.flatMap((command) => command.versions.flatMap((version) => inputFlags(loadsJson(version.inputJson)).map((flag) => `--${flag.name}`))),