@coderook/cli 0.25.4 → 0.27.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.27.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,26 @@ async function versions(repositoryId) {
             ? row.parentVersionIds.map(String)
             : [],
         authorName: String(row.author?.displayName ?? ""),
+        name: row.name == null ? null : String(row.name),
+        notes: row.notes == null ? null : String(row.notes),
+        /*
+          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 +438,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");
@@ -92,18 +93,62 @@ const done = (line) => {
         node_process_1.default.stdout.write("\r");
     }
 };
-function parse(argv) {
+/**
+ * The flags a command declares as taking a value.
+ *
+ * Read from the option's own help text, which already says so: a value is
+ * written as a placeholder after the name, as in `--name <text>`, and a
+ * switch has nothing after it. So there is no second list to keep in step
+ * with the first — the thing already written for the reader is the thing
+ * the parser uses.
+ */
+function valueTaking(spec) {
+    const names = new Set();
+    for (const option of spec?.options ?? []) {
+        if (!/[<[]/.test(option.flags))
+            continue;
+        for (const match of option.flags.matchAll(/--?([A-Za-z0-9][\w-]*)/g)) {
+            names.add(match[1]);
+        }
+    }
+    return names;
+}
+/**
+ * What was typed, split into positions and flags.
+ *
+ * A flag takes the word after it only when the command says it takes one.
+ * Guessing from the shape of the next word — anything not starting with a
+ * dash — meant `cbx take-down 1 --yes my-project` read the project name as
+ * the value of `--yes` and then reported that `--yes` had not been given,
+ * having also swallowed the argument that said which project. Every switch
+ * followed by a positional had the same fault.
+ */
+function parse(argv, spec) {
     const positional = [];
     const flags = new Map();
+    const takesValue = valueTaking(spec);
     for (let at = 0; at < argv.length; at += 1) {
         const item = argv[at];
         if (!item.startsWith("-")) {
             positional.push(item);
             continue;
         }
-        const name = item.replace(/^--?/, "");
+        /* `--name=value` says so itself and needs no declaration. */
+        const written = item.replace(/^--?/, "");
+        const split = written.indexOf("=");
+        if (split > 0) {
+            flags.set(written.slice(0, split), written.slice(split + 1));
+            continue;
+        }
+        const name = written;
         const next = argv[at + 1];
-        if (next && !next.startsWith("-")) {
+        /*
+          An undeclared flag keeps the old guess. Commands that never declared
+          their options rely on it, and narrowing that here would trade one
+          quiet misreading for another.
+        */
+        const wants = takesValue.size ? takesValue.has(name) : true;
+        if (wants && next !== undefined && !next.startsWith("-")) {
             flags.set(name, next);
             at += 1;
         }
@@ -397,7 +442,7 @@ async function commandImport(parsed) {
         flags: submitFlags,
     });
     if (code === 0 && plan.temporary) {
-        console.log(dim(`The working copy stays at ${plan.folder} until you remove it.
+        console.log(dim(`The working copy stays at ${plan.folder} until you remove it.
 ` +
             `Run ${accent("cbx get " + plan.name)} anywhere to fetch it fresh.`));
     }
@@ -525,17 +570,17 @@ async function commandSubmit(parsed) {
     */
     const shielded = (await (0, worktree_js_1.detectPrivateDirectories)(folder)).filter((finding) => [...sending].some((file) => file === finding.path || file.startsWith(`${finding.path}/`)));
     if (shielded.length && !hasFlag(parsed, "allow-private")) {
-        console.log(red(`
+        console.log(red(`
 ${shielded.length} folder${shielded.length === 1 ? "" : "s"} here belong${shielded.length === 1 ? "s" : ""} to a program, not to your project:`));
         for (const finding of shielded) {
             console.log(`  ${finding.path}  ${dim(`— ${finding.because}`)}`);
         }
-        console.log(`
+        console.log(`
 Nothing was sent. To leave them behind:`);
         for (const finding of shielded) {
             console.log(`  ${accent(`echo "${finding.rule}" >> .gitignore`)}`);
         }
-        console.error(`
+        console.error(`
 Or pass ${accent("--allow-private")} if they genuinely belong in the project.`);
         return 1;
     }
@@ -570,7 +615,7 @@ Or pass ${accent("--allow-private")} if they genuinely belong in the project.`);
     const pasted = await (0, worktree_js_1.detectPastedCredentials)(folder, files.map((file) => file.path));
     const stillPasted = pasted.filter((finding) => !exposed.includes(finding.path));
     if (stillPasted.length) {
-        console.log(red(`
+        console.log(red(`
 ${stillPasted.length} file${stillPasted.length === 1 ? " has a credential" : "s have credentials"} inside:`));
         for (const finding of stillPasted.slice(0, 20)) {
             console.log(`  ${finding.path}`);
@@ -585,11 +630,11 @@ ${stillPasted.length} file${stillPasted.length === 1 ? " has a credential" : "s
             console.log(dim(`  …and ${stillPasted.length - 20} more`));
         }
         if (!hasFlag(parsed, "allow-secrets")) {
-            console.error(`
+            console.error(`
 Nothing was sent. Move the key into an environment variable, and if` +
                 ` it has ever been published, replace it at the service that issued` +
                 ` it — a key that has leaked stays leaked.` +
-                `
+                `
 Pass ${accent("--allow-secrets")} if these are not real keys.`);
             return 1;
         }
@@ -687,7 +732,7 @@ Pass ${accent("--allow-secrets")} if these are not real keys.`);
         const failure = (0, publish_js_1.classifyPublishFailure)(error);
         const text = error instanceof Error ? error.message : String(error);
         if (failure?.kind === "interrupted") {
-            console.error(red(`
+            console.error(red(`
 The connection failed: ${text}`));
             console.error(`Your work may already have been saved. Run the same command again —` +
                 ` it will not create a second version.`);
@@ -889,7 +934,7 @@ async function commandGet(parsed) {
                     `changed while the interrupted fetch was stopped:`));
                 for (const file of changedInTheGap.slice(0, 20))
                     console.error(`  ${file.path}`);
-                console.error(`
+                console.error(`
 Save them with ${accent("cbx submit")}, or finish the fetch and ` +
                     `discard them with ${accent("cbx get --replace")}.`);
                 return 1;
@@ -1121,8 +1166,8 @@ async function suggestRules(folder, apply) {
     const addition = (0, detect_js_1.rulesFromSuggestions)(recommended);
     const shared = rules.shared.trimEnd();
     await (0, worktree_js_1.writeRules)(folder, {
-        shared: shared ? `${shared}
-
+        shared: shared ? `${shared}
+
 ${addition}` : addition,
         local: rules.local,
     });
@@ -1249,7 +1294,7 @@ async function commandMerges(parsed) {
         const counts = merge.conflicts;
         console.log(`${accent(merge.reference)}  ${counts ? `${counts.unresolved} of ${counts.total} still to decide` : ""}  ${dim(new Date(merge.createdAt).toLocaleString())}`);
     }
-    console.log(dim(`
+    console.log(dim(`
 Run cbx merge <reference> to look at one.`));
     return 0;
 }
@@ -1315,7 +1360,7 @@ async function commandMerge(parsed) {
         }
     }
     const now = await (0, api_js_1.mergeTrack)(summary.id);
-    console.log(`
+    console.log(`
 ${accent(now.mergeTrack.reference)} · ${now.provisional.fileCount} files · ` +
         (now.provisional.ready
             ? "ready to apply"
@@ -1330,19 +1375,19 @@ ${accent(now.mergeTrack.reference)} · ${now.provisional.fileCount} files · ` +
             return 1;
         }
         const applied = await (0, api_js_1.applyMerge)(summary.id);
-        console.log(`
+        console.log(`
 Applied as ${accent(`v${applied.version.sequence}`)}.`);
         console.log(dim("Run cbx get to bring it down to this folder."));
         return 0;
     }
     if (!decision) {
-        console.log(dim(`
+        console.log(dim(`
 --mine keeps yours, --theirs keeps what was already saved,` +
-            ` --drop removes the file.
+            ` --drop removes the file.
 Add --path <file> for one file, then --apply when ready.`));
     }
     else if (now.provisional.ready) {
-        console.log(dim(`
+        console.log(dim(`
 Run cbx merge ${now.mergeTrack.reference} --apply to publish it.`));
     }
     return 0;
@@ -1757,8 +1802,20 @@ const SPECS = [
         group: "Your projects",
         summary: "what has been saved to a project",
         usage: "versions [project]",
-        detail: "Newest first. Run it inside a linked folder to leave the name out.",
-        options: [{ flags: "--limit <n>", description: "how many to show (default 20)" }],
+        detail: "Newest first. Run it inside a linked folder to leave the name out.\n\n" +
+            "A save is a commit; a commit somebody named is a version, and versions\n" +
+            "are the only thing the public side shows. Both are listed together\n" +
+            "unless you ask for one lane — the same three views the website has.",
+        options: [
+            { flags: "--limit <n>", description: "how many to show (default 20)" },
+            { flags: "--versions", description: "only the ones that were named" },
+            { flags: "--commits", description: "only the ones that were not" },
+            { flags: "--notes", description: "print what each one says about itself" },
+        ],
+        examples: [
+            "cbx versions --versions",
+            "cbx versions my-project --commits",
+        ],
         run: project_commands_js_1.commandVersions,
     },
     {
@@ -1805,6 +1862,193 @@ 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" },
+            { flags: "--notes-file <path>", description: "what changed, from a file" },
+            { flags: "--edit", description: "write what changed in your editor" },
+        ],
+        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: "notes",
+        aliases: ["release-notes"],
+        group: "Your projects",
+        summary: "read or write what a version says about itself",
+        usage: "notes [n] [project]",
+        detail: "The release info the website shows on a version, and the same field\n" +
+            "`--notes` writes when promoting. With nothing to write it prints what\n" +
+            "is there, which the terminal could not do before: `cbx releases` shows\n" +
+            "the first line and stops.\n\n" +
+            "Written in Markdown, because that is what the page renders. --edit\n" +
+            "opens $EDITOR (or $VISUAL, or notepad on Windows) the way git does,\n" +
+            "which is the only comfortable way to write more than a sentence.",
+        options: [
+            { flags: "--edit", description: "write it in your editor" },
+            { flags: "--notes-file <path>", description: "take the text from a file" },
+            { flags: "--notes <text>", description: "set it in one line" },
+            { flags: "--clear", description: "remove what is there" },
+            { flags: "--project <name>", description: "which project" },
+        ],
+        examples: [
+            "cbx notes",
+            "cbx notes 41",
+            "cbx notes 41 --edit",
+            "cbx notes 41 --notes-file RELEASE.md",
+        ],
+        run: version_commands_js_1.commandNotes,
+    },
+    {
+        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: "--notes-file <path>", description: "what changed, from a file" },
+            { flags: "--edit", description: "write what changed in your editor" },
+            { flags: "--hide", description: "nobody outside the project can read it" },
+            { flags: "--show", description: "anybody can read it" },
+            {
+                flags: "--visibility <who>",
+                description: "public, or private to hold it back",
+            },
+            { 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 private",
+            '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
@@ -2093,7 +2337,7 @@ async function main(argv) {
     if (spec.deprecatedBy) {
         console.error(dim(`"${name}" is now "${spec.deprecatedBy}". The old name still works.`));
     }
-    return spec.run(parse(rest));
+    return spec.run(parse(rest, spec));
 }
 /**
  * Set the status and let Node wind down on its own.