@zocomputer/cli 0.0.0-stage → 0.1.0

package/dist/output.js

@@ -0,0 +1,221 @@
+import { SystemAPIError } from "@zocomputer/system-api";
+import { canonicalNumberFromToken, dumpsJson, JsonNumber, loadsJson, } from "@zocomputer/system-api/json";
+import { CliError, record, safeText } from "./errors.js";
+function toJson(value) {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean" ||
+        value instanceof JsonNumber)
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return canonicalNumberFromToken(String(value));
+    if (Array.isArray(value))
+        return value.map(toJson);
+    if (record(value))
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, entry]) => entry !== undefined)
+            .map(([key, entry]) => [key, toJson(entry)]));
+    throw new TypeError("Output must be JSON.");
+}
+function prettyJson(value, depth = 0) {
+    if (value === null ||
+        typeof value !== "object" ||
+        value instanceof JsonNumber)
+        return dumpsJson(value);
+    const indent = "  ".repeat(depth + 1);
+    const closing = "  ".repeat(depth);
+    if (Array.isArray(value))
+        return value.length
+            ? `[\n${value.map((entry) => `${indent}${prettyJson(entry, depth + 1)}`).join(",\n")}\n${closing}]`
+            : "[]";
+    const entries = Object.entries(value);
+    return entries.length
+        ? `{\n${entries.map(([key, entry]) => `${indent}${JSON.stringify(key)}: ${prettyJson(entry, depth + 1)}`).join(",\n")}\n${closing}}`
+        : "{}";
+}
+function terminalJson(text) {
+    return text.replace(/[\u007f-\u009f]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+export function writeJsonText(text, options = {}) {
+    const stdout = options.stdout ?? process.stdout;
+    const human = stdout.isTTY && !options.json && !options.envelope;
+    stdout.write(`${human ? terminalJson(prettyJson(loadsJson(text, { maxNodes: null, maxDepth: 256 }))) : text}\n`);
+}
+export function writeJson(value, options = {}) {
+    writeJsonText(dumpsJson(toJson(value)), options);
+}
+export function writeRpcResult(result, options = {}) {
+    if (result.kind === "preview") {
+        writeJsonText(`{"workspace_id":${JSON.stringify(result.workspaceId)},"request":${result.requestJson}}`, options);
+        return;
+    }
+    writeJsonText(options.envelope
+        ? result.response.envelopeJson
+        : result.response.resultJson, options);
+}
+const detailFields = {
+    invalid_envelope: ["reason"],
+    conflict: ["reason", "pointer"],
+    quota_exceeded: ["reason"],
+    invalid_input: ["violations"],
+    invalid_query: ["violations"],
+    invalid_implementation_output: ["violations"],
+    approval_required: ["reference"],
+    unsupported_version: ["available_versions"],
+    rate_limited: ["retry_after_seconds"],
+    invalid_definition: ["pointer", "reason"],
+    missing_grants: ["function_ids", "total"],
+    permission_denied: [
+        "subscription_ids",
+        "total",
+        "connection_id",
+        "action",
+        "reason",
+    ],
+};
+function boundedString(value, empty = false) {
+    return (typeof value === "string" &&
+        (empty || value.length > 0) &&
+        value.length <= 256);
+}
+function boundedInteger(value, maximum, minimum = 0) {
+    if (value instanceof JsonNumber && !value.isInteger)
+        return undefined;
+    const number = value instanceof JsonNumber ? Number(value.text) : value;
+    return typeof number === "number" &&
+        Number.isInteger(number) &&
+        number >= minimum &&
+        number <= maximum
+        ? canonicalNumberFromToken(String(number))
+        : undefined;
+}
+/** Mirror the public error detail fields in hostagent.system_api.errors. */
+export function safeDetails(code, details) {
+    if (!record(details))
+        return {};
+    const projected = {};
+    const fields = detailFields[code] ?? [];
+    for (const field of fields) {
+        const value = details[field];
+        if (["reason", "reference", "connection_id", "action", "pointer"].includes(field)) {
+            if (boundedString(value, field === "pointer"))
+                projected[field] = value;
+        }
+        else if (field === "total" || field === "retry_after_seconds") {
+            const integer = boundedInteger(value, field === "total" ? 2_147_483_647 : 86_400);
+            if (integer !== undefined)
+                projected[field] = integer;
+        }
+        else if (Array.isArray(value) && value.length <= 20) {
+            if (field === "violations") {
+                projected[field] = value.flatMap((item) => record(item) &&
+                    boundedString(item.code) &&
+                    boundedString(item.path, true)
+                    ? [{ code: item.code, path: item.path }]
+                    : []);
+            }
+            else if (field === "available_versions") {
+                projected[field] = value.flatMap((item) => {
+                    const integer = boundedInteger(item, 2_147_483_647, 1);
+                    return integer === undefined ? [] : [integer];
+                });
+            }
+            else if (field === "function_ids" || field === "subscription_ids")
+                projected[field] = value.filter((item) => boundedString(item));
+        }
+    }
+    if (details.outcome === "unknown" || details.outcome === "not_started")
+        projected.outcome = details.outcome;
+    return projected;
+}
+export function exitCode(error) {
+    if (error instanceof CliError)
+        return error.exitCode;
+    if (error instanceof SystemAPIError) {
+        if (error.code === "interrupted")
+            return 130;
+        if (error.code === "unauthenticated" || error.httpStatus === 401)
+            return 3;
+        if ([
+            "insufficient_scope",
+            "permission_denied",
+            "missing_grants",
+            "approval_required",
+        ].includes(error.code) ||
+            error.httpStatus === 403)
+            return 4;
+        if (error.httpStatus === undefined &&
+            error.outcome === "not_started" &&
+            [
+                "invalid_input",
+                "invalid_query",
+                "invalid_envelope",
+                "version_required",
+                "unsupported_version",
+                "action_not_found",
+            ].includes(error.code))
+            return 2;
+        return 5;
+    }
+    return error instanceof Error && error.name === "AbortError" ? 130 : 5;
+}
+function actionHint(error) {
+    if (error.code === "unauthenticated" || error.httpStatus === 401)
+        return "Run zo login for this profile, then explicitly repeat the command if appropriate.";
+    if (error.code === "insufficient_scope")
+        return "Run zo login and approve the selected workspace for this profile.";
+    if (error.code === "approval_required")
+        return "Complete the required approval before explicitly repeating the command.";
+    if (error.code === "permission_denied" || error.code === "missing_grants")
+        return "Ask a workspace owner to grant the selected identity access to this action or resource.";
+    return undefined;
+}
+export function writeError(error, options = {}) {
+    const status = exitCode(error);
+    const stderr = options.stderr ?? process.stderr;
+    const known = error instanceof CliError || error instanceof SystemAPIError;
+    const failure = {
+        code: known
+            ? error.code
+            : status === 130
+                ? "interrupted"
+                : "command_failed",
+        message: known
+            ? error.message
+            : status === 130
+                ? "Interrupted."
+                : "The command failed. Check your connection and local file permissions.",
+    };
+    if (error instanceof SystemAPIError) {
+        const details = safeDetails(error.code, error.details);
+        if (Object.keys(details).length > 0)
+            failure.details = details;
+        if (error.requestId !== undefined)
+            failure.request_id = error.requestId;
+        if (error.httpStatus !== undefined)
+            failure.http_status = canonicalNumberFromToken(String(error.httpStatus));
+        if (error.retryAfterSeconds !== undefined)
+            failure.retry_after_seconds = canonicalNumberFromToken(String(error.retryAfterSeconds));
+        if (error.outcome !== undefined)
+            failure.outcome = error.outcome;
+        const hint = actionHint(error);
+        if (hint !== undefined)
+            failure.hint = hint;
+    }
+    if (options.json)
+        stderr.write(`${dumpsJson({ error: failure })}\n`);
+    else {
+        stderr.write(`${safeText(String(failure.code))}: ${safeText(String(failure.message))}\n`);
+        if (failure.request_id !== undefined)
+            stderr.write(`Request: ${safeText(String(failure.request_id))}\n`);
+        if (failure.details !== undefined)
+            stderr.write(`Details: ${terminalJson(dumpsJson(failure.details))}\n`);
+        if (failure.retry_after_seconds !== undefined)
+            stderr.write(`Retry after: ${dumpsJson(failure.retry_after_seconds)} seconds.\n`);
+        if (failure.outcome !== undefined)
+            stderr.write(`Outcome: ${safeText(String(failure.outcome))}.${failure.outcome === "unknown" ? " The action may have run; the CLI did not replay it." : ""}\n`);
+        if (failure.hint !== undefined)
+            stderr.write(`${safeText(String(failure.hint))}\n`);
+    }
+    return status;
+}

package/dist/presentation.d.ts

@@ -0,0 +1,9 @@
+import { type OutputOptions } from "./output.ts";
+import type { RpcResult } from "./rpc.ts";
+export interface PresentationOptions extends OutputOptions {
+    workspaceId?: string;
+    identity?: string;
+    columns?: number;
+}
+export declare function tableResult(action: string, text: string, columns?: number): string | undefined;
+export declare function writeBuiltinResult(action: string, result: RpcResult, options?: PresentationOptions): void;

package/dist/presentation.js

@@ -0,0 +1,95 @@
+import { dumpsJson, loadsJson, JsonNumber, } from "@zocomputer/system-api/json";
+import { safeText } from "./errors.js";
+import { schemaObject } from "./flags.js";
+import { writeRpcResult } from "./output.js";
+const tables = {
+    "zo.machine.list": {
+        field: "machines",
+        columns: ["id", "display_name", "state"],
+    },
+    "zo.database.list": {
+        field: "databases",
+        columns: ["id", "display_name", "state"],
+    },
+    "zo.agent.list": { field: "agents", columns: ["id", "display_name"] },
+    "zo.connection.list": {
+        field: "connections",
+        columns: ["id", "display_name", "status"],
+    },
+    "zo.function.list": { field: "functions", columns: ["id", "display_name"] },
+    "zo.task.list": { field: "tasks", columns: ["id", "title", "status"] },
+    "zo.workflow.list": { field: "workflows", columns: ["id", "display_name"] },
+    "zo.activity.list": {
+        field: "activity",
+        columns: ["occurred_at", "action", "outcome", "summary"],
+    },
+};
+function cell(value) {
+    if (value === undefined || value === null)
+        return "-";
+    return safeText(typeof value === "string"
+        ? value
+        : value instanceof JsonNumber
+            ? value.text
+            : dumpsJson(value));
+}
+function clipped(text, width) {
+    const characters = Array.from(text);
+    return characters.length <= width
+        ? text.padEnd(width)
+        : `${characters.slice(0, width - 1).join("")}…`;
+}
+export function tableResult(action, text, columns = 100) {
+    const projection = tables[action];
+    if (!projection)
+        return undefined;
+    const result = schemaObject(loadsJson(text, { maxNodes: null, maxDepth: 256 }));
+    const rows = result?.[projection.field];
+    if (!result || !Array.isArray(rows))
+        return undefined;
+    if (rows.some((row) => {
+        const object = schemaObject(row);
+        return (!object ||
+            projection.columns.some((field) => !Object.hasOwn(object, field) ||
+                (object[field] !== null &&
+                    typeof object[field] === "object" &&
+                    !(object[field] instanceof JsonNumber))));
+    }))
+        return undefined;
+    const cells = rows.map((row) => projection.columns.map((field) => cell(schemaObject(row)?.[field])));
+    const width = Math.max(20, Math.floor(columns));
+    const visible = projection.columns.slice(0, Math.max(1, Math.floor((width + 2) / 12)));
+    const budget = Math.floor((width - (visible.length - 1) * 2) / visible.length);
+    const widths = visible.map((column, index) => Math.min(budget, Math.max(column.length, ...cells.map((row) => Array.from(row[index] ?? "").length))));
+    const format = (row) => visible
+        .map((_, index) => clipped(row[index] ?? "", widths[index] ?? budget))
+        .join("  ")
+        .trimEnd();
+    const lines = [
+        format(visible.map((column) => column.toUpperCase())),
+        ...cells.map(format),
+    ];
+    if (!rows.length)
+        lines.push("No results.");
+    if (result.next_cursor !== undefined && result.next_cursor !== null)
+        lines.push(`Next cursor: ${cell(result.next_cursor)}`);
+    lines.push("Use --json for the complete result.");
+    return `${lines.join("\n")}\n`;
+}
+export function writeBuiltinResult(action, result, options = {}) {
+    const stdout = options.stdout ?? process.stdout;
+    const stderr = options.stderr ?? process.stderr;
+    if (stdout.isTTY &&
+        !options.json &&
+        !options.envelope &&
+        result.kind === "success") {
+        if (options.workspaceId)
+            stderr.write(`Workspace: ${safeText(options.workspaceId)}${options.identity ? `  Identity: ${safeText(options.identity)}` : ""}\n`);
+        const table = tableResult(action, result.response.resultJson, options.columns ?? process.stdout.columns ?? 100);
+        if (table !== undefined) {
+            stdout.write(table);
+            return;
+        }
+    }
+    writeRpcResult(result, options);
+}

package/dist/profiles.d.ts

@@ -0,0 +1,37 @@
+export declare const environments: {
+    readonly production: {
+        readonly issuer: "https://auth.zo.computer";
+        readonly api: "https://api.zo.computer";
+        readonly audience: "https://api.zo.computer/zo-system-api";
+        readonly clientId: "zo-public-cli";
+    };
+    readonly staging: {
+        readonly issuer: "https://auth.zostaging.computer";
+        readonly api: "https://api.zostaging.computer";
+        readonly audience: "https://api.zostaging.computer/zo-system-api";
+        readonly clientId: "zo-public-cli";
+    };
+};
+export type Environment = keyof typeof environments;
+export interface Profile {
+    name: string;
+    environment: Environment;
+    workspaceId?: string;
+}
+interface Configuration {
+    version: 1;
+    activeProfile: string;
+    profiles: Record<string, Profile>;
+}
+export declare function profileName(name: string): string;
+export declare function workspaceId(value: string): string;
+export declare class Profiles {
+    readonly directory: string;
+    constructor(directory?: string);
+    read(): Promise<Configuration>;
+    resolve(name?: string): Promise<Profile>;
+    create(name?: string, environment?: Environment, signal?: AbortSignal): Promise<Profile>;
+    select(profile: Profile, selected: string, signal?: AbortSignal): Promise<void>;
+}
+export declare function selectedWorkspace(profile: Profile, explicit?: string, env?: NodeJS.ProcessEnv): string;
+export {};

package/dist/profiles.js

@@ -0,0 +1,123 @@
+import { join } from "node:path";
+import { CliError, record, throwIfInterrupted } from "./errors.js";
+import { configDirectory, privateDirectory, readPrivate, withLock, writePrivate, } from "./storage.js";
+export const environments = {
+    production: {
+        issuer: "https://auth.zo.computer",
+        api: "https://api.zo.computer",
+        audience: "https://api.zo.computer/zo-system-api",
+        clientId: "zo-public-cli",
+    },
+    staging: {
+        issuer: "https://auth.zostaging.computer",
+        api: "https://api.zostaging.computer",
+        audience: "https://api.zostaging.computer/zo-system-api",
+        clientId: "zo-public-cli",
+    },
+};
+export function profileName(name) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(name))
+        throw new CliError("Profile names must use letters, numbers, underscores or hyphens (1–64 characters).");
+    return name;
+}
+export function workspaceId(value) {
+    if (!/^wsp_[A-Za-z0-9_-]+$/.test(value))
+        throw new CliError("Use a workspace ID beginning with wsp_.");
+    return value;
+}
+export class Profiles {
+    directory;
+    constructor(directory = configDirectory()) {
+        this.directory = directory;
+    }
+    async read() {
+        await privateDirectory(this.directory);
+        const raw = await readPrivate(join(this.directory, "config.json"));
+        if (raw === undefined)
+            return { version: 1, activeProfile: "default", profiles: {} };
+        if (!record(raw) ||
+            raw.version !== 1 ||
+            typeof raw.activeProfile !== "string" ||
+            !record(raw.profiles))
+            throw new CliError("Invalid profile configuration.");
+        const profiles = {};
+        for (const [name, entry] of Object.entries(raw.profiles)) {
+            profileName(name);
+            if (!record(entry) ||
+                entry.name !== name ||
+                (entry.environment !== undefined &&
+                    entry.environment !== "production" &&
+                    entry.environment !== "staging") ||
+                (entry.workspaceId !== undefined &&
+                    typeof entry.workspaceId !== "string"))
+                throw new CliError("Invalid profile configuration.");
+            profiles[name] = {
+                name,
+                environment: entry.environment ?? "production",
+                ...(typeof entry.workspaceId === "string"
+                    ? { workspaceId: workspaceId(entry.workspaceId) }
+                    : {}),
+            };
+        }
+        return {
+            version: 1,
+            activeProfile: profileName(raw.activeProfile),
+            profiles,
+        };
+    }
+    async resolve(name) {
+        const config = await this.read();
+        const selected = profileName(name ?? config.activeProfile);
+        const saved = Object.hasOwn(config.profiles, selected)
+            ? config.profiles[selected]
+            : undefined;
+        if (saved)
+            return saved;
+        if (selected === "default")
+            return { name: selected, environment: "production" };
+        throw new CliError("Unknown profile. Create it with zo login --profile <name>.");
+    }
+    async create(name, environment, signal) {
+        return withLock(join(this.directory, "config.lock"), async () => {
+            const config = await this.read();
+            throwIfInterrupted(signal);
+            const selected = profileName(name ?? config.activeProfile);
+            const existing = Object.hasOwn(config.profiles, selected)
+                ? config.profiles[selected]
+                : undefined;
+            if (existing &&
+                environment !== undefined &&
+                existing.environment !== environment)
+                throw new CliError("A profile's environment cannot change. Choose a new profile name.");
+            const profile = existing ?? {
+                name: selected,
+                environment: environment ?? "production",
+            };
+            config.profiles[selected] = profile;
+            await writePrivate(join(this.directory, "config.json"), config);
+            throwIfInterrupted(signal);
+            return profile;
+        }, undefined, signal);
+    }
+    async select(profile, selected, signal) {
+        workspaceId(selected);
+        await withLock(join(this.directory, "config.lock"), async () => {
+            const config = await this.read();
+            throwIfInterrupted(signal);
+            const saved = Object.hasOwn(config.profiles, profile.name)
+                ? config.profiles[profile.name]
+                : undefined;
+            if (saved && saved.environment !== profile.environment)
+                throw new CliError("Profile environment changed.");
+            config.profiles[profile.name] = { ...profile, workspaceId: selected };
+            await writePrivate(join(this.directory, "config.json"), config);
+            throwIfInterrupted(signal);
+        }, undefined, signal);
+    }
+}
+export function selectedWorkspace(profile, explicit, env = process.env) {
+    const selected = explicit ?? env.ZO_WORKSPACE_ID ?? profile.workspaceId;
+    if (!selected)
+        throw new CliError("Select a workspace with zo context use <workspace-id> or --workspace.");
+    return workspaceId(selected);
+}

package/dist/rpc.d.ts

@@ -0,0 +1,26 @@
+import { type JsonCallResult } from "@zocomputer/system-api";
+import { type JsonObject } from "@zocomputer/system-api/json";
+import { type InvocationContext, type LoadedCatalog } from "./catalog.ts";
+export interface RpcOptions {
+    action: string;
+    input?: string;
+    inputFile?: string;
+    version?: number;
+    query?: string;
+    idempotencyKey?: string;
+    preview?: boolean;
+    stdin?: AsyncIterable<Uint8Array | string>;
+}
+export type RpcResult = {
+    kind: "success";
+    response: JsonCallResult;
+} | {
+    kind: "preview";
+    workspaceId: string;
+    requestJson: string;
+};
+export declare function parseJsonObject(text: string, label?: string): JsonObject;
+export declare function inputJson(options: Pick<RpcOptions, "input" | "inputFile" | "stdin"> & {
+    signal?: AbortSignal;
+}): Promise<string>;
+export declare function runRpc(context: InvocationContext, options: RpcOptions, loadedCatalog?: LoadedCatalog): Promise<RpcResult>;