@vendoai/vendo 0.4.0

package/dist/cli/cloud/deploy.js

@@ -0,0 +1,187 @@
+import { appStore, createStore, grantStore, } from "@vendoai/store";
+import { join } from "node:path";
+import { option, options as repeatedOptions } from "./args.js";
+import { CloudError, resolveCloudBaseUrl } from "./client.js";
+import { commandContext, } from "./command.js";
+import { errorMessage, formatTable, printJson } from "./output.js";
+export async function readLocalProject(options = {}) {
+    const store = options.storeFactory?.() ?? createStore({
+        dataDir: join(options.cwd ?? process.cwd(), ".vendo/data"),
+    });
+    try {
+        await store.ensureSchema();
+        const driver = store.raw();
+        const subjectRows = await driver.query("SELECT DISTINCT subject FROM vendo_apps ORDER BY subject ASC");
+        const subjects = subjectRows.rows.map((row) => row.subject);
+        if (subjects.length === 0)
+            throw new Error("No local Vendo apps found in .vendo/data");
+        let subject = options.subject;
+        if (subject === undefined) {
+            if (subjects.length > 1) {
+                throw new Error(`Multiple local Vendo subjects found: ${subjects.join(", ")}. Pass --subject <subject>.`);
+            }
+            subject = subjects[0];
+        }
+        else if (!subjects.includes(subject)) {
+            throw new Error(`Subject ${subject} was not found in the local Vendo store`);
+        }
+        const appIds = await driver.query("SELECT id FROM vendo_apps WHERE subject = $1 ORDER BY created_at ASC, id ASC", [subject]);
+        const apps = (await Promise.all(appIds.rows.map(async ({ id }) => {
+            const row = await appStore(store).get(id);
+            if (row === null || row.subject !== subject)
+                return null;
+            return { doc: row.doc, enabled: row.enabled };
+        }))).filter((row) => row !== null);
+        const grantIds = await driver.query(`SELECT id FROM vendo_grants
+       WHERE subject = $1 AND source = 'automation'
+         AND revoked_at IS NULL AND (expires_at IS NULL OR expires_at > now())
+       ORDER BY granted_at ASC, id ASC`, [subject]);
+        const grants = (await Promise.all(grantIds.rows.map(({ id }) => grantStore(store).get(id))))
+            .filter((grant) => grant !== null);
+        return { subject, apps, grants };
+    }
+    finally {
+        await store.close();
+    }
+}
+function machineOptions(args, context) {
+    return {
+        auth: "key",
+        apiKey: option(args, "--key"),
+        apiUrl: option(args, "--api-url"),
+        env: context.env,
+    };
+}
+function secretValues(args) {
+    const values = new Map();
+    for (const pair of repeatedOptions(args, "--secret")) {
+        const separator = pair.indexOf("=");
+        if (separator <= 0)
+            throw new Error("--secret must use NAME=VALUE");
+        values.set(pair.slice(0, separator), pair.slice(separator + 1));
+    }
+    return values;
+}
+function selectedApps(project, args) {
+    const requested = [...new Set(repeatedOptions(args, "--app"))];
+    if (requested.length === 0) {
+        const selected = project.apps.filter((app) => app.enabled && app.doc.trigger !== undefined);
+        if (selected.length === 0)
+            throw new Error("No enabled local automations found");
+        return selected;
+    }
+    const requestedIds = new Set(requested);
+    for (const appId of requested) {
+        const app = project.apps.find((candidate) => candidate.doc.id === appId);
+        if (app === undefined)
+            throw new Error(`App ${appId} was not found for subject ${project.subject}`);
+        if (app.doc.trigger === undefined)
+            throw new Error(`App ${appId} is not an automation`);
+    }
+    return project.apps.filter((app) => requestedIds.has(app.doc.id));
+}
+function warnUnsupportedFnSteps(context, apps) {
+    for (const app of apps) {
+        const run = app.doc.trigger?.run;
+        if (run?.kind === "steps" && run.steps.some((step) => step.tool.startsWith("fn:"))) {
+            context.output.error(`WARNING: Automation ${app.doc.id} has fn: steps that target the app's machine, which is unreachable from hosted sandboxes in v1; those steps will fail/park when fired hosted.`);
+        }
+    }
+}
+function deployResponse(value) {
+    if (typeof value !== "object" || value === null)
+        throw new Error("Vendo Cloud returned an invalid deploy response");
+    const result = value;
+    if (typeof result.org?.id !== "string"
+        || typeof result.org.slug !== "string"
+        || typeof result.instance?.status !== "string"
+        || typeof result.applied?.apps !== "number"
+        || typeof result.applied.grants !== "number"
+        || typeof result.applied.secrets !== "number"
+        || !Array.isArray(result.webhooks)
+        || result.webhooks.some((webhook) => typeof webhook.app_id !== "string"
+            || typeof webhook.source !== "string"
+            || typeof webhook.url !== "string")) {
+        throw new Error("Vendo Cloud returned an invalid deploy response");
+    }
+    return result;
+}
+function printDeploySummary(context, response) {
+    const lines = [
+        `Vendo Cloud deploy: ${response.org.slug} (${response.instance.status})`,
+        "",
+        formatTable(["APPLIED", "COUNT"], [
+            ["apps", String(response.applied.apps)],
+            ["grants", String(response.applied.grants)],
+            ["secrets", String(response.applied.secrets)],
+        ]),
+        "",
+    ];
+    if (response.webhooks.length === 0) {
+        lines.push("Webhooks: none");
+    }
+    else {
+        lines.push(formatTable(["AUTOMATION", "SOURCE", "WEBHOOK URL"], response.webhooks.map((webhook) => [
+            webhook.app_id,
+            webhook.source,
+            webhook.url,
+        ])));
+    }
+    context.output.log(lines.join("\n"));
+}
+export async function runDeploy(args, options = {}) {
+    const context = commandContext(options);
+    try {
+        const project = await (options.localProjectReader ?? readLocalProject)({
+            subject: option(args, "--subject"),
+            cwd: options.cwd ?? process.cwd(),
+        });
+        const apps = selectedApps(project, args);
+        warnUnsupportedFnSteps(context, apps);
+        const appIds = new Set(apps.map((app) => app.doc.id));
+        const grants = project.grants.filter((grant) => grant.subject === project.subject
+            && grant.source === "automation"
+            && grant.appId !== undefined
+            && appIds.has(grant.appId));
+        const provided = secretValues(args);
+        const referenced = new Set();
+        for (const app of apps) {
+            for (const name of app.doc.secrets ?? []) {
+                referenced.add(name);
+                if (!provided.has(name)) {
+                    context.output.error(`Automation ${app.doc.id} references missing secret ${name}; pass --secret ${name}=VALUE`);
+                }
+            }
+        }
+        const secrets = [...referenced]
+            .filter((name) => provided.has(name))
+            .map((name) => ({ name, value: provided.get(name) }));
+        const requestOptions = machineOptions(args, context);
+        if (secrets.length > 0 && new URL(resolveCloudBaseUrl(requestOptions)).protocol !== "https:") {
+            throw new Error("Deploying secret values requires an HTTPS Vendo Cloud URL");
+        }
+        const response = deployResponse(await context.fetcher("/api/v1/hosted/deploy", {
+            ...requestOptions,
+            method: "POST",
+            body: {
+                apps: apps.map((app) => ({ doc: app.doc, enabled: app.enabled })),
+                grants,
+                secrets,
+            },
+        }));
+        if (args.includes("--json"))
+            printJson(context.output, response);
+        else
+            printDeploySummary(context, response);
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof CloudError && error.code === "cloud-required") {
+            context.output.error("This key's org needs a Cloud plan (cloud-required).");
+        }
+        else {
+            context.output.error(errorMessage(error));
+        }
+        return 1;
+    }
+}

package/dist/cli/cloud/device-login.d.ts

@@ -0,0 +1,32 @@
+import { type Output, type TelemetryOptions } from "../shared.js";
+export interface DeviceLoginOptions {
+    output?: Output;
+    fetchImpl?: typeof fetch;
+    env?: Record<string, string | undefined>;
+    /** Where .env.local lives (default: the current working directory). */
+    root?: string;
+    /** Injectable pacing seam — tests run the ceremony in microseconds. */
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    /** TTY seam — a watching human gets the browser opened for them; a non-TTY
+        (agent) caller keeps the URL + code contract untouched. */
+    isTty?: boolean;
+    openBrowser?: (url: string) => void;
+    /** init runs the ceremony inline and picks the key up in the same run —
+        it suppresses the standalone "re-run `vendo init`" tail. */
+    rerunHint?: boolean;
+    /** Where ~/.vendo lives (default: the home directory) — the pending-claim
+        file that lets a fresh run resume a still-open ceremony (#479). */
+    home?: string;
+}
+/**
+ * `vendo login` — the top-level command surface: the identical ceremony
+ * wrapped in one `command_run` row (command "login", TELEMETRY.md). The
+ * ceremony's other two callers stay untracked here: `vendo cloud
+ * device-login` (the alias) calls runDeviceLogin directly, and init's
+ * embedded step already tracks itself as "cloud-init".
+ */
+export declare function runLoginCommand(args: string[], options?: DeviceLoginOptions & {
+    telemetry?: TelemetryOptions;
+}): Promise<number>;
+export declare function runDeviceLogin(args: string[], options?: DeviceLoginOptions): Promise<number>;

package/dist/cli/cloud/device-login.js

@@ -0,0 +1,259 @@
+import { execFile } from "node:child_process";
+import { join } from "node:path";
+import { option, positionals } from "./args.js";
+import { isVendoKey, resolveCloudBaseUrl } from "./client.js";
+import { errorMessage, printJson } from "./output.js";
+import { deletePendingClaim, readPendingClaim, writePendingClaim } from "./pending-claim.js";
+import { upsertEnvLocal } from "../cloud-init.js";
+import { browserOpenCommand } from "../playground.js";
+import { CLI_VERSION, consoleOutput, withCommandRun } from "../shared.js";
+/**
+ * `vendo login` (alias: `vendo cloud device-login`) — the auth.md
+ * user-claimed flow end to end (https://vendo.run/auth.md): open a claim on
+ * the console, show the human the pairing code + approval URL (a TTY gets
+ * the browser opened too), poll the RFC 8628 token endpoint, and land the
+ * minted VENDO_API_KEY in .env.local — exactly where init's --cloud-key flag
+ * and the interactive ceremony put it, so a re-run of `vendo init` picks it
+ * up with no key ever pasted or printed.
+ *
+ * The token endpoint speaks RFC 8628 §3.5 (top-level `error` string), which
+ * the console-envelope-shaped cloudFetch would flatten to http-400 — so this
+ * command talks to both endpoints with a raw (injectable) fetch instead.
+ */
+const CLAIM_PATH = "/api/v1/agent/claim";
+const TOKEN_PATH = "/api/v1/oauth/token";
+const CLAIM_GRANT_TYPE = "urn:workos:agent-auth:grant-type:claim";
+function defaultOpenBrowser(url) {
+    const { command, args } = browserOpenCommand(process.platform, url);
+    execFile(command, args, () => undefined); // best-effort: the printed URL is the fallback
+}
+function ceremonyFrom(value) {
+    const body = value;
+    if (typeof body?.claim_token !== "string"
+        || typeof body.user_code !== "string"
+        || typeof body.verification_uri !== "string"
+        || typeof body.expires_in !== "number"
+        || typeof body.interval !== "number") {
+        throw new Error("Vendo Cloud returned an invalid claim ceremony");
+    }
+    return body;
+}
+async function postJson(fetchImpl, url, contentType, body) {
+    const response = await fetchImpl(url, {
+        method: "POST",
+        headers: {
+            accept: "application/json",
+            "content-type": contentType,
+            "user-agent": `vendo-cli/${CLI_VERSION}`,
+        },
+        body,
+    });
+    const text = await response.text();
+    let parsed;
+    try {
+        parsed = text.length === 0 ? undefined : JSON.parse(text);
+    }
+    catch {
+        parsed = text;
+    }
+    return { status: response.status, body: parsed };
+}
+/**
+ * `vendo login` — the top-level command surface: the identical ceremony
+ * wrapped in one `command_run` row (command "login", TELEMETRY.md). The
+ * ceremony's other two callers stay untracked here: `vendo cloud
+ * device-login` (the alias) calls runDeviceLogin directly, and init's
+ * embedded step already tracks itself as "cloud-init".
+ */
+export async function runLoginCommand(args, options = {}) {
+    return withCommandRun({
+        command: "login",
+        // Where the key lands is the project the ceremony is for.
+        root: options.root ?? process.cwd(),
+        ...(options.telemetry === undefined ? {} : { telemetry: options.telemetry }),
+    }, () => runDeviceLogin(args, options));
+}
+export async function runDeviceLogin(args, options = {}) {
+    const output = options.output ?? consoleOutput;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const now = options.now ?? Date.now;
+    const base = resolveCloudBaseUrl({
+        apiUrl: option(args, "--api-url"),
+        env: options.env ?? process.env,
+    });
+    // `--wait <seconds>` (#479): the MAX wall-clock THIS invocation polls before
+    // giving up resumably — independent of, and capped by, the claim deadline.
+    // Absent: unchanged, block until the claim deadline (~10 min). `--wait 0`:
+    // one immediate poll, then exit resumably if still pending. An invalid value
+    // is ignored here (the `vendo login` entry validates it up front).
+    const waitRaw = option(args, "--wait");
+    const waitSeconds = waitRaw !== undefined && /^\d+$/.test(waitRaw) ? Number(waitRaw) : undefined;
+    const waitMs = waitSeconds === undefined ? undefined : waitSeconds * 1000;
+    const pendingHome = options.home === undefined ? {} : { home: options.home };
+    try {
+        // A still-open claim from a dead process (#479): resume polling it so the
+        // human's late approval — against the code they were already shown —
+        // still lands the key. An expired or unreadable file is discarded (a
+        // fresh ceremony overwrites it below).
+        const pending = await readPendingClaim(pendingHome);
+        const resume = pending !== null && pending.api_url === base && pending.expires_at > now()
+            ? pending
+            : null;
+        let claimToken;
+        let deadline;
+        let intervalMs;
+        let root;
+        let userCode;
+        let verificationUriComplete;
+        if (resume !== null) {
+            output.log(`Resuming pending approval — code ${resume.user_code}, approve at ${resume.verification_uri_complete}`);
+            output.log(`Waiting for approval (the code expires in ${Math.max(1, Math.round((resume.expires_at - now()) / 60_000))} minutes)…`);
+            claimToken = resume.claim_token;
+            deadline = resume.expires_at;
+            intervalMs = Math.max(resume.interval, 1) * 1000;
+            // The key lands where the ORIGINAL run intended, not where the resume runs.
+            root = resume.cwd;
+            userCode = resume.user_code;
+            verificationUriComplete = resume.verification_uri_complete;
+        }
+        else {
+            // Optional email hint — shown to the human on the approval page.
+            const email = option(args, "--email") ?? positionals(args, ["--api-url", "--email", "--wait"])[0];
+            const claim = await postJson(fetchImpl, `${base}${CLAIM_PATH}`, "application/json", JSON.stringify(email === undefined ? {} : { login_hint: email }));
+            if (claim.status !== 200) {
+                const envelope = claim.body;
+                throw new Error(typeof envelope?.error?.message === "string"
+                    ? envelope.error.message
+                    : `Vendo Cloud could not open a claim (${claim.status})`);
+            }
+            const ceremony = ceremonyFrom(claim.body);
+            const approvalUrl = ceremony.verification_uri_complete ?? ceremony.verification_uri;
+            output.log("Vendo Cloud device login — ask your human to approve this request:");
+            output.log(`  1. Open ${approvalUrl}`);
+            output.log(`  2. Confirm the code: ${ceremony.user_code}`);
+            const tty = options.isTty ?? (process.stdout.isTTY === true);
+            if (tty) {
+                output.log("Opening your browser… (approve there, then come back here)");
+                (options.openBrowser ?? defaultOpenBrowser)(approvalUrl);
+            }
+            output.log(`Waiting for approval (the code expires in ${Math.round(ceremony.expires_in / 60)} minutes)…`);
+            claimToken = ceremony.claim_token;
+            deadline = now() + ceremony.expires_in * 1000;
+            intervalMs = Math.max(ceremony.interval, 1) * 1000;
+            root = options.root ?? process.cwd();
+            userCode = ceremony.user_code;
+            verificationUriComplete = approvalUrl;
+            // Persist the ceremony so a fresh run can resume it if this process
+            // dies mid-poll. Deleted on redemption/denial/expiry; deliberately left
+            // in place on transient errors and interrupts.
+            await writePendingClaim({
+                claim_token: claimToken,
+                user_code: ceremony.user_code,
+                verification_uri_complete: approvalUrl,
+                expires_at: deadline,
+                interval: ceremony.interval,
+                api_url: base,
+                cwd: root,
+            }, pendingHome);
+        }
+        const pollBody = new URLSearchParams({
+            grant_type: CLAIM_GRANT_TYPE,
+            claim_token: claimToken,
+        }).toString();
+        if (waitMs !== undefined) {
+            output.log(`This call polls for up to ${waitSeconds}s — re-run \`vendo login\` to continue this same request.`);
+        }
+        const pollOnce = async () => {
+            const poll = await postJson(fetchImpl, `${base}${TOKEN_PATH}`, "application/x-www-form-urlencoded", pollBody);
+            if (poll.status === 200) {
+                const key = poll.body?.access_token;
+                if (typeof key !== "string" || !isVendoKey(key)) {
+                    throw new Error("Vendo Cloud returned an invalid credential");
+                }
+                await upsertEnvLocal(root, "VENDO_API_KEY", key);
+                await deletePendingClaim(pendingHome);
+                // Never print the key itself — .env.local is the hand-off, last4 the
+                // receipt. A resumed run names the full path: it may differ from cwd.
+                output.log(`Approved — wrote VENDO_API_KEY (…${key.slice(-4)}) to ${resume !== null ? join(root, ".env.local") : ".env.local"}.`);
+                if (options.rerunHint !== false) {
+                    output.log("Re-run `vendo init` to finish wiring (it picks the key up from .env.local).");
+                }
+                printJson(output, { deviceLogin: true, wroteEnvLocal: true, keyLast4: key.slice(-4) });
+                return "approved";
+            }
+            const error = poll.body?.error;
+            if (error === "authorization_pending")
+                return "pending";
+            if (error === "slow_down")
+                return "slow_down"; // RFC 8628 §3.5
+            if (error === "expired_token") {
+                await deletePendingClaim(pendingHome);
+                throw new Error("The code expired before it was approved; run `vendo login` again.");
+            }
+            if (error === "access_denied") {
+                await deletePendingClaim(pendingHome);
+                throw new Error("Your human denied the request — no key was minted.");
+            }
+            // Any other token error is terminal for THIS claim (invalid_grant =
+            // consumed/denied server-side; single-use means it can never succeed
+            // again). Delete the pending file so the next `vendo login` opens a
+            // fresh claim instead of resuming into the same error forever — the
+            // exact trap a live install hit.
+            await deletePendingClaim(pendingHome);
+            const description = poll.body?.error_description;
+            throw new Error(typeof description === "string"
+                ? description
+                : `Vendo Cloud token polling failed (${typeof error === "string" ? error : poll.status})`);
+        };
+        // Budget still pending: leave the claim file in place and exit 0 — pending
+        // is not a failure. A re-run resumes this same claim (#479).
+        const pendingExit = () => {
+            output.log(`Still waiting on approval — code ${userCode}. Re-run \`vendo login\` to resume (it continues this same request).`);
+            printJson(output, {
+                deviceLogin: true,
+                pending: true,
+                userCode,
+                verificationUriComplete,
+            });
+            return 0;
+        };
+        if (waitMs === undefined) {
+            // No budget: block to the claim deadline — unchanged TTY behavior.
+            while (now() < deadline) {
+                await sleep(intervalMs);
+                const result = await pollOnce();
+                if (result === "approved")
+                    return 0;
+                if (result === "slow_down")
+                    intervalMs += 5000;
+            }
+            await deletePendingClaim(pendingHome);
+            throw new Error("The code expired before it was approved; run `vendo login` again.");
+        }
+        // Bounded budget: poll immediately, then pace by interval, stopping at
+        // min(now+wait, deadline). `--wait 0` polls exactly once.
+        const pollDeadline = Math.min(deadline, now() + waitMs);
+        while (true) {
+            const result = await pollOnce();
+            if (result === "approved")
+                return 0;
+            if (result === "slow_down")
+                intervalMs += 5000;
+            if (now() >= deadline) {
+                await deletePendingClaim(pendingHome);
+                throw new Error("The code expired before it was approved; run `vendo login` again.");
+            }
+            if (now() >= pollDeadline)
+                return pendingExit();
+            // Cap the wait to the remaining budget so a small `--wait` (e.g. 1s
+            // against the default 5s interval) exits within its bound instead of
+            // sleeping a whole interval past it.
+            await sleep(Math.min(intervalMs, pollDeadline - now()));
+        }
+    }
+    catch (error) {
+        output.error(errorMessage(error));
+        return 1;
+    }
+}

package/dist/cli/cloud/index.d.ts

@@ -0,0 +1,5 @@
+import { type CloudAuthOptions } from "./auth.js";
+import type { CloudCommandOptions } from "./command.js";
+import { type DeviceLoginOptions } from "./device-login.js";
+export type RunCloudOptions = CloudCommandOptions & CloudAuthOptions & DeviceLoginOptions;
+export declare function runCloud(args: string[], options?: RunCloudOptions): Promise<number>;

package/dist/cli/cloud/index.js

@@ -0,0 +1,59 @@
+import { runLogin, runLogout, runWhoami } from "./auth.js";
+import { runDeviceLogin } from "./device-login.js";
+import { runKeys } from "./keys.js";
+import { runInvite, runMembers } from "./members.js";
+import { consoleOutput } from "../shared.js";
+import { runOrgs, runUsage } from "./read.js";
+const CLOUD_HELP = `vendo cloud — Vendo Cloud API client
+
+Usage: vendo cloud <command> [options]
+
+User commands:
+  device-login [EMAIL]                  alias of \`vendo login\` — the auth.md user-claimed
+                                        flow: your human approves a code in the browser;
+                                        the minted VENDO_API_KEY is written to .env.local
+                                        (never printed)
+  login EMAIL                           Fallback: send an email OTP (6-10 digits) and prompt for it
+  login --token <jwt>                   Fallback: store an access token directly
+  logout                               Delete the stored cloud session
+  whoami [--token <jwt>]                List organizations for the current user
+  orgs                                  List organizations
+  keys list --project <id>              List API keys
+  keys create --project <id> --name <name>  Create an API key
+  keys revoke --project <id> --id <keyId>   Revoke an API key
+  usage --project <id> [--days <days>]  Show usage (default 30 days)
+  members --org <id>                   List organization members
+  invite --org <id> --email <email> --role <admin|member>
+
+Global options:
+  --api-url <url>  Override VENDO_CLOUD_URL / https://console.vendo.run
+  --json           JSON output
+`;
+export async function runCloud(args, options = {}) {
+    const [command, ...commandArgs] = args;
+    const output = options.output ?? consoleOutput;
+    if (command === undefined || command === "--help" || command === "-h" || command === "help") {
+        output.log(CLOUD_HELP);
+        return 0;
+    }
+    if (command === "login")
+        return runLogin(commandArgs, options);
+    if (command === "device-login")
+        return runDeviceLogin(commandArgs, options);
+    if (command === "logout")
+        return runLogout(commandArgs, options);
+    if (command === "whoami")
+        return runWhoami(commandArgs, options);
+    if (command === "orgs")
+        return runOrgs(commandArgs, options);
+    if (command === "keys")
+        return runKeys(commandArgs, options);
+    if (command === "usage")
+        return runUsage(commandArgs, options);
+    if (command === "members")
+        return runMembers(commandArgs, options);
+    if (command === "invite")
+        return runInvite(commandArgs, options);
+    output.error(`Unknown cloud command: ${command}\n\n${CLOUD_HELP}`);
+    return 1;
+}

package/dist/cli/cloud/keys.d.ts

@@ -0,0 +1,2 @@
+import { type CloudCommandOptions } from "./command.js";
+export declare function runKeys(args: string[], options?: CloudCommandOptions): Promise<number>;

package/dist/cli/cloud/keys.js

@@ -0,0 +1,31 @@
+import { option } from "./args.js";
+import { resolveProjectId, runCommand, userOptions, } from "./command.js";
+export function runKeys(args, options = {}) {
+    return runCommand(options, async (context) => {
+        const [action] = args;
+        if (!action || !["list", "create", "revoke"].includes(action)) {
+            throw new Error("Usage: vendo cloud keys <list|create|revoke> --project <id>");
+        }
+        const projectId = await resolveProjectId(args, context);
+        const root = `/api/v1/projects/${encodeURIComponent(projectId)}/keys`;
+        if (action === "list")
+            return context.fetcher(root, userOptions(args, context));
+        if (action === "create") {
+            const name = option(args, "--name");
+            if (!name)
+                throw new Error("Key creation requires --name <name>");
+            return context.fetcher(root, {
+                ...userOptions(args, context),
+                method: "POST",
+                body: { name },
+            });
+        }
+        const keyId = option(args, "--id");
+        if (!keyId)
+            throw new Error("Key revocation requires --id <keyId>");
+        return context.fetcher(`${root}/${encodeURIComponent(keyId)}/revoke`, {
+            ...userOptions(args, context),
+            method: "POST",
+        });
+    });
+}

package/dist/cli/cloud/members.d.ts

@@ -0,0 +1,3 @@
+import { type CloudCommandOptions } from "./command.js";
+export declare function runMembers(args: string[], options?: CloudCommandOptions): Promise<number>;
+export declare function runInvite(args: string[], options?: CloudCommandOptions): Promise<number>;

package/dist/cli/cloud/members.js

@@ -0,0 +1,25 @@
+import { option } from "./args.js";
+import { resolveOrgId, runCommand, userOptions, } from "./command.js";
+export function runMembers(args, options = {}) {
+    return runCommand(options, async (context) => {
+        const orgId = await resolveOrgId(args, context);
+        return context.fetcher(`/api/v1/orgs/${encodeURIComponent(orgId)}/members`, userOptions(args, context));
+    });
+}
+export function runInvite(args, options = {}) {
+    return runCommand(options, async (context) => {
+        const email = option(args, "--email");
+        const role = option(args, "--role");
+        if (!email)
+            throw new Error("Inviting a member requires --email <email>");
+        if (role !== "admin" && role !== "member") {
+            throw new Error("Inviting a member requires --role <admin|member>");
+        }
+        const orgId = await resolveOrgId(args, context);
+        return context.fetcher(`/api/v1/orgs/${encodeURIComponent(orgId)}/invites`, {
+            ...userOptions(args, context),
+            method: "POST",
+            body: { email, role },
+        });
+    });
+}

package/dist/cli/cloud/output.d.ts

@@ -0,0 +1,4 @@
+import type { Output } from "../shared.js";
+export declare function printJson(output: Output, value: unknown): void;
+export declare function formatTable(headers: string[], rows: string[][]): string;
+export declare function errorMessage(error: unknown): string;

package/dist/cli/cloud/output.js

@@ -0,0 +1,12 @@
+export function printJson(output, value) {
+    output.log(JSON.stringify(value, null, 2));
+}
+export function formatTable(headers, rows) {
+    const widths = headers.map((header, column) => Math.max(header.length, ...rows.map((row) => row[column]?.length ?? 0)));
+    return [headers, ...rows]
+        .map((row) => row.map((cell, column) => cell.padEnd(widths[column] ?? cell.length)).join("  ").trimEnd())
+        .join("\n");
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : "Vendo Cloud request failed";
+}

package/dist/cli/cloud/pending-claim.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The pending-claim file (#479): a `vendo login` claim outlives the process
+ * that opened it. Coding agents' processes often live exactly one turn — if
+ * the poller dies and the human approves afterwards, the approval succeeds
+ * server-side but the claim_token existed only in the dead process's memory.
+ * Persisting the claim lets a fresh `vendo login` resume polling the SAME
+ * claim, so the late approval still lands the key.
+ */
+export interface PendingClaim {
+    claim_token: string;
+    user_code: string;
+    verification_uri_complete: string;
+    /** Unix timestamp in milliseconds — computed from the ceremony's expires_in. */
+    expires_at: number;
+    /** Poll pacing in seconds (RFC 8628). */
+    interval: number;
+    /** The console the claim was opened against — resume only on a match. */
+    api_url: string;
+    /** Where the original run intended .env.local to land. */
+    cwd: string;
+}
+export interface PendingClaimOptions {
+    home?: string;
+}
+/** An unreadable or malformed file reads as "no pending claim" — the caller
+    discards it by opening (and persisting) a fresh ceremony. */
+export declare function readPendingClaim(options?: PendingClaimOptions): Promise<PendingClaim | null>;
+export declare function writePendingClaim(claim: PendingClaim, options?: PendingClaimOptions): Promise<void>;
+export declare function deletePendingClaim(options?: PendingClaimOptions): Promise<void>;