bikeshed-now 0.4.1 → 0.6.0

package/README.md

@@ -30,6 +30,10 @@ bikeshed comments storage-migration
 # Fix that sentence, publish the revision, and say what you changed.
 bikeshed update storage-migration proposal.md
 bikeshed reply storage-migration <thread> "Rewritten to describe the dual-write period."
+
+# 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"
 ```
 
 Publishing identical bytes is a no-op: the bundle is hashed, and a matching hash
@@ -61,6 +65,24 @@ bikeshed comments 'https://bikeshed.now/d/build-estimate?k=…'
 `bikeshed --help` lists the rest — listing documents, folders, and installing the
 agent skills a deployment serves.
 
+## Forking
+
+To revise a document you can read but do not own, fork it. You get your own
+private copy, at the version you name or the current one, and it remembers what
+it was forked from.
+
+```bash
+bikeshed fork 'https://bikeshed.now/d/build-estimate?k=…'
+# forked build-estimate into build-estimate-x7k2p9 — https://bikeshed.now/d/build-estimate-x7k2p9
+bikeshed lineage build-estimate-x7k2p9
+# forked from  build-estimate v3  Build estimate   (changed since)
+```
+
+`lineage` shows each original you can open, nearest first, and whether the
+nearest has changed since you forked it. On a document you own it also counts
+its forks. The author of what you fork sees that it was forked — a count, never
+who.
+
 ## Sharing is not automated
 
 There is no command that shares a document, changes who can read it, or sets an

package/package.json

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

package/src/client.mjs

@@ -4,7 +4,7 @@
 import { readFileSync } from "node:fs";
 import { basename } from "node:path";
 
-export const CLIENT_NAME = "bikeshed-cli/0.4.1";
+export const CLIENT_NAME = "bikeshed-cli/0.6.0";
 
 /**
  * Three surfaces, and the split is deliberate rather than untidy.

package/src/index.mjs

@@ -39,9 +39,15 @@ const USAGE = `bikeshed — publish and revise documents
   bikeshed list                        documents you can read
   bikeshed publish <file>              create a new document
   bikeshed update <id> <file>          publish a new version
+  bikeshed fork <id>                   your own copy, which remembers its original
+  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
   bikeshed reply <id> <thread> <text>  reply in a thread
+  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 open <id>                   open it in a browser
 
   Where a command takes <id> it also takes the link you were sent. An unlisted
@@ -72,13 +78,19 @@ What you can publish
 
 Options
   --json                 machine-readable output
-  --title <text>         title for publish
+  --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
+  --folder <id>          destination folder for publish or fork
+  --version <v>          with fork: the version to copy (default: current)
   --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
+  --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
   --origin <url>         the deployment (default: the one you logged in to)
   --token <token>        override the stored token
@@ -188,7 +200,8 @@ async function list(flags) {
     }
     for (const doc of result.documents) {
       const marker = doc.visibility === "private" ? " " : doc.visibility === "public" ? "◉" : "◐";
-      console.log(`${marker} ${doc.id.padEnd(34)} ${doc.version.padEnd(5)} ${doc.title}`);
+      // ⑂ marks a fork; where it came from is `bikeshed lineage`'s to say.
+      console.log(`${marker} ${doc.id.padEnd(34)} ${doc.version.padEnd(5)} ${doc.title}${doc.forked ? "  ⑂" : ""}`);
     }
     if (result.nextCursor) console.log(`\n… more: --cursor ${result.nextCursor}`);
   });
@@ -299,6 +312,12 @@ 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).
+      if (thread.suggestion) {
+        const change = thread.suggestion.replacement === "" ? "(delete it)" : `“${thread.suggestion.replacement}”`;
+        console.log(`   → ${change}  [${thread.suggestion.state}]`);
+      }
       for (const comment of thread.comments) {
         const via = comment.via && comment.via !== "web" ? ` [via ${comment.via}]` : "";
         console.log(`   ${comment.author}${via}: ${comment.body}`);
@@ -320,6 +339,34 @@ async function reply(flags, [ref, threadId, ...rest]) {
   out(flags.json, result, () => console.log(`replied in ${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
+ * a quote can go straight from one command to the other.
+ */
+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 { origin, token } = resolveAuth(flags);
+  const result = await callTool(origin, token, "suggest_edit", {
+    ...docArgs(ref),
+    exact,
+    replacement: replacing ? flags.with : "",
+    ...(typeof flags.note === "string" ? { note: flags.note } : {}),
+    ...(typeof flags.prefix === "string" ? { prefix: flags.prefix } : {}),
+    ...(typeof flags.suffix === "string" ? { suffix: flags.suffix } : {}),
+  });
+  out(flags.json, result, () =>
+    console.log(`suggested in ${result.threadId}; a person who can approve will accept or reject it`),
+  );
+}
+
 async function folders(flags) {
   const { origin, token } = resolveAuth(flags);
   const result = await callTool(origin, token, "list_folders", {});
@@ -343,6 +390,71 @@ async function folders(flags) {
   });
 }
 
+/**
+ * Your own copy of a document you can read. The original's author sees that it
+ * was forked — a count, never who — and the fork records where it came from,
+ * which only people who can open the original are shown (SPEC §21).
+ */
+async function fork(flags, [ref]) {
+  if (!ref) fail("usage: bikeshed fork <id> [--version <v>] [--folder <id>] [--title <text>]");
+  const { origin, token } = resolveAuth(flags);
+  const args = docArgs(ref);
+  if (typeof flags.version === "string") args.version = flags.version;
+  if (typeof flags.folder === "string") args.folder = flags.folder;
+  if (typeof flags.title === "string") args.title = flags.title;
+  const result = await callTool(origin, token, "fork_document", args);
+  out(flags.json, { ...result, url: result.url ?? `${origin}/d/${result.docId}` }, () =>
+    console.log(`forked ${args.id} into ${result.docId} — ${result.url ?? `${origin}/d/${result.docId}`}`),
+  );
+}
+
+/**
+ * Where a document came from, nearest first, as far as you can open, and — for
+ * its owner — what has been forked from it. The deployment decides what you may
+ * see; this only prints it (SPEC §21).
+ */
+async function lineage(flags, [ref]) {
+  if (!ref) fail("usage: bikeshed lineage <id>");
+  const { origin, token } = resolveAuth(flags);
+  const result = await callTool(origin, token, "get_lineage", docArgs(ref));
+  out(flags.json, result, () => console.log(describeLineage(result)));
+}
+
+/** The human form of a get_lineage result. */
+function describeLineage(result) {
+  const lines = [];
+  if (result.forked) {
+    if (result.forkedFrom.length === 0) {
+      lines.push("forked from a document you can't open");
+    }
+    result.forkedFrom.forEach((a, i) => {
+      const changed = a.changedSince ? "   (changed since)" : "";
+      lines.push(`${i === 0 ? "forked from" : "  which was"}  ${a.id} ${a.version}  ${a.title}${changed}`);
+    });
+    if (result.forkedFrom.length > 0 && result.moreYouCannotOpen) {
+      lines.push("  which was   forked from a document you can't open");
+    }
+  } else if (!result.forks) {
+    lines.push(`${result.id} is not a fork.`);
+  }
+  if (result.forks) {
+    const { total, youCannotOpen, listed } = result.forks;
+    if (lines.length) lines.push("");
+    if (total === 0) {
+      lines.push("Nobody has forked it yet.");
+    } else {
+      const times = total === 1 ? "once" : `${total} times`;
+      lines.push(youCannotOpen ? `forked ${times}; ${youCannotOpen} you can't open` : `forked ${times}`);
+      for (const f of listed) {
+        const when = f.forkedAt ? f.forkedAt.slice(0, 10) : "";
+        const owner = f.owner ? `  ${f.owner}` : "";
+        lines.push(`  ${f.id.padEnd(34)} ${f.visibility.padEnd(8)} ${when.padEnd(10)} ${f.title}${owner}`);
+      }
+    }
+  }
+  return lines.join("\n");
+}
+
 async function mkdir(flags, rest) {
   const name = rest.join(" ");
   if (!name) fail("usage: bikeshed mkdir <name> [--parent <id>]");
@@ -454,9 +566,12 @@ const COMMANDS = {
   list,
   publish,
   update,
+  fork,
+  lineage,
   get,
   comments,
   reply,
+  suggest,
   open,
   folders,
   mkdir,
@@ -480,11 +595,17 @@ async function main() {
       title: { type: "string" },
       id: { type: "string" },
       folder: { type: "string" },
+      version: { type: "string" },
       parent: { type: "string" },
       origin: { type: "string" },
       token: { type: "string" },
       limit: { type: "string" },
       cursor: { type: "string" },
+      with: { type: "string" },
+      delete: { type: "boolean", default: false },
+      note: { type: "string" },
+      prefix: { type: "string" },
+      suffix: { type: "string" },
     },
   });