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

package/dist/cli/src/api.js

@@ -251,6 +251,7 @@ async function versions(repositoryId) {
             : [],
         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.

package/dist/cli/src/cli.js

@@ -93,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;
         }
@@ -398,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.`));
     }
@@ -526,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;
     }
@@ -571,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}`);
@@ -586,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;
         }
@@ -688,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.`);
@@ -890,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;
@@ -1122,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,
     });
@@ -1250,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;
 }
@@ -1316,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"
@@ -1331,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;
@@ -1758,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,
     },
     {
@@ -1844,6 +1900,8 @@ const SPECS = [
         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",
@@ -1867,6 +1925,34 @@ 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: "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",
@@ -1879,11 +1965,13 @@ const SPECS = [
             { 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: "private, unlisted (link only) or public",
+                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" },
@@ -1892,7 +1980,7 @@ const SPECS = [
         ],
         examples: [
             "cbx mark --name v2.1 --pin",
-            "cbx mark 41 --visibility unlisted",
+            "cbx mark 41 --visibility private",
             'cbx mark 41 --labels "shipped,client work"',
         ],
         run: version_commands_js_1.commandVersion,
@@ -2249,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.

package/dist/cli/src/git_remote.js

@@ -47,9 +47,19 @@ exports.main = main;
  * `coderook://` URLs, which is what lets every editor's built-in git panel work
  * with CodeRook without any per-editor work.
  *
- * Both directions are implemented: `push` publishes commits as versions, and
- * `import` rebuilds a git history from versions so `git clone` and `git fetch`
- * work.
+ * Both directions are implemented: `push` publishes each commit as a save, and
+ * `import` rebuilds a git history from those saves so `git clone` and `git
+ * fetch` work.
+ *
+ * The vocabulary matters here, because the two products do not agree by
+ * accident. A pushed commit becomes a *commit* in CodeRook — a save, inside
+ * the project, that nobody outside can see. Tagging it names it, and a named
+ * save is a *version*, which is the only thing the public side offers. That
+ * is the same distinction git already draws between a commit and a tag, so
+ * the mapping is one-to-one rather than an approximation.
+ *
+ * A save also carries a description of its own, separate from its message.
+ * That travels as a git note on `refs/notes/coderook` in both directions.
  *
  * ## Why the `push` capability rather than `export`
  *
@@ -143,6 +153,26 @@ function git(args) {
     }
     return result.stdout;
 }
+/**
+ * Where CodeRook keeps a save's description inside a git repository.
+ *
+ * `refs/notes/coderook` rather than git's default `refs/notes/commits`,
+ * because the default is shared ground — anything else attaching notes writes
+ * there too, and a fetch that overwrote somebody's own notes with ours would
+ * be taking something that was not offered.
+ */
+const NOTES_REF = "refs/notes/coderook";
+/**
+ * The description attached to a commit, if there is one.
+ *
+ * Empty rather than throwing for every ordinary reason it can be missing: no
+ * notes ref at all, no note on this commit, or a repository where notes have
+ * never been used. None of those is a problem worth stopping a push for.
+ */
+function noteOn(sha) {
+    const result = (0, node_child_process_1.spawnSync)("git", ["notes", `--ref=${NOTES_REF}`, "show", sha], { encoding: "utf8", maxBuffer: 1024 * 1024 * 8 });
+    return result.status === 0 ? (result.stdout ?? "").trim() : "";
+}
 /** Run git for its exit status alone. False rather than throwing. */
 function gitOk(args) {
     return ((0, node_child_process_1.spawnSync)("git", args, { encoding: "utf8", stdio: "ignore" }).status === 0);
@@ -665,6 +695,40 @@ async function doImport(refs, url) {
                 say(`  ${done}/${fresh.length} versions`);
             }
         }
+        /*
+          What each save says about itself, as git notes.
+    
+          A CodeRook save carries a description separate from its message — the
+          thing the website shows as release info and `cbx notes` writes — and a
+          fetch used to drop all of it except on the few versions that were also
+          releases. Git's answer for text attached to a commit without changing
+          the commit is a note, so that is where it goes: `git log
+          --notes=coderook` shows them, and pushing them back returns them.
+    
+          Written as one commit on its own ref after every version commit exists,
+          because a note has to name a commit that is already in the stream.
+        */
+        const described = fresh.filter((version) => (version.notes ?? "").trim());
+        if (described.length) {
+            send(`commit ${(0, git_history_js_1.importRef)(NOTES_REF)}`);
+            send(`committer CodeRook <noreply@coderook.com> ` +
+                `${(0, git_history_js_1.stamp)(new Date().toISOString())} +0000`);
+            const why = Buffer.from("What each save says about itself\n", "utf8");
+            send(`data ${why.length}`);
+            node_process_1.default.stdout.write(why);
+            node_process_1.default.stdout.write("\n");
+            for (const version of described) {
+                const mark = commitMark.get(version.id);
+                if (mark === undefined)
+                    continue;
+                const body = Buffer.from(`${(version.notes ?? "").trim()}\n`, "utf8");
+                send(`N inline :${mark}`);
+                send(`data ${body.length}`);
+                node_process_1.default.stdout.write(body);
+                node_process_1.default.stdout.write("\n");
+            }
+            say(`  ${described.length} description${described.length === 1 ? "" : "s"} as git notes`);
+        }
         /* Every ref git asked for, named outright now the commits exist. */
         settleRefs();
         /*
@@ -856,7 +920,7 @@ async function doPush(requests, url) {
                     const existing = await releases(repositoryId).catch(() => []);
                     const already = existing.find((release) => release.versionId === versionId && release.name !== tag);
                     if (already) {
-                        say(`  note: v${already.sequence} was already released as "${already.name}".
+                        say(`  note: v${already.sequence} was already released as "${already.name}".
 ` +
                             `        A version carries one name, so it is now "${tag}".`);
                     }
@@ -1098,10 +1162,10 @@ async function doPush(requests, url) {
                           happened and go looking for a way to undo it.
                         */
                         send(`error ${request.dst} the connection failed part way through`);
-                        say(`
-  ${published} of ${commits.length} commits were published.
+                        say(`
+  ${published} of ${commits.length} commits were published.
 ` +
-                            `  Push again — commits already published are not sent twice.
+                            `  Push again — commits already published are not sent twice.
 `);
                         throw error;
                     }
@@ -1113,8 +1177,8 @@ async function doPush(requests, url) {
                           anyway.
                         */
                         send(`error ${request.dst} this commit carries a credential`);
-                        say(`
-  ${failure.message}
+                        say(`
+  ${failure.message}
 `);
                         /*
                           Deleting the file in a later commit does not help, and saying
@@ -1124,14 +1188,14 @@ async function doPush(requests, url) {
                           The history has to lose it.
                         */
                         say(`  A later commit that deletes it is not enough — every commit` +
-                            ` being pushed
+                            ` being pushed
   becomes a version, and the one that added` +
-                            ` the key still carries it.
+                            ` the key still carries it.
 ` +
                             `  Rewrite it out (git rebase -i, or git commit --amend if it` +
-                            ` is the last one),
+                            ` is the last one),
   or publish this deliberately with` +
-                            ` cbx submit --allow-secrets.
+                            ` cbx submit --allow-secrets.
 `);
                         /*
                           Reported already, and in more detail than the wrapper can. The
@@ -1141,8 +1205,8 @@ async function doPush(requests, url) {
                     }
                     if (failure?.kind === "conflict") {
                         send(`error ${request.dst} somebody published to "${branch}" while this push was running`);
-                        say(`
-  git fetch, then push again.
+                        say(`
+  git fetch, then push again.
 `);
                         throw error;
                     }
@@ -1154,6 +1218,27 @@ async function doPush(requests, url) {
                 }
                 currentRepositoryId = result.repositoryId;
                 baseVersionId = result.versionId;
+                /*
+                  A note on the commit becomes what the version says about itself.
+        
+                  CodeRook lets a save be described before anybody decides to publish
+                  it, and git has exactly one place for text attached to a commit
+                  without altering it. Sent after the publish rather than with it,
+                  because a note is not part of what was saved and a failure to
+                  record one must not fail the push.
+                */
+                const note = noteOn(sha);
+                if (note) {
+                    try {
+                        const { changeVersion } = await Promise.resolve().then(() => __importStar(require("./api.js")));
+                        await changeVersion(result.repositoryId, result.versionId, {
+                            notes: note,
+                        });
+                    }
+                    catch {
+                        say(`  note: the description on ${sha.slice(0, 8)} could not be saved`);
+                    }
+                }
                 /*
                   The version and the commit it came from are the same thing in this
                   repository from here on. Recorded so a later fetch does not rebuild

package/dist/cli/src/project_commands.js

@@ -131,10 +131,39 @@ async function commandVersions(parsed) {
         console.log(dim("Nothing has been saved to this project yet."));
         return 0;
     }
+    /*
+      The same two lanes the website shows.
+  
+      A version is a commit somebody named, so the lanes are a split of one
+      history rather than two histories — asking for commits gives the saves
+      still waiting on that decision, and asking for versions gives the ones
+      the public side can see. Neither contains the other; with no flag you get
+      both, which is what this always did.
+    */
+    const onlyVersions = parsed.flags.get("versions") === true;
+    const onlyCommits = parsed.flags.get("commits") === true;
+    if (onlyVersions && onlyCommits) {
+        console.error(red("Pick one: --versions or --commits, or neither for both."));
+        return 1;
+    }
+    const lane = saved.filter((version) => {
+        if (onlyVersions)
+            return Boolean(version.name);
+        if (onlyCommits)
+            return !version.name;
+        return true;
+    });
+    if (!lane.length) {
+        console.log(dim(onlyVersions
+            ? "Nothing has been made a version yet."
+            : "Every save here has been made a version."));
+        return 0;
+    }
+    const withNotes = parsed.flags.get("notes") === true;
     const asked = Number(parsed.flags.get("limit") ?? 20);
     const limit = Number.isFinite(asked) && asked > 0 ? asked : 20;
     console.log(bold(project.name));
-    for (const version of saved.slice(0, limit)) {
+    for (const version of lane.slice(0, limit)) {
         const when = version.createdAt
             ? new Date(version.createdAt).toLocaleString()
             : "";
@@ -155,8 +184,11 @@ async function commandVersions(parsed) {
             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") : "",
+            /*
+              Said only of a version, because only a version is offered to anybody.
+              A commit nobody has promoted is not hidden — it was never on offer.
+            */
+            version.name && version.visibility === "private" ? dim("hidden") : "",
             ...version.labels.map((label) => accent(label.name)),
         ].filter(Boolean);
         console.log(`  ${accent(`v${version.sequence}`).padEnd(16)} ${when.padEnd(22)}` +
@@ -164,9 +196,18 @@ async function commandVersions(parsed) {
             (marks.length ? `  ${marks.join(" ")}` : ""));
         if (version.message)
             console.log(`    ${dim(version.message)}`);
+        /*
+          Indented under the save it belongs to rather than printed flat, so a
+          note of several paragraphs still reads as part of one row.
+        */
+        if (withNotes && version.notes?.trim()) {
+            for (const line of version.notes.trim().split(/\r?\n/)) {
+                console.log(`      ${line}`);
+            }
+        }
     }
-    if (saved.length > limit) {
-        console.log(dim(`  … ${saved.length - limit} older. Use --limit to see more.`));
+    if (lane.length > limit) {
+        console.log(dim(`  … ${lane.length - limit} older. Use --limit to see more.`));
     }
     return 0;
 }

package/dist/cli/src/version_commands.js

@@ -16,6 +16,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.split = split;
+exports.commandNotes = commandNotes;
 exports.commandVersion = commandVersion;
 exports.commandLabels = commandLabels;
 exports.commandHeld = commandHeld;
@@ -26,6 +27,10 @@ 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_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = __importDefault(require("node:path"));
 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
@@ -34,6 +39,7 @@ const dim = (value) => `${value}`;
 const bold = (value) => `${value}`;
 const red = (value) => `${value}`;
 const accent = (value) => `${value}`;
+const green = (value) => `${value}`;
 /**
  * Which of `[n] [project]` the arguments actually were.
  *
@@ -112,6 +118,148 @@ function colourOf(given) {
 function paint(label) {
     return accent(label.name);
 }
+/**
+ * Release info, from wherever the writer keeps it.
+ *
+ * `--notes "..."` is fine for a sentence and hopeless for anything real: a
+ * release note has paragraphs and lists in it, and the shell trick people
+ * reach for — `--notes "$(cat NOTES.md)"` — is not a thing in PowerShell or
+ * cmd, which is most of this product's users. So the text can come from a
+ * file, or from the editor already set up for writing commit messages.
+ *
+ * Returns undefined when none of them were asked for, which is different from
+ * an empty string: one means leave it alone, the other means clear it.
+ */
+function notesFrom(parsed) {
+    const inline = parsed.flags.get("notes");
+    const file = parsed.flags.get("notes-file");
+    const edit = parsed.flags.get("edit") === true;
+    const chosen = [
+        typeof inline === "string",
+        typeof file === "string",
+        edit,
+    ].filter(Boolean).length;
+    if (chosen > 1) {
+        throw new Error("Use one of --notes, --notes-file or --edit, not several.");
+    }
+    if (typeof inline === "string")
+        return inline;
+    if (typeof file === "string") {
+        try {
+            return (0, node_fs_1.readFileSync)(file, "utf8");
+        }
+        catch {
+            throw new Error(`Could not read ${file}.`);
+        }
+    }
+    /*
+      --edit is answered by the caller, which has the existing text to seed the
+      editor with. Nothing to report from here.
+    */
+    return undefined;
+}
+/**
+ * Write in the editor this person already uses, the way git does.
+ *
+ * The comment lines are stripped, so the instructions at the bottom of the
+ * file cannot end up published as part of the release. Quitting without
+ * saving leaves the notes untouched rather than clearing them, because an
+ * empty buffer is far more often a change of mind than an instruction.
+ */
+function writeInEditor(existing) {
+    const editor = node_process_1.default.env.CODEROOK_EDITOR ??
+        node_process_1.default.env.VISUAL ??
+        node_process_1.default.env.EDITOR ??
+        (node_process_1.default.platform === "win32" ? "notepad" : "nano");
+    const directory = (0, node_fs_1.mkdtempSync)(node_path_1.default.join((0, node_os_1.tmpdir)(), "cbx-notes-"));
+    const file = node_path_1.default.join(directory, "RELEASE_NOTES.md");
+    try {
+        (0, node_fs_1.writeFileSync)(file, `${existing}\n\n` +
+            "# Write what changed in this version, in Markdown.\n" +
+            "# Lines starting with # in the first column are removed.\n" +
+            "# Save an empty file to leave the notes as they were.\n", "utf8");
+        /*
+          No shell. Handing the arguments to one concatenates them into a command
+          line without escaping, which makes the editor setting — and the path
+          beside it — a place to hide a second command. An editor is a program
+          and some arguments, so it is split here and run directly, which also
+          means a path with a space in it survives.
+        */
+        const parts = editor.match(/"[^"]+"|\S+/g) ?? [editor];
+        const unquote = (value) => value.replace(/^"|"$/g, "");
+        const run = (0, node_child_process_1.spawnSync)(unquote(parts[0] ?? editor), [...parts.slice(1).map(unquote), file], { stdio: "inherit" });
+        if (run.status !== 0)
+            return null;
+        const written = (0, node_fs_1.readFileSync)(file, "utf8")
+            .split(/\r?\n/)
+            .filter((line) => !/^#\s/.test(line) && line !== "#")
+            .join("\n")
+            .trim();
+        return written ? written : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        (0, node_fs_1.rmSync)(directory, { recursive: true, force: true });
+    }
+}
+/**
+ * Read or write what a version says about itself.
+ *
+ * The website grew a place to write this and the terminal could only set it
+ * as a one-line flag while promoting, and could not read it back at all —
+ * `cbx releases` prints the first line and stops. Somebody working here could
+ * publish release info but never check what they had published.
+ */
+async function commandNotes(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;
+    if (parsed.flags.get("clear") === true) {
+        await (0, api_js_1.changeVersion)(project.id, target.id, { notes: null });
+        console.log(green(`Cleared the notes on v${target.sequence}.`));
+        return 0;
+    }
+    let next;
+    try {
+        next = notesFrom(parsed);
+    }
+    catch (error) {
+        console.error(red(error instanceof Error ? error.message : String(error)));
+        return 1;
+    }
+    if (parsed.flags.get("edit") === true) {
+        const written = writeInEditor(target.notes ?? "");
+        if (written === null) {
+            console.log(dim("Left as it was."));
+            return 0;
+        }
+        next = written;
+    }
+    if (next === undefined) {
+        /* Nothing to write, so this is a read. */
+        const text = (target.notes ?? "").trim();
+        if (!text) {
+            console.log(dim(`v${target.sequence} has no notes.`) +
+                dim("  Write some with --edit, --notes-file or --notes"));
+            return 0;
+        }
+        console.log(bold(`v${target.sequence}${target.name ? ` ${target.name}` : ""}`));
+        console.log(text);
+        return 0;
+    }
+    const text = (next ?? "").trim();
+    await (0, api_js_1.changeVersion)(project.id, target.id, { notes: text ? next : null });
+    console.log(green(text
+        ? `Wrote the notes on v${target.sequence}.`
+        : `Cleared the notes on v${target.sequence}.`));
+    return 0;
+}
 async function commandVersion(parsed) {
     const which = split(parsed);
     const project = await (0, project_commands_js_1.resolveProject)(which.project);
@@ -126,16 +274,27 @@ async function commandVersion(parsed) {
         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;
+    try {
+        const notes = notesFrom(parsed);
+        if (notes !== undefined)
+            patch.notes = notes;
+    }
+    catch (error) {
+        console.error(red(error instanceof Error ? error.message : String(error)));
+        return 1;
+    }
+    if (parsed.flags.get("edit") === true) {
+        const written = writeInEditor(target.notes ?? "");
+        if (written !== null)
+            patch.notes = written;
+    }
     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)) {
+        if (!["private", "public"].includes(visibility)) {
             console.error(red("Visibility is private, unlisted or public."));
             return 1;
         }

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

@@ -229,6 +229,7 @@ class Downloader {
                 ...(row.objectId ? { objectId: String(row.objectId) } : {}),
                 sha256: String(row.sha256 ?? ""),
                 sourceSize: Number(row.sourceSize ?? 0),
+                ...(row.sealed === true ? { sealed: true } : {}),
                 ...(packed?.objectId
                     ? {
                         pack: {
@@ -298,7 +299,7 @@ class Downloader {
         const packed = new Map();
         for (const file of files) {
             const id = file.pack?.objectId;
-            if (!id)
+            if (!id || file.sealed)
                 continue;
             const group = packed.get(id) ?? [];
             group.push(file);
@@ -323,7 +324,7 @@ class Downloader {
             for (const file of files) {
                 this.check();
                 progress(file.path);
-                const packId = file.pack?.objectId;
+                const packId = file.sealed ? undefined : file.pack?.objectId;
                 if (packId && restoredPacks.has(packId))
                     continue;
                 if (packId) {
@@ -372,7 +373,14 @@ class Downloader {
     }
     async fetchInto(repositoryId, versionId, file, target) {
         const whole = (0, node_crypto_1.createHash)("sha256");
-        const pieces = file.chunks ?? [];
+        /*
+          A sealed file is read whole, by path, whatever shape it is stored in.
+    
+          Its pieces and its object are the covered bytes; only the per-path route
+          puts the real value back. Reading it any other way fetches something
+          that cannot match the digest this file was listed with.
+        */
+        const pieces = file.sealed ? [] : (file.chunks ?? []);
         // Captured so the generators below do not need `this` rebound.
         const request = (route) => this.request(route);
         const check = () => this.check();
@@ -399,7 +407,7 @@ class Downloader {
                 }
             })()
             : (async function* () {
-                const reply = await request(file.objectId
+                const reply = await request(file.objectId && !file.sealed
                     ? `/v1/repositories/${repositoryId}/objects/${file.objectId}`
                     : `/v1/repositories/${repositoryId}/versions/${versionId}/file` +
                         `?path=${encodeURIComponent(file.path)}`);
@@ -456,7 +464,8 @@ class Downloader {
             let bytes = 0;
             const packed = new Map();
             for (const file of files) {
-                const id = file.pack?.objectId;
+                /* Sealed members never come out of the pack — see `sealed` above. */
+                const id = file.sealed ? undefined : file.pack?.objectId;
                 if (!id)
                     continue;
                 const group = packed.get(id) ?? [];
@@ -479,7 +488,7 @@ class Downloader {
                 if (parts.some((part) => part === ".." || part.includes("\0"))) {
                     throw new Error(`That version contains an unsafe path: ${file.path}`);
                 }
-                const packId = file.pack?.objectId;
+                const packId = file.sealed ? undefined : file.pack?.objectId;
                 if (packId && restoredPacks.has(packId))
                     continue;
                 if (packId) {

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

@@ -66,6 +66,24 @@ class Tracks {
         const body = await this.call(`/v1/repositories/${repositoryId}/versions`);
         return body.versions ?? [];
     }
+    /**
+     * What the account says about this project, as distinct from this folder.
+     *
+     * The local record knows where a folder saves to and nothing about how the
+     * project is published — so the history window could show which saves were
+     * public without being able to say whether the project itself was, which is
+     * the half that decides whether anybody can reach them.
+     */
+    async project(repositoryId) {
+        try {
+            const body = await this.call(`/v1/repositories/${repositoryId}`);
+            return { visibility: body.visibility ?? null };
+        }
+        catch {
+            /* Not knowing is not worth failing the window for. */
+            return { visibility: null };
+        }
+    }
     async labels(repositoryId) {
         const body = await this.call(`/v1/repositories/${repositoryId}/labels`);
         return body.labels ?? [];

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

@@ -1163,6 +1163,10 @@ class Uploader {
                 ...(request.track ? { track: request.track } : {}),
                 ...(request.allowIgnored ? { allowIgnored: true } : {}),
                 ...(request.allowSecrets ? { allowSecrets: true } : {}),
+                ...(request.linesAdded === undefined ? {} : { linesAdded: request.linesAdded }),
+                ...(request.linesRemoved === undefined
+                    ? {}
+                    : { linesRemoved: request.linesRemoved }),
                 /*
                   Names this attempt so a retry after a lost connection is answered
                   with the version already made, rather than making a second one.

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

@@ -999,9 +999,26 @@ async function uploadConcerns(root, include) {
  * matches no service's format and so is invisible to the pattern scan — the
  * only thing that identifies it is the name of the file it is sitting in.
  */
+/**
+ * The `.env.<something>` files that exist to be committed.
+ *
+ * `.env.example` is the file a project is *supposed* to publish — it is the
+ * documentation of which variables exist, with the values left empty. Refusing
+ * to send it, and then advising it be added to .gitignore, is advice that
+ * breaks the project for the next person who clones it.
+ *
+ * The same list the service uses when it decides what to cover, so a file is
+ * not a template in one half of the system and a credential in the other.
+ */
+const TEMPLATE_SUFFIXES = [".example", ".sample", ".template", ".dist", ".defaults"];
+function isTemplateName(name) {
+    return TEMPLATE_SUFFIXES.some((suffix) => name.endsWith(suffix));
+}
 function isCredentialByName(relativePath) {
     const parts = relativePath.split("/");
     const name = (parts[parts.length - 1] ?? "").toLowerCase();
+    if (isTemplateName(name))
+        return false;
     return (SECRET_NAMES.has(name) ||
         name.startsWith(".env.") ||
         SECRET_SUFFIXES.some((suffix) => name.endsWith(suffix)) ||
@@ -1032,14 +1049,15 @@ async function detectSecrets(root) {
                 continue;
             }
             seen += 1;
-            const name = entry.name.toLowerCase();
-            const isSecret = SECRET_NAMES.has(name) ||
-                name.startsWith(".env.") ||
-                SECRET_SUFFIXES.some((suffix) => name.endsWith(suffix)) ||
-                node_path_1.default.relative(root, directory).split(node_path_1.default.sep).includes("secrets");
-            if (isSecret) {
-                found.push(node_path_1.default.relative(root, full).split(node_path_1.default.sep).join("/"));
-            }
+            /*
+              Asked of the one function rather than repeated here. These were two
+              copies of the same rule, which is how `.env.example` came to be
+              refused by the command line long after the service had learned that
+              templates are not credentials.
+            */
+            const relative = node_path_1.default.relative(root, full).split(node_path_1.default.sep).join("/");
+            if (isCredentialByName(relative))
+                found.push(relative);
         }
     }
     return found;

package/package.json

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