@coderook/cli 0.27.0 → 0.28.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.28.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,48 @@ 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) {
+                console.log(accent("Heads up") +
+                    `  somebody has saved since you last caught up, and ` +
+                    `${ahead.collidingPaths.length} of your file` +
+                    `${ahead.collidingPaths.length === 1 ? "" : "s"} ` +
+                    `${ahead.collidingPaths.length === 1 ? "is" : "are"} 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) => {
@@ -1847,11 +1890,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 +1915,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 +2009,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 +2190,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,
     },
     {

package/dist/cli/src/service_commands.js

@@ -21,6 +21,7 @@ exports.commandRuns = commandRuns;
 exports.commandLogs = commandLogs;
 exports.commandTokens = commandTokens;
 exports.commandDelete = commandDelete;
+exports.commandHooks = commandHooks;
 const node_process_1 = __importDefault(require("node:process"));
 const promises_1 = require("node:readline/promises");
 const api_js_1 = require("./api.js");
@@ -51,11 +52,47 @@ async function commandIssues(parsed) {
     }
     if (typeof title === "string" && title.trim()) {
         const body = parsed.flags.get("body");
+        /*
+          Labels at the moment it is opened, rather than in a second command
+          afterwards. The service has always taken them here; nothing had ever
+          sent any, so every issue arrived unlabelled and the label filter on the
+          website had nothing to filter by until somebody went back and tidied.
+        */
+        const named = parsed.flags.get("labels");
+        const labels = typeof named === "string"
+            ? named
+                .split(",")
+                .map((one) => one.trim())
+                .filter(Boolean)
+            : [];
+        /*
+          And which save it is about, when it is about one. "It broke" and "it
+          broke in v41" are different reports, and only the first could be
+          written down.
+        */
+        const about = parsed.flags.get("version");
+        let versionId;
+        if (typeof about === "string" && about.trim()) {
+            const wanted = about.trim().replace(/^v/i, "");
+            const all = await (0, api_js_1.versions)(project.id);
+            const found = all.find((one) => String(one.sequence) === wanted);
+            if (!found) {
+                console.error(red(`${project.name} has no version ${about.trim()}.`));
+                return 1;
+            }
+            versionId = found.id;
+        }
         const created = await (0, api_js_1.createIssue)(project.id, {
             title: title.trim(),
             body: typeof body === "string" ? body : "",
+            labels,
+            ...(versionId ? { versionId } : {}),
         });
         console.log(green(`Opened issue #${created.number} on ${project.name}.`));
+        if (labels.length)
+            console.log(dim(`  labelled ${labels.join(", ")}`));
+        if (versionId)
+            console.log(dim(`  about v${about}`));
         return 0;
     }
     const found = await (0, api_js_1.issues)(project.id);
@@ -216,10 +253,67 @@ async function commandWatch(parsed) {
 }
 /** The automations a project has, and how they have been going. */
 async function commandWorkflows(parsed) {
-    const project = await (0, project_commands_js_1.resolveProject)(parsed.positional[0]);
+    const project = await (0, project_commands_js_1.resolveProject)(typeof parsed.flags.get("project") === "string"
+        ? String(parsed.flags.get("project"))
+        : parsed.positional[0]);
     if (!project)
         return 1;
     const found = (await (0, api_js_1.workflows)(project.id)).filter((workflow) => !workflow.archivedAt);
+    /*
+      Setting, before printing. `cbx actions --ship Build` reads as a sentence
+      and then shows the list it has just changed, which is the same shape
+      `cbx notes` uses: one command, print by default, flags to write.
+    */
+    const ship = parsed.flags.get("ship");
+    const stop = parsed.flags.get("no-ship");
+    if (ship !== undefined || stop !== undefined) {
+        const wanted = ship !== undefined;
+        const named = wanted ? ship : stop;
+        if (typeof named !== "string" || !named.trim()) {
+            console.error(red("Which action?") + dim(`  cbx actions ${wanted ? "--ship" : "--no-ship"} "Build"`));
+            return 1;
+        }
+        const target = found.find((workflow) => workflow.name.toLowerCase() === named.trim().toLowerCase());
+        if (!target) {
+            console.error(red(`${project.name} has no action called ${named.trim()}.`));
+            if (found.length) {
+                console.error(dim(`  It has: ${found.map((one) => one.name).join(", ")}`));
+            }
+            return 1;
+        }
+        if (wanted && !target.artifactPaths.length) {
+            /*
+              Refused rather than set. Shipping what a run collected means nothing
+              when the run collects nothing, and a flag that reported success and
+              then never produced a download would be indistinguishable from the
+              feature being broken.
+            */
+            console.error(red(`${target.name} keeps no files, so it has nothing to ship.`));
+            console.error(dim("  Give it something to keep on the Actions screen first, e.g. dist/*.exe"));
+            return 1;
+        }
+        try {
+            await (0, api_js_1.changeWorkflow)(project.id, target.id, { attachArtifacts: wanted });
+        }
+        catch (error) {
+            console.error(red(error instanceof Error ? error.message : String(error)));
+            return 1;
+        }
+        target.attachArtifacts = wanted;
+        console.log(wanted
+            ? green(`${target.name} will attach what it builds to the version it ran against.`)
+            : green(`${target.name} will keep its files without attaching them.`));
+        if (wanted) {
+            /*
+              Said plainly, because attaching is publishing. An attachment on a
+              public version is a download anybody can take, and somebody turning
+              this on for a workflow that builds an internal tool deserves to hear
+              that before the next run rather than after it.
+            */
+            console.log(dim("  Anything it attaches to a public version is public the moment it lands."));
+        }
+        console.log("");
+    }
     if (!found.length) {
         console.log(dim("No actions on this project."));
         return 0;
@@ -232,6 +326,12 @@ async function commandWorkflows(parsed) {
         console.log(`  ${workflow.name.padEnd(24)} ${dim(workflow.trigger).padEnd(20)} ` +
             `${dim(workflow.runsOn).padEnd(18)} ${health}`);
         console.log(`    ${dim(workflow.command)}`);
+        if (workflow.artifactPaths.length) {
+            console.log(`    ${dim("keeps")} ${dim(workflow.artifactPaths.join(", "))}` +
+                (workflow.attachArtifacts
+                    ? ` ${accent("→ downloads on the version")}`
+                    : ""));
+        }
     }
     return 0;
 }
@@ -399,3 +499,103 @@ async function commandDelete(parsed) {
     console.log(green(`Deleted ${project.name}.`));
     return 0;
 }
+/**
+ * Where a project tells something else that something happened.
+ *
+ * The service has been able to do this since Merge Tracks shipped — queue an
+ * event, sign it, deliver it after the request that caused it — and nothing
+ * could reach it. A project could not be told to notify a build box, a chat
+ * room or a status page, because no client asked.
+ */
+async function commandHooks(parsed) {
+    const project = await (0, project_commands_js_1.resolveProject)(typeof parsed.flags.get("project") === "string"
+        ? String(parsed.flags.get("project"))
+        : parsed.positional[0]);
+    if (!project)
+        return 1;
+    const adding = parsed.flags.get("add");
+    if (adding !== undefined) {
+        if (typeof adding !== "string" || !adding.trim()) {
+            console.error(red("Which address?") + dim("  cbx hooks --add https://example.com/hook"));
+            return 1;
+        }
+        const url = adding.trim();
+        if (!/^https:\/\//i.test(url)) {
+            /*
+              Refused here as well as by the service. A webhook carries a signed
+              payload about a private project, and http would put it on the wire in
+              the clear — worth saying before the round trip rather than after.
+            */
+            console.error(red("A webhook address has to be https."));
+            return 1;
+        }
+        const named = parsed.flags.get("events");
+        const events = typeof named === "string"
+            ? named.split(",").map((one) => one.trim()).filter(Boolean)
+            : [];
+        try {
+            const made = await (0, api_js_1.addWebhook)(project.id, url, events);
+            console.log(green(`${project.name} will notify ${url}.`));
+            console.log("");
+            /*
+              Printed once because it exists once. The service generates it and no
+              route ever hands it back, so this is the only moment anybody can
+              write it down — and saying so is the difference between a person
+              copying it and a person losing it.
+            */
+            console.log(`  ${bold("Signing secret")}  ${made.secret}`);
+            console.log(dim("  Written once and never again. Use it to check the signature on"));
+            console.log(dim("  what arrives, so nobody else can post to your endpoint."));
+            if (events.length)
+                console.log(dim(`  Sending: ${events.join(", ")}`));
+            else
+                console.log(dim("  Sending: everything this project announces"));
+        }
+        catch (error) {
+            console.error(red(error instanceof Error ? error.message : String(error)));
+            return 1;
+        }
+        return 0;
+    }
+    const removing = parsed.flags.get("remove");
+    if (removing !== undefined) {
+        if (typeof removing !== "string" || !removing.trim()) {
+            console.error(red("Which one?") + dim("  cbx hooks --remove <id>"));
+            return 1;
+        }
+        const wanted = removing.trim();
+        const found = (await (0, api_js_1.webhooks)(project.id)).find((one) => one.id === wanted || one.url === wanted);
+        if (!found) {
+            console.error(red(`${project.name} has no webhook called ${wanted}.`));
+            return 1;
+        }
+        await (0, api_js_1.removeWebhook)(project.id, found.id);
+        console.log(green(`${found.url} will not be notified any more.`));
+        return 0;
+    }
+    const found = await (0, api_js_1.webhooks)(project.id);
+    if (!found.length) {
+        console.log(dim("This project notifies nothing."));
+        console.log(dim("  cbx hooks --add https://example.com/coderook"));
+        return 0;
+    }
+    console.log(bold(project.name));
+    for (const hook of found) {
+        /*
+          A run of failures shown rather than hidden. A webhook that has been
+          failing for a week looks exactly like one that works until somebody
+          checks the receiving end, which is the wrong place to find out.
+        */
+        const health = !hook.active
+            ? red("off")
+            : hook.consecutiveFailures
+                ? red(`${hook.consecutiveFailures} failed in a row`)
+                : hook.lastDeliveredAt
+                    ? green("delivering")
+                    : dim("nothing sent yet");
+        console.log(`  ${hook.url}`);
+        console.log(`    ${dim(hook.id)}  ${health}` +
+            (hook.events.length ? `  ${dim(hook.events.join(", "))}` : `  ${dim("everything")}`));
+    }
+    return 0;
+}

package/dist/desktop-app/src/main/tracks.js

@@ -1,8 +1,66 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Tracks = void 0;
+/**
+ * The lines a project is saved on, and the merges waiting on a person.
+ *
+ * The service has had all of this since Tracks existed: a project has one or
+ * more lines of versions, and a publish that diverges from what the account
+ * holds is put on a Merge Track of its own rather than laid over work the
+ * uploader had not seen. That is the right behaviour and it already happens.
+ *
+ * What did not exist was any way to know. The app never asked for a track, so
+ * a save that diverted reported "done" and said nothing about where the work
+ * went — the version was safe, on a track nobody could see, and the only way
+ * to find it was the website. This is the half that was missing.
+ */
+const node_crypto_1 = require("node:crypto");
 const identify_js_1 = require("./identify.js");
 const retry_js_1 = require("./retry.js");
+/** A media type from the name, so an edited file is stored as what it is. */
+function mediaTypeForPath(path) {
+    const known = {
+        css: "text/css",
+        html: "text/html",
+        js: "text/javascript",
+        json: "application/json",
+        md: "text/markdown",
+        py: "text/x-python",
+        ts: "text/typescript",
+        tsx: "text/typescript",
+        xml: "application/xml",
+        yaml: "application/yaml",
+        yml: "application/yaml",
+    };
+    return known[path.split(".").pop()?.toLowerCase() ?? ""] ?? "text/plain";
+}
+/**
+ * The error to raise for a failed request, with a refusal said properly.
+ *
+ * A build refused for being too old is not a network failure and must not
+ * read like one: the person can fix it, and only if they are told how. The
+ * two requests below build their own fetches rather than going through
+ * `call`, so without this a refused desktop was told only "(426)".
+ */
+function refusalOrError(body, status, fallback) {
+    const tooOld = (0, identify_js_1.readRefusal)(status, body);
+    if (tooOld) {
+        return new Error(`${tooOld.message} You are running ${tooOld.yourVersion ?? "an older build"}; ` +
+            `update from ${tooOld.upgradeUrl}.`);
+    }
+    let message = `${fallback} (${status})`;
+    if (body.trimStart().startsWith("{")) {
+        try {
+            message =
+                JSON.parse(body).error?.message ??
+                    message;
+        }
+        catch {
+            /* keep the generic message */
+        }
+    }
+    return Object.assign(new Error(message), { status });
+}
 class Tracks {
     credentials;
     constructor(credentials) {
@@ -177,17 +235,106 @@ class Tracks {
             return [];
         }
     }
-    /** One merge and every path it is waiting on. */
+    /**
+     * One merge and every path it is waiting on.
+     *
+     * The merge itself is nested under `mergeTrack`, which this used to spread
+     * flat — so `track.reference` was undefined and the window's title fell
+     * back to the word "Merge" on every merge there has ever been. The rest of
+     * the reply was thrown away with it, including the two version ids that
+     * make showing the conflict possible at all.
+     */
     async merge(mergeTrackId) {
         const body = await this.call(`/v1/merge-tracks/${mergeTrackId}`);
-        const { conflicts = [], ...track } = body;
-        return { track: track, conflicts };
+        return {
+            track: body.mergeTrack,
+            conflicts: body.conflicts ?? [],
+            repositoryId: body.mergeTrack.repositoryId,
+            candidateVersionId: body.mergeTrack.candidateVersionId ?? null,
+            currentTargetVersionId: body.currentTargetVersionId ?? null,
+            checks: body.checks ?? [],
+            ready: body.provisional?.ready ?? false,
+            unresolvedPaths: body.provisional?.unresolvedPaths ?? [],
+            blockedByChecks: body.provisional?.blockedByChecks ?? [],
+        };
+    }
+    /**
+     * One side of a conflict, as text.
+     *
+     * Both sides of a merge are versions, so this is the ordinary file route.
+     * Null means there is genuinely no file on that side, which is half of
+     * these conflicts: one person edited what another deleted.
+     */
+    async fileAt(repositoryId, versionId, path) {
+        if (!versionId)
+            return null;
+        const token = await this.credentials.token();
+        if (!token)
+            throw new Error("Sign in again");
+        const response = await fetch(`${this.credentials.origin()}/v1/repositories/${repositoryId}` +
+            `/versions/${versionId}/file?path=${encodeURIComponent(path)}`, {
+            headers: {
+                authorization: `Bearer ${token}`,
+                "user-agent": "CodeRook/0.1",
+                ...(0, identify_js_1.clientHeaders)(),
+            },
+        });
+        if (response.status === 404)
+            return null;
+        if (!response.ok) {
+            throw refusalOrError(await response.text().catch(() => ""), response.status, `Could not read ${path}`);
+        }
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        /*
+          Decoded strictly, so a file that is not UTF-8 reports itself as binary
+          rather than arriving as a screenful of replacement characters somebody
+          might then save over the real thing.
+        */
+        let text = null;
+        try {
+            text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+            if (text.includes("\u0000"))
+                text = null;
+        }
+        catch {
+            text = null;
+        }
+        return { text, bytes: bytes.byteLength };
+    }
+    /**
+     * Send a file somebody wrote, and answer with the object it became.
+     *
+     * The other half of an edited resolution: the service takes an object id,
+     * and something has to put the bytes there first.
+     */
+    async putText(repositoryId, path, text) {
+        const token = await this.credentials.token();
+        if (!token)
+            throw new Error("Sign in again");
+        const bytes = new TextEncoder().encode(text);
+        const digest = (0, node_crypto_1.createHash)("sha256").update(bytes).digest("hex");
+        const response = await fetch(`${this.credentials.origin()}/v1/repositories/${repositoryId}` +
+            `/objects/${digest}?kind=chunk&role=chunk&logicalSize=${bytes.byteLength}` +
+            `&mediaType=${encodeURIComponent(mediaTypeForPath(path))}`, {
+            method: "PUT",
+            headers: {
+                authorization: `Bearer ${token}`,
+                "content-type": "application/octet-stream",
+                "user-agent": "CodeRook/0.1",
+                ...(0, identify_js_1.clientHeaders)(),
+            },
+            body: bytes,
+        });
+        const body = await response.text();
+        if (!response.ok)
+            throw refusalOrError(body, response.status, "Could not send the file");
+        return JSON.parse(body).objectId;
     }
-    /** Settle one path. */
-    async resolve(mergeTrackId, conflictId, resolution) {
+    /** Settle one path. An edit also names the object it produced. */
+    async resolve(mergeTrackId, conflictId, resolution, objectId) {
         await this.call(`/v1/merge-tracks/${mergeTrackId}/conflicts/${conflictId}`, {
             method: "PUT",
-            body: JSON.stringify({ resolution }),
+            body: JSON.stringify(objectId ? { resolution, objectId } : { resolution }),
         });
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coderook/cli",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "CodeRook from the command line, on any operating system",
   "license": "SEE LICENSE IN LICENSE.txt",
   "homepage": "https://coderook.com",