@coderook/cli 0.25.4 → 0.26.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.25.4",
+  "version": "0.26.0",
   "author": {
     "name": "ACCA Gaming Productions",
     "url": "https://coderook.com"

package/dist/cli/src/api.js

@@ -28,6 +28,14 @@ exports.runLogs = runLogs;
 exports.tokens = tokens;
 exports.revokeToken = revokeToken;
 exports.deleteProject = deleteProject;
+exports.projectLabels = projectLabels;
+exports.createProjectLabel = createProjectLabel;
+exports.deleteProjectLabel = deleteProjectLabel;
+exports.changeVersion = changeVersion;
+exports.reviewVersion = reviewVersion;
+exports.removeVersionContent = removeVersionContent;
+exports.versionAttachments = versionAttachments;
+exports.undoTo = undoTo;
 /** 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");
@@ -242,6 +250,25 @@ async function versions(repositoryId) {
             ? row.parentVersionIds.map(String)
             : [],
         authorName: String(row.author?.displayName ?? ""),
+        name: row.name == null ? null : String(row.name),
+        /*
+          Falls back to the older field, so this keeps working against a service
+          that has not been updated yet rather than reporting everything private.
+        */
+        visibility: row.visibility ??
+            (row.public === false ? "private" : "public"),
+        state: String(row.state ?? "verified"),
+        pinned: row.pinned === true,
+        labels: Array.isArray(row.labels)
+            ? row.labels.map((one) => ({
+                id: String(one.id ?? ""),
+                name: String(one.name ?? ""),
+                colour: String(one.colour ?? "#888888"),
+                description: one.description == null ? null : String(one.description),
+            }))
+            : [],
+        removedAt: row.removedAt == null ? null : String(row.removedAt),
+        head: row.head === true,
     }));
 }
 /**
@@ -410,3 +437,61 @@ async function deleteProject(repositoryId) {
         method: "DELETE",
     });
 }
+async function projectLabels(repositoryId) {
+    const body = await call(`/v1/repositories/${encodeURIComponent(repositoryId)}/labels`);
+    return (body.labels ?? []).map((row) => ({
+        id: String(row.id ?? ""),
+        name: String(row.name ?? ""),
+        colour: String(row.colour ?? "#888888"),
+        description: row.description == null ? null : String(row.description),
+    }));
+}
+async function createProjectLabel(repositoryId, name, colour, description) {
+    const body = await call(`/v1/repositories/${encodeURIComponent(repositoryId)}/labels`, { method: "POST", body: { name, colour, ...(description ? { description } : {}) } });
+    return {
+        id: String(body.label?.id ?? ""),
+        name: String(body.label?.name ?? name),
+        colour: String(body.label?.colour ?? colour),
+        description: body.label?.description == null ? null : String(body.label.description),
+    };
+}
+async function deleteProjectLabel(repositoryId, labelId) {
+    await call(`/v1/repositories/${encodeURIComponent(repositoryId)}/labels/${encodeURIComponent(labelId)}`, { method: "DELETE" });
+}
+/**
+ * Everything about a version, changed in one call.
+ *
+ * Deliberately one request rather than one per field. The service takes a
+ * patch, so a command that sets a name and a colour at once is one round trip
+ * and, more to the point, one thing that either happened or did not.
+ */
+async function changeVersion(repositoryId, versionId, patch) {
+    await call(`/v1/repositories/${encodeURIComponent(repositoryId)}` +
+        `/versions/${encodeURIComponent(versionId)}`, { method: "PATCH", body: patch });
+}
+/** Accept a held version, or turn it down with a reason. */
+async function reviewVersion(repositoryId, versionId, decision, note) {
+    const body = await call(`/v1/repositories/${encodeURIComponent(repositoryId)}` +
+        `/versions/${encodeURIComponent(versionId)}/review`, { method: "POST", body: { decision, ...(note ? { note } : {}) } });
+    return { state: String(body.state ?? decision) };
+}
+/** Take a version's content down, leaving the version itself as a record. */
+async function removeVersionContent(repositoryId, versionId, reason) {
+    const query = reason ? `?reason=${encodeURIComponent(reason)}` : "";
+    await call(`/v1/repositories/${encodeURIComponent(repositoryId)}` +
+        `/versions/${encodeURIComponent(versionId)}/content${query}`, { method: "DELETE" });
+}
+async function versionAttachments(repositoryId, versionId) {
+    const body = await call(`/v1/repositories/${encodeURIComponent(repositoryId)}` +
+        `/versions/${encodeURIComponent(versionId)}/attachments`);
+    return (body.attachments ?? []).map((row) => ({
+        id: String(row.id ?? ""),
+        name: String(row.name ?? ""),
+        sizeBytes: Number(row.sizeBytes ?? 0),
+        mediaType: String(row.mediaType ?? "application/octet-stream"),
+    }));
+}
+/** Put the project back on an earlier commit. */
+async function undoTo(repositoryId, to) {
+    return await call(`/v1/repositories/${encodeURIComponent(repositoryId)}/undo`, { method: "POST", body: to ? { to } : {} });
+}

package/dist/cli/src/cli.js

@@ -37,6 +37,7 @@ const worktree_js_1 = require("../../desktop-app/src/main/worktree.js");
 const upload_js_1 = require("../../desktop-app/src/main/upload.js");
 const download_js_1 = require("../../desktop-app/src/main/download.js");
 const faults_js_1 = require("../../desktop-app/src/main/faults.js");
+const version_commands_js_1 = require("./version_commands.js");
 const identify_js_1 = require("../../desktop-app/src/main/identify.js");
 const detect_js_1 = require("../../desktop-app/src/main/detect.js");
 const cbx_js_1 = require("../../desktop-app/src/main/cbx.js");
@@ -1805,6 +1806,161 @@ const SPECS = [
         usage: "releases [project]",
         run: service_commands_js_1.commandReleases,
     },
+    {
+        /*
+          The half that hiding never covered.
+    
+          Hiding a bad push stops strangers reading it and leaves the project
+          standing on it, so the next person to pull still lands on the mistake.
+          This moves the project.
+        */
+        name: "undo",
+        group: "Your projects",
+        summary: "put the project back on an earlier save",
+        usage: "undo [n] [project]",
+        detail: "Goes back one save unless you name another to go back to.\n\n" +
+            "Nothing is deleted and nothing is renumbered — the saves that get\n" +
+            "passed over stay in the history, and the next save carries on from\n" +
+            "wherever the project now stands.",
+        examples: ["cbx undo", "cbx undo 41"],
+        run: version_commands_js_1.commandUndo,
+    },
+    {
+        /*
+          The decision that separates a working history from a published one.
+    
+          Every save is a commit and most of them are nobody else's business. This
+          is where one becomes a version — the thing the public side of a project
+          actually offers.
+        */
+        name: "promote",
+        group: "Your projects",
+        summary: "turn a commit into a version people can fetch",
+        usage: "promote [n] [project]",
+        detail: "Shows the last ten commits and asks which one. Give a number to skip\n" +
+            "the list.\n\n" +
+            "A version is a commit with a name on it. Until a project promotes its\n" +
+            "first one its public page shows everything, as it always did.",
+        options: [
+            { flags: "--name <text>", description: "what to call it" },
+            { flags: "--notes <text>", description: "what changed" },
+        ],
+        examples: [
+            "cbx promote",
+            "cbx promote 41 --name v2.1",
+            'cbx promote --name "Client build" --notes "Fixes the export dialog"',
+        ],
+        run: version_commands_js_1.commandPromote,
+    },
+    {
+        /*
+          One command for everything a version can be, because the service takes
+          one patch. Three separate commands would be three requests, and three
+          chances for a person to end up with a version that is named but not
+          pinned because the second one failed.
+        */
+        /*
+          Not called "version".
+    
+          `cbx version` has printed the version number since the first release,
+          and quietly changing that when arguments follow is the kind of thing
+          that works until somebody scripts it. This marks a save — pins it,
+          hides it, labels it — which is what it does anyway.
+        */
+        name: "mark",
+        aliases: ["set"],
+        group: "Your projects",
+        summary: "name, hide, pin or label one save",
+        usage: "mark [n] [project]",
+        detail: "Changes the newest version unless you name another.\n" +
+            "Everything you ask for happens in one request, so it either all\n" +
+            "lands or none of it does.",
+        options: [
+            { flags: "--name <text>", description: "give it a code name" },
+            { flags: "--unname", description: "take the name off again" },
+            { flags: "--notes <text>", description: "what changed" },
+            { flags: "--hide", description: "nobody outside the project can read it" },
+            { flags: "--show", description: "anybody can read it" },
+            {
+                flags: "--visibility <who>",
+                description: "private, unlisted (link only) or public",
+            },
+            { flags: "--pin", description: "keep it at the top of the list" },
+            { flags: "--unpin", description: "put it back in order" },
+            { flags: "--labels <a,b>", description: "the labels it should wear" },
+            { flags: "--clear-labels", description: "take them all off" },
+        ],
+        examples: [
+            "cbx mark --name v2.1 --pin",
+            "cbx mark 41 --visibility unlisted",
+            'cbx mark 41 --labels "shipped,client work"',
+        ],
+        run: version_commands_js_1.commandVersion,
+    },
+    {
+        name: "labels",
+        group: "Your projects",
+        summary: "the labels this project puts on versions",
+        usage: "labels [list|add|remove] [name] [colour]",
+        detail: "A label is a name and a colour. Put as many on a version as you like —\n" +
+            "how you group and colour your own history is yours to decide.",
+        examples: [
+            "cbx labels",
+            "cbx labels add shipped green",
+            "cbx labels add urgent #e0574a",
+            "cbx labels remove shipped",
+        ],
+        run: version_commands_js_1.commandLabels,
+    },
+    {
+        name: "held",
+        aliases: ["waiting"],
+        group: "Your projects",
+        summary: "versions waiting for somebody to approve them",
+        usage: "held [project]",
+        detail: "A project can be set to hold pushes from anyone below admin until an\n" +
+            "admin accepts them. Those versions are real and stored — they are just\n" +
+            "not the current version, and not on the public page.",
+        run: version_commands_js_1.commandHeld,
+    },
+    {
+        name: "review",
+        group: "Your projects",
+        summary: "accept a held version, or turn it down",
+        usage: "review <n> --approve | --decline",
+        options: [
+            {
+                flags: "--approve",
+                description: "accept it; it becomes the current version",
+            },
+            { flags: "--decline", description: "turn it down" },
+            { flags: "--note <text>", description: "why" },
+        ],
+        examples: [
+            "cbx review 41 --approve",
+            'cbx review 41 --decline --note "wrong branch"',
+        ],
+        run: version_commands_js_1.commandReview,
+    },
+    {
+        /*
+          Named for what it does rather than "delete", because it does not delete
+          the version. The files go; the version stays in the history as a gap
+          saying what was removed and by whom.
+        */
+        name: "take-down",
+        group: "Your projects",
+        summary: "remove a version's files, for something published by mistake",
+        usage: "take-down <n> --yes",
+        detail: "The files go and do not come back. The version stays in the history as\n" +
+            "a gap saying what was removed and by whom, so nothing is quietly\n" +
+            "rewritten.",
+        options: [
+            { flags: "--yes", description: "confirm; without it nothing happens" },
+            { flags: "--reason <text>", description: "recorded against the gap" },
+        ],
+        run: version_commands_js_1.commandTakeDown,
+    },
     {
         /*
           A release is a version with a name on it, so this names one rather than

package/dist/cli/src/project_commands.js

@@ -138,8 +138,30 @@ async function commandVersions(parsed) {
         const when = version.createdAt
             ? new Date(version.createdAt).toLocaleString()
             : "";
+        /*
+          What the project has made of this version, said before the numbers.
+    
+          A name, a pin and a set of labels are how somebody finds the version
+          they meant among forty; the file count is how they check it once they
+          have. Putting the arrangement first is the difference between a log and
+          a list they organised.
+        */
+        const marks = [
+            /* Which one the project is standing on, which is not the same as which
+               one is at the top once somebody has pinned something. */
+            version.head ? green("current") : "",
+            version.pinned ? accent("pinned") : "",
+            version.name ? bold(version.name) : "",
+            version.state === "held" ? red("held") : "",
+            version.state === "declined" ? dim("declined") : "",
+            version.removedAt ? dim("taken down") : "",
+            version.visibility === "private" ? dim("private") : "",
+            version.visibility === "unlisted" ? dim("link only") : "",
+            ...version.labels.map((label) => accent(label.name)),
+        ].filter(Boolean);
         console.log(`  ${accent(`v${version.sequence}`).padEnd(16)} ${when.padEnd(22)}` +
-            `${String(version.fileCount).padStart(5)} files  ${bytes(version.storedSize)}`);
+            `${String(version.fileCount).padStart(5)} files  ${bytes(version.storedSize)}` +
+            (marks.length ? `  ${marks.join(" ")}` : ""));
         if (version.message)
             console.log(`    ${dim(version.message)}`);
     }

package/dist/cli/src/service_commands.js

@@ -105,7 +105,8 @@ async function commandRelease(parsed) {
     const wanted = parsed.flags.get("version");
     const target = typeof wanted === "string"
         ? all.find((version) => String(version.sequence) === wanted.replace(/^v/i, ""))
-        : all[0];
+        /* The newest by number rather than by position in the list. */
+        : all.reduce((newest, one) => (one.sequence > newest.sequence ? one : newest));
     if (!target) {
         console.error(red(`This project has no version ${String(wanted)}.`));
         return 1;

package/dist/cli/src/version_commands.js

@@ -0,0 +1,493 @@
+"use strict";
+/**
+ * Arranging a project's versions from the terminal.
+ *
+ * Every one of these things could already be done — from the website, and only
+ * from the website. That is the gap this closes: naming worked here, hiding
+ * did not, and colouring and pinning existed nowhere. A person who works in a
+ * terminal should not have to open a browser to say which version matters.
+ *
+ * One command does the changing, because the service takes one patch: `cbx
+ * version 12 --name v2.1 --hide --pin` is a single request that either happened
+ * or did not, rather than three that can half-happen.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.split = split;
+exports.commandVersion = commandVersion;
+exports.commandLabels = commandLabels;
+exports.commandHeld = commandHeld;
+exports.commandReview = commandReview;
+exports.commandTakeDown = commandTakeDown;
+exports.commandPromote = commandPromote;
+exports.commandUndo = commandUndo;
+const api_js_1 = require("./api.js");
+const project_commands_js_1 = require("./project_commands.js");
+const promises_1 = require("node:readline/promises");
+const node_process_1 = __importDefault(require("node:process"));
+/* Written out rather than imported: the same four escapes every other command
+   file in here declares for itself, and a shared module for four one-line
+   functions would be the only thing they all depend on. */
+const dim = (value) => `${value}`;
+const bold = (value) => `${value}`;
+const red = (value) => `${value}`;
+const accent = (value) => `${value}`;
+/**
+ * Which of `[n] [project]` the arguments actually were.
+ *
+ * Both are optional and both are positional, so `cbx undo blog` has to be read
+ * as a project and `cbx undo 41` as a save — the shape of the word is the only
+ * thing that separates them. A save is digits, optionally with a leading v;
+ * anything else is a project name.
+ *
+ * That leaves a project whose whole name is digits unreachable this way. It
+ * still works as `--project 41`, and reading a bare number as a save is the
+ * one that comes up.
+ */
+function split(parsed) {
+    const named = parsed.flags.get("project") ?? parsed.flags.get("p");
+    const flagged = typeof named === "string" && named ? named : undefined;
+    const [first, second] = parsed.positional;
+    if (second !== undefined)
+        return { n: first, project: flagged ?? second };
+    if (first === undefined)
+        return { project: flagged };
+    if (flagged)
+        return { n: first, project: flagged };
+    return /^v?\d+$/i.test(first) ? { n: first } : { project: first };
+}
+/** The version somebody meant, which is usually the newest one. */
+async function pick(repositoryId, wanted) {
+    const all = await (0, api_js_1.versions)(repositoryId);
+    if (!all.length) {
+        console.error(red("This project has no versions yet."));
+        return null;
+    }
+    /*
+      The newest by number, not by position.
+  
+      The list arrives newest first today, and relying on that is how three
+      callers started reporting a pinned old save as the current one when the
+      order changed for a while. Asking for the largest number cannot be broken
+      by how the list happens to be sorted.
+    */
+    if (!wanted) {
+        return all.reduce((newest, one) => (one.sequence > newest.sequence ? one : newest));
+    }
+    const sequence = wanted.replace(/^v/i, "");
+    const found = all.find((one) => String(one.sequence) === sequence);
+    if (!found) {
+        console.error(red(`This project has no version ${wanted}.`));
+        return null;
+    }
+    return found;
+}
+const SWATCH = {
+    red: "#e0574a",
+    amber: "#e8a13f",
+    yellow: "#e8d13f",
+    green: "#5fcf8d",
+    blue: "#5aa9e6",
+    purple: "#a98ae0",
+    pink: "#e68ab8",
+    grey: "#8c968f",
+    gray: "#8c968f",
+};
+/**
+ * A colour, given either as a name or as hex.
+ *
+ * Names because nobody remembers hex, hex because somebody will want their own
+ * exact one and being told "pick from these eight" is the kind of small refusal
+ * that makes a tool feel like it is arguing.
+ */
+function colourOf(given) {
+    const value = given.trim().toLowerCase();
+    if (SWATCH[value])
+        return SWATCH[value];
+    const hex = value.startsWith("#") ? value : `#${value}`;
+    return /^#[0-9a-f]{6}$/.test(hex) ? hex : null;
+}
+function paint(label) {
+    return accent(label.name);
+}
+async function commandVersion(parsed) {
+    const which = split(parsed);
+    const project = await (0, project_commands_js_1.resolveProject)(which.project);
+    if (!project)
+        return 1;
+    const target = await pick(project.id, which.n);
+    if (!target)
+        return 1;
+    const patch = {};
+    const name = parsed.flags.get("name");
+    if (typeof name === "string")
+        patch.name = name;
+    if (parsed.flags.get("unname") === true)
+        patch.name = null;
+    const notes = parsed.flags.get("notes");
+    if (typeof notes === "string")
+        patch.notes = notes;
+    if (parsed.flags.get("hide") === true)
+        patch.visibility = "private";
+    if (parsed.flags.get("show") === true)
+        patch.visibility = "public";
+    const visibility = parsed.flags.get("visibility");
+    if (typeof visibility === "string") {
+        if (!["private", "unlisted", "public"].includes(visibility)) {
+            console.error(red("Visibility is private, unlisted or public."));
+            return 1;
+        }
+        patch.visibility = visibility;
+    }
+    if (parsed.flags.get("pin") === true)
+        patch.pinned = true;
+    if (parsed.flags.get("unpin") === true)
+        patch.pinned = false;
+    const labelNames = parsed.flags.get("labels");
+    if (typeof labelNames === "string") {
+        const known = await (0, api_js_1.projectLabels)(project.id);
+        const wanted = labelNames
+            .split(",")
+            .map((one) => one.trim())
+            .filter(Boolean);
+        const ids = [];
+        for (const one of wanted) {
+            const found = known.find((label) => label.name.toLowerCase() === one.toLowerCase());
+            if (!found) {
+                console.error(red(`This project has no "${one}" label.`) +
+                    dim(`  Make one with cbx labels add ${one} green`));
+                return 1;
+            }
+            ids.push(found.id);
+        }
+        patch.labelIds = ids;
+    }
+    if (parsed.flags.get("clear-labels") === true)
+        patch.labelIds = [];
+    if (!Object.keys(patch).length) {
+        console.error(red("Say what to change.") +
+            dim("  --name, --notes, --hide, --show, --visibility, --pin, --labels"));
+        return 1;
+    }
+    try {
+        await (0, api_js_1.changeVersion)(project.id, target.id, patch);
+    }
+    catch (error) {
+        console.error(red(error instanceof Error ? error.message : String(error)));
+        return 1;
+    }
+    const said = [];
+    if (patch.name !== undefined) {
+        said.push(patch.name ? `named ${accent(patch.name)}` : "name removed");
+    }
+    if (patch.visibility)
+        said.push(patch.visibility);
+    if (patch.pinned !== undefined)
+        said.push(patch.pinned ? "pinned" : "unpinned");
+    if (patch.labelIds) {
+        said.push(patch.labelIds.length ? "labelled" : "labels cleared");
+    }
+    console.log(`${bold(`v${target.sequence}`)} ${said.join(", ")}.`);
+    return 0;
+}
+async function commandLabels(parsed) {
+    const action = parsed.positional[0] ?? "list";
+    if (action === "list") {
+        const project = await (0, project_commands_js_1.resolveProject)(parsed.positional[1]);
+        if (!project)
+            return 1;
+        const labels = await (0, api_js_1.projectLabels)(project.id);
+        if (!labels.length) {
+            console.log(dim("No labels yet. Make one with cbx labels add shipped green"));
+            return 0;
+        }
+        console.log(bold(project.name));
+        for (const label of labels) {
+            console.log(`  ${paint(label).padEnd(28)} ${dim(label.colour)}` +
+                (label.description ? `  ${dim(label.description)}` : ""));
+        }
+        return 0;
+    }
+    if (action === "add") {
+        const name = parsed.positional[1];
+        const colour = parsed.positional[2] ?? "grey";
+        if (!name) {
+            console.error(red("Name the label: cbx labels add shipped green"));
+            return 1;
+        }
+        const project = await (0, project_commands_js_1.resolveProject)(parsed.positional[3]);
+        if (!project)
+            return 1;
+        const hex = colourOf(colour);
+        if (!hex) {
+            console.error(red(`"${colour}" is not a colour.`) +
+                dim(`  Try one of ${Object.keys(SWATCH).slice(0, 8).join(", ")}, or #rrggbb`));
+            return 1;
+        }
+        try {
+            const made = await (0, api_js_1.createProjectLabel)(project.id, name, hex);
+            console.log(`Added ${paint(made)} ${dim(made.colour)}.`);
+        }
+        catch (error) {
+            console.error(red(error instanceof Error ? error.message : String(error)));
+            return 1;
+        }
+        return 0;
+    }
+    if (action === "remove" || action === "rm") {
+        const name = parsed.positional[1];
+        if (!name) {
+            console.error(red("Name the label to remove: cbx labels remove shipped"));
+            return 1;
+        }
+        const project = await (0, project_commands_js_1.resolveProject)(parsed.positional[2]);
+        if (!project)
+            return 1;
+        const labels = await (0, api_js_1.projectLabels)(project.id);
+        const found = labels.find((one) => one.name.toLowerCase() === name.toLowerCase());
+        if (!found) {
+            console.error(red(`This project has no "${name}" label.`));
+            return 1;
+        }
+        await (0, api_js_1.deleteProjectLabel)(project.id, found.id);
+        console.log(`Removed ${found.name}. ` +
+            dim("Versions that wore it keep everything else about them."));
+        return 0;
+    }
+    console.error(red(`Unknown: cbx labels ${action}`) + dim("  Try list, add or remove"));
+    return 1;
+}
+/**
+ * The versions a project is holding until somebody says yes.
+ *
+ * Listed first rather than requiring a version number, because the person
+ * running this is usually asking "is there anything waiting for me" rather
+ * than acting on one they already know about.
+ */
+async function commandHeld(parsed) {
+    const project = await (0, project_commands_js_1.resolveProject)(parsed.positional[0]);
+    if (!project)
+        return 1;
+    const waiting = (await (0, api_js_1.versions)(project.id)).filter((one) => one.state === "held");
+    if (!waiting.length) {
+        console.log(dim("Nothing is waiting for a decision."));
+        return 0;
+    }
+    console.log(bold(`${waiting.length} waiting on ${project.name}`));
+    for (const one of waiting) {
+        console.log(`  ${accent(`v${one.sequence}`).padEnd(16)} ${one.authorName.padEnd(20)} ` +
+            dim(one.message));
+    }
+    console.log(dim(`\n  cbx review v${waiting[0].sequence} --approve`));
+    return 0;
+}
+async function commandReview(parsed) {
+    const which = split(parsed);
+    const approve = parsed.flags.get("approve") === true;
+    const decline = parsed.flags.get("decline") === true;
+    if (approve === decline) {
+        console.error(red("Say which: --approve or --decline."));
+        return 1;
+    }
+    const project = await (0, project_commands_js_1.resolveProject)(which.project);
+    if (!project)
+        return 1;
+    const target = await pick(project.id, which.n);
+    if (!target)
+        return 1;
+    if (target.state !== "held") {
+        console.error(red(`v${target.sequence} is not waiting for a decision.`));
+        return 1;
+    }
+    const note = parsed.flags.get("note");
+    try {
+        await (0, api_js_1.reviewVersion)(project.id, target.id, approve ? "approve" : "decline", typeof note === "string" ? note : null);
+    }
+    catch (error) {
+        console.error(red(error instanceof Error ? error.message : String(error)));
+        return 1;
+    }
+    console.log(approve
+        ? `${bold(`v${target.sequence}`)} approved. It is now the current version.`
+        : `${bold(`v${target.sequence}`)} declined. It stays in the history as a version that was not accepted.`);
+    return 0;
+}
+/**
+ * Take a version's content down.
+ *
+ * Asks first, and says exactly what will survive, because this is the one
+ * command here that destroys something. The version itself stays — the list
+ * keeps a gap saying what went and who removed it — and that distinction is
+ * the difference between this and rewriting history.
+ */
+async function commandTakeDown(parsed) {
+    const which = split(parsed);
+    const project = await (0, project_commands_js_1.resolveProject)(which.project);
+    if (!project)
+        return 1;
+    const target = await pick(project.id, which.n);
+    if (!target)
+        return 1;
+    const reason = parsed.flags.get("reason");
+    if (parsed.flags.get("yes") !== true) {
+        console.log(red(`This removes the files in v${target.sequence}. They do not come back.`));
+        console.log(dim(`  The version stays in the history as a gap saying it was removed.\n` +
+            `  Add --yes when you are sure.`));
+        return 1;
+    }
+    try {
+        await (0, api_js_1.removeVersionContent)(project.id, target.id, typeof reason === "string" ? reason : null);
+    }
+    catch (error) {
+        console.error(red(error instanceof Error ? error.message : String(error)));
+        return 1;
+    }
+    console.log(`${bold(`v${target.sequence}`)} taken down.`);
+    return 0;
+}
+/**
+ * Turning a commit into a version.
+ *
+ * A project's history is its working history — most of it says "fix that
+ * file", and none of that is anybody else's business. A version is a commit
+ * somebody decided was worth showing, and this is where that decision gets
+ * made: the last ten, pick one, name it.
+ *
+ * Named rather than numbered on purpose. A version people fetch is "v2.1" or
+ * "the one for the client", and inventing a second counter beside the commit
+ * numbers would give everybody two numbers to hold and tell them nothing.
+ */
+async function commandPromote(parsed) {
+    const which = split(parsed);
+    const project = await (0, project_commands_js_1.resolveProject)(which.project);
+    if (!project)
+        return 1;
+    const all = await (0, api_js_1.versions)(project.id);
+    if (!all.length) {
+        console.error(red("This project has nothing saved yet."));
+        return 1;
+    }
+    const named = parsed.flags.get("name");
+    const notes = parsed.flags.get("notes");
+    /* A number given outright skips the list, for anybody scripting this. */
+    const asked = which.n;
+    let target = asked
+        ? all.find((one) => String(one.sequence) === asked.replace(/^v/i, ""))
+        : null;
+    if (asked && !target) {
+        console.error(red(`This project has no ${asked}.`));
+        return 1;
+    }
+    if (!target) {
+        const recent = all.filter((one) => one.state === "verified").slice(0, 10);
+        if (!recent.length) {
+            console.error(red("Nothing here can be promoted yet."));
+            return 1;
+        }
+        console.log(bold(`Recent commits on ${project.name}`));
+        recent.forEach((one, at) => {
+            const when = one.createdAt
+                ? new Date(one.createdAt).toLocaleString()
+                : "";
+            const already = one.name ? accent(`  → ${one.name}`) : "";
+            console.log(`  ${String(at + 1).padStart(2)}. ${accent(`v${one.sequence}`).padEnd(16)}` +
+                `${when.padEnd(22)}${dim(one.message)}${already}`);
+        });
+        const prompt = (0, promises_1.createInterface)({
+            input: node_process_1.default.stdin,
+            output: node_process_1.default.stdout,
+        });
+        const typed = await prompt.question("\nWhich one? (1-" + recent.length + ", or blank to stop) ");
+        prompt.close();
+        const choice = Number(typed.trim());
+        if (!typed.trim()) {
+            console.log(dim("Nothing promoted."));
+            return 0;
+        }
+        if (!Number.isInteger(choice) || choice < 1 || choice > recent.length) {
+            console.error(red("That was not one of the numbers listed."));
+            return 1;
+        }
+        target = recent[choice - 1];
+    }
+    let versionName = typeof named === "string" ? named.trim() : "";
+    if (!versionName) {
+        const prompt = (0, promises_1.createInterface)({
+            input: node_process_1.default.stdin,
+            output: node_process_1.default.stdout,
+        });
+        const typed = await prompt.question(`Call it what? (blank for v${target.sequence}.0) `);
+        prompt.close();
+        versionName = typed.trim() || `v${target.sequence}.0`;
+    }
+    try {
+        await (0, api_js_1.changeVersion)(project.id, target.id, {
+            name: versionName,
+            ...(typeof notes === "string" ? { notes } : {}),
+        });
+    }
+    catch (error) {
+        console.error(red(error instanceof Error ? error.message : String(error)));
+        return 1;
+    }
+    console.log(`${bold(versionName)} is now a version. ` +
+        dim("It is what the public side of this project offers."));
+    return 0;
+}
+/**
+ * Putting the project back where it was.
+ *
+ * Hiding a bad push stops strangers reading it and leaves everybody on the
+ * team standing on it. This moves the project itself, which is the half that
+ * was missing — and it destroys nothing: the commits that get passed over stay
+ * in the history with their numbers, and a later save carries on from here.
+ */
+async function commandUndo(parsed) {
+    const which = split(parsed);
+    const project = await (0, project_commands_js_1.resolveProject)(which.project);
+    if (!project)
+        return 1;
+    const all = await (0, api_js_1.versions)(project.id);
+    if (all.length < 2) {
+        console.error(red("There is nothing before this to go back to."));
+        return 1;
+    }
+    let to = null;
+    const asked = which.n;
+    if (asked) {
+        const wanted = all.find((one) => String(one.sequence) === asked.replace(/^v/i, ""));
+        if (!wanted) {
+            console.error(red(`This project has no ${asked}.`));
+            return 1;
+        }
+        to = wanted.id;
+    }
+    try {
+        const undone = await (0, api_js_1.undoTo)(project.id, to);
+        console.log(`${bold(project.name)} is back on ${accent(`v${undone.to.sequence}`)}.`);
+        if (undone.skipped.length) {
+            /*
+              Named rather than counted. "3 commits passed over" tells somebody
+              nothing they can act on; the numbers let them look at one, or promote
+              one, or put the head back where it was.
+            */
+            console.log(dim(`  Passed over: ${undone.skipped
+                .map((one) => `v${one.sequence}${one.name ? ` (${one.name})` : ""}`)
+                .join(", ")}`));
+            console.log(dim("  They are still here. Nothing was deleted and nothing renumbered."));
+            const stillPublic = undone.skipped.filter((one) => one.name);
+            if (stillPublic.length) {
+                console.log(dim(`  ${stillPublic.map((one) => one.name).join(", ")} ` +
+                    `${stillPublic.length === 1 ? "is" : "are"} still a published version — ` +
+                    `use cbx mark to take ${stillPublic.length === 1 ? "it" : "them"} down.`));
+            }
+        }
+    }
+    catch (error) {
+        console.error(red(error instanceof Error ? error.message : String(error)));
+        return 1;
+    }
+    return 0;
+}

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

@@ -367,6 +367,7 @@ const READABLE = new Set([
     ".groovy",
     ".h",
     ".hpp",
+    ".hcl",
     ".hs",
     ".htm",
     ".html",

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

@@ -54,6 +54,64 @@ class Tracks {
         }
         return (text ? JSON.parse(text) : {});
     }
+    /**
+     * A project's saves, as the owner sees them.
+     *
+     * Every one of them, including the ones held for review and the ones whose
+     * files were taken down — this is the working history, not the published
+     * one, and the whole point of showing it here is deciding what becomes
+     * published.
+     */
+    async versions(repositoryId) {
+        const body = await this.call(`/v1/repositories/${repositoryId}/versions`);
+        return body.versions ?? [];
+    }
+    async labels(repositoryId) {
+        const body = await this.call(`/v1/repositories/${repositoryId}/labels`);
+        return body.labels ?? [];
+    }
+    async createLabel(repositoryId, name, colour) {
+        const body = await this.call(`/v1/repositories/${repositoryId}/labels`, { method: "POST", body: JSON.stringify({ name, colour }) });
+        return body.label;
+    }
+    async reviewVersion(repositoryId, versionId, decision, note) {
+        await this.call(`/v1/repositories/${repositoryId}/versions/${versionId}/review`, {
+            method: "POST",
+            body: JSON.stringify({ decision, ...(note ? { note } : {}) }),
+        });
+    }
+    async takeVersionDown(repositoryId, versionId, reason) {
+        const query = reason ? `?reason=${encodeURIComponent(reason)}` : "";
+        await this.call(`/v1/repositories/${repositoryId}/versions/${versionId}/content${query}`, { method: "DELETE" });
+    }
+    /** Put the project back on an earlier save. Nothing is deleted. */
+    async undo(repositoryId, to) {
+        return await this.call(`/v1/repositories/${repositoryId}/undo`, {
+            method: "POST",
+            body: JSON.stringify(to ? { to } : {}),
+        });
+    }
+    /** Publish an older save's content again, as a new save. */
+    async restoreVersion(repositoryId, versionId, message) {
+        await this.call(`/v1/repositories/${repositoryId}/versions/${versionId}/restore`, {
+            method: "POST",
+            body: JSON.stringify({ message }),
+        });
+    }
+    /**
+     * Everything about a version, changed in one call.
+     *
+     * Named, hidden, pinned or labelled from the desktop app for the first time.
+     * All three clients call the same route with the same patch, which is what
+     * stops the next capability being reachable from one of them and not the
+     * others.
+     */
+    async changeVersion(repositoryId, versionId, patch) {
+        await this.call(`/v1/repositories/${repositoryId}/versions/${versionId}`, {
+            method: "PATCH",
+            body: JSON.stringify(patch),
+        });
+    }
     /**
      * Every line and merge this project has.
      *

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

@@ -1233,6 +1233,7 @@ class Uploader {
             repositoryId,
             versionId: completed.version.id,
             sequence: completed.version.sequence,
+            ...(completed.version.state === "held" ? { held: true } : {}),
             ...(completed.mergeTrack ? { mergeTrack: completed.mergeTrack } : {}),
             ...(completed.repeated ? { repeated: true } : {}),
             sourceBytes: completed.version.sourceSize ?? sourceBytes,

package/package.json

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

package/skills/coderook/SKILL.md

@@ -81,6 +81,28 @@ cbx submit --track spike -m "…"
 Switching says where the next save goes and nothing else — no files move.
 Run `cbx get` afterwards to bring that line's files in.
 
+## Versions, and going back
+
+Every save is a commit. A commit becomes a *version* — the thing the public
+side of a project offers, and the thing a collaborator pulls — only when
+somebody promotes it.
+
+```bash
+cbx promote                    # pick from the last ten and name one
+cbx mark 41 --pin              # pin, hide, rename or label one save
+cbx labels add shipped green   # the labels a project can wear
+cbx undo                       # put the project back on the save before this one
+```
+
+`undo` moves where the project stands. Nothing is deleted and nothing is
+renumbered — the saves passed over stay in the history, and the next save
+carries on from wherever it now stands. It is the answer to "I pushed the
+wrong thing"; hiding a version stops strangers reading it but leaves the
+project standing on it, so the next person to pull still lands on the mistake.
+
+**Ask before `undo`, `promote` and `take-down`.** They change what other
+people see. `cbx versions` first, so the person can say which save they mean.
+
 ## When two saves collide
 
 If somebody saved while this folder was behind, the second save becomes a merge
@@ -121,6 +143,8 @@ cbx unbundle project.cbx ./restored
   again and gains nothing.
 - Do not guess a project name. `cbx projects` lists them; a folder that is
   already linked needs no name at all.
+- Do not run `cbx take-down`. It destroys the files in a version and they do
+  not come back. Say it exists and let its owner run it.
 
 ## If something refuses