@coderook/cli 0.26.0 → 0.28.0

package/dist/cli/src/cli.js

@@ -25,6 +25,7 @@ const registry_js_1 = require("./registry.js");
 const help_js_1 = require("./help.js");
 const progress_js_1 = require("./progress.js");
 const publish_js_1 = require("./publish.js");
+const attach_command_js_1 = require("./attach_command.js");
 const project_commands_js_1 = require("./project_commands.js");
 const track_commands_js_1 = require("./track_commands.js");
 const tracks_js_1 = require("../../desktop-app/src/main/tracks.js");
@@ -93,18 +94,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 +443,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 +571,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 +616,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 +631,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;
         }
@@ -649,6 +694,48 @@ Pass ${accent("--allow-secrets")} if these are not real keys.`);
         ...(hasFlag(parsed, "allow-secrets") ? { allowSecrets: true } : {}),
         ...(link ? { known: link.local ?? link.manifest ?? {} } : {}),
     });
+    /*
+      Whether this is walking into a merge, asked before anything is sent.
+  
+      The service has offered this since Merge Tracks shipped and nothing ever
+      asked, so the first anybody heard that their upload would be diverted was
+      after it had finished — which on a slow line is the worst possible moment
+      to find out. It is advice: the answer can be stale by the time the
+      publish lands and the publish path decides for real, so this says what is
+      coming and gets out of the way.
+    */
+    if (link?.repositoryId && link.baseVersionId) {
+        try {
+            const ahead = await (0, api_js_1.collisionCheck)(link.repositoryId, link.baseVersionId, files.filter((file) => !file.deleted).map((file) => file.path));
+            if (ahead.collidingPaths.length) {
+                console.log(accent("Heads up") +
+                    `  somebody has saved since you last caught up, and ` +
+                    `${ahead.collidingPaths.length} of your file` +
+                    `${ahead.collidingPaths.length === 1 ? "" : "s"} ` +
+                    `${ahead.collidingPaths.length === 1 ? "is" : "are"} among what they changed.`);
+                for (const path of ahead.collidingPaths.slice(0, 5)) {
+                    console.log(dim(`  ${path}`));
+                }
+                if (ahead.collidingPaths.length > 5) {
+                    console.log(dim(`  and ${ahead.collidingPaths.length - 5} more`));
+                }
+                console.log(dim("  Your upload will be kept whole and put on a merge for you to settle."));
+                console.log(dim("  Run cbx get first if you would rather build on theirs."));
+                console.log("");
+            }
+            else if (ahead.behind) {
+                console.log(dim("Somebody has saved since you last caught up, but not to any file " +
+                    "you changed — this will combine on its own."));
+                console.log("");
+            }
+        }
+        catch {
+            /*
+              Advice that cannot be fetched is not a reason to refuse a publish.
+              The service checks properly at the point it matters.
+            */
+        }
+    }
     let result;
     try {
         const plan = await uploader.plan(uploadRequest, (progress) => {
@@ -688,7 +775,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 +977,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 +1209,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 +1337,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 +1403,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 +1418,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 +1845,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,
     },
     {
@@ -1791,11 +1890,21 @@ const SPECS = [
         group: "Your projects",
         summary: "issues on a project, or open one",
         usage: "issues [project]",
+        detail: "Labels are given when the issue is opened rather than added\n" +
+            "afterwards, and any name that does not exist yet is created.\n\n" +
+            "--version says which save it is about. \"It broke\" and \"it broke in\n" +
+            "v41\" are different reports, and the second is the one somebody can\n" +
+            "act on.",
         options: [
             { flags: '--new "<title>"', description: "open a new issue" },
             { flags: "--body <text>", description: "the description for a new one" },
+            { flags: "--labels <a,b>", description: "labels for a new one, comma separated" },
+            { flags: "--version <n>", description: "which save it is about" },
+        ],
+        examples: [
+            'cbx issues my-project --new "Crash on export"',
+            'cbx issues --new "Installer will not run" --labels bug,windows --version 41',
         ],
-        examples: ['cbx issues my-project --new "Crash on export"'],
         run: service_commands_js_1.commandIssues,
     },
     {
@@ -1806,6 +1915,37 @@ const SPECS = [
         usage: "releases [project]",
         run: service_commands_js_1.commandReleases,
     },
+    {
+        /*
+          The service has been able to notify something else since Merge Tracks
+          shipped — queue an event, sign it, deliver it after the request that
+          caused it — and nothing could reach it, so no project could be told to
+          tell a build box or a status page anything.
+        */
+        name: "hooks",
+        aliases: ["webhooks"],
+        group: "Your projects",
+        summary: "where this project tells something else what happened",
+        usage: "hooks [project]",
+        detail: "A signed POST to an address of yours when something happens here.\n" +
+            "The signing secret is generated by the service and shown once, when\n" +
+            "the hook is added — no route hands it back afterwards.\n\n" +
+            "Events: version.published, merge.opened, merge.applied,\n" +
+            "check.reported, change_request.opened, change_request.reviewed.\n" +
+            "Naming none of them sends all of them.",
+        options: [
+            { flags: "--add <url>", description: "notify this address; https only" },
+            { flags: "--events <a,b>", description: "only these, comma separated" },
+            { flags: "--remove <id>", description: "stop notifying it" },
+            { flags: "--project <name>", description: "which project" },
+        ],
+        examples: [
+            "cbx hooks",
+            "cbx hooks --add https://example.com/coderook",
+            "cbx hooks --add https://example.com/builds --events version.published",
+        ],
+        run: service_commands_js_1.commandHooks,
+    },
     {
         /*
           The half that hiding never covered.
@@ -1844,6 +1984,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 +2009,58 @@ const SPECS = [
           that works until somebody scripts it. This marks a save — pins it,
           hides it, labels it — which is what it does anyway.
         */
+        name: "attach",
+        group: "Your projects",
+        summary: "put a file people can download on a version",
+        usage: "attach <file> [n] [project]",
+        detail: "A version can carry downloads — an installer, a build, a changelog —\n" +
+            "and until now the only thing that could put one there was a workflow\n" +
+            "run. This attaches a file from this machine.\n\n" +
+            "Attaching is not publishing. A download on a commit is reachable by\n" +
+            "nobody until that commit is made a version; on a version already\n" +
+            "offered it is public the moment it lands.\n\n" +
+            "Large files go up in parts, so a 95 MB installer works the same way a\n" +
+            "text file does.",
+        options: [
+            { flags: "--name <text>", description: "call it something else on the version" },
+            { flags: "--project <name>", description: "which project" },
+        ],
+        examples: [
+            "cbx attach ./release/Installer-1.0.exe",
+            "cbx attach ./release/app.dmg 41",
+            'cbx attach ./notes.pdf --name "Release notes.pdf"',
+        ],
+        run: attach_command_js_1.commandAttach,
+    },
+    {
+        name: "notes",
+        aliases: ["release-notes"],
+        group: "Your projects",
+        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 +2073,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 +2088,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,
@@ -1994,7 +2190,22 @@ const SPECS = [
         summary: "the automations a project has",
         usage: "actions [project]",
         detail: "Shows what each action runs, what it runs on, and how many of its\n" +
-            "runs have passed. Use `cbx runner` to execute them on this machine.",
+            "runs have passed. Use `cbx runner` to execute them on this machine.\n\n" +
+            "An action that keeps files can hand them straight to the version it\n" +
+            "ran against, so a passing build becomes a download without anybody\n" +
+            "opening the website. --ship turns that on for one action.\n\n" +
+            "Attaching is publishing: what an action ships onto a public version\n" +
+            "is a download anybody can take, from the moment the run passes.",
+        options: [
+            { flags: "--ship <action>", description: "its builds become downloads on the version" },
+            { flags: "--no-ship <action>", description: "keep its files without attaching them" },
+            { flags: "--project <name>", description: "which project" },
+        ],
+        examples: [
+            "cbx actions",
+            'cbx actions --ship "Windows installer"',
+            'cbx actions --no-ship "Windows installer"',
+        ],
         run: service_commands_js_1.commandWorkflows,
     },
     {
@@ -2249,7 +2460,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