@coderook/cli 0.36.0 → 0.37.0

package/dist/cli/src/runner.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.maskSecrets = maskSecrets;
 exports.withoutCredentials = withoutCredentials;
 exports.claim = claim;
 exports.defaultLabels = defaultLabels;
@@ -38,6 +39,15 @@ const download_js_1 = require("../../cbx/src/core/download.js");
 const identify_js_1 = require("../../cbx/src/core/identify.js");
 const config_js_1 = require("./config.js");
 const progress_js_1 = require("./progress.js");
+/** Replace each secret's value with ***, longest first. */
+function maskSecrets(text, secrets) {
+    let out = text;
+    for (const value of secrets) {
+        if (value.length >= 4 && out.includes(value))
+            out = out.split(value).join("***");
+    }
+    return out;
+}
 /** How often to tell the service the machine is still working. */
 const HEARTBEAT_MS = 30_000;
 /** How often log lines are sent up while a command is running. */
@@ -65,7 +75,9 @@ async function call(route, options = {}) {
     const text = await response.text();
     const body = text ? JSON.parse(text) : {};
     if (!response.ok) {
-        throw new Error(body?.error?.message ?? `${route} failed (${response.status})`);
+        const error = new Error(body?.error?.message ?? `${route} failed (${response.status})`);
+        error.code = body?.error?.code;
+        throw error;
     }
     return body;
 }
@@ -333,6 +345,32 @@ function patternMatcher(pattern) {
  */
 async function performRun(repositoryId, run, runner) {
     const progress = new progress_js_1.RunProgress();
+    /* Set when somebody cancels the run on CodeRook: the work stops now rather than when it ends. */
+    let cancelled = false;
+    /* Set when the workflow's time limit passes on this machine. */
+    let timedOut = false;
+    let limitTimer;
+    const secrets = (run.secretNames ?? [])
+        .map((name) => run.environment?.[name] ?? "")
+        .filter(Boolean)
+        .sort((a, b) => b.length - a.length);
+    let child = null;
+    const stopChild = () => {
+        if (!child?.pid || child.exitCode !== null)
+            return;
+        if (process.platform === "win32") {
+            /* The command runs through a shell; the whole tree goes, not only the shell. */
+            (0, node_child_process_1.spawn)("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore" });
+        }
+        else {
+            try {
+                process.kill(-child.pid, "SIGTERM");
+            }
+            catch {
+                child.kill("SIGTERM");
+            }
+        }
+    };
     const logs = new LogShipper(repositoryId, run.runId, (line) => progress.say(line));
     const started = Date.now();
     const workspace = await (0, promises_1.mkdtemp)(node_path_1.default.join((0, node_os_1.tmpdir)(), "coderook-run-"));
@@ -343,13 +381,18 @@ async function performRun(repositoryId, run, runner) {
             void call(`/v1/repositories/${repositoryId}/runs/${run.runId}/heartbeat`, {
                 method: "POST",
                 body: { runner },
-            }).catch(() => {
+            }).catch((error) => {
                 /*
-                  A lost lease means the service has given this run to somebody else,
-                  and the local process is now doing work nobody will accept. Stopping
-                  the heartbeat is enough: the report at the end will be refused too,
-                  and the run that matters is the one the other machine is doing.
+                  Cancelled: end the work now. A lost lease otherwise means the service
+                  has given this run to somebody else, and the local process is doing
+                  work nobody will accept; the report at the end changes nothing, and
+                  the run that matters is the one the other machine is doing.
                 */
+                if (error?.code === "run_cancelled" && !cancelled) {
+                    cancelled = true;
+                    logs.add("Cancelled on CodeRook. Stopping.", "stderr");
+                    stopChild();
+                }
             });
         }, HEARTBEAT_MS);
         if (run.versionId) {
@@ -384,11 +427,18 @@ async function performRun(repositoryId, run, runner) {
               Which shell is the platform's own, so a Windows machine reads it the
               way a Windows user wrote it.
             */
-            const child = (0, node_child_process_1.spawn)(command, {
+            if (cancelled) {
+                settle(1);
+                return;
+            }
+            child = (0, node_child_process_1.spawn)(command, {
                 cwd: directory,
                 shell: true,
+                /* Its own process group off Windows, so cancelling can stop everything it started. */
+                detached: process.platform !== "win32",
                 env: {
                     ...withoutCredentials(process.env),
+                    ...(run.environment ?? {}),
                     CI: "true",
                     CODEROOK_RUN: String(run.number),
                     CODEROOK_VERSION: run.versionSequence
@@ -402,7 +452,7 @@ async function performRun(repositoryId, run, runner) {
               can tell a slow build from a stuck one.
             */
             const tee = (chunk, stream) => {
-                const text = chunk.toString("utf8");
+                const text = maskSecrets(chunk.toString("utf8"), secrets);
                 logs.add(text, stream);
                 progress.say(text);
             };
@@ -413,7 +463,16 @@ async function performRun(repositoryId, run, runner) {
                 settle(1);
             });
             child.on("close", (status) => settle(status ?? 1));
+            if (run.timeoutMinutes) {
+                limitTimer = setTimeout(() => {
+                    timedOut = true;
+                    logs.add(`Stopped: past this workflow's time limit of ${run.timeoutMinutes} minutes.`, "stderr");
+                    stopChild();
+                }, run.timeoutMinutes * 60_000);
+            }
         });
+        if (limitTimer)
+            clearTimeout(limitTimer);
         /*
           What it built, before the folder goes.
     
@@ -433,6 +492,10 @@ async function performRun(repositoryId, run, runner) {
         }
         await logs.flush();
         const seconds = Math.round((Date.now() - started) / 1000);
+        if (timedOut)
+            return { status: "failed", summary: `Stopped after its time limit of ${run.timeoutMinutes} minutes` };
+        if (cancelled)
+            return { status: "cancelled", summary: `Cancelled after ${seconds}s` };
         return code === 0
             ? { status: "passed", summary: `Passed in ${seconds}s` }
             : { status: "failed", summary: `Exited ${code} after ${seconds}s` };
@@ -448,6 +511,8 @@ async function performRun(repositoryId, run, runner) {
           goes out would overwrite the verdict the caller is about to print.
         */
         progress.done();
+        if (limitTimer)
+            clearTimeout(limitTimer);
         if (beating)
             clearInterval(beating);
         if (flushing)

package/dist/cli/src/service_commands.js

@@ -19,9 +19,12 @@ exports.commandWatch = commandWatch;
 exports.commandWorkflows = commandWorkflows;
 exports.commandRuns = commandRuns;
 exports.commandLogs = commandLogs;
+exports.commandCancel = commandCancel;
+exports.commandRerun = commandRerun;
 exports.commandTokens = commandTokens;
 exports.commandDelete = commandDelete;
 exports.commandHooks = commandHooks;
+const actions_command_js_1 = require("./actions_command.js");
 const node_process_1 = __importDefault(require("node:process"));
 const promises_1 = require("node:readline/promises");
 const api_js_1 = require("./api.js");
@@ -129,14 +132,33 @@ async function commandRelease(parsed) {
         console.error((0, colour_js_1.red)("--downloads is public or private: cbx release v1.0 --downloads public"));
         return 1;
     }
-    const name = parsed.positional[0];
-    if (!name && downloads === undefined) {
+    /* `cbx release publish` publishes a draft (backend release_extras.ts). */
+    const publishing = parsed.positional[0] === "publish";
+    const name = publishing ? undefined : parsed.positional[0];
+    if (!name && downloads === undefined && !publishing) {
         console.error((0, colour_js_1.red)("Name the release: cbx release v1.0"));
         return 1;
     }
-    const project = await (0, project_commands_js_1.resolveProject)(name ? parsed.positional[1] : parsed.positional[0]);
+    const project = await (0, project_commands_js_1.resolveProject)(name || publishing ? parsed.positional[1] : parsed.positional[0]);
     if (!project)
         return 1;
+    if (publishing) {
+        const listing = await (0, api_js_1.callApi)(`/v1/repositories/${encodeURIComponent(project.id)}/releases`);
+        const drafts = listing.drafts ?? [];
+        const asked = parsed.flags.get("version");
+        const draft = typeof asked === "string"
+            ? drafts.find((one) => String(one.sequence) === asked.replace(/^v/i, ""))
+            : drafts.length === 1
+                ? drafts[0]
+                : undefined;
+        if (!draft) {
+            console.error((0, colour_js_1.red)(drafts.length ? `Which draft? ${drafts.map((one) => `${one.name} (--version ${one.sequence})`).join(", ")}` : "This project has no draft releases."));
+            return 1;
+        }
+        const published = await (0, api_js_1.callApi)(`/v1/repositories/${encodeURIComponent(project.id)}/versions/${encodeURIComponent(draft.versionId)}/release-draft/publish`, { method: "POST" });
+        console.log(`${(0, colour_js_1.green)("Published")} ${(0, colour_js_1.bold)(published.name)} ${(0, colour_js_1.dim)("at")} v${published.sequence}`);
+        return 0;
+    }
     const all = await (0, api_js_1.versions)(project.id);
     if (!all.length) {
         console.error((0, colour_js_1.red)("This project has no versions to release."));
@@ -170,10 +192,29 @@ async function commandRelease(parsed) {
         console.error((0, colour_js_1.red)(`This project has no version ${String(wanted)}.`));
         return 1;
     }
-    const notes = parsed.flags.get("notes");
+    let notes = parsed.flags.get("notes");
+    /* Notes written from what changed since the last release (release_extras.ts). */
+    if (parsed.flags.has("generate-notes")) {
+        const written = await (0, api_js_1.callApi)(`/v1/repositories/${encodeURIComponent(project.id)}/versions/${encodeURIComponent(target.id)}/release-notes`);
+        notes = typeof notes === "string" ? `${notes}\n\n${written.notes}` : written.notes;
+    }
+    const channelFlag = parsed.flags.get("channel");
+    const options = {
+        ...(parsed.flags.has("prerelease") ? { prerelease: true } : {}),
+        ...(typeof channelFlag === "string" ? { channel: channelFlag } : {}),
+    };
+    if (name && parsed.flags.has("draft")) {
+        await (0, api_js_1.callApi)(`/v1/repositories/${encodeURIComponent(project.id)}/versions/${encodeURIComponent(target.id)}/release-draft`, {
+            method: "PUT",
+            body: { name, notes: typeof notes === "string" ? notes : null, ...options },
+        });
+        console.log(`${(0, colour_js_1.green)("Drafted")} ${(0, colour_js_1.bold)(name)} ${(0, colour_js_1.dim)("at")} v${target.sequence}${(0, colour_js_1.dim)(" — nothing is public yet.")}`);
+        console.log((0, colour_js_1.dim)(`  Attach builds with cbx attach, then: cbx release publish --version ${target.sequence}`));
+        return 0;
+    }
     if (name) {
         try {
-            await (0, api_js_1.markRelease)(project.id, target.id, name, typeof notes === "string" ? notes : null);
+            await (0, api_js_1.markRelease)(project.id, target.id, name, typeof notes === "string" ? notes : null, options);
         }
         catch (error) {
             console.error((0, colour_js_1.red)(error instanceof Error ? error.message : String(error)));
@@ -346,6 +387,11 @@ async function commandWatch(parsed) {
 }
 /** The automations a project has, and how they have been going. */
 async function commandWorkflows(parsed) {
+    /* `cbx actions check …` and `cbx actions set …` (actions_command.ts). */
+    if (parsed.positional[0] === "check")
+        return (0, actions_command_js_1.commandCheckWorkflows)(parsed);
+    if (parsed.positional[0] === "set")
+        return (0, actions_command_js_1.commandSetWorkflow)(parsed);
     const project = await (0, project_commands_js_1.resolveProject)(typeof parsed.flags.get("project") === "string"
         ? String(parsed.flags.get("project"))
         : parsed.positional[0]);
@@ -559,6 +605,27 @@ async function commandLogs(parsed) {
         }
         return 1;
     }
+    /*
+      --follow: keep printing as the runner sends, until the run ends. A build
+      that takes ten minutes shows its progress rather than nothing.
+    */
+    if (parsed.flags.has("follow")) {
+        console.log(`${(0, colour_js_1.accent)(`#${run.number}`)} ${(0, colour_js_1.bold)(run.workflow)} — following until it ends`);
+        let shown = 0;
+        let state = run;
+        for (;;) {
+            const lines = await (0, api_js_1.runLogs)(project.id, run.id);
+            for (const line of lines.slice(shown))
+                console.log(line.stream === "stderr" ? (0, colour_js_1.red)(line.line) : line.line);
+            shown = Math.max(shown, lines.length);
+            if (state.status !== "queued" && state.status !== "running")
+                break;
+            await new Promise((resolve) => setTimeout(resolve, 2000));
+            state = (await (0, api_js_1.runs)(project.id)).find((one) => one.id === run.id) ?? state;
+        }
+        console.log(`${statusText(state.status)}${state.summary ? ` · ${(0, colour_js_1.dim)(state.summary)}` : ""}`);
+        return state.status === "failed" ? 1 : 0;
+    }
     const lines = await (0, api_js_1.runLogs)(project.id, run.id);
     console.log(`${(0, colour_js_1.accent)(`#${run.number}`)} ${(0, colour_js_1.bold)(run.workflow)} — ${statusText(run.status)}` +
         `${run.summary ? ` · ${(0, colour_js_1.dim)(run.summary)}` : ""}`);
@@ -578,6 +645,55 @@ async function commandLogs(parsed) {
     }
     return run.status === "failed" ? 1 : 0;
 }
+/** Stop a run that is waiting or working, by the number people say. */
+async function commandCancel(parsed) {
+    const asked = parsed.positional[0];
+    const number = Number((asked ?? "").replace(/^#/, ""));
+    if (!asked || !Number.isInteger(number) || number < 1) {
+        console.error((0, colour_js_1.red)("Which run? Try: cbx cancel 12"));
+        return 1;
+    }
+    const project = await (0, project_commands_js_1.resolveProject)(parsed.positional[1]);
+    if (!project)
+        return 1;
+    const run = (await (0, api_js_1.runs)(project.id)).find((one) => one.number === number);
+    if (!run) {
+        console.error((0, colour_js_1.red)(`${project.name} has no run #${number}.`));
+        return 1;
+    }
+    if (run.status !== "queued" && run.status !== "running") {
+        console.error((0, colour_js_1.red)(`#${number} has already finished (${run.status}).`));
+        return 1;
+    }
+    await (0, api_js_1.cancelRun)(project.id, run.id);
+    console.log(`${(0, colour_js_1.accent)(`#${number}`)} cancelled. A runner working on it stops at its next heartbeat.`);
+    return 0;
+}
+/** Run a finished run again, against the same save. */
+async function commandRerun(parsed) {
+    const asked = parsed.positional[0];
+    const number = Number((asked ?? "").replace(/^#/, ""));
+    if (!asked || !Number.isInteger(number) || number < 1) {
+        console.error((0, colour_js_1.red)("Which run? Try: cbx rerun 12"));
+        return 1;
+    }
+    const project = await (0, project_commands_js_1.resolveProject)(parsed.positional[1]);
+    if (!project)
+        return 1;
+    const run = (await (0, api_js_1.runs)(project.id)).find((one) => one.number === number);
+    if (!run) {
+        console.error((0, colour_js_1.red)(`${project.name} has no run #${number}.`));
+        return 1;
+    }
+    if (run.status === "queued" || run.status === "running") {
+        console.error((0, colour_js_1.red)(`#${number} is still going. Cancel it first with cbx cancel ${number}.`));
+        return 1;
+    }
+    const queued = await (0, api_js_1.rerunRun)(project.id, run.id);
+    console.log(`${(0, colour_js_1.accent)(`#${queued.number}`)} queued: #${number} again, against the same save.`);
+    console.log((0, colour_js_1.dim)(`Follow it with: cbx logs ${queued.number} --follow`));
+    return 0;
+}
 /** The tokens that can act as this account. */
 async function commandTokens(parsed) {
     const revoke = parsed.flags.get("revoke");

package/dist/cli/src/verify_command.js

@@ -0,0 +1,135 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PINNED_RELEASE_KEY = void 0;
+exports.manifestBytes = manifestBytes;
+exports.signatureValid = signatureValid;
+exports.commandVerify = commandVerify;
+exports.commandDeps = commandDeps;
+/**
+ * `cbx verify` — check a downloaded file against its release's signed manifest.
+ * `cbx deps`   — known vulnerabilities in a save's dependencies.
+ *
+ * verify fetches the release's manifest (every file with its size and SHA-256,
+ * signed with CodeRook's Ed25519 release key), checks the signature, then
+ * hashes the local file and compares. The key is the one this copy of cbx was
+ * built with when it has one, otherwise the one the service publishes, and
+ * --key pins another.
+ */
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const api_js_1 = require("./api.js");
+const colour_js_1 = require("./colour.js");
+const config_js_1 = require("./config.js");
+const project_commands_js_1 = require("./project_commands.js");
+/** CodeRook's release key as published when this version of cbx was built; empty means ask the service. */
+exports.PINNED_RELEASE_KEY = "H8/DZlJXqNjUBOT7OXIoR4aEM+gcfhxurfdCrk83wNA=";
+/** The exact bytes the service signs: the same key order, files by name. */
+function manifestBytes(manifest) {
+    return new TextEncoder().encode(JSON.stringify({
+        format: manifest.format,
+        project: manifest.project,
+        release: manifest.release,
+        version: manifest.version,
+        channel: manifest.channel,
+        prerelease: manifest.prerelease,
+        publishedAt: manifest.publishedAt,
+        files: [...manifest.files]
+            .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+            .map((file) => ({ name: file.name, size: file.size, sha256: file.sha256 })),
+    }));
+}
+async function signatureValid(publicKey, manifest, signature) {
+    const key = await node_crypto_1.webcrypto.subtle.importKey("raw", Buffer.from(publicKey, "base64"), { name: "Ed25519" }, false, ["verify"]);
+    return node_crypto_1.webcrypto.subtle.verify({ name: "Ed25519" }, key, Buffer.from(signature, "base64"), manifestBytes(manifest));
+}
+async function sha256File(file) {
+    const hash = (0, node_crypto_1.createHash)("sha256");
+    await new Promise((resolve, reject) => {
+        (0, node_fs_1.createReadStream)(file)
+            .on("data", (chunk) => hash.update(chunk))
+            .on("end", () => resolve())
+            .on("error", reject);
+    });
+    return hash.digest("hex");
+}
+async function commandVerify(parsed) {
+    const [project, release, ...files] = parsed.positional;
+    if (!project || !project.includes("/") || !release || !files.length) {
+        console.error((0, colour_js_1.red)("Try: cbx verify owner/project v1.0 ./app-setup.exe"));
+        return 1;
+    }
+    const [owner, slug] = project.split("/");
+    const base = `${(0, config_js_1.apiOrigin)()}/v1/public/projects/${encodeURIComponent(owner)}/${encodeURIComponent(slug)}/releases/${encodeURIComponent(release)}`;
+    const response = await fetch(`${base}/manifest.json`, { signal: AbortSignal.timeout(60_000) });
+    if (!response.ok) {
+        console.error((0, colour_js_1.red)(`No signed manifest for ${project} ${release} (${response.status}).`));
+        return 1;
+    }
+    const answer = (await response.json());
+    const pinned = parsed.flags.get("key");
+    const key = typeof pinned === "string" ? pinned : exports.PINNED_RELEASE_KEY && (0, config_js_1.apiOrigin)() === config_js_1.DEFAULT_API ? exports.PINNED_RELEASE_KEY : answer.publicKey;
+    if (!(await signatureValid(key, answer.manifest, answer.signature))) {
+        console.error((0, colour_js_1.red)("The manifest's signature does not check out. Do not trust these files."));
+        return 1;
+    }
+    console.log(`${(0, colour_js_1.green)("✓")} Signed manifest for ${(0, colour_js_1.bold)(`${answer.manifest.project} ${answer.manifest.release}`)} ${(0, colour_js_1.dim)(`(key ${key.slice(0, 12)}…)`)}`);
+    let failed = false;
+    for (const file of files) {
+        const name = node_path_1.default.basename(file);
+        const entry = answer.manifest.files.find((one) => one.name === name);
+        if (!entry) {
+            console.log(`${(0, colour_js_1.red)("×")} ${name}: not one of this release's files`);
+            failed = true;
+            continue;
+        }
+        const size = (await (0, promises_1.stat)(file)).size;
+        const digest = await sha256File(file);
+        if (size !== entry.size || digest !== entry.sha256) {
+            console.log(`${(0, colour_js_1.red)("×")} ${name}: does not match (${size} bytes, ${digest.slice(0, 16)}…; expected ${entry.size} bytes, ${entry.sha256.slice(0, 16)}…)`);
+            failed = true;
+        }
+        else {
+            console.log(`${(0, colour_js_1.green)("✓")} ${name} ${(0, colour_js_1.dim)(`${digest.slice(0, 16)}…`)}`);
+        }
+    }
+    return failed ? 1 : 0;
+}
+async function commandDeps(parsed) {
+    const named = parsed.flags.get("project");
+    const project = await (0, project_commands_js_1.resolveProject)(typeof named === "string" ? named : undefined);
+    if (!project)
+        return 1;
+    const all = await (0, api_js_1.versions)(project.id);
+    const asked = parsed.positional[0];
+    const target = asked
+        ? all.find((one) => String(one.sequence) === asked.replace(/^v/i, ""))
+        : all.reduce((newest, one) => (!newest || one.sequence > newest.sequence ? one : newest), undefined);
+    if (!target) {
+        console.error((0, colour_js_1.red)(asked ? `${project.name} has no version ${asked}.` : "This project has no saves yet."));
+        return 1;
+    }
+    const report = await (0, api_js_1.callApi)(`/v1/repositories/${encodeURIComponent(project.id)}/versions/${encodeURIComponent(target.id)}/dependencies${parsed.flags.has("fresh") ? "?fresh=1" : ""}`);
+    if (report.state === "none") {
+        console.log((0, colour_js_1.dim)(`v${target.sequence} has no lockfile to check.`));
+        return 0;
+    }
+    if (report.state === "failed") {
+        console.error((0, colour_js_1.red)(`Could not ask OSV: ${report.error ?? "unknown"}`));
+        return 1;
+    }
+    if (!report.findings.length) {
+        console.log(`${(0, colour_js_1.green)("✓")} v${target.sequence}: ${report.packages} packages, no known vulnerabilities.`);
+        return 0;
+    }
+    console.log((0, colour_js_1.red)(`v${target.sequence}: ${report.findings.length} of ${report.packages} packages have known vulnerabilities`));
+    for (const finding of report.findings) {
+        console.log(`  ${(0, colour_js_1.accent)(`${finding.name}@${finding.version}`)} ${(0, colour_js_1.dim)(`${finding.ecosystem} · ${finding.file}`)}`);
+        console.log(`    ${finding.ids.slice(0, 4).join(", ")}${finding.summary ? (0, colour_js_1.dim)(` — ${finding.summary}`) : ""}`);
+    }
+    return 1;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coderook/cli",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "description": "The command line for CodeRook (coderook.com): version control and project hosting for projects of any size. Every save is a compressed snapshot, private or public, never used to train AI.",
   "license": "Apache-2.0",
   "homepage": "https://coderook.com",

package/skills/coderook/SKILL.md

@@ -306,24 +306,56 @@ unasked. `--ship` attaches the results to the newest save, so **ask before
 `--ship`**, as before any save. A project's own build description lives in
 `coderook.build.json`.
 
-## Reviewing proposals with GitHub tools
+## Pull requests
 
-When someone wants CodeRabbit, Blacksmith or GitHub Actions on their CodeRook
-proposals, that is `cbx github`: a GitHub repository mirrors each open
-proposal as a pull request, and the results come back as checks named
-`github/<check>` and `review/<reviewer>`.
+A pull request is a proposal: a line offered to another line (`cbx propose`
+opens one). Read and review them with `cbx pr`:
 
 ```bash
-cbx github setup OWNER/REPO   # token limited to this project, secret, workflow file
-cbx submit                    # the workflow has to be saved into the project
-cbx github sync --repo OWNER/REPO
+cbx pr list                         # what is open on this project
+cbx pr view M-3                     # reviews, checks, conversation, what blocks merging
+cbx pr files M-3                    # what it changes
+cbx pr comment M-3 --line src/app.ts:42 -m "…"
+cbx pr approve M-3                  # or request-changes M-3 -m "…"
+cbx pr merge M-3
 ```
 
-**Ask before `setup`**: it creates a token and stores it in GitHub. The person
-adds the second secret, `CODEROOK_BRIDGE_PUSH` (a GitHub fine-grained token
-with Contents and Pull requests read/write), themselves, because it is their
-GitHub credential. Every proposal also carries a `coderook/malware` check; a
-failure names the file. Do not try to get round it.
+**Ask before** `approve`, `request-changes`, `merge`, `close` and any comment:
+each is the person speaking or acting, and is seen by others. An approval
+stops counting when new saves land on the line, so re-check after pushing.
+Every pull request carries a `coderook/malware` check: what the line adds or
+changes is scanned before it can land, and a failure names the file. Do not
+try to get round it.
+
+## Private files
+
+`cbx private add "design/"` keeps matching files out of everything outside the
+project (listings, zips, clone, Pages). Ask before changing the list: it
+decides what strangers can see.
+
+## Runs
+
+`cbx runs`, `cbx logs 12 --follow` to watch one, `cbx cancel 12` to stop one,
+`cbx rerun 12` to run it again, `cbx approve 14` for one waiting for approval
+(ask before each). Workflows can be YAML files in `.rook/workflows`; check
+them with `cbx actions check` before saving. Never print or echo secrets:
+`cbx secret set NAME` asks for the value itself, so let the person type it.
+
+Inside a run, `CODEROOK_TOKEN`, `CODEROOK_API` and `CODEROOK_PROJECT` are set,
+so `cbx issue comment`, `cbx pr label` and `cbx release` work with no sign-in.
+
+## Issues, forks and security
+
+`cbx issue view|comment|close|label|assign`, `cbx fork`, `cbx security`. Ask
+before closing, labelling, assigning, forking, or sending anything: each is the
+person acting where others see it. A security report is private to the
+project's owner; never put vulnerability details in a public issue.
+
+## Releases
+
+`cbx release v2.0 --draft --generate-notes` then `cbx release publish`;
+`cbx verify owner/project v2.0 ./file` checks a download; `cbx deps` lists
+known vulnerabilities in the lockfiles. Ask before publishing.
 
 ## Mod repositories for games