bikeshed-now 0.12.0 → 0.14.1

package/README.md

@@ -44,12 +44,20 @@ bikeshed comments storage-migration
 # Fix that sentence, say what you changed in its thread, then publish the
 # revision. Reply first: a thread belongs to the version it was written on.
 bikeshed reply storage-migration <thread> "Rewritten to describe the dual-write period."
+bikeshed resolve storage-migration <thread>   # closes it, with a note saying you did
 bikeshed update storage-migration proposal.md
 
 # Given "Can suggest" rather than "Can edit"? Propose the change instead, for a
 # person to accept or reject.
 bikeshed suggest storage-migration "a single weekend" --with "two weekends"
 
+# Own the document, or can approve on it? Decide somebody's suggestions: an
+# accept goes into the draft, a rejection carries the reason its author is sent,
+# and commit publishes the draft as one version.
+bikeshed accept storage-migration <thread>
+bikeshed reject storage-migration <thread> --reason "Already in section 3."
+bikeshed commit storage-migration
+
 # Something nobody has raised yet? Start a thread on the passage it is about.
 bikeshed comment storage-migration "a single weekend" --body "Is the dual-write fortnight in this?"
 ```
@@ -72,6 +80,13 @@ bikeshed publish platform.md --id 01-platform
 If the id is taken, the document is still published, at the id plus a few
 random characters, and the CLI says so on stderr.
 
+A rename changes the title and leaves the address alone, so links already sent
+keep working:
+
+```bash
+bikeshed rename 01-platform Platform review, second pass
+```
+
 Wherever a command takes an id, it also takes the link you were sent. An
 unlisted document you are not a member of needs the link, because its key is in
 it; without the key the document answers as an id that does not exist.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bikeshed-now",
-  "version": "0.12.0",
+  "version": "0.14.1",
   "license": "Apache-2.0",
   "type": "module",
   "description": "Publish and revise documents on a Bikeshed deployment from the terminal.",

package/src/index.mjs

@@ -53,13 +53,26 @@ const USAGE = `bikeshed ${VERSION} — publish and revise documents
   bikeshed lineage <id>                what it was forked from; for its owner, its forks
   bikeshed get <id>                    print a document's source
   bikeshed comments <id>               unresolved feedback, with its anchored text
+                                       (--version <v> for an earlier version's)
   bikeshed comment <id> <text> --body <comment>
                                        start a thread on a passage
   bikeshed reply <id> <thread> <text>  reply in a thread
+  bikeshed resolve <id> <thread>       close a thread once its point is dealt with
+  bikeshed reopen <id> <thread>        open a resolved thread again
   bikeshed suggest <id> <text> --with <new text>
                                        propose new text for a passage, for a
                                        person to accept or reject (--delete to
                                        propose removing it)
+  bikeshed revise <id> <thread> --with <new text>
+                                       change your suggestion before it is
+                                       decided; what it said before is kept
+  bikeshed withdraw <id> <thread>      take back your suggestion before it is
+                                       decided; its thread stays
+  bikeshed accept <id> <thread>        accept a suggestion, as its owner or an
+                                       approver: the change goes into the draft
+  bikeshed reject <id> <thread>        decline a suggestion, as its owner or an
+                                       approver (--reason <why>)
+  bikeshed commit <id>                 publish the draft as the next version
   bikeshed open <id>                   open it in a browser
 
   Where a command takes <id> it also takes the link you were sent. An unlisted
@@ -69,6 +82,7 @@ Organising
   bikeshed folders                     the folder tree, with ids
   bikeshed mkdir <name> [--parent <id>]  create a folder
   bikeshed mv <id> <folder|root>       move a document
+  bikeshed rename <id> <title>         change a document's title; its address stays
 
 Skills
   bikeshed skills                      skills this deployment publishes
@@ -93,15 +107,17 @@ Options
   --title <text>         title for publish or fork (fork default: the original's)
   --id <id>              with publish: the address, /d/<id> (default: from the title)
   --folder <id>          destination folder for publish or fork
-  --version <v>          with fork: the version to copy (default: current);
-                         on its own, which version of bikeshed this is
+  --version <v>          with fork: the version to copy; with comments: the
+                         version to read (default: current); on its own,
+                         which version of bikeshed this is
   --parent <id>          parent folder for mkdir
   --limit <n>            with list: rows per page (default 20, max 50)
   --cursor <id>          with list: the page after the one that printed it
   --all                  with list: every page; with comments: resolved too
-  --with <text>          with suggest: what the passage should say instead
-  --delete               with suggest: propose deleting the passage
-  --note <text>          with suggest: why, for whoever decides
+  --with <text>          with suggest or revise: what the passage should say instead
+  --delete               with suggest or revise: propose deleting the passage
+  --note <text>          with suggest or revise: why, for whoever decides
+  --reason <text>        with reject: why, for the suggestion's author
   --prefix <text>        with suggest: words just before a passage that repeats
   --suffix <text>        with suggest: words just after it
   --watch                with publish/update: republish on every save
@@ -506,6 +522,9 @@ async function comments(flags, [ref]) {
   const { origin, token } = resolveAuth(flags);
   const result = await callTool(origin, token, "get_comments", {
     ...docArgs(ref),
+    // Threads belong to the version they were opened on; a version in a link
+    // is not taken as a request for one, only the flag is.
+    ...(typeof flags.version === "string" ? { version: flags.version } : {}),
     includeResolved: Boolean(flags.all),
   });
   out(flags.json, result, () => {
@@ -518,11 +537,14 @@ async function comments(flags, [ref]) {
       // which passage to change without opening the document.
       console.log(`\n── ${thread.threadId}${thread.section ? `  (${thread.section})` : ""}`);
       if (thread.quote) console.log(`   “${thread.quote}”`);
-      // A suggested edit says what the passage would become, and whether a
-      // person has decided it yet (SPEC §22).
+      // A suggested edit says what the passage would become, whether it is
+      // still open, and what its author proposed before changing it (SPEC §22).
       if (thread.suggestion) {
-        const change = thread.suggestion.replacement === "" ? "(delete it)" : `“${thread.suggestion.replacement}”`;
-        console.log(`   → ${change}  [${thread.suggestion.state}]`);
+        const said = (text) => (text === "" ? "(delete it)" : `“${text}”`);
+        console.log(`   → ${said(thread.suggestion.replacement)}  [${thread.suggestion.state}]`);
+        for (const earlier of thread.suggestion.revisions ?? []) {
+          console.log(`     was ${said(earlier.replacement)}${earlier.note ? `  (${earlier.note})` : ""}`);
+        }
       }
       for (const comment of thread.comments) {
         const via = comment.via && comment.via !== "web" ? ` [via ${comment.via}]` : "";
@@ -568,6 +590,27 @@ async function reply(flags, [ref, threadId, ...rest]) {
   out(flags.json, result, () => console.log(`replied in ${threadId}`));
 }
 
+/**
+ * Close a thread on the current version, or open it again. Either leaves a
+ * note in the thread saying who did it and through what, which is how the
+ * person who raised the point hears (SPEC §19).
+ */
+// `resolve` alone is node:path's, imported above.
+async function resolveThread(flags, args) {
+  await setResolved(flags, args, "resolve");
+}
+
+async function reopenThread(flags, args) {
+  await setResolved(flags, args, "reopen");
+}
+
+async function setResolved(flags, [ref, threadId, ...rest], verb) {
+  if (!ref || !threadId || rest.length) fail(`usage: bikeshed ${verb} <id> <thread>`);
+  const { origin, token } = resolveAuth(flags);
+  const result = await callTool(origin, token, `${verb}_thread`, { ...docArgs(ref), threadId });
+  out(flags.json, result, () => console.log(`${verb === "resolve" ? "resolved" : "reopened"} ${threadId}`));
+}
+
 /**
  * Propose new text for one passage of a document's current version. The
  * passage is quoted as a reader sees it, which is how `comments` prints it, so
@@ -577,16 +620,12 @@ async function suggest(flags, [ref, ...rest]) {
   const exact = rest.join(" ");
   const usage = "usage: bikeshed suggest <id> <text> (--with <new text> | --delete) [--note <why>]";
   if (!ref || !exact) fail(usage);
-  const replacing = typeof flags.with === "string";
-  if (replacing === Boolean(flags.delete)) fail(usage);
-  // An empty --with is what an unset shell variable sends; deleting a passage
-  // has to be asked for by name.
-  if (replacing && flags.with === "") fail("an empty --with would delete the passage; say --delete if you mean that");
+  const replacement = replacementFrom(flags, usage);
   const { origin, token } = resolveAuth(flags);
   const result = await callTool(origin, token, "suggest_edit", {
     ...docArgs(ref),
     exact,
-    replacement: replacing ? flags.with : "",
+    replacement,
     ...(typeof flags.note === "string" ? { note: flags.note } : {}),
     ...(typeof flags.prefix === "string" ? { prefix: flags.prefix } : {}),
     ...(typeof flags.suffix === "string" ? { suffix: flags.suffix } : {}),
@@ -596,6 +635,82 @@ async function suggest(flags, [ref, ...rest]) {
   );
 }
 
+/** The replacement `suggest` and `revise` were given: --with, or --delete by name. */
+function replacementFrom(flags, usage) {
+  const replacing = typeof flags.with === "string";
+  if (replacing === Boolean(flags.delete)) fail(usage);
+  // An empty --with is what an unset shell variable sends; deleting a passage
+  // has to be asked for by name.
+  if (replacing && flags.with === "") fail("an empty --with would delete the passage; say --delete if you mean that");
+  return replacing ? flags.with : "";
+}
+
+/**
+ * Change the text of a suggestion of yours that nobody has decided yet. What
+ * it said before is kept, for whoever decides (SPEC §22).
+ */
+async function revise(flags, [ref, threadId, ...rest]) {
+  const usage = "usage: bikeshed revise <id> <thread> (--with <new text> | --delete) [--note <why>]";
+  if (!ref || !threadId || rest.length) fail(usage);
+  const replacement = replacementFrom(flags, usage);
+  const { origin, token } = resolveAuth(flags);
+  const result = await callTool(origin, token, "revise_suggestion", {
+    ...docArgs(ref),
+    threadId,
+    replacement,
+    ...(typeof flags.note === "string" ? { note: flags.note } : {}),
+  });
+  out(flags.json, result, () => console.log(`changed ${threadId}; what it said before is kept`));
+}
+
+/**
+ * Accept a suggestion, as the document's owner or an approver. The change is
+ * made in the draft, where the decisions of a review gather until `commit`
+ * publishes them as one version (SPEC §22).
+ */
+async function accept(flags, [ref, threadId, ...rest]) {
+  if (!ref || !threadId || rest.length) fail("usage: bikeshed accept <id> <thread>");
+  const { origin, token } = resolveAuth(flags);
+  // Deciding takes a real role on the document, never a link, so only the id is sent.
+  const result = await callTool(origin, token, "accept_suggestion", { id: docArgs(ref).id, threadId });
+  out(flags.json, result, () => console.log(`accepted ${threadId}; the change is in the draft — \`bikeshed commit\` publishes it`));
+}
+
+/** Publish the draft as the document's next version, as "Save as new version" does in the app. */
+async function commit(flags, [ref, ...rest]) {
+  if (!ref || rest.length) fail("usage: bikeshed commit <id>");
+  const { origin, token } = resolveAuth(flags);
+  const result = await callTool(origin, token, "commit_draft", { id: docArgs(ref).id });
+  out(flags.json, result, () =>
+    console.log(result.deduped ? `nothing new: the draft is ${result.versionId} already` : `published ${result.versionId}`),
+  );
+}
+
+/**
+ * Decline a suggestion, as the document's owner or an approver. The passage
+ * stays as it is and the thread closes with a note giving the reason, which
+ * its author is sent (SPEC §22).
+ */
+async function reject(flags, [ref, threadId, ...rest]) {
+  if (!ref || !threadId || rest.length) fail("usage: bikeshed reject <id> <thread> [--reason <why>]");
+  const { origin, token } = resolveAuth(flags);
+  // Deciding takes a real role on the document, never a link, so only the id is sent.
+  const result = await callTool(origin, token, "reject_suggestion", {
+    id: docArgs(ref).id,
+    threadId,
+    ...(typeof flags.reason === "string" ? { reason: flags.reason } : {}),
+  });
+  out(flags.json, result, () => console.log(`rejected ${threadId}`));
+}
+
+/** Take back a suggestion of yours that nobody has decided yet; its thread stays. */
+async function withdraw(flags, [ref, threadId, ...rest]) {
+  if (!ref || !threadId || rest.length) fail("usage: bikeshed withdraw <id> <thread>");
+  const { origin, token } = resolveAuth(flags);
+  const result = await callTool(origin, token, "withdraw_suggestion", { ...docArgs(ref), threadId });
+  out(flags.json, result, () => console.log(`withdrew ${threadId}`));
+}
+
 async function folders(flags) {
   const { origin, token } = resolveAuth(flags);
   const result = await callTool(origin, token, "list_folders", {});
@@ -706,13 +821,30 @@ async function mv(flags, [id, dest]) {
    */
   if (!id || !dest) fail("usage: bikeshed mv <id> <folder|root>");
   const { origin, token } = resolveAuth(flags);
-  const args = dest === "root" ? { id } : { id, folder: dest };
+  // Moving is an editor's act, and a link's key only lets somebody read, so
+  // only the id goes along.
+  const doc = docArgs(id).id;
+  const args = dest === "root" ? { id: doc } : { id: doc, folder: dest };
   const result = await callTool(origin, token, "move_document", args);
   out(flags.json, result, () =>
-    console.log(result.folder ? `moved ${id} into ${result.folder}` : `moved ${id} to the root`),
+    console.log(result.folder ? `moved ${doc} into ${result.folder}` : `moved ${doc} to the root`),
   );
 }
 
+/**
+ * Give a document a new title. Its address is its id, which never changes, so
+ * every link already sent keeps working (SPEC §4). The title is the rest of the
+ * line, so it needs no quotes.
+ */
+async function rename(flags, [ref, ...rest]) {
+  const title = rest.join(" ").trim();
+  if (!ref || !title) fail("usage: bikeshed rename <id> <title>");
+  const { origin, token } = resolveAuth(flags);
+  // Renaming takes no link key, as in the workspace list: only the id is sent.
+  const result = await callTool(origin, token, "rename_document", { id: docArgs(ref).id, title });
+  out(flags.json, result, () => console.log(`renamed ${result.id} to “${result.title}”`));
+}
+
 /**
  * Skills are instructions, not code, and they are fetched from the DEPLOYMENT
  * rather than bundled with this CLI on purpose: a deployment running an older
@@ -757,10 +889,13 @@ async function skillsCommand(flags, [sub, dir]) {
   });
 }
 
-async function open(flags, [id]) {
-  if (!id) fail("usage: bikeshed open <id>");
+async function open(flags, [ref]) {
+  if (!ref) fail("usage: bikeshed open <id>");
   const { origin } = resolveAuth(flags);
-  const url = `${origin}/d/${id}`;
+  // An unlisted document opens only with its key, and the link is the one place
+  // the key lives, so a link keeps it.
+  const { id, k } = docArgs(ref);
+  const url = `${origin}/d/${encodeURIComponent(id)}${k ? `?k=${encodeURIComponent(k)}` : ""}`;
   // Best effort, and the address is printed either way. This used to spawn
   // `start`, which is a cmd.exe builtin rather than a program, so on Windows
   // the spawn failed and, with nothing listening for the error, crashed.
@@ -802,11 +937,19 @@ const COMMANDS = {
   comments,
   comment,
   reply,
+  resolve: resolveThread,
+  reopen: reopenThread,
   suggest,
+  revise,
+  withdraw,
+  accept,
+  reject,
+  commit,
   open,
   folders,
   mkdir,
   mv,
+  rename,
   skills: skillsCommand,
 };
 
@@ -837,6 +980,7 @@ async function main() {
       paste: { type: "boolean", default: false },
       "no-browser": { type: "boolean", default: false },
       note: { type: "string" },
+      reason: { type: "string" },
       body: { type: "string" },
       prefix: { type: "string" },
       suffix: { type: "string" },