bikeshed-now 0.4.0 → 0.5.0

package/README.md

@@ -3,24 +3,26 @@
 Publish a document to a [Bikeshed](https://bikeshed.now) deployment, then read
 the comments people left on it — each one with the exact sentence it is about.
 
-Bikeshed is self-hosted. This client talks to whichever deployment you point it
-at, over HTTPS, with a personal access token that carries exactly your own
-permissions.
+It talks to [bikeshed.now](https://bikeshed.now) over HTTPS, with a personal
+access token that carries exactly your own permissions. Bikeshed is also
+self-hostable: point the client at your own deployment and everything below
+works the same, with your address in place of `https://bikeshed.now`.
 
 ```bash
 npm i -g bikeshed-now
 bikeshed login            # asks for the deployment and a token
 ```
 
-Create a token in the deployment's interface, under **Account → Access tokens**.
-It is shown once. `BIKESHED_ORIGIN` and `BIKESHED_TOKEN` work instead of
-`login` where an interactive command cannot run — a CI job, or an agent.
+Create a token at [bikeshed.now/account](https://bikeshed.now/account) — choose
+**Command line**. It is shown once. `BIKESHED_ORIGIN` and `BIKESHED_TOKEN` work
+instead of `login` where an interactive command cannot run — a CI job, or an
+agent.
 
 ## The loop
 
 ```bash
 bikeshed publish proposal.md --title "Storage migration"
-# published storage-migration v1 — https://<deployment>/d/storage-migration
+# published storage-migration v1 — https://bikeshed.now/d/storage-migration
 
 # Somebody highlights a sentence and says what is wrong with it.
 bikeshed comments storage-migration
@@ -42,7 +44,7 @@ The address comes from the title. To choose it, pass `--id`:
 
 ```bash
 bikeshed publish platform.md --id 01-platform
-# published 01-platform v1 — https://<deployment>/d/01-platform
+# published 01-platform v1 — https://bikeshed.now/d/01-platform
 ```
 
 If the id is taken, the document is still published, at the id plus a few
@@ -53,12 +55,30 @@ 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.
 
 ```bash
-bikeshed comments 'https://<deployment>/d/build-estimate?k=…'
+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
@@ -66,8 +86,9 @@ expiry. Those are decisions a person makes in the interface, deliberately.
 
 ## For agents
 
-A deployment serves its own instructions at `https://<deployment>/llms.txt`, and
-the skills behind them at `/skills/index.json`. `bikeshed skills install <dir>`
+A deployment serves its own instructions at
+[`https://bikeshed.now/llms.txt`](https://bikeshed.now/llms.txt), and the skills
+behind them at `/skills/index.json`. `bikeshed skills install <dir>`
 writes them where your harness reads skills from.
 
 Everything done with a token is stamped with the channel it came through, so a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bikeshed-now",
-  "version": "0.4.0",
+  "version": "0.5.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.0";
+export const CLIENT_NAME = "bikeshed-cli/0.5.0";
 
 /**
  * Three surfaces, and the split is deliberate rather than untidy.

package/src/index.mjs

@@ -39,6 +39,8 @@ 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
@@ -72,9 +74,10 @@ 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
@@ -188,7 +191,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}`);
   });
@@ -343,6 +347,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,6 +523,8 @@ const COMMANDS = {
   list,
   publish,
   update,
+  fork,
+  lineage,
   get,
   comments,
   reply,
@@ -480,6 +551,7 @@ async function main() {
       title: { type: "string" },
       id: { type: "string" },
       folder: { type: "string" },
+      version: { type: "string" },
       parent: { type: "string" },
       origin: { type: "string" },
       token: { type: "string" },