@zocomputer/cli 0.0.0-stage → 0.1.1

package/dist/rpc.js

@@ -0,0 +1,208 @@
+import { createReadStream } from "node:fs";
+import { addAbortSignal, Readable } from "node:stream";
+import { createClient, SystemAPIError, } from "@zocomputer/system-api";
+import { JsonError, JsonNumber, loadsJson, } from "@zocomputer/system-api/json";
+import { compileSchema, SchemaValidationError, SchemaDefinitionError, } from "@zocomputer/system-api/validation";
+import { apiBaseUrl, loadCatalog, resolveAction, } from "./catalog.js";
+import { CliError } from "./errors.js";
+import { workspaceId } from "./profiles.js";
+const MAX_INPUT_BYTES = 5 * 1024 * 1024;
+async function readInput(source, signal) {
+    const chunks = [];
+    let size = 0;
+    const stream = source instanceof Readable ? source : Readable.from(source);
+    if (signal)
+        addAbortSignal(signal, stream);
+    for await (const chunk of stream) {
+        const bytes = Buffer.from(chunk);
+        size += bytes.byteLength;
+        if (size > MAX_INPUT_BYTES)
+            throw new CliError("Input exceeds the 5 MiB request limit.");
+        chunks.push(bytes);
+    }
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks));
+    }
+    catch {
+        throw new CliError("Input must be valid UTF-8 JSON.");
+    }
+}
+export function parseJsonObject(text, label = "Input") {
+    let value;
+    try {
+        value = loadsJson(text, { maxBytes: MAX_INPUT_BYTES });
+    }
+    catch (error) {
+        if (error instanceof JsonError)
+            throw new CliError(`${label}: ${error.message}`, 2, error.code);
+        throw error;
+    }
+    if (value === null ||
+        typeof value !== "object" ||
+        Array.isArray(value) ||
+        value instanceof JsonNumber)
+        throw new CliError(`${label} must be a JSON object.`);
+    return value;
+}
+export async function inputJson(options) {
+    if (options.input !== undefined && options.inputFile !== undefined)
+        throw new CliError("Use either --input or --input-file.");
+    let text;
+    if (options.input !== undefined)
+        text = options.input;
+    else if (options.inputFile !== undefined) {
+        try {
+            text = await readInput(options.inputFile === "-"
+                ? (options.stdin ?? process.stdin)
+                : createReadStream(options.inputFile), options.signal);
+        }
+        catch (error) {
+            if (options.signal?.aborted)
+                throw new SystemAPIError({
+                    code: "interrupted",
+                    message: "Interrupted.",
+                    outcome: "not_started",
+                });
+            if (error instanceof CliError)
+                throw error;
+            throw new CliError("Could not read --input-file.");
+        }
+    }
+    else
+        text = "{}";
+    parseJsonObject(text);
+    return text;
+}
+function compileContract(schema) {
+    try {
+        return compileSchema(schema);
+    }
+    catch (error) {
+        if (error instanceof SchemaDefinitionError)
+            throw new SystemAPIError({
+                code: "invalid_definition",
+                message: "The published contract cannot be validated by this CLI. Update @zocomputer/cli or inspect the action with zo actions describe.",
+                outcome: "not_started",
+            });
+        throw error;
+    }
+}
+function validateInput(schema, value, label) {
+    try {
+        schema.validate(value, { applyDefaults: true });
+    }
+    catch (error) {
+        if (error instanceof SchemaValidationError)
+            throw new CliError(`${label} does not match the action contract: ${error.message}`, 2, label === "Input" ? "invalid_input" : "invalid_query");
+        throw error;
+    }
+}
+export async function runRpc(context, options, loadedCatalog) {
+    workspaceId(context.workspaceId);
+    if (context.signal?.aborted)
+        throw new SystemAPIError({
+            code: "interrupted",
+            message: "Interrupted.",
+            outcome: "not_started",
+        });
+    const input = await inputJson({ ...options, signal: context.signal });
+    const query = options.query === undefined
+        ? undefined
+        : parseJsonObject(options.query, "Query");
+    if (options.version !== undefined &&
+        (!Number.isInteger(options.version) ||
+            options.version < 1 ||
+            options.version > 2_147_483_647))
+        throw new CliError("--version must be a positive 32-bit integer.");
+    if (options.idempotencyKey !== undefined &&
+        !/^[\x21-\x7e]{1,255}$/.test(options.idempotencyKey))
+        throw new CliError("--idempotency-key must contain 1–255 visible ASCII characters without spaces.");
+    const { catalog, runtimeCatalog, authenticatedContext } = loadedCatalog ?? (await loadCatalog(context));
+    if (authenticatedContext.workspaceId !== context.workspaceId ||
+        catalog.selection?.workspace !== context.workspaceId ||
+        catalog.selection.catalog !== "scoped" ||
+        apiBaseUrl(authenticatedContext) !== apiBaseUrl(context))
+        throw new CliError("Invocation requires a scoped catalog for the selected workspace and environment.");
+    const contract = resolveAction(catalog, options.action, options.version);
+    if (contract.availability === "definition")
+        throw new CliError("This action is a definition without a callable contract in the selected workspace.", 2, "action_not_found");
+    if (options.idempotencyKey !== undefined &&
+        options.action.startsWith("zo.") &&
+        options.action !== "zo.function.invoke")
+        throw new CliError(`${options.action} does not accept an envelope idempotency key.`);
+    if (query !== undefined && contract.query === undefined)
+        throw new CliError(`${options.action} version ${contract.version} does not declare query options.`, 2, "invalid_query");
+    const inputSchema = compileContract(contract.input);
+    const outputSchema = compileContract(contract.output);
+    validateInput(inputSchema, parseJsonObject(input), "Input");
+    if (query !== undefined && contract.query !== undefined)
+        validateInput(compileContract(contract.query), query, "Query");
+    const wireOptions = JSON.stringify({
+        version: contract.version,
+        ...(options.idempotencyKey !== undefined
+            ? { idempotency_key: options.idempotencyKey }
+            : {}),
+    });
+    const requestJson = `{"action":${JSON.stringify(options.action)},"input":${input},"options":${wireOptions.slice(0, -1)}${options.query === undefined ? "" : `,"query":${options.query}`}}}`;
+    if (Buffer.byteLength(requestJson) > MAX_INPUT_BYTES)
+        throw new CliError("Request exceeds the 5 MiB request limit.");
+    if (context.signal?.aborted)
+        throw new SystemAPIError({
+            code: "interrupted",
+            message: "Interrupted.",
+            outcome: "not_started",
+        });
+    if (options.preview)
+        return { kind: "preview", workspaceId: context.workspaceId, requestJson };
+    // Snapshot calls may run for 210 seconds; leave time to receive that result.
+    const timeout = AbortSignal.timeout(240_000);
+    const signal = context.signal
+        ? AbortSignal.any([context.signal, timeout])
+        : timeout;
+    const client = createClient({
+        catalog: runtimeCatalog,
+        baseUrl: apiBaseUrl(context),
+        workspaceId: context.workspaceId,
+        accessToken: authenticatedContext.accessToken,
+        fetch: (url, init) => (context.fetch ?? fetch)(url, { ...init, signal }),
+        validator: {
+            validateRequestBody() { },
+            validateSuccessBody(_target, text) {
+                const body = loadsJson(text, { maxDepth: 34, maxNodes: null });
+                if (body === null ||
+                    typeof body !== "object" ||
+                    Array.isArray(body) ||
+                    body instanceof JsonNumber ||
+                    body.result === undefined)
+                    throw new Error("Response has no result.");
+                outputSchema.validate(body.result);
+            },
+        },
+    });
+    try {
+        return {
+            kind: "success",
+            response: await client.callJson(options.action, input, {
+                version: contract.version,
+                ...(options.query !== undefined ? { queryJson: options.query } : {}),
+                ...(options.idempotencyKey !== undefined
+                    ? { idempotencyKey: options.idempotencyKey }
+                    : {}),
+            }),
+        };
+    }
+    catch (error) {
+        if (signal.aborted && error instanceof SystemAPIError)
+            throw new SystemAPIError({
+                code: context.signal?.aborted
+                    ? "interrupted"
+                    : "execution_deadline_exceeded",
+                message: context.signal?.aborted
+                    ? "Interrupted."
+                    : "The request deadline expired.",
+                requestId: error.requestId,
+                outcome: error.outcome ?? "unknown",
+            });
+        throw error;
+    }
+}

package/dist/session.d.ts

@@ -0,0 +1,17 @@
+export interface Subject {
+    type: "user" | "agent" | "function" | "service" | "machine" | "service_account" | "workflow";
+    id: string;
+}
+export interface Workspace {
+    workspace_id: string;
+    name: string;
+    subject: Subject;
+}
+export interface Session {
+    credential_kind: "sign_in" | "bearer";
+    approving_subject: Subject | null;
+    expires_at: string | null;
+    access_token_expires_at: string;
+    workspaces: Workspace[];
+}
+export declare function parseSession(raw: unknown): Session;

package/dist/session.js

@@ -0,0 +1,48 @@
+import { CliError, record } from "./errors.js";
+function subject(raw) {
+    if (!record(raw) ||
+        (raw.type !== "user" &&
+            raw.type !== "agent" &&
+            raw.type !== "function" &&
+            raw.type !== "service" &&
+            raw.type !== "machine" &&
+            raw.type !== "service_account" &&
+            raw.type !== "workflow") ||
+        typeof raw.id !== "string")
+        throw new CliError("Invalid session subject.", 5, "invalid_response");
+    return { type: raw.type, id: raw.id };
+}
+export function parseSession(raw) {
+    if (!record(raw) ||
+        (raw.credential_kind !== "sign_in" && raw.credential_kind !== "bearer") ||
+        (raw.expires_at !== null &&
+            (typeof raw.expires_at !== "string" ||
+                !Number.isFinite(Date.parse(raw.expires_at)))) ||
+        typeof raw.access_token_expires_at !== "string" ||
+        !Number.isFinite(Date.parse(raw.access_token_expires_at)) ||
+        !Array.isArray(raw.workspaces) ||
+        raw.workspaces.length > 10)
+        throw new CliError("Invalid session response.", 5, "invalid_response");
+    const workspaces = raw.workspaces.map((entry) => {
+        if (!record(entry) ||
+            typeof entry.workspace_id !== "string" ||
+            !/^wsp_[A-Za-z0-9_-]+$/.test(entry.workspace_id) ||
+            typeof entry.name !== "string")
+            throw new CliError("Invalid session workspace.", 5, "invalid_response");
+        return {
+            workspace_id: entry.workspace_id,
+            name: entry.name,
+            subject: subject(entry.subject),
+        };
+    });
+    if (new Set(workspaces.map((entry) => entry.workspace_id)).size !==
+        workspaces.length)
+        throw new CliError("Duplicate session workspace.", 5, "invalid_response");
+    return {
+        credential_kind: raw.credential_kind,
+        approving_subject: raw.approving_subject === null ? null : subject(raw.approving_subject),
+        expires_at: raw.expires_at,
+        access_token_expires_at: raw.access_token_expires_at,
+        workspaces,
+    };
+}

package/dist/storage.d.ts

@@ -0,0 +1,10 @@
+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 class PrivateWriteDurabilityError extends CliError {
+    constructor();
+}
+export declare function writePrivate(path: string, value: unknown): Promise<void>;
+export declare function removePrivate(path: string): Promise<void>;
+export declare function withLock<T>(path: string, work: () => Promise<T>, timeoutMs?: number, signal?: AbortSignal): Promise<T>;

package/dist/storage.js

@@ -0,0 +1,209 @@
+import { constants } from "node:fs";
+import { lstat, mkdir, open, readdir, rename, unlink } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { dirname, join, resolve, parse } from "node:path";
+import { homedir } from "node:os";
+import { setTimeout as delay } from "node:timers/promises";
+import { CliError, errorCode, record, throwIfInterrupted } from "./errors.js";
+export function configDirectory(env = process.env) {
+    const base = env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+    if (!base.startsWith("/"))
+        throw new CliError("XDG_CONFIG_HOME must be an absolute path.");
+    return join(base, "zo", "cli");
+}
+export async function privateDirectory(path) {
+    const absolute = resolve(path);
+    let current = parse(absolute).root;
+    for (const part of absolute.slice(current.length).split("/")) {
+        current = join(current, part);
+        try {
+            await mkdir(current, { mode: 0o700 });
+            await syncDirectory(dirname(current));
+        }
+        catch (error) {
+            if (errorCode(error) !== "EEXIST")
+                throw error;
+        }
+        const stat = await lstat(current);
+        if (stat.uid !== 0 && stat.uid !== process.getuid?.())
+            throw new CliError("Credential path parents must be owned by you or root.");
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new CliError("Credential paths must not contain symlinks.");
+        if ((stat.mode & 0o022) !== 0 && (stat.mode & 0o1000) === 0)
+            throw new CliError("Credential path parents must not be writable by other users.");
+    }
+    const stat = await lstat(absolute);
+    if (stat.uid !== process.getuid?.() || (stat.mode & 0o077) !== 0)
+        throw new CliError("Credential directories must be owned by you with mode 0700.");
+}
+async function checkedFile(path) {
+    const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const stat = await file.stat();
+    if (!stat.isFile() ||
+        stat.uid !== process.getuid?.() ||
+        (stat.mode & 0o077) !== 0 ||
+        stat.nlink > 1) {
+        await file.close();
+        throw new CliError("Credential files must be private, regular files owned by you.");
+    }
+    return file;
+}
+export async function readPrivate(path) {
+    let file;
+    try {
+        file = await checkedFile(path);
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    try {
+        if ((await file.stat()).size > 1_048_576)
+            throw new CliError("Local configuration is too large.", 2, "invalid_local_data");
+        return JSON.parse(await file.readFile("utf8"));
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            throw new CliError("Local configuration is malformed.", 2, "invalid_local_data");
+        throw error;
+    }
+    finally {
+        await file.close();
+    }
+}
+async function checkExistingFile(path) {
+    try {
+        const file = await checkedFile(path);
+        await file.close();
+        return true;
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+export class PrivateWriteDurabilityError extends CliError {
+    constructor() {
+        super("The local file was replaced, but its directory could not be synced. Saved credentials were retained; retry before removing local files.", 5, "local_durability_failed");
+    }
+}
+export async function writePrivate(path, value) {
+    await privateDirectory(dirname(path));
+    await checkExistingFile(path);
+    const temporary = join(dirname(path), `.${randomUUID()}.tmp`);
+    const file = await open(temporary, constants.O_WRONLY |
+        constants.O_CREAT |
+        constants.O_EXCL |
+        constants.O_NOFOLLOW, 0o600);
+    try {
+        await file.writeFile(JSON.stringify(value));
+        await file.sync();
+        await file.close();
+        await rename(temporary, path);
+        try {
+            await syncDirectory(dirname(path));
+        }
+        catch {
+            // The replacement is already visible. Callers must retain its tokens
+            // even though a crash could still lose the directory update.
+            throw new PrivateWriteDurabilityError();
+        }
+    }
+    finally {
+        await file.close();
+        await unlink(temporary).catch((error) => {
+            if (errorCode(error) !== "ENOENT")
+                throw error;
+        });
+    }
+}
+async function syncDirectory(path) {
+    const directory = await open(path, constants.O_RDONLY);
+    try {
+        await directory.sync();
+    }
+    finally {
+        await directory.close();
+    }
+}
+export async function removePrivate(path) {
+    if (!(await checkExistingFile(path)))
+        return;
+    await unlink(path);
+    await syncDirectory(dirname(path));
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return errorCode(error) !== "ESRCH";
+    }
+}
+// Bakery tickets avoid replacing a shared stale lock: each process removes only
+// its own UUID path. A live owner is never evicted by elapsed time.
+export async function withLock(path, work, timeoutMs = 30_000, signal) {
+    throwIfInterrupted(signal);
+    await privateDirectory(path);
+    const name = `${process.pid}-${randomUUID()}.json`;
+    const own = join(path, name);
+    const start = performance.now();
+    const claims = async () => {
+        const found = [];
+        for (const entry of await readdir(path)) {
+            if (!entry.endsWith(".json"))
+                continue;
+            const claim = await readPrivate(join(path, entry));
+            if (claim === undefined)
+                continue;
+            if (!record(claim) ||
+                !Number.isSafeInteger(claim.pid) ||
+                Number(claim.pid) <= 0 ||
+                !Number.isSafeInteger(claim.ticket) ||
+                Number(claim.ticket) < 0)
+                throw new CliError("Malformed credential lock.");
+            if (alive(Number(claim.pid)))
+                found.push([
+                    entry,
+                    { pid: Number(claim.pid), ticket: Number(claim.ticket) },
+                ]);
+            else
+                await removePrivate(join(path, entry)).catch((error) => {
+                    if (errorCode(error) !== "ENOENT")
+                        throw error;
+                });
+        }
+        return found;
+    };
+    await writePrivate(own, { pid: process.pid, ticket: 0 });
+    try {
+        throwIfInterrupted(signal);
+        const ticket = Math.max(0, ...(await claims()).map(([, claim]) => claim.ticket)) + 1;
+        await writePrivate(own, { pid: process.pid, ticket });
+        for (;;) {
+            throwIfInterrupted(signal);
+            const blocked = (await claims()).some(([entry, claim]) => entry !== name &&
+                (claim.ticket === 0 ||
+                    claim.ticket < ticket ||
+                    (claim.ticket === ticket && entry < name)));
+            throwIfInterrupted(signal);
+            if (!blocked)
+                return await work();
+            if (performance.now() - start >= timeoutMs)
+                throw new CliError("Timed out waiting for another Zo process. Try again after it finishes.", 3, "credential_locked");
+            try {
+                await delay(20, undefined, { signal });
+            }
+            catch (error) {
+                throwIfInterrupted(signal);
+                throw error;
+            }
+        }
+    }
+    finally {
+        await removePrivate(own);
+    }
+}

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "@zocomputer/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Public Zo command line client",
+  "bin": {
+    "zo": "./dist/main.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": "^22.23.4 || ^24.22.1 || ^26.13.0"
+  },
+  "dependencies": {
+    "@zocomputer/system-api": "0.1.1"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}