@zocomputer/cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,169 @@
-# Temporary Holding Version
+# Zo CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The public Zo CLI signs in through your browser and selects a workspace for
+System API commands. It supports the maintained Node 22, 24 and 26 LTS lines on macOS and Linux;
+see [runtime requirements](../README.md#set-up).
+Version 0.1.0 is a release candidate. Publish it only after the production
+OAuth client and session endpoint are live and the release checks pass.
+
+## Install or upgrade
+
+After publication, install the versioned package:
+
+```sh
+npm install --global @zocomputer/cli@0.1.0
+zo --version
+zo login
+```
+
+Use the same install command with the desired version to upgrade. The CLI
+installs its matching public SDK dependency. It performs no update check when
+you run a command.
+
+To test unpublished artifacts, install both tarballs together:
+
+```sh
+npm install --global ./zocomputer-system-api-0.1.0.tgz ./zocomputer-cli-0.1.0.tgz
+zo --version
+```
+
+## Develop locally
+
+Install the independent client workspace, then build the CLI:
+
+```sh
+cd clients
+nvm use
+npm ci
+npm run build
+```
+
+The CLI build compiles the SDK first. npm links the two packages inside this
+workspace; application pnpm settings and dependencies are not used.
+
+From this package directory:
+
+```sh
+node dist/main.js --help
+node dist/main.js login
+node dist/main.js context list
+node dist/main.js context use wsp_example
+node dist/main.js auth status
+```
+
+Use `node dist/main.js` while working in this repository. The repository's
+internal operator CLI is `./zocli/zo` from the repository root. Run `type -a zo`
+to diagnose a PATH collision; the two clients store separate sign-ins.
+
+## Accounts and workspaces
+
+Use named profiles to keep separate sign-ins. New profiles use production:
+
+```sh
+node dist/main.js login --profile work
+node dist/main.js auth status --profile work
+```
+
+A missing `environment` in a saved profile also means production. Internal
+testing can explicitly create a staging profile with
+`login --profile staging --environment staging`. An existing profile keeps its
+environment when you sign in again; changing it requires a different profile.
+
+Workspace selection uses `--workspace`, then
+`ZO_WORKSPACE_ID`, then the profile's saved default. An unavailable selected
+workspace produces an error; the CLI never switches identities or workspaces
+to make a command succeed.
+
+Login selects a sole authorized workspace automatically. With several
+workspaces, a terminal prompts for a selection; scripts must supply
+`--workspace` or subsequently run `context use`. Status shows the approving
+person separately from the effective subject in the selected workspace.
+`context list`, `context use` and status refresh that view from the server.
+
+`login --no-browser` prints the authorization URL on stderr and listens for
+the same loopback callback. It is not a device-code login. The browser must
+reach the CLI's localhost callback.
+
+## Tokens and logout
+
+`auth token` explicitly prints a short-lived access token. Add `--headers` to
+print an Authorization JSON object for an MCP client. Status never prints a
+token. `ZO_SYSTEM_API_ACCESS_TOKEN` supplies an explicit automation token for
+the selected profile's fixed origins; the CLI never saves or refreshes it,
+including when the server refuses it.
+
+`logout` revokes the saved sign-in and pending replaced sign-ins. If revocation
+fails, local credentials remain so you can retry. `logout --local-only`
+removes local credentials without revoking server access. Unset a bearer
+override before logging in or out of a saved profile.
+
+If a credential file is malformed, revoke its login in **Authorized apps**,
+then run `logout --local-only` for that profile before signing in again.
+Ordinary login and logout preserve the unreadable file so they do not silently
+discard pending revocations.
+
+## Local storage
+
+Configuration lives in `${XDG_CONFIG_HOME:-$HOME/.config}/zo/cli/`:
+
+- `config.json` stores versioned profiles and workspace selections.
+- `credentials/<profile>.json` stores the profile binding, access and refresh
+  tokens, refresh state, and pending revocations.
+- `credentials/<profile>.lock/` contains temporary process claims.
+
+Directories use mode 0700; files use 0600. The CLI checks ownership and refuses
+symlinks and writable parent directories. Credential writes sync a private
+file, replace the previous file atomically, then sync the directory. These
+permissions protect against other OS users, not programs running as you.
+
+Every credential change uses a cross-process bakery lock. Each process
+publishes a unique choosing claim, then an ordered ticket. It waits for lower
+tickets before entering the credential operation. Waits stop after 30 seconds;
+a live owner is never evicted based on elapsed time. Claims from dead PIDs are
+removed. A reused PID can delay recovery until the unrelated process exits;
+it cannot admit two credential writers. This uses native Node APIs on both
+supported systems without depending on Python or native lock extensions.
+
+Refresh starts only with 60 seconds or less remaining on the access token.
+Before sending, the CLI durably marks the outcome uncertain. If syncing that
+marker fails after replacement, it attempts to restore the original ready
+credential and reports the storage error; no exchange was sent. A lost response
+may be retried once under the lock within the server's 30-second recovery
+window. Saving the received successor clears the marker. A crash, failure to
+replace the credential file, or unresolved second request leaves the marker
+in place and requires login;
+later processes cannot unknowingly replay that refresh token.
+
+Replacing a login saves the new token and the old token's pending revocation
+in one atomic credential write before contacting the revocation endpoint.
+Failed cleanup remains in that journal and is retried by logout or the next
+replacement login. Replacement login reports success with a warning when old
+sign-in cleanup fails; the newly saved credential remains usable. Revoke the
+previous sign-in in Authorized apps if needed. Logout revokes the current
+sign-in too.
+
+## Checks
+
+```sh
+npm run build
+npm exec -- vitest run test/auth.test.ts test/credentials.test.ts test/profiles.test.ts test/context.test.ts
+npm run lint
+npm run typecheck
+npm run test:packed
+```
+
+The packed check builds both public packages and checks their contents. It
+installs their tarballs outside the monorepo and runs the installed binary's
+help, completion, version, RPC, preview and generated commands. A local fake
+API checks that large integers and exact decimals survive invocation. No live
+account or token is needed.
+
+To retain release archives for inspection or installation:
+
+```sh
+npm run pack:release -- --out /tmp/zo-cli-release
+```
+
+The command checks generated-command drift and writes both versioned tarballs.
+It rejects source files, missing compiled entry points, internal dependencies
+and unresolved workspace dependencies. It does not publish either package.

package/dist/argv.d.ts

@@ -0,0 +1,15 @@
+export interface GlobalOptions {
+    profile?: string;
+    workspace?: string;
+    json: boolean;
+    envelope: boolean;
+    help: boolean;
+}
+export declare function parseGlobals(argv: readonly string[]): {
+    args: string[];
+    options: GlobalOptions;
+};
+export declare function commandOptions(args: readonly string[], values: readonly string[], flags?: readonly string[]): {
+    values: Map<string, string>;
+    flags: Set<string>;
+};

package/dist/argv.js

@@ -0,0 +1,83 @@
+import { CliError } from "./errors.js";
+const switches = new Set(["json", "envelope", "help", "preview"]);
+export function parseGlobals(argv) {
+    const options = { json: false, envelope: false, help: false };
+    const seen = new Set();
+    const args = [];
+    let command = false;
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index];
+        if (arg === undefined)
+            continue;
+        if (!arg.startsWith("--")) {
+            args.push(arg);
+            command = true;
+            continue;
+        }
+        const equal = arg.indexOf("=");
+        const name = arg.slice(2, equal === -1 ? undefined : equal);
+        if (!/^[a-z][a-z0-9-]*$/.test(name))
+            throw new CliError("Invalid option syntax.");
+        const localSwitch = (name === "no-browser" && args[0] === "login") ||
+            (name === "local-only" && args[0] === "logout") ||
+            (name === "headers" && args[0] === "auth" && args[1] === "token");
+        const flag = switches.has(name) || localSwitch || (name === "version" && !command);
+        if (flag && equal !== -1)
+            throw new CliError(`--${name} does not take a value.`);
+        const value = flag
+            ? undefined
+            : equal === -1
+                ? argv[++index]
+                : arg.slice(equal + 1);
+        if (!flag &&
+            (value === undefined || (equal === -1 && value.startsWith("--"))))
+            throw new CliError(`--${name} requires a value. Use --name=value for values beginning with --.`);
+        if (["profile", "workspace", "json", "envelope", "help"].includes(name)) {
+            if (seen.has(name))
+                throw new CliError(`Repeated --${name}.`);
+            seen.add(name);
+            if (name === "profile" || name === "workspace") {
+                if (!value)
+                    throw new CliError(`--${name} requires a nonempty value.`);
+                options[name] = value;
+            }
+            else if (name === "json" || name === "envelope" || name === "help")
+                options[name] = true;
+        }
+        else {
+            args.push(arg);
+            if (!flag && equal === -1 && value !== undefined)
+                args.push(value);
+        }
+    }
+    return { args, options };
+}
+export function commandOptions(args, values, flags = []) {
+    const parsed = {
+        values: new Map(),
+        flags: new Set(),
+    };
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (!arg?.startsWith("--"))
+            throw new CliError("Unexpected argument. Run this command with --help.");
+        const equal = arg.indexOf("=");
+        const name = arg.slice(2, equal === -1 ? undefined : equal);
+        if (parsed.values.has(name) || parsed.flags.has(name))
+            throw new CliError(`Repeated --${name}.`);
+        if (flags.includes(name)) {
+            if (equal !== -1)
+                throw new CliError(`--${name} does not take a value.`);
+            parsed.flags.add(name);
+        }
+        else if (values.includes(name)) {
+            const value = equal === -1 ? args[++index] : arg.slice(equal + 1);
+            if (value === undefined || (equal === -1 && value.startsWith("--")))
+                throw new CliError(`--${name} requires a value.`);
+            parsed.values.set(name, value);
+        }
+        else
+            throw new CliError(`Unknown option --${name}. Run this command with --help.`);
+    }
+    return parsed;
+}

package/dist/auth.d.ts

@@ -0,0 +1,39 @@
+import { type LoginOptions } from "./login.ts";
+import { type Profile } from "./profiles.ts";
+import { type Session } from "./session.ts";
+interface Binding {
+    issuer: string;
+    api: string;
+    audience: string;
+    clientId: string;
+}
+export interface AuthOptions {
+    fetch?: typeof fetch;
+    environment?: Binding;
+    env?: NodeJS.ProcessEnv;
+    now?: () => number;
+    signal?: AbortSignal;
+}
+export declare class AuthClient {
+    readonly profile: Profile;
+    readonly directory: string;
+    readonly binding: Binding;
+    readonly path: string;
+    private readonly fetcher;
+    private readonly env;
+    private readonly now;
+    private readonly signal?;
+    constructor(profile: Profile, directory: string, options?: AuthOptions);
+    private locked;
+    private read;
+    private tokenRequest;
+    accessToken(): Promise<string>;
+    session(): Promise<Session>;
+    private revoke;
+    private cleanup;
+    login(options?: LoginOptions): Promise<{
+        cleanupPending: boolean;
+    }>;
+    logout(localOnly?: boolean): Promise<void>;
+}
+export {};

package/dist/auth.js

@@ -0,0 +1,290 @@
+import { join } from "node:path";
+import { CliError, record, throwIfInterrupted } from "./errors.js";
+import { requestJson, RequestFailure } from "./http.js";
+import { loginCode } from "./login.js";
+import { environments, profileName } from "./profiles.js";
+import { parseSession } from "./session.js";
+import { privateDirectory, PrivateWriteDurabilityError, readPrivate, removePrivate, withLock, writePrivate, } from "./storage.js";
+function tokens(raw, now) {
+    if (!record(raw) ||
+        raw.error !== undefined ||
+        typeof raw.access_token !== "string" ||
+        !raw.access_token ||
+        typeof raw.refresh_token !== "string" ||
+        !raw.refresh_token ||
+        typeof raw.token_type !== "string" ||
+        raw.token_type.toLowerCase() !== "bearer" ||
+        typeof raw.expires_in !== "number" ||
+        !Number.isSafeInteger(raw.expires_in) ||
+        raw.expires_in <= 0 ||
+        raw.expires_in > 300)
+        throw new RequestFailure(false, "invalid_token_response");
+    return {
+        accessToken: raw.access_token,
+        refreshToken: raw.refresh_token,
+        expiresAt: now + raw.expires_in * 1000,
+    };
+}
+function invalidCredential() {
+    return new CliError("The saved credential cannot be read safely. Revoke Zo CLI in Authorized apps, then run zo logout --local-only for this profile before signing in again. Local-only logout does not revoke server access.", 3, "invalid_credential");
+}
+export class AuthClient {
+    profile;
+    directory;
+    binding;
+    path;
+    fetcher;
+    env;
+    now;
+    signal;
+    constructor(profile, directory, options = {}) {
+        this.profile = profile;
+        this.directory = directory;
+        this.binding = options.environment ?? environments[profile.environment];
+        this.path = join(directory, "credentials", `${profileName(profile.name)}.json`);
+        this.fetcher = options.fetch ?? fetch;
+        this.env = options.env ?? process.env;
+        this.now = options.now ?? Date.now;
+        this.signal = options.signal;
+    }
+    async locked(work, signal = this.signal) {
+        throwIfInterrupted(signal);
+        await privateDirectory(this.directory);
+        await privateDirectory(join(this.directory, "credentials"));
+        return withLock(join(this.directory, "credentials", `${this.profile.name}.lock`), work, undefined, signal);
+    }
+    async read() {
+        let raw;
+        try {
+            raw = await readPrivate(this.path);
+        }
+        catch (error) {
+            if (error instanceof CliError && error.code === "invalid_local_data")
+                throw invalidCredential();
+            throw error;
+        }
+        if (raw === undefined)
+            return undefined;
+        if (!record(raw) ||
+            raw.version !== 1 ||
+            !record(raw.binding) ||
+            !Object.entries(this.binding).every(([key, value]) => record(raw.binding) && raw.binding[key] === value) ||
+            !Array.isArray(raw.pendingRevocations) ||
+            !raw.pendingRevocations.every((entry) => typeof entry === "string" && entry.length > 0) ||
+            (raw.refreshState !== "ready" && raw.refreshState !== "uncertain"))
+            throw invalidCredential();
+        let active;
+        if (raw.active !== undefined) {
+            if (!record(raw.active) ||
+                typeof raw.active.accessToken !== "string" ||
+                !raw.active.accessToken ||
+                typeof raw.active.refreshToken !== "string" ||
+                !raw.active.refreshToken ||
+                typeof raw.active.expiresAt !== "number" ||
+                !Number.isFinite(raw.active.expiresAt))
+                throw invalidCredential();
+            active = {
+                accessToken: raw.active.accessToken,
+                refreshToken: raw.active.refreshToken,
+                expiresAt: raw.active.expiresAt,
+            };
+        }
+        return {
+            version: 1,
+            binding: this.binding,
+            ...(active ? { active } : {}),
+            pendingRevocations: raw.pendingRevocations,
+            refreshState: raw.refreshState,
+        };
+    }
+    async tokenRequest(form, signal = this.signal) {
+        const issuedAt = this.now();
+        return tokens(await requestJson(`${this.binding.issuer}/zo-system-api/oauth/token`, {
+            method: "POST",
+            signal,
+            body: new URLSearchParams({
+                ...form,
+                client_id: this.binding.clientId,
+                resource: this.binding.audience,
+            }),
+        }, this.fetcher), issuedAt);
+    }
+    async accessToken() {
+        throwIfInterrupted(this.signal);
+        const override = this.env.ZO_SYSTEM_API_ACCESS_TOKEN;
+        if (override !== undefined) {
+            if (!override || /\s/.test(override))
+                throw new CliError("ZO_SYSTEM_API_ACCESS_TOKEN is empty or invalid.", 3, "invalid_token");
+            return override;
+        }
+        return this.locked(async () => {
+            const credential = await this.read();
+            throwIfInterrupted(this.signal);
+            if (!credential?.active)
+                throw new CliError("Sign in with zo login.", 3, "login_required");
+            if (credential.refreshState !== "ready")
+                throw new CliError("The previous refresh outcome is unknown. Run zo login; automatic refresh is stopped.", 3, "refresh_uncertain");
+            if (credential.active.expiresAt - this.now() > 60_000)
+                return credential.active.accessToken;
+            credential.refreshState = "uncertain";
+            try {
+                await writePrivate(this.path, credential);
+            }
+            catch (error) {
+                if (error instanceof PrivateWriteDurabilityError) {
+                    // No exchange was sent, so the visible journal can safely be undone.
+                    credential.refreshState = "ready";
+                    await writePrivate(this.path, credential);
+                }
+                throw error;
+            }
+            const started = performance.now();
+            const startedAt = this.now();
+            const form = {
+                grant_type: "refresh_token",
+                refresh_token: credential.active.refreshToken,
+            };
+            let successor;
+            try {
+                successor = await this.tokenRequest(form);
+            }
+            catch (error) {
+                throwIfInterrupted(this.signal);
+                // Two eight-second requests fit the issuer's thirty-second recovery
+                // window. Wall time also catches suspension of the monotonic clock.
+                const elapsed = this.now() - startedAt;
+                if (!(error instanceof RequestFailure) ||
+                    !error.ambiguous ||
+                    performance.now() - started >= 20_000 ||
+                    elapsed < 0 ||
+                    elapsed >= 20_000)
+                    throw error;
+                successor = await this.tokenRequest(form);
+            }
+            credential.active = successor;
+            credential.refreshState = "ready";
+            await writePrivate(this.path, credential);
+            throwIfInterrupted(this.signal);
+            return successor.accessToken;
+        });
+    }
+    async session() {
+        const token = await this.accessToken();
+        return parseSession(await requestJson(`${this.binding.api}/zo-system-api/v1/session`, { headers: { Authorization: `Bearer ${token}` }, signal: this.signal }, this.fetcher, { systemApi: true, timeoutMs: 30_000 }));
+    }
+    async revoke(token, signal = this.signal) {
+        throwIfInterrupted(signal);
+        const timeout = AbortSignal.timeout(8_000);
+        let response;
+        try {
+            response = await this.fetcher(`${this.binding.issuer}/zo-system-api/oauth/revoke`, {
+                method: "POST",
+                body: new URLSearchParams({
+                    client_id: this.binding.clientId,
+                    token,
+                    token_type_hint: "refresh_token",
+                }),
+                redirect: "error",
+                signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+            });
+        }
+        catch {
+            throwIfInterrupted(signal);
+            throw new CliError("Revocation failed. Local credentials were retained; retry zo logout.", 5, "revocation_failed");
+        }
+        await response.body?.cancel();
+        throwIfInterrupted(signal);
+        if (!response.ok)
+            throw new CliError("Revocation failed. Local credentials were retained; retry zo logout.", 5, "revocation_failed");
+    }
+    async cleanup(credential, signal = this.signal) {
+        while (credential.pendingRevocations.length) {
+            const token = credential.pendingRevocations[0];
+            if (token === undefined)
+                break;
+            await this.revoke(token, signal);
+            credential.pendingRevocations.shift();
+            await writePrivate(this.path, credential);
+            throwIfInterrupted(signal);
+        }
+    }
+    async login(options = {}) {
+        const signal = this.signal && options.signal
+            ? AbortSignal.any([this.signal, options.signal])
+            : (this.signal ?? options.signal);
+        throwIfInterrupted(signal);
+        if (this.env.ZO_SYSTEM_API_ACCESS_TOKEN !== undefined)
+            throw new CliError("Unset ZO_SYSTEM_API_ACCESS_TOKEN before browser login.");
+        return this.locked(async () => {
+            const previous = await this.read();
+            throwIfInterrupted(signal);
+            const code = await loginCode(this.binding.issuer, this.binding.audience, this.binding.clientId, { ...options, signal });
+            const active = await this.tokenRequest({
+                grant_type: "authorization_code",
+                code: code.code,
+                code_verifier: code.verifier,
+                redirect_uri: code.redirectUri,
+            }, signal);
+            const credential = {
+                version: 1,
+                binding: this.binding,
+                active,
+                refreshState: "ready",
+                pendingRevocations: [
+                    ...(previous?.pendingRevocations ?? []),
+                    ...(previous?.active ? [previous.active.refreshToken] : []),
+                ],
+            };
+            try {
+                await writePrivate(this.path, credential);
+            }
+            catch (error) {
+                if (error instanceof PrivateWriteDurabilityError)
+                    throw error;
+                try {
+                    // Saving failed; cleanup must still run after an interruption.
+                    await this.revoke(active.refreshToken, null);
+                }
+                catch {
+                    throw new CliError("Could not save or revoke the new sign-in. Revoke Zo CLI in Authorized apps before retrying login.", 5, "unsaved_sign_in");
+                }
+                throw error;
+            }
+            throwIfInterrupted(signal);
+            try {
+                await this.cleanup(credential, signal);
+            }
+            catch {
+                throwIfInterrupted(signal);
+                // The new sign-in is durable. Cleanup failure must not send the user
+                // to logout, which would revoke that successfully saved replacement.
+                return { cleanupPending: true };
+            }
+            return { cleanupPending: false };
+        }, signal);
+    }
+    async logout(localOnly = false) {
+        throwIfInterrupted(this.signal);
+        if (this.env.ZO_SYSTEM_API_ACCESS_TOKEN !== undefined)
+            throw new CliError("Unset ZO_SYSTEM_API_ACCESS_TOKEN before logging out a saved profile.");
+        await this.locked(async () => {
+            if (localOnly) {
+                await removePrivate(this.path);
+                throwIfInterrupted(this.signal);
+                return;
+            }
+            const credential = await this.read();
+            throwIfInterrupted(this.signal);
+            if (!credential)
+                return;
+            if (credential.active) {
+                await this.revoke(credential.active.refreshToken);
+                delete credential.active;
+                await writePrivate(this.path, credential);
+            }
+            await this.cleanup(credential);
+            await removePrivate(this.path);
+            throwIfInterrupted(this.signal);
+        });
+    }
+}

package/dist/catalog.d.ts

@@ -0,0 +1,23 @@
+import { type FetchLike, type RuntimeCatalog } from "@zocomputer/system-api";
+import { type NormalizedCatalog, type OperationVersion } from "@zocomputer/system-api/catalog";
+import { type JsonObject, type JsonValue } from "@zocomputer/system-api/json";
+export interface InvocationContext {
+    workspaceId: string;
+    apiOrigin: string;
+    accessToken: () => Promise<string>;
+    fetch?: FetchLike;
+    signal?: AbortSignal;
+}
+export interface LoadedCatalog {
+    authenticatedContext: InvocationContext;
+    catalog: NormalizedCatalog;
+    runtimeCatalog: RuntimeCatalog;
+}
+export declare function apiBaseUrl(context: InvocationContext): string;
+export declare function loadCatalog(context: InvocationContext, options?: {
+    catalog?: "scoped" | "all";
+}): Promise<LoadedCatalog>;
+export declare function parseVersion(value: string): number;
+export declare function resolveAction(catalog: NormalizedCatalog, action: string, explicitVersion?: number): OperationVersion;
+export declare function listActions(catalog: NormalizedCatalog): JsonValue;
+export declare function describeAction(catalog: NormalizedCatalog, action: string, version?: number): JsonObject;