@uic-coe-connect/cli 0.11.0 → 0.13.0

package/dist/client.js

@@ -25,8 +25,44 @@ async function fail(res, server) {
     }
     if (res.status === 404)
         throw new CliError(`Not found: ${message}`, 4);
+    // A refusal the caller can act on: bad input (400), something that can't be
+    // done in the current state (409, e.g. "this COEConnect doesn't manage that
+    // VM" or "nothing is deploying"), or input the server understood and
+    // rejected (422). These used to fall through to the generic 1, which is not
+    // in the documented table at all — so a script told to branch on exit codes
+    // got an undocumented one for the most common recoverable failures.
+    if ([400, 409, 422].includes(res.status))
+        throw new CliError(message, 6);
     throw new CliError(message, 1);
 }
+/**
+ * How long a plain request may take before the CLI gives up.
+ *
+ * Generous — some reads go out to a VM agent and back — but finite. Without a
+ * limit a server that accepts the connection and then never answers leaves the
+ * CLI waiting for ever, printing nothing: no spinner, no error, no exit. That
+ * is what `coe auth list` did in production on 2026-09-22, and the silence
+ * made it look like the CLI itself was broken rather than one route on the
+ * server.
+ */
+const REQUEST_TIMEOUT_MS = 30_000;
+/** Uploads and downloads move real files, so they get longer. */
+const TRANSFER_TIMEOUT_MS = 120_000;
+/**
+ * A deploy stream has no overall limit — a pipeline legitimately runs for
+ * minutes — so it is policed on *silence* instead. The server heartbeats every
+ * ten seconds precisely so a quiet build still looks alive, which makes a long
+ * gap a real failure rather than a slow step.
+ */
+const STREAM_IDLE_TIMEOUT_MS = 120_000;
+/** Turns a timeout into something that says what to do next. */
+function timeoutError(server, seconds) {
+    return new CliError(`${server} did not respond within ${seconds}s.`, 5, "The server accepted the connection but never answered. Try again, and if it persists " +
+        "check the server's logs — a route that throws can stop responding without closing.");
+}
+function isAbort(error) {
+    return error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError");
+}
 /**
  * Spread into a fetch init. Omits `body` entirely rather than passing
  * `undefined` — fetch rejects a body on GET even when it's undefined.
@@ -49,9 +85,16 @@ export function createClient(options = {}) {
         async request(method, path, body) {
             let res;
             try {
-                res = await fetch(`${server}${path}`, { method, headers, ...bodyInit(body) });
+                res = await fetch(`${server}${path}`, {
+                    method,
+                    headers,
+                    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                    ...bodyInit(body),
+                });
             }
             catch (error) {
+                if (isAbort(error))
+                    throw timeoutError(server, REQUEST_TIMEOUT_MS / 1000);
                 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)
@@ -72,40 +115,82 @@ export function createClient(options = {}) {
                     "X-File-Name": encodeURIComponent(filename),
                 },
                 body: bytes,
+                signal: AbortSignal.timeout(TRANSFER_TIMEOUT_MS),
+            }).catch((error) => {
+                if (isAbort(error))
+                    throw timeoutError(server, TRANSFER_TIMEOUT_MS / 1000);
+                throw error;
             });
             if (!res.ok)
                 await fail(res, server);
             return (await res.json());
         },
         async download(path) {
-            const res = await fetch(`${server}${path}`, { headers });
+            const res = await fetch(`${server}${path}`, {
+                headers,
+                signal: AbortSignal.timeout(TRANSFER_TIMEOUT_MS),
+            }).catch((error) => {
+                if (isAbort(error))
+                    throw timeoutError(server, TRANSFER_TIMEOUT_MS / 1000);
+                throw error;
+            });
             if (!res.ok)
                 await fail(res, server);
             return new Uint8Array(await res.arrayBuffer());
         },
         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);
+            // No overall deadline here, only an idle one: the whole point of this
+            // call is to sit open while a deploy runs.
+            const idle = new AbortController();
+            let watchdog;
+            const resetWatchdog = () => {
+                if (watchdog)
+                    clearTimeout(watchdog);
+                watchdog = setTimeout(() => idle.abort(), STREAM_IDLE_TIMEOUT_MS);
+                watchdog.unref?.();
+            };
+            resetWatchdog();
+            try {
+                const res = await fetch(`${server}${path}`, {
+                    method,
+                    headers,
+                    signal: idle.signal,
+                    ...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;
+                    resetWatchdog();
+                    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);
+            }
+            catch (error) {
+                if (isAbort(error)) {
+                    throw new CliError(`${server} sent nothing for ${STREAM_IDLE_TIMEOUT_MS / 1000}s.`, 5, "A running deploy heartbeats every 10s, so this means the connection died — " +
+                        "the deploy itself may still be going. Check: coe builds <app>");
+                }
+                throw error;
+            }
+            finally {
+                if (watchdog)
+                    clearTimeout(watchdog);
             }
-            if (buffer)
-                onLine(buffer);
         },
     };
 }

package/dist/commands/access.js

@@ -1,5 +1,5 @@
 import { CliError } from "../client.js";
-import { details, emit, info } from "../output.js";
+import { details, emit, info, success } from "../output.js";
 import { register } from "../registry.js";
 import { resolveApp } from "./apps.js";
 function currentAccess(app) {
@@ -42,7 +42,7 @@ export function registerAccessCommands() {
             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(", ")}`));
+            emit({ appId: app.id, devTeam, added: toAdd }, () => success(`Dev team for ${app.id}: ${devTeam.join(", ")}`));
         },
     }, {
         name: "access remove-dev",
@@ -60,7 +60,7 @@ export function registerAccessCommands() {
                 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)"}`));
+            emit({ appId: app.id, devTeam, removed: [...toRemove] }, () => success(`Dev team for ${app.id}: ${devTeam.join(", ") || "(none)"}`));
         },
     }, {
         name: "access set-staff",
@@ -79,7 +79,7 @@ export function registerAccessCommands() {
                 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}`));
+            emit({ appId: app.id, staffAccess: mode }, () => success(`Staff access for ${app.id}: ${mode}`));
         },
     }, {
         name: "access add-staff",
@@ -93,7 +93,7 @@ export function registerAccessCommands() {
             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(", ")}`);
+                success(`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.");
                 }
@@ -110,7 +110,7 @@ export function registerAccessCommands() {
             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)"}`));
+            emit({ appId: app.id, members, removed: [...toRemove] }, () => success(`Staff members for ${app.id}: ${members.join(", ") || "(none)"}`));
         },
     }, {
         name: "access block",
@@ -123,7 +123,7 @@ export function registerAccessCommands() {
             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(", ")}`));
+            emit({ appId: app.id, blacklist: exceptions, added: toAdd }, () => success(`Blacklist for ${app.id}: ${exceptions.join(", ")}`));
         },
     }, {
         name: "access unblock",
@@ -136,7 +136,7 @@ export function registerAccessCommands() {
             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)"}`));
+            emit({ appId: app.id, blacklist: exceptions, removed: [...toRemove] }, () => success(`Blacklist for ${app.id}: ${exceptions.join(", ") || "(none)"}`));
         },
     });
 }

package/dist/commands/auth.js

@@ -1,7 +1,7 @@
 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 { details, emit, info, isJsonMode, style, success } from "../output.js";
 import { register } from "../registry.js";
 /** Best-effort browser open. Never fatal — the URL is always printed too. */
 function openBrowser(url) {
@@ -80,7 +80,7 @@ export function registerAuthCommands() {
             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)`));
+            emit({ loggedOut: true, revoked: result.revoked }, () => success(`Signed out (${result.revoked} session${result.revoked === 1 ? "" : "s"} revoked)`));
         },
     }, {
         name: "whoami",
@@ -112,10 +112,19 @@ export function registerAuthCommands() {
                 }
                 for (const s of sessions) {
                     details([
-                        ["Label", s.label],
+                        ["Label", s.current ? `${s.label} ${style.ok("(this terminal)")}` : s.label],
                         ["Created", new Date(s.createdAt).toLocaleString()],
                         ["Expires", new Date(s.expiresAt).toLocaleString()],
-                        ["Last used", s.lastUsedAt ? new Date(s.lastUsedAt).toLocaleString() : "never"],
+                        [
+                            "Last used",
+                            // Your own row reads "never" because authenticating stamps the
+                            // timestamp after this read — say so rather than look wrong.
+                            s.current
+                                ? "now"
+                                : s.lastUsedAt
+                                    ? new Date(s.lastUsedAt).toLocaleString()
+                                    : "never",
+                        ],
                     ]);
                     info("");
                 }
@@ -131,7 +140,7 @@ export function registerAuthCommands() {
             }
             const result = await client().request("DELETE", "/cli/sessions?all=true");
             clearCredentials();
-            emit(result, () => info(`✓ Revoked ${result.revoked} session(s)`));
+            emit(result, () => success(`Revoked ${result.revoked} session(s)`));
         },
     }, {
         name: "auth status",

package/dist/commands/deploy.js

@@ -1,25 +1,41 @@
 import { CliError } from "../client.js";
-import { emit, info, isJsonMode, table } from "../output.js";
+import { emit, info, isJsonMode, table, style } 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__";
+const CANCELLED = "__DEPLOY_CANCELLED__";
 /**
  * Machine markers the server interleaves for the web UI's pipeline diagram.
  * They're meaningless here and read as debug noise, so they never reach the
  * console or the JSON log — the stream already carries a human line for each.
  */
-const MARKER = /^__(NODE|COMMIT)__:/;
+const MARKER = /^__(NODE|COMMIT|PREV)__:/;
+/**
+ * The engine's marker for a line worth remembering after the run.
+ *
+ * Unlike the others it carries text a person should read, so it is unwrapped
+ * rather than dropped — the summary at the end counts the same lines.
+ */
+const WARN_MARKER = "__WARN__:";
 export function registerDeployCommands() {
     register({
         name: "deploy",
         summary: "Run a deploy pipeline, streaming its output",
-        usage: "deploy <app> [--pipeline <p>] [--branch <b>|--current] [--version <v>]",
+        usage: "deploy <app> [--pipeline <p>] [--branch <b>|--commit <sha>] [--version <v>] [--confirm-script]",
         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.",
+            "",
+            "--commit deploys an exact commit rather than a branch tip, which is what",
+            "a rollback is: `coe builds <app>` prints each build's previous commit.",
+            "Exit code 8 means somebody cancelled the run, which is not a failure.",
+            "",
+            "A pipeline with a `script` step needs --confirm-script on every run, not",
+            "once: the pipeline fixes which file runs, not what is in it, and that",
+            "changes with the commit being deployed.",
         ],
         async run({ args, client }) {
             const c = client();
@@ -37,35 +53,60 @@ export function registerDeployCommands() {
                 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 commit = args.flag("commit");
+            if (commit && !/^[0-9a-f]{7,40}$/i.test(commit)) {
+                throw new CliError(`"${commit}" is not a commit SHA.`, 4, "Pass the short or full SHA, e.g. --commit a1b2c3d.");
+            }
+            const source = commit
+                ? { mode: "commit", commit, branch }
+                : args.bool("current")
+                    ? { mode: "current" }
+                    : branch
+                        ? { mode: "branch", branch }
+                        : {};
             const body = {
                 pipelineId: chosen.id,
                 version: args.flag("version"),
                 source,
                 confirmMigrate: args.bool("confirm-migrate"),
+                confirmScript: args.bool("confirm-script"),
             };
             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.");
             }
+            /**
+             * A script step is confirmed on every run, not once when it was added.
+             *
+             * Every other step's behaviour is fixed by the pipeline. A script's is
+             * whatever the file says on the commit being deployed — so approving it
+             * once would approve code that had not been written yet.
+             */
+            const scripts = chosen.config.steps.filter((x) => x.type === "script");
+            if (scripts.length > 0 && !args.bool("confirm-script")) {
+                const files = scripts.map((x) => [x.subdir, x.file].filter(Boolean).join("/"));
+                throw new CliError(`Pipeline "${chosen.name}" runs ${files.join(", ")} from the app's repo as root.`, 6, "Read that file on the commit you're deploying, then re-run with --confirm-script.");
+            }
             info(`Deploying ${app.id} · pipeline "${chosen.name}"${branch ? ` · branch ${branch}` : ""}`);
             const lines = [];
             const sentinels = [];
-            let commit;
+            const warnings = [];
+            let deployed;
             await c.stream("POST", `/registered-apps/${app.id}/deploy`, body, (line) => {
-                if (line === OK || line === FAILED) {
+                if (line === OK || line === FAILED || line === CANCELLED) {
                     sentinels.push(line);
                     return;
                 }
-                if (MARKER.test(line)) {
+                if (line.startsWith(WARN_MARKER)) {
+                    const text = line.slice(WARN_MARKER.length);
+                    warnings.push(text);
+                    line = `⚠ ${text}`;
+                }
+                else if (MARKER.test(line)) {
                     // Keep the one piece of information a marker carries that the
                     // human stream doesn't structure: which commit got deployed.
                     if (line.startsWith("__COMMIT__:"))
-                        commit = line.split(":")[1];
+                        deployed = line.split(":")[1];
                     return;
                 }
                 lines.push(line);
@@ -81,40 +122,156 @@ export function registerDeployCommands() {
             // 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, commit, log: lines }, () => {
-                info(outcome === "ok" ? `\n✓ Deploy succeeded` : `\n✗ Deploy ${outcome}`);
+                : sentinels.includes(CANCELLED)
+                    ? "cancelled"
+                    : sentinels.includes(FAILED)
+                        ? "failed"
+                        : "unknown";
+            emit({
+                appId: app.id,
+                pipeline: chosen.name,
+                status: outcome,
+                commit: deployed,
+                warnings,
+                log: lines,
+            }, () => {
+                info(outcome === "ok"
+                    ? "\n✓ Deploy succeeded"
+                    : outcome === "cancelled"
+                        ? "\n■ Deploy cancelled"
+                        : `\n✗ Deploy ${outcome}`);
+                // The console has usually scrolled well past these by now, and a
+                // deploy that worked is the case where nobody scrolls back.
+                if (warnings.length > 0) {
+                    info(`\n${warnings.length} warning(s):`);
+                    for (const w of warnings)
+                        info(`  ⚠ ${w}`);
+                }
             });
             // 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);
+                    : outcome === "cancelled"
+                        ? "The deploy was cancelled. The app is in whatever state the stopped step left it."
+                        : "The deploy stream ended without a result; check build history.", outcome === "cancelled" ? 8 : 7);
             }
         },
     }, {
         name: "builds",
         summary: "Show an app's build history",
-        usage: "builds <app> [--limit <n>]",
+        usage: "builds <app> [--limit <n>] [--offset <n>]",
+        details: [
+            "The `warn` column counts warnings the build produced — things that did",
+            "not stop it and that nobody reads in a console nobody reopens. Use",
+            "`coe build-log` to see them in context.",
+            "",
+            "`rollback` is the commit that was live before that build: deploying it",
+            "is what undoing that build means.",
+        ],
         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) => ({
+            const limit = args.num("limit", 20);
+            const offset = args.num("offset", 0);
+            const { builds, total } = await c.request("GET", `/registered-apps/${app.id}/builds?limit=${limit}&offset=${offset}`);
+            emit({ appId: app.id, builds, total, offset }, () => {
+                table(builds.map((b) => ({
                     started: new Date(b.startedAt).toLocaleString(),
-                    status: b.status,
+                    status: style.state(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"]);
+                    rollback: b.previousCommit?.slice(0, 8) ?? "—",
+                    warn: String((b.warnings ?? []).reduce((n, w) => n + w.count, 0) || "—"),
+                })), ["started", "status", "version", "pipeline", "source", "by", "commit", "rollback", "warn"]);
+                if (total > builds.length) {
+                    info(`\nShowing ${builds.length} of ${total} — use --offset to page back.`);
+                }
+            });
+        },
+    }, {
+        name: "build-log",
+        summary: "Print a past build's console",
+        usage: "build-log <app> <buildId>",
+        details: [
+            "Only the most recent builds keep a console — `coe builds` marks the ones",
+            "that still have one. A build's warnings are printed first, because they",
+            "are the part of a successful deploy worth reading.",
+        ],
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const buildId = args.arg(1, "buildId");
+            const { builds } = await c.request("GET", `/registered-apps/${app.id}/builds?limit=100`);
+            const build = builds.find((b) => b.id === buildId || b.version === buildId);
+            if (!build) {
+                throw new CliError(`No build "${buildId}" on ${app.id}.`, 4, "List them with: coe builds " + app.id);
+            }
+            const { lines } = await c.request("GET", `/registered-apps/${app.id}/builds/${build.id}/log`);
+            emit({ appId: app.id, build, lines }, () => {
+                for (const w of build.warnings ?? []) {
+                    info(`⚠ ${w.count > 1 ? `${w.count}× ` : ""}${w.label}`);
+                    if (w.hint)
+                        info(`  ${w.hint}`);
+                }
+                if ((build.warnings ?? []).length > 0)
+                    info("");
+                for (const line of lines)
+                    process.stdout.write(`${line}\n`);
+            });
+        },
+    }, {
+        name: "commits",
+        summary: "List recent commits on a branch of an app's repo",
+        usage: "commits <app> [--branch <b>] [--limit <n>]",
+        details: [
+            "Reads the app's own checkout on its VM, so this is what `coe deploy",
+            "--commit` can actually deploy — not what your local clone has.",
+        ],
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const branch = args.flag("branch") ?? app.branch;
+            if (!branch) {
+                throw new CliError(`${app.id} has no default branch set.`, 4, "Name one with --branch, or set it on the app.");
+            }
+            const limit = args.num("limit", 25);
+            const { commits } = await c.request("GET", `/registered-apps/${app.id}/commits?branch=${encodeURIComponent(branch)}&limit=${limit}`);
+            emit({ appId: app.id, branch, commits }, () => {
+                table(commits.map((x) => ({
+                    commit: x.sha,
+                    subject: x.subject,
+                    author: x.author,
+                    date: new Date(x.date).toLocaleString(),
+                })), ["commit", "subject", "author", "date"]);
+            });
+        },
+    }, {
+        name: "cancel",
+        summary: "Stop the deploy running on an app",
+        usage: "cancel <app>",
+        details: [
+            "Stops the pipeline: the running command is killed and no further step",
+            "starts. It does not put anything back — the checkout is wherever the",
+            "stopped step left it, and if that step was building or installing, the",
+            "app needs another deploy to reach a state somebody chose.",
+            "",
+            "To undo a deploy, deploy what was live before it:",
+            "  coe deploy <app> --commit $(coe builds <app> --limit 1 --json | …)",
+        ],
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            // A 409 — "nothing is deploying on this app right now" — is the ordinary
+            // race, not an error worth dressing up: it finished while you typed.
+            // The server's own message says exactly that, so it is left to surface.
+            const result = await c.request("POST", `/registered-apps/${app.id}/deploy/cancel`);
+            emit({ appId: app.id, ...result }, () => {
+                info(`■ Asked ${app.id}'s deploy to stop. Watch it finish with: coe logs ${app.id}`);
             });
         },
     }, {

package/dist/commands/env.js

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 import { CliError } from "../client.js";
-import { emit, info, table } from "../output.js";
+import { emit, info, success, table } from "../output.js";
 import { register } from "../registry.js";
 import { resolveApp } from "./apps.js";
 /**
@@ -95,7 +95,7 @@ export function registerEnvCommands() {
             // clobbers the app's name/url/icon the way a full record PUT would.
             const next = { ...env, ...updates };
             await c.request("PUT", `/registered-apps/${app.id}/env`, { env: next });
-            emit({ appId: app.id, set: Object.keys(updates), count: Object.keys(next).length }, () => info(`✓ Set ${Object.keys(updates).join(", ")} on ${app.id}`));
+            emit({ appId: app.id, set: Object.keys(updates), count: Object.keys(next).length }, () => success(`Set ${Object.keys(updates).join(", ")} on ${app.id}`));
         },
     }, {
         name: "env unset",
@@ -116,7 +116,7 @@ export function registerEnvCommands() {
             for (const key of keys)
                 delete next[key];
             await c.request("PUT", `/registered-apps/${app.id}/env`, { env: next });
-            emit({ appId: app.id, removed: keys, count: Object.keys(next).length }, () => info(`✓ Removed ${keys.join(", ")} from ${app.id}`));
+            emit({ appId: app.id, removed: keys, count: Object.keys(next).length }, () => success(`Removed ${keys.join(", ")} from ${app.id}`));
         },
     });
 }

package/dist/commands/logs.js

@@ -22,7 +22,7 @@ export function registerLogCommands() {
             const c = client();
             const app = await resolveApp(c, args.arg(0, "app"));
             const stream = args.bool("out") ? "out" : "err";
-            const tail = Number(args.flag("tail") ?? 100);
+            const tail = args.num("tail", 100);
             if (!Number.isFinite(tail) || tail < 1) {
                 throw new CliError(`--tail must be a positive number, got "${args.flag("tail")}".`, 6);
             }

package/dist/commands/pipelines.js

@@ -1,17 +1,28 @@
 import { readFileSync } from "node:fs";
 import { CliError } from "../client.js";
-import { emit, info, table } from "../output.js";
+import { emit, info, success, table } from "../output.js";
 import { register } from "../registry.js";
 import { resolveApp } from "./apps.js";
 /**
  * Steps are written as a compact `type:arg` list so a pipeline can be created
  * in one command instead of hand-authoring JSON:
  *
- *   pull  scan  env:backend  npm:ci@backend  migrate:backend  chown  pm2:restart@my-api
+ *   preflight  pull  scan  backup:db  npm:ci@backend  chown  pm2:restart@my-api  health:/healthz
  *
  * `--steps-file` takes the raw JSON array instead, for anything this shorthand
- * can't express.
+ * can't express — a `script` step's arguments, say.
  */
+/** Everything `clean` is allowed to delete. Mirrors the engine's allowlist. */
+const CLEAN_TARGETS = [
+    "node_modules",
+    "dist",
+    "build",
+    ".next",
+    ".nuxt",
+    ".cache",
+    "target",
+    "vendor",
+];
 function parseStep(token) {
     const [head, subdir] = token.split("@");
     const [type, arg] = head.split(":");
@@ -41,8 +52,36 @@ function parseStep(token) {
             if (!arg)
                 throw new CliError(`pm2 step needs an action: pm2:restart@process-name`, 6);
             return { type: "pm2", action: arg, process: subdir || undefined };
+        case "preflight":
+            return { type: "preflight", minFreeMb: arg ? Number(arg) || undefined : undefined };
+        case "apache":
+            return { type: "apache" };
+        case "clean": {
+            // Comma-separated, and each one checked here so a typo is a refusal with
+            // the valid list rather than a step that silently cleans nothing.
+            const wanted = (arg || "dist").split(",").filter(Boolean);
+            const bad = wanted.filter((t) => !CLEAN_TARGETS.includes(t));
+            if (bad.length > 0) {
+                throw new CliError(`clean step can't remove ${bad.join(", ")}.`, 6, `It only removes well-known build output: ${CLEAN_TARGETS.join(", ")}`);
+            }
+            return { type: "clean", targets: wanted, subdir: subdir || undefined };
+        }
+        case "backup":
+            if (arg && arg !== "db") {
+                throw new CliError(`backup step takes "db" or nothing: got "${arg}"`, 6);
+            }
+            return { type: "backup", db: arg === "db", subdir: subdir || undefined };
+        case "health":
+            // `health:/healthz` — the path keeps its slash because only the first
+            // colon splits the token.
+            return { type: "health", path: arg ? `/${arg.replace(/^\//, "")}` : undefined };
+        case "script":
+            if (!arg) {
+                throw new CliError(`script step needs a file: script:deploy/after-build.sh`, 6, "It must be an executable committed to the app's repo. Use --steps-file to pass arguments.");
+            }
+            return { type: "script", file: arg, subdir: subdir || undefined };
         default:
-            throw new CliError(`Unknown step "${token}".`, 6, "Valid: pull, scan, env[:subdir], chown, npm:<script>[@subdir], migrate[:subdir], docker[:<up|restart|build>][@subdir], pm2:<action>[@process]");
+            throw new CliError(`Unknown step "${token}".`, 6, "Valid: preflight[:minFreeMb], pull, scan, backup[:db][@subdir], clean[:a,b][@subdir], env[:subdir], chown, npm:<script>[@subdir], migrate[:subdir], docker[:<up|restart|build>][@subdir], pm2:<action>[@process], apache, health[:path], script:<file>[@subdir]");
     }
 }
 function describeStep(step) {
@@ -57,6 +96,18 @@ function describeStep(step) {
             return `docker compose ${step.action ?? "up"}${step.subdir ? ` (${step.subdir})` : ""}`;
         case "pm2":
             return `pm2 ${step.action}${step.process ? ` ${step.process}` : ""}`;
+        case "preflight":
+            return "pre-flight checks";
+        case "clean":
+            return `clean ${(step.targets ?? ["dist"]).join(", ")}${step.subdir ? ` (${step.subdir})` : ""}`;
+        case "backup":
+            return step.db ? "backup (code + database)" : "backup (code)";
+        case "health":
+            return `health check ${step.path ?? "/"}`;
+        case "apache":
+            return "apache configtest + reload";
+        case "script":
+            return `run ${step.file}${step.subdir ? ` (${step.subdir})` : ""}`;
         default:
             return step.type;
     }
@@ -151,7 +202,7 @@ export function registerPipelineCommands() {
             pipelines.push({ id: "", name, config: { steps } });
             const updated = await savePipelines(c, app.id, pipelines);
             const created = (updated.pipelines ?? []).find((p) => p.name === name);
-            emit({ appId: app.id, pipeline: created }, () => info(`✓ Created pipeline "${name}" on ${app.id} (${steps.length} steps)`));
+            emit({ appId: app.id, pipeline: created }, () => success(`Created pipeline "${name}" on ${app.id} (${steps.length} steps)`));
         },
     }, {
         name: "pipelines set-steps",
@@ -166,7 +217,7 @@ export function registerPipelineCommands() {
                 throw new CliError("A pipeline needs at least one step.", 6);
             const pipelines = (app.pipelines ?? []).map((p) => p.id === pipeline.id ? { ...p, config: { steps } } : p);
             await savePipelines(c, app.id, pipelines);
-            emit({ appId: app.id, pipelineId: pipeline.id, steps }, () => info(`✓ Updated "${pipeline.name}" on ${app.id} (${steps.length} steps)`));
+            emit({ appId: app.id, pipelineId: pipeline.id, steps }, () => success(`Updated "${pipeline.name}" on ${app.id} (${steps.length} steps)`));
         },
     }, {
         name: "pipelines rename",
@@ -179,7 +230,7 @@ export function registerPipelineCommands() {
             const newName = args.arg(2, "new-name");
             const pipelines = (app.pipelines ?? []).map((p) => p.id === pipeline.id ? { ...p, name: newName } : p);
             await savePipelines(c, app.id, pipelines);
-            emit({ appId: app.id, pipelineId: pipeline.id, name: newName }, () => info(`✓ Renamed "${pipeline.name}" → "${newName}"`));
+            emit({ appId: app.id, pipelineId: pipeline.id, name: newName }, () => success(`Renamed "${pipeline.name}" → "${newName}"`));
         },
     }, {
         name: "pipelines delete",
@@ -194,7 +245,7 @@ export function registerPipelineCommands() {
             }
             const pipelines = (app.pipelines ?? []).filter((p) => p.id !== pipeline.id);
             await savePipelines(c, app.id, pipelines);
-            emit({ appId: app.id, deleted: pipeline.id }, () => info(`✓ Deleted pipeline "${pipeline.name}" from ${app.id}`));
+            emit({ appId: app.id, deleted: pipeline.id }, () => success(`Deleted pipeline "${pipeline.name}" from ${app.id}`));
         },
     });
 }

package/dist/commands/reports.js

@@ -1,7 +1,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { basename } from "node:path";
 import { CliError } from "../client.js";
-import { details, emit, info, table } from "../output.js";
+import { details, emit, info, success, table } from "../output.js";
 import { register } from "../registry.js";
 /**
  * Bug reports and feature requests from the terminal.
@@ -184,7 +184,7 @@ export function registerReportCommands() {
             const message = args.arg(1, "message");
             const status = args.flag("status") ? assertStatus(args.flag("status")) : undefined;
             const { report } = await client().request("POST", `/reports/${id}/comments`, { body: message, status });
-            emit({ report }, () => info(`✓ Replied on ${report.id}${status ? ` — now ${report.status}` : ""}`));
+            emit({ report }, () => success(`Replied on ${report.id}${status ? ` — now ${report.status}` : ""}`));
         },
     }, {
         name: "reports status",
@@ -198,7 +198,7 @@ export function registerReportCommands() {
             const id = args.arg(0, "id");
             const status = assertStatus(args.arg(1, "status"));
             const { report } = await client().request("POST", `/reports/${id}/comments`, { body: args.flag("note") ?? "", status });
-            emit({ report }, () => info(`✓ ${report.id} is now ${report.status}`));
+            emit({ report }, () => success(`${report.id} is now ${report.status}`));
         },
     }, {
         name: "reports close",
@@ -213,7 +213,7 @@ export function registerReportCommands() {
             const id = args.arg(0, "id");
             const status = args.bool("wont-do") ? "declined" : "done";
             const { report } = await client().request("POST", `/reports/${id}/comments`, { body: args.flag("note") ?? "", status });
-            emit({ report }, () => info(`✓ Closed ${report.id} as ${report.status}`));
+            emit({ report }, () => success(`Closed ${report.id} as ${report.status}`));
         },
     }, {
         name: "reports reopen",
@@ -222,7 +222,7 @@ export function registerReportCommands() {
         async run({ args, client }) {
             const id = args.arg(0, "id");
             const { report } = await client().request("POST", `/reports/${id}/comments`, { body: args.flag("note") ?? "", status: "open" });
-            emit({ report }, () => info(`✓ Reopened ${report.id}`));
+            emit({ report }, () => success(`Reopened ${report.id}`));
         },
     }, {
         name: "reports attach",
@@ -244,7 +244,7 @@ export function registerReportCommands() {
                 throw new CliError(`Can't read ${filePath}: ${error instanceof Error ? error.message : String(error)}`, 4);
             }
             const file = await client().upload(`/reports/${id}/attachments`, basename(filePath), bytes);
-            emit({ attachment: file }, () => info(`✓ Attached ${file.name} (${humanSize(file.size)}) to ${id}`));
+            emit({ attachment: file }, () => success(`Attached ${file.name} (${humanSize(file.size)}) to ${id}`));
         },
     }, {
         name: "reports download",
@@ -258,7 +258,7 @@ export function registerReportCommands() {
             const bytes = await c.download(`/reports/${id}/attachments/${file.id}`);
             const out = args.flag("out") ?? file.name;
             writeFileSync(out, bytes);
-            emit({ reportId: id, attachment: file.name, out, bytes: bytes.length }, () => info(`✓ Wrote ${out} (${humanSize(bytes.length)})`));
+            emit({ reportId: id, attachment: file.name, out, bytes: bytes.length }, () => success(`Wrote ${out} (${humanSize(bytes.length)})`));
         },
     }, {
         name: "reports file",
@@ -290,7 +290,7 @@ export function registerReportCommands() {
                     attachment = await c.upload(`/reports/${report.id}/attachments`, basename(attach), readFileSync(attach));
                 }
                 catch (error) {
-                    info(`✓ Filed ${report.id} — ${report.title}`);
+                    success(`Filed ${report.id} — ${report.title}`);
                     throw new CliError(`The report was filed, but ${attach} did not attach: ` +
                         (error instanceof Error ? error.message : String(error)), 1, `Try again with: coe reports attach ${report.id} ${attach}`);
                 }

package/dist/commands/resources.js

@@ -1,7 +1,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { CliError } from "../client.js";
-import { details, emit, info, table } from "../output.js";
+import { details, emit, success, table } from "../output.js";
 import { register } from "../registry.js";
 import { resolveApp } from "./apps.js";
 function humanSize(bytes) {
@@ -70,7 +70,7 @@ export function registerResourceCommands() {
             if (description) {
                 await c.request("PATCH", `/registered-apps/${app.id}/files/${file.id}`, { description });
             }
-            emit({ appId: app.id, file }, () => info(`✓ Uploaded ${file.name} (${humanSize(file.size)}) to ${app.id}`));
+            emit({ appId: app.id, file }, () => success(`Uploaded ${file.name} (${humanSize(file.size)}) to ${app.id}`));
         },
     }, {
         name: "files download",
@@ -87,7 +87,7 @@ export function registerResourceCommands() {
             const bytes = await c.download(`/registered-apps/${app.id}/files/${file.id}`);
             const out = args.flag("out") ?? file.name;
             writeFileSync(out, bytes);
-            emit({ appId: app.id, file: file.name, out, bytes: bytes.length }, () => info(`✓ Wrote ${out} (${humanSize(bytes.length)})`));
+            emit({ appId: app.id, file: file.name, out, bytes: bytes.length }, () => success(`Wrote ${out} (${humanSize(bytes.length)})`));
         },
     }, {
         name: "files delete",
@@ -102,7 +102,7 @@ export function registerResourceCommands() {
                 throw new CliError(`This deletes "${file.name}" from ${app.id}.`, 6, "Re-run with --yes to confirm.");
             }
             await c.request("DELETE", `/registered-apps/${app.id}/files/${file.id}`);
-            emit({ appId: app.id, deleted: file.name }, () => info(`✓ Deleted ${file.name} from ${app.id}`));
+            emit({ appId: app.id, deleted: file.name }, () => success(`Deleted ${file.name} from ${app.id}`));
         },
     }, {
         name: "files link",
@@ -118,7 +118,7 @@ export function registerResourceCommands() {
                 name: args.flag("name"),
                 description: args.flag("description"),
             });
-            emit({ appId: app.id, link }, () => info(`✓ Linked "${link.name}" → ${link.url}`));
+            emit({ appId: app.id, link }, () => success(`Linked "${link.name}" → ${link.url}`));
         },
     }, {
         name: "files show",

package/dist/commands/tips.d.ts

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

package/dist/commands/tips.js

@@ -0,0 +1,113 @@
+import { CliError } from "../client.js";
+import { emit, info, style, success, table } from "../output.js";
+import { register } from "../registry.js";
+import { resolveApp } from "./apps.js";
+export function registerTipCommands() {
+    register({
+        name: "tips submit",
+        summary: "Suggest advice for a deploy failure or warning",
+        usage: 'tips submit <app> --kind <failure|warning> --trigger "<text>" --tip "<advice>"',
+        details: [
+            "Nothing you submit is shown to anyone else until a webadmin reviews it.",
+            "",
+            "--trigger is what identifies the situation to the *next* person: the",
+            "warning category, or the distinctive part of an error line. Leave the",
+            "app-specific parts out — paths, ports, process names and SHAs are",
+            "normalised away so the same problem from five apps is one entry with a",
+            "count, and that count is the thing worth acting on.",
+            "",
+            "--tip is the advice itself: what the line means and what to do. Write it",
+            "for somebody who has not just spent an hour on it.",
+            "",
+            "Never put credentials, tokens or connection strings in either field.",
+        ],
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const kind = args.flag("kind");
+            if (kind !== "failure" && kind !== "warning") {
+                throw new CliError("--kind must be failure or warning.", 6);
+            }
+            const trigger = args.flag("trigger");
+            const tip = args.flag("tip");
+            if (!trigger || !tip) {
+                throw new CliError("--trigger and --tip are both required.", 6, 'e.g. coe tips submit myapp --kind warning --trigger "npm warn EBADENGINE" --tip "The app declares an engines range this VM\'s Node does not satisfy; bump the range or the VM\'s Node."');
+            }
+            const result = await c.request("POST", `/registered-apps/${app.id}/deploy-tips`, {
+                kind,
+                trigger,
+                tip,
+                buildId: args.flag("build"),
+                source: args.flag("source"),
+            });
+            emit({ appId: app.id, ...result }, () => {
+                if (result.alreadyReviewed === "rejected") {
+                    info("■ A maintainer has already looked at this trigger and declined advice for it. " +
+                        "Your submission was counted, not queued again — don't keep suggesting it.");
+                    return;
+                }
+                if (result.alreadyReviewed === "accepted") {
+                    success("This trigger already has accepted advice. Counted, not queued again.");
+                    return;
+                }
+                info(result.created
+                    ? `✓ Suggested (${result.id}). It sits in the review queue until a webadmin accepts it.`
+                    : `✓ Folded into an existing suggestion — now reported ${result.occurrences} times.`);
+            });
+        },
+    }, {
+        name: "tips list",
+        summary: "The suggested-advice review queue (webadmin)",
+        usage: "tips list [--status new|accepted|rejected]",
+        details: [
+            "Sorted by most recent activity. `seen` is how many times a trigger has",
+            "been reported — the column to sort your attention by, since one report",
+            "is an anecdote and five from different apps is a gap in the product.",
+        ],
+        async run({ args, client }) {
+            const c = client();
+            const status = args.flag("status") ?? "";
+            const query = status ? `?status=${encodeURIComponent(status)}` : "";
+            const { tips, newCount } = await c.request("GET", `/deploy-tips${query}`);
+            emit({ tips, newCount }, () => {
+                if (tips.length === 0) {
+                    info(status ? `No ${status} suggestions.` : "No suggestions yet.");
+                    return;
+                }
+                table(tips.map((t) => ({
+                    id: t.id,
+                    status: style.state(t.status),
+                    kind: t.kind,
+                    seen: String(t.occurrences),
+                    apps: t.appIds.join(", "),
+                    trigger: t.trigger.slice(0, 48),
+                    tip: t.tip.slice(0, 60),
+                })), ["id", "status", "kind", "seen", "apps", "trigger", "tip"]);
+                if (!status && newCount > 0)
+                    info(`\n${newCount} awaiting review.`);
+            });
+        },
+    }, {
+        name: "tips review",
+        summary: "Accept or reject a suggestion (webadmin)",
+        usage: 'tips review <id> <accepted|rejected> [--note "<why>"]',
+        details: [
+            "Rejecting is not a delete: the entry is kept so the same suggestion is",
+            "recognised and counted rather than re-queued, and whoever submitted it",
+            "is told it has already been declined.",
+        ],
+        async run({ args, client }) {
+            const c = client();
+            const id = args.arg(0, "id");
+            const status = args.arg(1, "status");
+            if (status !== "accepted" && status !== "rejected") {
+                throw new CliError("Status must be accepted or rejected.", 6);
+            }
+            const { tip } = await c.request("POST", `/deploy-tips/${id}/review`, {
+                status,
+                note: args.flag("note"),
+            });
+            emit({ tip }, () => success(`${tip.id} marked ${tip.status}.`));
+        },
+    });
+}

package/dist/index.js

@@ -12,8 +12,9 @@ import { registerLogCommands } from "./commands/logs.js";
 import { registerPipelineCommands } from "./commands/pipelines.js";
 import { registerReportCommands } from "./commands/reports.js";
 import { registerResourceCommands } from "./commands/resources.js";
+import { registerTipCommands } from "./commands/tips.js";
 import { registerVmCommands } from "./commands/vms.js";
-import { info, setJsonMode } from "./output.js";
+import { failure, setJsonMode } from "./output.js";
 import { allCommands, findCommand, register } from "./registry.js";
 registerAuthCommands();
 registerAppCommands();
@@ -28,6 +29,7 @@ registerLogCommands();
 registerVmCommands();
 registerReportCommands();
 registerDirectoryCommands();
+registerTipCommands();
 function parseArgs(argv) {
     const positional = [];
     const flags = {};
@@ -69,6 +71,19 @@ function parseArgs(argv) {
         bool(name) {
             return flags[name] !== undefined;
         },
+        num(name, fallback) {
+            const raw = flags[name];
+            if (raw === undefined)
+                return fallback;
+            if (raw === true) {
+                throw new CliError(`--${name} needs a number.`, 6, `e.g. --${name} ${fallback}`);
+            }
+            const value = Number(raw);
+            if (!Number.isFinite(value)) {
+                throw new CliError(`--${name} must be a number, not "${raw}".`, 6);
+            }
+            return value;
+        },
     };
 }
 function printHelp() {
@@ -123,11 +138,9 @@ async function main() {
 }
 main().catch((error) => {
     if (error instanceof CliError) {
-        info(`error: ${error.message}`);
-        if (error.hint)
-            info(`  ${error.hint}`);
+        failure(error.message, error.hint);
         process.exit(error.exitCode);
     }
-    info(`error: ${error instanceof Error ? error.message : String(error)}`);
+    failure(error instanceof Error ? error.message : String(error));
     process.exit(1);
 });

package/dist/output.d.ts

@@ -8,12 +8,29 @@
  */
 export declare function setJsonMode(on: boolean): void;
 export declare function isJsonMode(): boolean;
+/** Marks a value for the reader's eye. Safe to pass into `table` or `details`. */
+export declare const style: {
+    ok: (t: string) => string;
+    bad: (t: string) => string;
+    warn: (t: string) => string;
+    muted: (t: string) => string;
+    strong: (t: string) => string;
+    id: (t: string) => string;
+    /** A build/process state, coloured by what it means rather than by name. */
+    state: (t: string) => string;
+};
 /** The command's result. In JSON mode this is the only thing on stdout. */
 export declare function emit(data: unknown, human: () => void): void;
 /** Progress/status chatter. Always stderr, so it never pollutes piped JSON. */
 export declare function info(message: string): void;
 export declare function warn(message: string): void;
+/** A command that did what it was asked. */
+export declare function success(message: string): void;
+/** How a failure is rendered, including the hint that says what to do next. */
+export declare function failure(message: string, hint?: string): void;
 /** Minimal column alignment — no dependency, and stable enough to eyeball. */
 export declare function table(rows: Array<Record<string, string>>, columns: string[]): void;
 /** Key/value block for `show`-style commands. */
 export declare function details(pairs: Array<[string, string]>): void;
+/** A heading above a block, for commands that print more than one. */
+export declare function heading(text: string): void;

package/dist/output.js

@@ -13,6 +13,71 @@ export function setJsonMode(on) {
 export function isJsonMode() {
     return jsonMode;
 }
+// ---- colour ----------------------------------------------------------------
+/**
+ * Colour only when a person is actually looking at that stream.
+ *
+ * Checked per stream, not once: stdout is frequently redirected while stderr
+ * is still a terminal (`coe builds app > builds.txt`), and escape codes in the
+ * redirected half would corrupt a file someone is about to parse. `NO_COLOR`
+ * is honoured because it is the convention, and `FORCE_COLOR` exists so output
+ * can be inspected through a pipe when working on this file.
+ */
+function allowColor(stream) {
+    if (process.env.NO_COLOR !== undefined)
+        return false;
+    if (process.env.FORCE_COLOR)
+        return true;
+    return stream.isTTY === true && process.env.TERM !== "dumb";
+}
+const CODES = {
+    reset: "\u001B[0m",
+    bold: "\u001B[1m",
+    dim: "\u001B[2m",
+    red: "\u001B[31m",
+    green: "\u001B[32m",
+    yellow: "\u001B[33m",
+    blue: "\u001B[34m",
+    cyan: "\u001B[36m",
+};
+function paint(text, style, stream) {
+    return allowColor(stream) ? `${CODES[style]}${text}${CODES.reset}` : text;
+}
+/** Style for stdout (data). Never colours in JSON mode. */
+const out = (text, style) => jsonMode ? text : paint(text, style, process.stdout);
+/** Style for stderr (chatter). */
+const err = (text, style) => paint(text, style, process.stderr);
+/**
+ * Length as a terminal renders it.
+ *
+ * Column widths are computed from cell contents, and an escape sequence is
+ * zero columns wide but several characters long — measuring the raw string
+ * makes every coloured cell over-padded and the table ragged.
+ */
+// eslint-disable-next-line no-control-regex
+const ANSI = /\u001B\[[0-9;]*m/g;
+const visibleLength = (text) => text.replace(ANSI, "").length;
+/** Marks a value for the reader's eye. Safe to pass into `table` or `details`. */
+export const style = {
+    ok: (t) => out(t, "green"),
+    bad: (t) => out(t, "red"),
+    warn: (t) => out(t, "yellow"),
+    muted: (t) => out(t, "dim"),
+    strong: (t) => out(t, "bold"),
+    id: (t) => out(t, "cyan"),
+    /** A build/process state, coloured by what it means rather than by name. */
+    state: (t) => {
+        const s = t.toLowerCase();
+        if (["ok", "online", "up", "done", "accepted", "active", "yes"].includes(s))
+            return style.ok(t);
+        if (["failed", "error", "down", "stopped", "rejected", "errored"].includes(s))
+            return style.bad(t);
+        if (["cancelled", "running", "new", "pending", "queued", "unknown"].includes(s))
+            return style.warn(t);
+        return t;
+    },
+};
+// ---- writers ---------------------------------------------------------------
 /** The command's result. In JSON mode this is the only thing on stdout. */
 export function emit(data, human) {
     if (jsonMode) {
@@ -26,18 +91,29 @@ export function info(message) {
     process.stderr.write(`${message}\n`);
 }
 export function warn(message) {
-    process.stderr.write(`warning: ${message}\n`);
+    process.stderr.write(`${err("warning:", "yellow")} ${message}\n`);
+}
+/** A command that did what it was asked. */
+export function success(message) {
+    process.stderr.write(`${err("✓", "green")} ${message}\n`);
+}
+/** How a failure is rendered, including the hint that says what to do next. */
+export function failure(message, hint) {
+    process.stderr.write(`${err("error:", "red")} ${message}\n`);
+    if (hint)
+        process.stderr.write(`${err(`  ${hint}`, "dim")}\n`);
 }
 /** Minimal column alignment — no dependency, and stable enough to eyeball. */
 export function table(rows, columns) {
     if (rows.length === 0) {
-        info("(none)");
+        info(err("(none)", "dim"));
         return;
     }
-    const width = (col) => Math.max(col.length, ...rows.map((r) => (r[col] ?? "").length));
+    const width = (col) => Math.max(col.length, ...rows.map((r) => visibleLength(r[col] ?? "")));
     const widths = columns.map(width);
-    const line = (cells) => cells.map((c, i) => c.padEnd(i === cells.length - 1 ? 0 : widths[i])).join("  ").trimEnd();
-    process.stdout.write(`${line(columns.map((c) => c.toUpperCase()))}\n`);
+    const pad = (cell, i, last) => last ? cell : cell + " ".repeat(Math.max(0, widths[i] - visibleLength(cell)));
+    const line = (cells) => cells.map((c, i) => pad(c, i, i === cells.length - 1)).join("  ").trimEnd();
+    process.stdout.write(`${out(line(columns.map((c) => c.toUpperCase())), "dim")}\n`);
     for (const row of rows) {
         process.stdout.write(`${line(columns.map((c) => row[c] ?? ""))}\n`);
     }
@@ -46,6 +122,10 @@ export function table(rows, columns) {
 export function details(pairs) {
     const width = Math.max(...pairs.map(([k]) => k.length));
     for (const [k, v] of pairs) {
-        process.stdout.write(`${k.padEnd(width)}  ${v}\n`);
+        process.stdout.write(`${out(k.padEnd(width), "dim")}  ${v}\n`);
     }
 }
+/** A heading above a block, for commands that print more than one. */
+export function heading(text) {
+    process.stderr.write(`\n${err(text.toUpperCase(), "bold")}\n`);
+}

package/dist/registry.d.ts

@@ -12,6 +12,14 @@ export interface Args {
     /** A flag's value, or undefined. `--flag` with no value reads as true. */
     flag(name: string): string | undefined;
     bool(name: string): boolean;
+    /**
+     * A numeric flag, or the fallback when it wasn't given.
+     *
+     * Rejects a value that isn't a number instead of quietly falling back:
+     * `--limit abc` used to print the default twenty rows and exit 0, which
+     * reads exactly like a limit that worked.
+     */
+    num(name: string, fallback: number): number;
 }
 export interface CommandContext {
     args: Args;

package/dist/types.d.ts

@@ -4,6 +4,7 @@
  * on its own against a deployed server, so it must not depend on the API's
  * build output.
  */
+export type CleanTarget = "node_modules" | "dist" | "build" | ".next" | ".nuxt" | ".cache" | "target" | "vendor";
 export type DeployStep = {
     type: "pull";
 } | {
@@ -28,6 +29,42 @@ export type DeployStep = {
     type: "pm2";
     action: string;
     process?: string;
+}
+/** Checks the rest of the pipeline can run before any of it does. */
+ | {
+    type: "preflight";
+    minFreeMb?: number;
+}
+/** Removes build artefacts, from a fixed allowlist of directory names. */
+ | {
+    type: "clean";
+    subdir?: string;
+    targets?: CleanTarget[];
+}
+/** Records the rollback point, and optionally dumps the app's database. */
+ | {
+    type: "backup";
+    subdir?: string;
+    db?: boolean;
+    keepDays?: number;
+}
+/** Asks the app over HTTP whether it works — what pm2 can't tell you. */
+ | {
+    type: "health";
+    path?: string;
+    status?: number;
+    retries?: number;
+}
+/** apachectl configtest, then a graceful reload. */
+ | {
+    type: "apache";
+}
+/** Runs an executable committed to the app's own repo. */
+ | {
+    type: "script";
+    subdir?: string;
+    file: string;
+    args?: string[];
 };
 export interface DeployConfig {
     steps: DeployStep[];
@@ -90,6 +127,14 @@ export interface RegisteredApp {
     createdAt: string;
     updatedAt: string;
 }
+/** A category of warning a build produced, with how many times it occurred. */
+export interface BuildWarning {
+    code: string;
+    label: string;
+    count: number;
+    samples: string[];
+    hint?: string;
+}
 export interface Build {
     id: string;
     appId: string;
@@ -97,9 +142,25 @@ export interface Build {
     pipelineName?: string;
     source: string;
     by?: string;
-    status: "running" | "ok" | "failed";
+    /** `cancelled` is its own outcome — somebody stopped it, it didn't break. */
+    status: "running" | "ok" | "failed" | "cancelled";
     startedAt: string;
     finishedAt?: string;
     commit?: string;
     commitSubject?: string;
+    /** What was live before this build — what rolling it back would deploy. */
+    previousCommit?: string;
+    previousCommitSubject?: string;
+    warnings?: BuildWarning[];
+    /** Whether this build's console is still stored (only the recent ones are). */
+    hasLog?: boolean;
+    cancelledBy?: string;
+    error?: string;
+}
+/** One commit on a branch, as `coe commits` lists them. */
+export interface CommitSummary {
+    sha: string;
+    subject: string;
+    author: string;
+    date: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uic-coe-connect/cli",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "The coe CLI \u2014 manage COEConnect apps (pipelines, deploys, access, env) from a terminal, with browser-approved auth. Designed to be driven by an AI agent.",
   "type": "module",
   "bin": {