@coderook/cli 0.27.0 → 0.29.0

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "coderook",
   "displayName": "CodeRook",
   "description": "Save, browse and restore whole-snapshot versions of a project on CodeRook, from Claude Code.",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "author": {
     "name": "ACCA Gaming Productions",
     "url": "https://coderook.com"

package/dist/cli/src/api.js

@@ -1,5 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.putObject = putObject;
+exports.beginUpload = beginUpload;
+exports.uploadPart = uploadPart;
+exports.completeUpload = completeUpload;
+exports.attachToVersion = attachToVersion;
 exports.whoami = whoami;
 exports.projects = projects;
 exports.findPublicProject = findPublicProject;
@@ -23,6 +28,7 @@ exports.invite = invite;
 exports.watch = watch;
 exports.setWatch = setWatch;
 exports.workflows = workflows;
+exports.changeWorkflow = changeWorkflow;
 exports.runs = runs;
 exports.runLogs = runLogs;
 exports.tokens = tokens;
@@ -36,6 +42,10 @@ exports.reviewVersion = reviewVersion;
 exports.removeVersionContent = removeVersionContent;
 exports.versionAttachments = versionAttachments;
 exports.undoTo = undoTo;
+exports.webhooks = webhooks;
+exports.addWebhook = addWebhook;
+exports.removeWebhook = removeWebhook;
+exports.collisionCheck = collisionCheck;
 /** The small part of the API the command-line tool needs directly. */
 const identify_js_1 = require("../../desktop-app/src/main/identify.js");
 const config_js_1 = require("./config.js");
@@ -65,6 +75,73 @@ async function call(route, options = {}) {
     }
     return body;
 }
+/**
+ * Send raw bytes, rather than JSON.
+ *
+ * `call` is built for a JSON request and a JSON reply; an object upload is a
+ * body of bytes with the digest in the path, so it needs its own door rather
+ * than a flag threaded through that one.
+ */
+async function send(route, method, bytes, contentType) {
+    const token = await (0, config_js_1.loadToken)();
+    if (!token)
+        throw new Error("Not signed in. Run: cbx sign-in");
+    const response = await fetch(`${(0, config_js_1.apiOrigin)()}${route}`, {
+        method,
+        headers: {
+            accept: "application/json",
+            authorization: `Bearer ${token}`,
+            "user-agent": "CodeRook-CLI/0.1",
+            ...(0, identify_js_1.clientHeaders)(),
+            "content-type": contentType,
+            "content-length": String(bytes.byteLength),
+        },
+        body: bytes,
+    });
+    const text = await response.text();
+    const body = text ? JSON.parse(text) : {};
+    if (!response.ok) {
+        throw new Error(body?.error?.message ??
+            `${route} failed (${response.status})`);
+    }
+    return body;
+}
+/** One object, small enough for a single request. Returns its id. */
+async function putObject(repositoryId, sha256, bytes, mediaType) {
+    const body = await send(`/v1/repositories/${encodeURIComponent(repositoryId)}/objects/${sha256}` +
+        `?kind=chunk&role=chunk&mediaType=${encodeURIComponent(mediaType)}`, "PUT", bytes, "application/octet-stream");
+    return String(body.objectId ?? "");
+}
+/** Start a multipart upload, for anything the direct route will not take. */
+async function beginUpload(repositoryId, definition) {
+    const body = await call(`/v1/repositories/${encodeURIComponent(repositoryId)}/uploads`, {
+        method: "POST",
+        body: definition,
+    });
+    const id = body.uploadSessionId ?? body.id;
+    if (!id)
+        throw new Error("The service did not return an upload session");
+    return {
+        uploadSessionId: String(id),
+        maximumPartBytes: Number(body.maximumPartBytes ?? 95 * 1024 * 1024),
+    };
+}
+/** One numbered part of a multipart upload. */
+async function uploadPart(uploadSessionId, partNumber, bytes) {
+    await send(`/v1/uploads/${encodeURIComponent(uploadSessionId)}/parts/${partNumber}`, "PUT", bytes, "application/octet-stream");
+}
+/** Close a multipart upload and take the object it became. */
+async function completeUpload(uploadSessionId) {
+    const body = await call(`/v1/uploads/${encodeURIComponent(uploadSessionId)}/complete`, { method: "POST" });
+    if (!body.objectId)
+        throw new Error("The upload did not produce an object");
+    return String(body.objectId);
+}
+/** Make an object already on the project a download on one of its versions. */
+async function attachToVersion(repositoryId, versionId, name, objectId) {
+    await call(`/v1/repositories/${encodeURIComponent(repositoryId)}` +
+        `/versions/${encodeURIComponent(versionId)}/attachments`, { method: "POST", body: { name, objectId } });
+}
 async function whoami() {
     const body = await call("/v1/auth/session");
     if (!body.user)
@@ -313,7 +390,15 @@ async function createIssue(repositoryId, input) {
       itself, and exactly the kind of small wrongness that makes somebody stop
       trusting the rest of the output.
     */
-    const created = await call(`/v1/repositories/${encodeURIComponent(repositoryId)}/issues`, { method: "POST", body: { title: input.title, body: input.body ?? "" } });
+    const created = await call(`/v1/repositories/${encodeURIComponent(repositoryId)}/issues`, {
+        method: "POST",
+        body: {
+            title: input.title,
+            body: input.body ?? "",
+            ...(input.labels?.length ? { labels: input.labels } : {}),
+            ...(input.versionId ? { versionId: input.versionId } : {}),
+        },
+    });
     return { number: Number(created.number ?? 0) };
 }
 async function releases(repositoryId) {
@@ -367,15 +452,29 @@ async function setWatch(repositoryId, change) {
 async function workflows(repositoryId) {
     const body = await call(`/v1/repositories/${encodeURIComponent(repositoryId)}/workflows`);
     return (body.workflows ?? []).map((row) => ({
+        /*
+          The id was dropped here for as long as this only ever printed a list.
+          Anything that acts on one workflow needs it, and a list that has thrown
+          away the identity of its rows can only be re-fetched.
+        */
+        id: String(row.id ?? ""),
         name: String(row.name ?? ""),
         trigger: String(row.trigger ?? ""),
         command: String(row.command ?? ""),
         runsOn: String(row.runsOn ?? "hosted"),
+        artifactPaths: Array.isArray(row.artifactPaths)
+            ? row.artifactPaths.map((one) => String(one))
+            : [],
+        attachArtifacts: row.attachArtifacts === true,
         runs: Number(row.runs ?? 0),
         passing: Number(row.passing ?? 0),
         archivedAt: row.archivedAt ? String(row.archivedAt) : null,
     }));
 }
+/** Change a workflow. Only what is named is touched. */
+async function changeWorkflow(repositoryId, workflowId, change) {
+    await call(`/v1/repositories/${encodeURIComponent(repositoryId)}/workflows/${encodeURIComponent(workflowId)}`, { method: "PATCH", body: change });
+}
 /**
  * What has run on a project.
  *
@@ -496,3 +595,58 @@ async function versionAttachments(repositoryId, versionId) {
 async function undoTo(repositoryId, to) {
     return await call(`/v1/repositories/${encodeURIComponent(repositoryId)}/undo`, { method: "POST", body: to ? { to } : {} });
 }
+/** Where this project tells somebody else that something happened. */
+async function webhooks(repositoryId) {
+    const body = await call(`/v1/repositories/${encodeURIComponent(repositoryId)}/webhooks`);
+    return (body.webhooks ?? []).map((row) => ({
+        id: String(row.id ?? ""),
+        url: String(row.url ?? ""),
+        events: Array.isArray(row.events) ? row.events.map((one) => String(one)) : [],
+        active: row.active !== false,
+        lastDeliveredAt: row.last_delivered_at
+            ? String(row.last_delivered_at)
+            : null,
+        consecutiveFailures: Number(row.consecutive_failures ?? 0),
+    }));
+}
+/**
+ * Add one, and answer with the signing secret.
+ *
+ * The secret is generated by the service and returned exactly once — it is
+ * not readable from any route afterwards — so whatever prints this is the
+ * only chance anybody gets to write it down.
+ */
+async function addWebhook(repositoryId, url, events) {
+    const created = await call(`/v1/repositories/${encodeURIComponent(repositoryId)}/webhooks`, { method: "POST", body: events.length ? { url, events } : { url } });
+    return { id: String(created.id ?? ""), secret: String(created.secret ?? "") };
+}
+async function removeWebhook(repositoryId, webhookId) {
+    await call(`/v1/repositories/${encodeURIComponent(repositoryId)}/webhooks/${encodeURIComponent(webhookId)}`, { method: "DELETE" });
+}
+/**
+ * What would collide if this folder published right now.
+ *
+ * Advice, asked before anything is sent. The service has offered this since
+ * Merge Tracks shipped and no client asked, so the first anybody heard that
+ * their upload was walking into a merge was after it had finished — which on
+ * a slow line is the worst possible moment to find out.
+ *
+ * The answer can be stale by the time the publish arrives; the publish path
+ * decides for real. That is why this warns rather than refuses.
+ */
+async function collisionCheck(repositoryId, baseVersionId, paths) {
+    const body = await call(`/v1/repositories/${encodeURIComponent(repositoryId)}/collision-check`, {
+        method: "POST",
+        /*
+          Capped, because this is advice and a folder can hold a hundred thousand
+          paths. The colliding ones are what matter and a long list of them is
+          already a merge nobody wants to read on a terminal.
+        */
+        body: { baseVersionId, paths: paths.slice(0, 5000) },
+    });
+    return {
+        behind: body.behind === true,
+        movedPaths: body.movedPaths ?? [],
+        collidingPaths: body.collidingPaths ?? [],
+    };
+}

package/dist/cli/src/attach_command.js

@@ -0,0 +1,217 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.commandAttach = commandAttach;
+/**
+ * `cbx attach` — put a file people can download on a version.
+ *
+ * A version could already hold downloads and there was no way to add one. The
+ * service accepted an attachment naming any object already on the project,
+ * and the only thing that ever put an object there through this door was a
+ * workflow run — so shipping a build made anywhere else meant a person
+ * clicking through the website, and shipping one built on this machine meant
+ * nothing at all.
+ *
+ * The size is the interesting part. A single PUT is capped at 95 MiB by the
+ * service, and the installer this was written for is 95.5 MB — so the
+ * comfortable path is the one that does not work for the thing people most
+ * want to attach. Anything above the cap goes up in parts instead, which is
+ * the same route the desktop uploader uses.
+ */
+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 project_commands_js_1 = require("./project_commands.js");
+const version_commands_js_1 = require("./version_commands.js");
+const api_js_2 = require("./api.js");
+const dim = (value) => `${value}`;
+const bold = (value) => `${value}`;
+const red = (value) => `${value}`;
+const green = (value) => `${value}`;
+const accent = (value) => `${value}`;
+/** What the service will take in one request. */
+const DIRECT_LIMIT = 95 * 1024 * 1024;
+/** Comfortably under the cap, so one slow part does not hold the rest up. */
+const PART_SIZE = 32 * 1024 * 1024;
+function readable(bytes) {
+    const units = ["B", "KB", "MB", "GB"];
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit += 1;
+    }
+    return `${value >= 10 || unit === 0 ? Math.round(value) : value.toFixed(1)} ${units[unit]}`;
+}
+/**
+ * The digest, read a piece at a time.
+ *
+ * A ninety-five megabyte installer read into memory to be hashed and then
+ * read again to be sent is two hundred megabytes of a small machine's memory
+ * spent saying something a stream can say for nothing.
+ */
+async function digestOf(file) {
+    const hash = (0, node_crypto_1.createHash)("sha256");
+    await new Promise((resolve, reject) => {
+        const stream = (0, node_fs_1.createReadStream)(file);
+        stream.on("data", (piece) => hash.update(piece));
+        stream.on("error", reject);
+        stream.on("end", () => resolve());
+    });
+    return hash.digest("hex");
+}
+/** A media type from the name, because the service records one either way. */
+function mediaTypeOf(name) {
+    const known = {
+        ".exe": "application/vnd.microsoft.portable-executable",
+        ".dmg": "application/x-apple-diskimage",
+        ".deb": "application/vnd.debian.binary-package",
+        ".rpm": "application/x-rpm",
+        ".appimage": "application/x-executable",
+        ".zip": "application/zip",
+        ".gz": "application/gzip",
+        ".tgz": "application/gzip",
+        ".7z": "application/x-7z-compressed",
+        ".pdf": "application/pdf",
+        ".md": "text/markdown",
+        ".txt": "text/plain",
+        ".json": "application/json",
+    };
+    return known[node_path_1.default.extname(name).toLowerCase()] ?? "application/octet-stream";
+}
+/**
+ * Send the bytes and return the object they became.
+ *
+ * Two routes, one answer. Which one is used is a property of the size and not
+ * something a caller should have to think about, so it is decided here.
+ */
+async function sendFile(repositoryId, file, size, sha256, mediaType, say) {
+    if (size <= DIRECT_LIMIT) {
+        const handle = await (0, promises_1.open)(file, "r");
+        try {
+            const bytes = await handle.readFile();
+            return await (0, api_js_1.putObject)(repositoryId, sha256, bytes, mediaType);
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    /*
+      Parts, because the service will not take this in one request. Sent one at
+      a time rather than at once: the point of this path is a file too big to
+      hold comfortably, and holding four of its pieces to go faster gives that
+      back.
+    */
+    const session = await (0, api_js_1.beginUpload)(repositoryId, {
+        sha256,
+        size,
+        mediaType,
+        kind: "chunk",
+        repositoryRole: "chunk",
+    });
+    const parts = Math.ceil(size / PART_SIZE);
+    say(dim(`  ${readable(size)} in ${parts} parts`));
+    const handle = await (0, promises_1.open)(file, "r");
+    try {
+        for (let index = 0; index < parts; index += 1) {
+            const start = index * PART_SIZE;
+            const length = Math.min(PART_SIZE, size - start);
+            const buffer = Buffer.alloc(length);
+            await handle.read(buffer, 0, length, start);
+            await (0, api_js_1.uploadPart)(session.uploadSessionId, index + 1, buffer);
+            say(dim(`  part ${index + 1}/${parts}`));
+        }
+    }
+    finally {
+        await handle.close();
+    }
+    return await (0, api_js_1.completeUpload)(session.uploadSessionId);
+}
+async function commandAttach(parsed) {
+    const file = parsed.positional[0];
+    if (!file) {
+        console.error(red("Which file?") + dim("  cbx attach ./release/Installer.exe"));
+        return 1;
+    }
+    let size;
+    try {
+        const info = await (0, promises_1.stat)(file);
+        if (!info.isFile()) {
+            console.error(red(`${file} is not a file.`));
+            return 1;
+        }
+        size = info.size;
+    }
+    catch {
+        console.error(red(`There is no file at ${file}.`));
+        return 1;
+    }
+    if (size === 0) {
+        console.error(red("That file is empty."));
+        return 1;
+    }
+    /*
+      The version is the second positional, so `cbx attach build.exe 41` reads
+      the way the other version commands do. Without one it is the newest save,
+      which is almost always the one just built against.
+    */
+    const which = (0, version_commands_js_1.split)({
+        ...parsed,
+        positional: parsed.positional.slice(1),
+    });
+    const project = await (0, project_commands_js_1.resolveProject)(which.project);
+    if (!project)
+        return 1;
+    const all = await (0, api_js_2.versions)(project.id);
+    if (!all.length) {
+        console.error(red("This project has no versions yet."));
+        return 1;
+    }
+    const target = which.n
+        ? all.find((one) => String(one.sequence) === which.n.replace(/^v/i, ""))
+        : all.reduce((newest, one) => (one.sequence > newest.sequence ? one : newest));
+    if (!target) {
+        console.error(red(`This project has no version ${which.n}.`));
+        return 1;
+    }
+    const named = parsed.flags.get("name");
+    const name = typeof named === "string" && named.trim() ? named.trim() : node_path_1.default.basename(file);
+    console.log(`${bold(name)} ${dim(`(${readable(size)})`)} → ${accent(`v${target.sequence}`)} of ${project.name}`);
+    let objectId;
+    try {
+        const sha256 = await digestOf(file);
+        objectId = await sendFile(project.id, file, size, sha256, mediaTypeOf(name), (text) => console.log(text));
+    }
+    catch (error) {
+        console.error(red(error instanceof Error ? error.message : String(error)));
+        return 1;
+    }
+    try {
+        await (0, api_js_1.attachToVersion)(project.id, target.id, name, objectId);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(red(message));
+        if (/already has something called/i.test(message)) {
+            console.error(dim("  Use --name to give this one a different name on the version."));
+        }
+        return 1;
+    }
+    console.log(green(`Attached. It is a download on v${target.sequence}.`));
+    if (!target.name) {
+        /*
+          Said because it is the difference between attaching and publishing. A
+          commit is not offered to anybody, so the download exists and nobody
+          outside the project can reach it yet.
+        */
+        console.log(dim("  v") +
+            dim(String(target.sequence)) +
+            dim(" is a commit, so nobody outside the project can take it yet."));
+        console.log(dim(`  Make it a version: cbx mark ${target.sequence} --name v1.0`));
+    }
+    return 0;
+}

package/dist/cli/src/cli.js

@@ -25,6 +25,7 @@ const registry_js_1 = require("./registry.js");
 const help_js_1 = require("./help.js");
 const progress_js_1 = require("./progress.js");
 const publish_js_1 = require("./publish.js");
+const attach_command_js_1 = require("./attach_command.js");
 const project_commands_js_1 = require("./project_commands.js");
 const track_commands_js_1 = require("./track_commands.js");
 const tracks_js_1 = require("../../desktop-app/src/main/tracks.js");
@@ -693,6 +694,53 @@ Pass ${accent("--allow-secrets")} if these are not real keys.`);
         ...(hasFlag(parsed, "allow-secrets") ? { allowSecrets: true } : {}),
         ...(link ? { known: link.local ?? link.manifest ?? {} } : {}),
     });
+    /*
+      Whether this is walking into a merge, asked before anything is sent.
+  
+      The service has offered this since Merge Tracks shipped and nothing ever
+      asked, so the first anybody heard that their upload would be diverted was
+      after it had finished — which on a slow line is the worst possible moment
+      to find out. It is advice: the answer can be stale by the time the
+      publish lands and the publish path decides for real, so this says what is
+      coming and gets out of the way.
+    */
+    if (link?.repositoryId && link.baseVersionId) {
+        try {
+            const ahead = await (0, api_js_1.collisionCheck)(link.repositoryId, link.baseVersionId, files.filter((file) => !file.deleted).map((file) => file.path));
+            if (ahead.collidingPaths.length) {
+                /*
+                  "1 of your file is" — the plural was on the wrong noun. It is one
+                  of *your files*, however many of them collided, so only the verb
+                  changes with the count.
+                */
+                const many = ahead.collidingPaths.length !== 1;
+                console.log(accent("Heads up") +
+                    `  somebody has saved since you last caught up, and ` +
+                    `${ahead.collidingPaths.length} of your files ` +
+                    `${many ? "are" : "is"} among what they changed.`);
+                for (const path of ahead.collidingPaths.slice(0, 5)) {
+                    console.log(dim(`  ${path}`));
+                }
+                if (ahead.collidingPaths.length > 5) {
+                    console.log(dim(`  and ${ahead.collidingPaths.length - 5} more`));
+                }
+                console.log(dim("  Your upload will be kept whole and put on a merge for you to settle."));
+                console.log(dim("  Run cbx get first if you would rather build on theirs."));
+                console.log("");
+            }
+            else if (ahead.behind) {
+                console.log(dim("Somebody has saved since you last caught up, but not to any file " +
+                    "you changed — this will combine on its own."));
+                console.log("");
+            }
+        }
+        catch {
+            /*
+              Advice that cannot be fetched is not a reason to refuse a publish.
+              The service checks properly at the point it matters.
+            */
+        }
+    }
     let result;
     try {
         const plan = await uploader.plan(uploadRequest, (progress) => {
@@ -824,7 +872,13 @@ The connection failed: ${text}`));
             ? `, ${result.alreadyStoredFiles} already on the account`
             : "") +
         (result.reusedFiles ? `, ${result.reusedFiles} unchanged` : "") +
-        ` · version holds ${bytes(result.sourceBytes)}`);
+        /*
+          "version holds" was the old fused vocabulary. `cbx submit` makes a
+          save; a save becomes a version when somebody names it, which is what
+          `cbx release` does. Saying "version" here promised something this
+          command does not do.
+        */
+        ` · the save holds ${bytes(result.sourceBytes)}`);
     return 0;
 }
 /**
@@ -1136,8 +1190,17 @@ trackName) {
  */
 async function suggestRules(folder, apply) {
     const rules = await (0, worktree_js_1.readRules)(folder);
-    const files = await (0, worktree_js_1.changedFiles)(folder, rules, null);
-    const suggestions = (0, detect_js_1.suggestExclusions)(await (0, worktree_js_1.fileSizes)(folder, files));
+    /*
+      Sizes for the whole folder, not for the listed rows.
+  
+      This used to measure `changedFiles`, which stops at twenty thousand — so
+      on the projects with the most to leave out, the sizes here were a fraction
+      of the truth and the biggest item could be missing from the list outright.
+      The scan carries a size for every file it walks past now, capped or not.
+    */
+    const listing = { listed: 0, total: 0, sizes: [] };
+    await (0, worktree_js_1.changedFiles)(folder, rules, null, "add-and-update", undefined, listing);
+    const suggestions = (0, detect_js_1.suggestExclusions)(listing.sizes);
     if (!suggestions.length) {
         console.log(dim("Nothing here looks like it should be left out."));
         return 0;
@@ -1556,11 +1619,14 @@ const SPECS = [
         name: "submit",
         aliases: ["publish", "push"],
         group: "Working with a folder",
-        summary: "send the changes as a new version",
+        summary: "send the changes as a new save",
         usage: 'submit [folder] -m "…"',
-        detail: "Sends everything that changed since the last version. If the folder is\n" +
+        detail: "Sends everything that changed since the last save. If the folder is\n" +
             "not linked to a project yet, one is created on your account, named\n" +
-            "after the folder and private to begin with.",
+            "after the folder and private to begin with.\n\n" +
+            "A save is not a version. Nobody outside the project can see one until\n" +
+            "it is named, which is what `cbx release` does — so submitting is as\n" +
+            "cheap and as private as you want it to be.",
         options: [
             { flags: "-m, --message <text>", description: "what changed, in a sentence" },
             { flags: "-n, --dry-run", description: "show what would be sent, send nothing" },
@@ -1847,11 +1913,21 @@ const SPECS = [
         group: "Your projects",
         summary: "issues on a project, or open one",
         usage: "issues [project]",
+        detail: "Labels are given when the issue is opened rather than added\n" +
+            "afterwards, and any name that does not exist yet is created.\n\n" +
+            "--version says which save it is about. \"It broke\" and \"it broke in\n" +
+            "v41\" are different reports, and the second is the one somebody can\n" +
+            "act on.",
         options: [
             { flags: '--new "<title>"', description: "open a new issue" },
             { flags: "--body <text>", description: "the description for a new one" },
+            { flags: "--labels <a,b>", description: "labels for a new one, comma separated" },
+            { flags: "--version <n>", description: "which save it is about" },
+        ],
+        examples: [
+            'cbx issues my-project --new "Crash on export"',
+            'cbx issues --new "Installer will not run" --labels bug,windows --version 41',
         ],
-        examples: ['cbx issues my-project --new "Crash on export"'],
         run: service_commands_js_1.commandIssues,
     },
     {
@@ -1862,6 +1938,37 @@ const SPECS = [
         usage: "releases [project]",
         run: service_commands_js_1.commandReleases,
     },
+    {
+        /*
+          The service has been able to notify something else since Merge Tracks
+          shipped — queue an event, sign it, deliver it after the request that
+          caused it — and nothing could reach it, so no project could be told to
+          tell a build box or a status page anything.
+        */
+        name: "hooks",
+        aliases: ["webhooks"],
+        group: "Your projects",
+        summary: "where this project tells something else what happened",
+        usage: "hooks [project]",
+        detail: "A signed POST to an address of yours when something happens here.\n" +
+            "The signing secret is generated by the service and shown once, when\n" +
+            "the hook is added — no route hands it back afterwards.\n\n" +
+            "Events: version.published, merge.opened, merge.applied,\n" +
+            "check.reported, change_request.opened, change_request.reviewed.\n" +
+            "Naming none of them sends all of them.",
+        options: [
+            { flags: "--add <url>", description: "notify this address; https only" },
+            { flags: "--events <a,b>", description: "only these, comma separated" },
+            { flags: "--remove <id>", description: "stop notifying it" },
+            { flags: "--project <name>", description: "which project" },
+        ],
+        examples: [
+            "cbx hooks",
+            "cbx hooks --add https://example.com/coderook",
+            "cbx hooks --add https://example.com/builds --events version.published",
+        ],
+        run: service_commands_js_1.commandHooks,
+    },
     {
         /*
           The half that hiding never covered.
@@ -1925,6 +2032,30 @@ const SPECS = [
           that works until somebody scripts it. This marks a save — pins it,
           hides it, labels it — which is what it does anyway.
         */
+        name: "attach",
+        group: "Your projects",
+        summary: "put a file people can download on a version",
+        usage: "attach <file> [n] [project]",
+        detail: "A version can carry downloads — an installer, a build, a changelog —\n" +
+            "and until now the only thing that could put one there was a workflow\n" +
+            "run. This attaches a file from this machine.\n\n" +
+            "Attaching is not publishing. A download on a commit is reachable by\n" +
+            "nobody until that commit is made a version; on a version already\n" +
+            "offered it is public the moment it lands.\n\n" +
+            "Large files go up in parts, so a 95 MB installer works the same way a\n" +
+            "text file does.",
+        options: [
+            { flags: "--name <text>", description: "call it something else on the version" },
+            { flags: "--project <name>", description: "which project" },
+        ],
+        examples: [
+            "cbx attach ./release/Installer-1.0.exe",
+            "cbx attach ./release/app.dmg 41",
+            'cbx attach ./notes.pdf --name "Release notes.pdf"',
+        ],
+        run: attach_command_js_1.commandAttach,
+    },
+    {
         name: "notes",
         aliases: ["release-notes"],
         group: "Your projects",
@@ -2082,7 +2213,22 @@ const SPECS = [
         summary: "the automations a project has",
         usage: "actions [project]",
         detail: "Shows what each action runs, what it runs on, and how many of its\n" +
-            "runs have passed. Use `cbx runner` to execute them on this machine.",
+            "runs have passed. Use `cbx runner` to execute them on this machine.\n\n" +
+            "An action that keeps files can hand them straight to the version it\n" +
+            "ran against, so a passing build becomes a download without anybody\n" +
+            "opening the website. --ship turns that on for one action.\n\n" +
+            "Attaching is publishing: what an action ships onto a public version\n" +
+            "is a download anybody can take, from the moment the run passes.",
+        options: [
+            { flags: "--ship <action>", description: "its builds become downloads on the version" },
+            { flags: "--no-ship <action>", description: "keep its files without attaching them" },
+            { flags: "--project <name>", description: "which project" },
+        ],
+        examples: [
+            "cbx actions",
+            'cbx actions --ship "Windows installer"',
+            'cbx actions --no-ship "Windows installer"',
+        ],
         run: service_commands_js_1.commandWorkflows,
     },
     {