@uic-coe-connect/cli 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A command failed in a way the user (or the AI reading stderr) should act on.
+ * Carries an exit code so `main` can exit meaningfully without every command
+ * duplicating process.exit plumbing.
+ */
+export declare class CliError extends Error {
+    readonly exitCode: number;
+    readonly hint?: string | undefined;
+    constructor(message: string, exitCode?: number, hint?: string | undefined);
+}
+export interface ClientOptions {
+    /** Server override from --server. */
+    server?: string;
+    /** Skip the credential requirement (only `login` needs this). */
+    anonymous?: boolean;
+}
+export interface Client {
+    server: string;
+    netid: string;
+    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+    /** Streams a text/plain response line by line — used by `deploy`. */
+    stream(method: string, path: string, body: unknown, onLine: (line: string) => void): Promise<void>;
+}
+export declare function createClient(options?: ClientOptions): Client;

package/dist/client.js

@@ -0,0 +1,88 @@
+import { readCredentials, resolveServer } from "./config.js";
+/**
+ * A command failed in a way the user (or the AI reading stderr) should act on.
+ * Carries an exit code so `main` can exit meaningfully without every command
+ * duplicating process.exit plumbing.
+ */
+export class CliError extends Error {
+    exitCode;
+    hint;
+    constructor(message, exitCode = 1, hint) {
+        super(message);
+        this.exitCode = exitCode;
+        this.hint = hint;
+    }
+}
+/** Turns a non-2xx response into a CliError carrying the server's own message. */
+async function fail(res, server) {
+    const body = (await res.json().catch(() => ({})));
+    const message = body.error ?? `${res.status} ${res.statusText}`;
+    if (res.status === 401) {
+        throw new CliError(`Not authenticated: ${message}`, 2, `Run: coe login --server ${server}`);
+    }
+    if (res.status === 403) {
+        throw new CliError(`Not permitted: ${message}`, 3, "You must be on that app's dev team (or a webadmin). Check with: coe apps list");
+    }
+    if (res.status === 404)
+        throw new CliError(`Not found: ${message}`, 4);
+    throw new CliError(message, 1);
+}
+/**
+ * Spread into a fetch init. Omits `body` entirely rather than passing
+ * `undefined` — fetch rejects a body on GET even when it's undefined.
+ */
+function bodyInit(body) {
+    return body === undefined ? {} : { body: JSON.stringify(body) };
+}
+export function createClient(options = {}) {
+    const server = resolveServer(options.server);
+    const creds = readCredentials();
+    if (!options.anonymous && (!creds || creds.server !== server)) {
+        throw new CliError(creds ? `No session for ${server} (you're logged in to ${creds.server}).` : "Not logged in.", 2, `Run: coe login --server ${server}`);
+    }
+    const headers = { "Content-Type": "application/json" };
+    if (creds?.token)
+        headers.Authorization = `Bearer ${creds.token}`;
+    return {
+        server,
+        netid: creds?.netid ?? "",
+        async request(method, path, body) {
+            let res;
+            try {
+                res = await fetch(`${server}${path}`, { method, headers, ...bodyInit(body) });
+            }
+            catch (error) {
+                throw new CliError(`Could not reach ${server}: ${error instanceof Error ? error.message : String(error)}`, 5, "Check the server URL, and that you're on the campus network or VPN.");
+            }
+            if (!res.ok)
+                await fail(res, server);
+            if (res.status === 204)
+                return undefined;
+            return (await res.json());
+        },
+        async stream(method, path, body, onLine) {
+            const res = await fetch(`${server}${path}`, { method, headers, ...bodyInit(body) });
+            if (!res.ok)
+                await fail(res, server);
+            if (!res.body)
+                throw new CliError("The server sent no output stream.");
+            // The deploy endpoint writes plain newline-delimited text, not SSE, so
+            // buffer across chunk boundaries rather than assuming whole lines.
+            const reader = res.body.getReader();
+            const decoder = new TextDecoder();
+            let buffer = "";
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split("\n");
+                buffer = lines.pop() ?? "";
+                for (const line of lines)
+                    onLine(line);
+            }
+            if (buffer)
+                onLine(buffer);
+        },
+    };
+}

package/dist/commands/access.d.ts

@@ -0,0 +1 @@
+export declare function registerAccessCommands(): void;

package/dist/commands/access.js

@@ -0,0 +1,141 @@
+import { CliError } from "../client.js";
+import { details, emit, info } from "../output.js";
+import { register } from "../registry.js";
+import { resolveApp } from "./apps.js";
+function currentAccess(app) {
+    return (app.access ?? { devTeam: [], staff: { everyone: true, members: [], rules: [], exceptions: [] } });
+}
+/** Comma- or space-separated NetIDs, deduped. */
+function netids(raw) {
+    return [...new Set(raw.split(/[,\s]+/).map((s) => s.trim()).filter(Boolean))];
+}
+async function saveAccess(client, appId, access) {
+    return client.request("PUT", `/registered-apps/${appId}/access`, { access });
+}
+export function registerAccessCommands() {
+    register({
+        name: "access show",
+        summary: "Show an app's dev team and staff access",
+        usage: "access show <app>",
+        async run({ args, client }) {
+            const app = await resolveApp(client(), args.arg(0, "app"));
+            const access = currentAccess(app);
+            emit({ appId: app.id, access }, () => {
+                details([
+                    ["Dev team", access.devTeam.join(", ") || "(none — webadmins only)"],
+                    ["Staff access", access.staff.everyone ? "everyone" : "restricted"],
+                    ["  Members", access.staff.members.join(", ") || "(none)"],
+                    ["  Blacklist", access.staff.exceptions.join(", ") || "(none)"],
+                    ["  Rules", String(access.staff.rules.length)],
+                ]);
+            });
+        },
+    }, {
+        name: "access add-dev",
+        summary: "Add NetIDs to an app's dev team",
+        usage: "access add-dev <app> <netid>[,<netid>...]",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const toAdd = netids(args.arg(1, "netid"));
+            const access = currentAccess(app);
+            const devTeam = [...new Set([...access.devTeam, ...toAdd])];
+            await saveAccess(c, app.id, { ...access, devTeam });
+            emit({ appId: app.id, devTeam, added: toAdd }, () => info(`✓ Dev team for ${app.id}: ${devTeam.join(", ")}`));
+        },
+    }, {
+        name: "access remove-dev",
+        summary: "Remove NetIDs from an app's dev team",
+        usage: "access remove-dev <app> <netid>[,<netid>...]",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const toRemove = new Set(netids(args.arg(1, "netid")));
+            const access = currentAccess(app);
+            const devTeam = access.devTeam.filter((n) => !toRemove.has(n));
+            // Emptying the dev team hands the app back to webadmins only — and can
+            // lock the caller out of their own app. Make that an explicit choice.
+            if (devTeam.length === 0 && access.devTeam.length > 0 && !args.bool("yes")) {
+                throw new CliError(`That removes everyone from ${app.id}'s dev team, leaving it webadmin-only.`, 6, "Re-run with --yes if that's intended.");
+            }
+            await saveAccess(c, app.id, { ...access, devTeam });
+            emit({ appId: app.id, devTeam, removed: [...toRemove] }, () => info(`✓ Dev team for ${app.id}: ${devTeam.join(", ") || "(none)"}`));
+        },
+    }, {
+        name: "access set-staff",
+        summary: "Set staff access to everyone or restricted",
+        usage: "access set-staff <app> everyone|restricted",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const mode = args.arg(1, "mode");
+            if (mode !== "everyone" && mode !== "restricted") {
+                throw new CliError(`Mode must be "everyone" or "restricted".`, 6);
+            }
+            const access = currentAccess(app);
+            const next = {
+                ...access,
+                staff: { ...access.staff, everyone: mode === "everyone" },
+            };
+            await saveAccess(c, app.id, next);
+            emit({ appId: app.id, staffAccess: mode }, () => info(`✓ Staff access for ${app.id}: ${mode}`));
+        },
+    }, {
+        name: "access add-staff",
+        summary: "Add NetIDs to the staff members list",
+        usage: "access add-staff <app> <netid>[,<netid>...]",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const toAdd = netids(args.arg(1, "netid"));
+            const access = currentAccess(app);
+            const members = [...new Set([...access.staff.members, ...toAdd])];
+            await saveAccess(c, app.id, { ...access, staff: { ...access.staff, members } });
+            emit({ appId: app.id, members, added: toAdd }, () => {
+                info(`✓ Staff members for ${app.id}: ${members.join(", ")}`);
+                if (access.staff.everyone) {
+                    info("  note: staff access is still 'everyone', so this list isn't enforced yet.");
+                }
+            });
+        },
+    }, {
+        name: "access remove-staff",
+        summary: "Remove NetIDs from the staff members list",
+        usage: "access remove-staff <app> <netid>[,<netid>...]",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const toRemove = new Set(netids(args.arg(1, "netid")));
+            const access = currentAccess(app);
+            const members = access.staff.members.filter((n) => !toRemove.has(n));
+            await saveAccess(c, app.id, { ...access, staff: { ...access.staff, members } });
+            emit({ appId: app.id, members, removed: [...toRemove] }, () => info(`✓ Staff members for ${app.id}: ${members.join(", ") || "(none)"}`));
+        },
+    }, {
+        name: "access block",
+        summary: "Add NetIDs to the blacklist (overrides every grant)",
+        usage: "access block <app> <netid>[,<netid>...]",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const toAdd = netids(args.arg(1, "netid"));
+            const access = currentAccess(app);
+            const exceptions = [...new Set([...access.staff.exceptions, ...toAdd])];
+            await saveAccess(c, app.id, { ...access, staff: { ...access.staff, exceptions } });
+            emit({ appId: app.id, blacklist: exceptions, added: toAdd }, () => info(`✓ Blacklist for ${app.id}: ${exceptions.join(", ")}`));
+        },
+    }, {
+        name: "access unblock",
+        summary: "Remove NetIDs from the blacklist",
+        usage: "access unblock <app> <netid>[,<netid>...]",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const toRemove = new Set(netids(args.arg(1, "netid")));
+            const access = currentAccess(app);
+            const exceptions = access.staff.exceptions.filter((n) => !toRemove.has(n));
+            await saveAccess(c, app.id, { ...access, staff: { ...access.staff, exceptions } });
+            emit({ appId: app.id, blacklist: exceptions, removed: [...toRemove] }, () => info(`✓ Blacklist for ${app.id}: ${exceptions.join(", ") || "(none)"}`));
+        },
+    });
+}

package/dist/commands/apps.d.ts

@@ -0,0 +1,9 @@
+import type { Client } from "../client.js";
+import type { RegisteredApp } from "../types.js";
+/**
+ * Resolve an app by id, or by a unique name/URL fragment. Agents and humans
+ * both tend to type the app's display name, and a 404 on "Travel Form" when
+ * the id is "travel-form" is a bad first experience.
+ */
+export declare function resolveApp(client: Client, ref: string): Promise<RegisteredApp>;
+export declare function registerAppCommands(): void;

package/dist/commands/apps.js

@@ -0,0 +1,63 @@
+import { CliError } from "../client.js";
+import { details, emit, table } from "../output.js";
+import { register } from "../registry.js";
+/**
+ * Resolve an app by id, or by a unique name/URL fragment. Agents and humans
+ * both tend to type the app's display name, and a 404 on "Travel Form" when
+ * the id is "travel-form" is a bad first experience.
+ */
+export async function resolveApp(client, ref) {
+    const { apps } = await client.request("GET", "/registered-apps");
+    const exact = apps.find((a) => a.id === ref);
+    if (exact)
+        return client.request("GET", `/registered-apps/${exact.id}`);
+    const needle = ref.toLowerCase();
+    const matches = apps.filter((a) => a.name.toLowerCase().includes(needle) || a.url.toLowerCase().includes(needle));
+    if (matches.length === 1) {
+        return client.request("GET", `/registered-apps/${matches[0].id}`);
+    }
+    if (matches.length > 1) {
+        throw new CliError(`"${ref}" matches ${matches.length} apps: ${matches.map((a) => a.id).join(", ")}`, 4, "Use the exact app id.");
+    }
+    throw new CliError(`No app "${ref}" that you can manage.`, 4, apps.length > 0
+        ? `You manage: ${apps.map((a) => a.id).join(", ")}`
+        : "You aren't on any app's dev team.");
+}
+export function registerAppCommands() {
+    register({
+        name: "apps list",
+        summary: "List the apps you can manage",
+        usage: "apps list",
+        async run({ client }) {
+            const { apps } = await client().request("GET", "/registered-apps");
+            emit({ apps }, () => {
+                table(apps.map((a) => ({
+                    id: a.id,
+                    name: a.name,
+                    url: a.url,
+                    pipelines: String(a.pipelines?.length ?? 0),
+                })), ["id", "name", "url", "pipelines"]);
+            });
+        },
+    }, {
+        name: "apps show",
+        summary: "Show one app's full configuration",
+        usage: "apps show <app>",
+        async run({ args, client }) {
+            const app = await resolveApp(client(), args.arg(0, "app"));
+            emit(app, () => {
+                details([
+                    ["Id", app.id],
+                    ["Name", app.name],
+                    ["URL", app.url],
+                    ["Repo", app.repo ?? "—"],
+                    ["Branch", app.branch ?? "—"],
+                    ["Pipelines", (app.pipelines ?? []).map((p) => p.name).join(", ") || "(none)"],
+                    ["Dev team", (app.access?.devTeam ?? []).join(", ") || "(none)"],
+                    ["Env vars", Object.keys(app.env ?? {}).join(", ") || "(none)"],
+                    ["Updated", new Date(app.updatedAt).toLocaleString()],
+                ]);
+            });
+        },
+    });
+}

package/dist/commands/auth.d.ts

@@ -0,0 +1 @@
+export declare function registerAuthCommands(): void;

package/dist/commands/auth.js

@@ -0,0 +1,163 @@
+import { spawn } from "node:child_process";
+import { CliError, createClient } from "../client.js";
+import { clearCredentials, credentialsPath, readCredentials, resolveServer, saveCredentials, saveServer, sessionLabel, } from "../config.js";
+import { details, emit, info, isJsonMode } from "../output.js";
+import { register } from "../registry.js";
+/** Best-effort browser open. Never fatal — the URL is always printed too. */
+function openBrowser(url) {
+    const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    try {
+        spawn(command, [url], { stdio: "ignore", detached: true, shell: process.platform === "win32" })
+            .on("error", () => { })
+            .unref();
+    }
+    catch {
+        /* headless box or no opener — the printed URL is the fallback */
+    }
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export function registerAuthCommands() {
+    register({
+        name: "login",
+        summary: "Start a session (approve it in your browser)",
+        usage: "login [--server <url>]",
+        details: [
+            "Prints a code, opens the approval page, and waits. The token is minted",
+            "against whichever NetID is signed in there, so a terminal can never hold",
+            "more permission than the human who approved it.",
+        ],
+        anonymous: true,
+        async run({ args }) {
+            const server = resolveServer(args.flag("server"));
+            const client = createClient({ server, anonymous: true });
+            const start = await client.request("POST", "/cli/auth/start", {
+                label: sessionLabel(),
+            });
+            const url = `${server}/cli/authorize?code=${encodeURIComponent(start.userCode)}`;
+            info(`\n  Your code:  ${start.userCode}`);
+            info(`  Approve at: ${url}\n`);
+            if (!args.bool("no-browser"))
+                openBrowser(url);
+            info("Waiting for approval… (Ctrl-C to cancel)");
+            const deadline = Date.now() + start.expiresIn * 1000;
+            for (;;) {
+                if (Date.now() > deadline) {
+                    throw new CliError("That code expired before it was approved.", 2, "Run: coe login");
+                }
+                await sleep(2000);
+                const poll = await client.request("GET", `/cli/auth/poll?deviceCode=${encodeURIComponent(start.deviceCode)}`);
+                if (poll.status === "pending")
+                    continue;
+                if (poll.status === "denied")
+                    throw new CliError("That login was denied.", 2);
+                if (poll.status === "expired") {
+                    throw new CliError("That code expired or was already used.", 2, "Run: coe login");
+                }
+                // Expiry is tracked client-side purely to give a clean "run coe login"
+                // instead of a 401 mid-command; the server is still the authority.
+                const expiresAt = new Date(Date.now() + 12 * 60 * 60 * 1000).toISOString();
+                saveCredentials({ server, netid: poll.netid, token: poll.token, expiresAt });
+                saveServer(server);
+                emit({ loggedIn: true, netid: poll.netid, server, expiresAt }, () => {
+                    info(`\n✓ Signed in as ${poll.netid} on ${server}`);
+                    info(`  Session expires ${new Date(expiresAt).toLocaleString()}`);
+                });
+                return;
+            }
+        },
+    }, {
+        name: "logout",
+        summary: "End this session (or all of them with --all)",
+        usage: "logout [--all]",
+        anonymous: true,
+        async run({ args }) {
+            const creds = readCredentials();
+            if (!creds) {
+                emit({ loggedOut: false, reason: "no active session" }, () => info("No active session."));
+                return;
+            }
+            const client = createClient({ server: creds.server });
+            const all = args.bool("all");
+            const result = await client.request("DELETE", `/cli/sessions${all ? "?all=true" : ""}`);
+            clearCredentials();
+            emit({ loggedOut: true, revoked: result.revoked }, () => info(`✓ Signed out (${result.revoked} session${result.revoked === 1 ? "" : "s"} revoked)`));
+        },
+    }, {
+        name: "whoami",
+        summary: "Show the signed-in NetID, server, and what you can manage",
+        usage: "whoami",
+        async run({ client }) {
+            const c = client();
+            const me = await c.request("GET", "/me");
+            const apps = await c.request("GET", "/registered-apps");
+            emit({ ...me.user, server: c.server, manages: apps.apps.map((a) => a.id) }, () => {
+                details([
+                    ["NetID", me.user.netid],
+                    ["Server", c.server],
+                    ["Roles", me.user.roles?.join(", ") || "(none)"],
+                    ["Manages", apps.apps.map((a) => a.id).join(", ") || "(no apps)"],
+                ]);
+            });
+        },
+    }, {
+        name: "auth list",
+        summary: "List your active terminal sessions",
+        usage: "auth list",
+        async run({ client }) {
+            const { sessions } = await client().request("GET", "/cli/sessions");
+            emit({ sessions }, () => {
+                if (sessions.length === 0) {
+                    info("(no active sessions)");
+                    return;
+                }
+                for (const s of sessions) {
+                    details([
+                        ["Label", s.label],
+                        ["Created", new Date(s.createdAt).toLocaleString()],
+                        ["Expires", new Date(s.expiresAt).toLocaleString()],
+                        ["Last used", s.lastUsedAt ? new Date(s.lastUsedAt).toLocaleString() : "never"],
+                    ]);
+                    info("");
+                }
+            });
+        },
+    }, {
+        name: "auth revoke",
+        summary: "Revoke every terminal session for your NetID",
+        usage: "auth revoke --all",
+        async run({ args, client }) {
+            if (!args.bool("all")) {
+                throw new CliError("Pass --all to confirm revoking every session.", 6);
+            }
+            const result = await client().request("DELETE", "/cli/sessions?all=true");
+            clearCredentials();
+            emit(result, () => info(`✓ Revoked ${result.revoked} session(s)`));
+        },
+    }, {
+        name: "auth status",
+        summary: "Where credentials are stored and whether they're valid",
+        usage: "auth status",
+        anonymous: true,
+        async run() {
+            const creds = readCredentials();
+            const payload = {
+                authenticated: Boolean(creds),
+                netid: creds?.netid ?? null,
+                server: creds?.server ?? resolveServer(),
+                expiresAt: creds?.expiresAt ?? null,
+                credentialsPath: credentialsPath(),
+            };
+            emit(payload, () => {
+                details([
+                    ["Authenticated", payload.authenticated ? "yes" : "no — run: coe login"],
+                    ["NetID", payload.netid ?? "—"],
+                    ["Server", payload.server],
+                    ["Expires", payload.expiresAt ? new Date(payload.expiresAt).toLocaleString() : "—"],
+                    ["Credentials", payload.credentialsPath],
+                ]);
+            });
+            if (!payload.authenticated && !isJsonMode())
+                info("\nRun `coe login` to start a session.");
+        },
+    });
+}

package/dist/commands/deploy.d.ts

@@ -0,0 +1,4 @@
+import type { RegisteredApp } from "../types.js";
+export declare function registerDeployCommands(): void;
+/** Re-exported for the docs generator and tests. */
+export type { RegisteredApp };

package/dist/commands/deploy.js

@@ -0,0 +1,120 @@
+import { CliError } from "../client.js";
+import { emit, info, isJsonMode, table } from "../output.js";
+import { register } from "../registry.js";
+import { resolveApp } from "./apps.js";
+/** Sentinels the deploy stream ends with — the server's own success signal. */
+const OK = "__DEPLOY_OK__";
+const FAILED = "__DEPLOY_FAILED__";
+export function registerDeployCommands() {
+    register({
+        name: "deploy",
+        summary: "Run a deploy pipeline, streaming its output",
+        usage: "deploy <app> [--pipeline <p>] [--branch <b>|--current] [--version <v>]",
+        details: [
+            "Streams the live console. Exits 0 only if the deploy succeeded, so it's",
+            "safe to chain. A pipeline containing a DB migrate step needs",
+            "--confirm-migrate, matching the confirmation the web UI asks for.",
+        ],
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const pipelines = app.pipelines ?? [];
+            if (pipelines.length === 0) {
+                throw new CliError(`${app.id} has no deploy pipeline configured.`, 6, "Create one with: coe pipelines create");
+            }
+            const ref = args.flag("pipeline");
+            const chosen = ref
+                ? (pipelines.find((p) => p.id === ref) ??
+                    pipelines.find((p) => p.name.toLowerCase() === ref.toLowerCase()))
+                : pipelines[0];
+            if (!chosen) {
+                throw new CliError(`No pipeline "${ref}" on ${app.id}.`, 4, `Available: ${pipelines.map((p) => p.name).join(", ")}`);
+            }
+            const branch = args.flag("branch");
+            const source = args.bool("current")
+                ? { mode: "current" }
+                : branch
+                    ? { mode: "branch", branch }
+                    : {};
+            const body = {
+                pipelineId: chosen.id,
+                version: args.flag("version"),
+                source,
+                confirmMigrate: args.bool("confirm-migrate"),
+            };
+            const needsMigrate = chosen.config.steps.some((s) => s.type === "migrate");
+            if (needsMigrate && !args.bool("confirm-migrate")) {
+                throw new CliError(`Pipeline "${chosen.name}" runs database migrations.`, 6, "Re-run with --confirm-migrate once you've checked the migration is safe.");
+            }
+            info(`Deploying ${app.id} · pipeline "${chosen.name}"${branch ? ` · branch ${branch}` : ""}`);
+            const lines = [];
+            const sentinels = [];
+            await c.stream("POST", `/registered-apps/${app.id}/deploy`, body, (line) => {
+                if (line === OK || line === FAILED) {
+                    sentinels.push(line);
+                    return;
+                }
+                lines.push(line);
+                // In JSON mode the log is part of the final payload instead, so stdout
+                // stays parseable; progress still shows on stderr.
+                if (isJsonMode())
+                    info(line);
+                else
+                    process.stdout.write(`${line}\n`);
+            });
+            // Derived after the stream rather than assigned inside the callback:
+            // "unknown" is a real third state — a dropped connection mid-deploy
+            // ends the stream with no sentinel at all.
+            const outcome = sentinels.includes(OK)
+                ? "ok"
+                : sentinels.includes(FAILED)
+                    ? "failed"
+                    : "unknown";
+            emit({ appId: app.id, pipeline: chosen.name, status: outcome, log: lines }, () => {
+                info(outcome === "ok" ? `\n✓ Deploy succeeded` : `\n✗ Deploy ${outcome}`);
+            });
+            // A stream that ended without a sentinel means the connection dropped
+            // mid-deploy — the deploy may still be running, so don't report success.
+            if (outcome !== "ok") {
+                throw new CliError(outcome === "failed"
+                    ? "The deploy failed — see the output above."
+                    : "The deploy stream ended without a result; check build history.", 7);
+            }
+        },
+    }, {
+        name: "builds",
+        summary: "Show an app's build history",
+        usage: "builds <app> [--limit <n>]",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const { builds } = await c.request("GET", `/registered-apps/${app.id}/builds`);
+            const limit = Number(args.flag("limit") ?? 20);
+            const shown = builds.slice(0, Number.isFinite(limit) ? limit : 20);
+            emit({ appId: app.id, builds: shown }, () => {
+                table(shown.map((b) => ({
+                    started: new Date(b.startedAt).toLocaleString(),
+                    status: b.status,
+                    version: b.version ?? "—",
+                    pipeline: b.pipelineName ?? "—",
+                    source: b.source,
+                    by: b.by ?? "—",
+                    commit: b.commit?.slice(0, 8) ?? "—",
+                })), ["started", "status", "version", "pipeline", "source", "by", "commit"]);
+            });
+        },
+    }, {
+        name: "branches",
+        summary: "List the branches of an app's repo",
+        usage: "branches <app>",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const result = await c.request("GET", `/registered-apps/${app.id}/branches`);
+            emit({ appId: app.id, ...result }, () => {
+                for (const b of result.branches)
+                    process.stdout.write(`${b}\n`);
+            });
+        },
+    });
+}

package/dist/commands/env.d.ts

@@ -0,0 +1 @@
+export declare function registerEnvCommands(): void;