bikeshed-now 0.16.0 → 0.18.0

package/README.md

@@ -82,7 +82,10 @@ bikeshed publish platform.md --id 01-platform
 `publish` says where it filed the document and who can read it there.
 `bikeshed folders` counts who can read each folder, and `bikeshed folder <id>`
 names them: filing a document in a folder shares it with all of them, and
-nobody is emailed.
+nobody is emailed. Under a folder shared by link or made public it is readable
+by anyone holding the link, or anyone, and the output says through which
+folder. Given a folder's link, `bikeshed folder <link>` lists what that link
+opens, to read only.
 
 Ids are shared by the whole deployment and never change, so choose one every
 time: put the date first on something time-bound
@@ -146,6 +149,13 @@ to change visibility, `--public-edit true|false` to change open editing, or
 Omitted settings stay unchanged. These commands are owner-only, including on
 expired documents; the returned URL includes an unlisted key when needed.
 
+`bikeshed visibility folder <id|link>` does the same for a folder, without
+`--public-edit`. A folder's link or public level opens everything beneath it to
+read, without an account: its subfolders, documents filed later, and documents
+that are private on their own. Its expiry ends only that; the people it is
+shared with keep their access. `bikeshed visibility document <id>` names a
+document explicitly, for one whose id is `folder`.
+
 `bikeshed rename-folder <id> <name>` and
 `bikeshed move-folder <id> <folder|root>` require edit rights.
 `bikeshed delete-folder <id>` is owner-only: contents move to its parent or the
@@ -166,3 +176,32 @@ reviewer can always tell which feedback came from a person.
 
 Apache-2.0. The deployment it talks to is the same repository:
 [DeputyHumans/bikeshed-now](https://github.com/DeputyHumans/bikeshed-now).
+
+### Previous versions and write guards
+
+Use `list_versions({id, limit:20, cursor})` or `bikeshed versions <id|link>
+--all --json` to discover published history. Pages are newest first, default 20,
+maximum 50; pass `nextCursor` as `cursor` until null. Each row has a pinned URL.
+History uses the document's current access rules and expiry. A missing or
+withdrawn version is an error, never a request for the latest version.
+
+Read a chosen version with `get_document({id, version:"v2"})` and
+`get_comments({id, version:"v2", includeResolved:true})`, or
+`bikeshed get <id> --version v2` and `bikeshed comments <id> --version v2 --all`.
+Read results name `currentVersion` and `isCurrent`; historical write capabilities
+are false. Existing comments and suggestions remain readable as an archive.
+Older versions cannot be edited or receive, revise, delete, reply to, resolve,
+reopen, accept, reject, claim or withdraw feedback. Fork one to make a new,
+independent document with `fork_document({id, version:"v2"})`.
+
+CLI `get`, `comments`, `fork`, and `open` preserve a version in a pasted
+`/d/<id>/<version>?k=...` URL. Feedback commands also preserve it as a write
+guard. `--version` must agree with the URL; conflicts fail. Keys are retained.
+Document-wide sharing, folder and lineage operations still address the document.
+
+Before changing feedback, read the latest version and its feedback, then pass
+that `version` to every feedback tool (`--version` in the CLI). Pass
+`baseVersion` to `update_document` and `commit_draft` (`--base` on `bikeshed
+update` and `bikeshed commit`). A versioned URL supplies the CLI base too.
+If the head changes, the server refuses the write. Read the new head and
+reassess the request; never silently redirect a historical request to it.

package/package.json

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

package/src/index.mjs

@@ -51,7 +51,8 @@ const USAGE = `bikeshed ${VERSION} — publish and revise documents
   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 get <id> [--version <v>]    print a published version's source
+  bikeshed versions <id>               list published history (--all for every page)
   bikeshed comments <id>               unresolved feedback, with its anchored text
                                        (--version <v> for an earlier version's)
   bikeshed changes <id> --since <cursor|last|all>
@@ -83,7 +84,8 @@ const USAGE = `bikeshed ${VERSION} — publish and revise documents
 
 Organising
   bikeshed folders                     the folder tree, with ids and readers
-  bikeshed folder <id>                 who can read a folder, and so what is in it
+  bikeshed folder <id|link>            who can read a folder, and so what is in it;
+                                       with a folder's link, what the link opens
   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
@@ -95,6 +97,9 @@ Management
   bikeshed visibility <id> [private|unlisted|public]
     --public-edit true|false            change open editing
     --expires <ISO timestamp|none>      set or clear expiry; omitted settings stay unchanged
+  bikeshed visibility folder <id> [private|unlisted|public] [--expires <ISO timestamp|none>]
+                                       a folder's link or public level opens EVERYTHING
+                                       beneath it to read; its expiry ends only that
   bikeshed rename-folder <id> <name>    rename a folder you can edit
   bikeshed move-folder <id> <folder|root> move a folder and recompute inherited access
   bikeshed delete-folder <id>           owner-only; reparent contents, retain documents
@@ -122,9 +127,9 @@ 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; with comments: the
-                         version to read (default: current); on its own,
-                         which version of bikeshed this is
+  --version <v>          get/comments/fork/open: the published version to read
+                         or copy; feedback commands: require that version to
+                         still be current. On its own: the CLI version
   --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
@@ -136,7 +141,7 @@ Options
                          60, at least 30)
   --timeout <s>          with changes --wait: give up after this long (default
                          3600), exit 3, and print the cursor to resume from
-  --base <v>             with update: the version you revised; refused if
+  --base <v>             with update/commit: the version you revised; refused if
                          somebody has published since
   --all                  with list: every page; with comments: resolved too
   --with <text>          with suggest or revise: what the passage should say instead
@@ -175,18 +180,31 @@ function out(json, value, human) {
  * for both — `…/d/<id>[/<version>]?k=<key>` — and the key goes along as the
  * tools' `k` argument (SPEC §17).
  */
-function docArgs(ref) {
-  if (!/^https?:\/\//i.test(ref)) return { id: ref };
-  let url;
-  try {
-    url = new URL(ref);
-  } catch {
-    fail(`not a document link: ${ref}`);
+function docArgs(ref, flags) {
+  let id = ref;
+  let k;
+  let linkedVersion;
+  if (/^https?:\/\//i.test(ref)) {
+    let url;
+    try { url = new URL(ref); } catch { fail(`not a document link: ${ref}`); }
+    const match = url.pathname.match(/^\/d\/([^/]+)(?:\/([^/]+))?\/?$/);
+    if (!match) fail(`not a document link: ${ref}`);
+    id = decodeURIComponent(match[1]);
+    linkedVersion = match[2] ? decodeURIComponent(match[2]) : undefined;
+    k = url.searchParams.get("k");
   }
-  const match = url.pathname.match(/^\/d\/([^/]+)(?:\/[^/]+)?\/?$/);
-  if (!match) fail(`not a document link: ${ref}`);
-  const k = url.searchParams.get("k");
-  return { id: decodeURIComponent(match[1]), ...(k ? { k } : {}) };
+  // Document-wide operations deliberately use only the document id/key.
+  if (flags === undefined) return { id, ...(k ? { k } : {}) };
+  const explicit = flags.version;
+  if (explicit !== undefined && (typeof explicit !== "string" || !explicit || /[\/\\?#\s]/.test(explicit))) {
+    fail("invalid version");
+  }
+  if (explicit && linkedVersion && explicit !== linkedVersion) {
+    fail(`conflicting versions: the link names ${linkedVersion}, the flag names ${explicit}`);
+  }
+  const version = explicit ?? linkedVersion;
+  if (version && (version === "." || version === ".." || /[\/\\?#\s]/.test(version))) fail("invalid version");
+  return { id, ...(k ? { k } : {}), ...(version ? { version } : {}) };
 }
 
 const ZIP_MAGIC = Buffer.from([0x50, 0x4b, 0x03, 0x04]);
@@ -496,7 +514,7 @@ async function update(flags, [ref, path]) {
   if (!ref || !path) fail("usage: bikeshed update <id> <file>");
   const { origin, token } = resolveAuth(flags);
   const file = resolve(path);
-  const doc = docArgs(ref);
+  const { version: selectedBase, ...doc } = docArgs(ref, { version: flags.base });
   const { id } = doc;
 
   const once = async () => {
@@ -505,7 +523,7 @@ async function update(flags, [ref, path]) {
     // text, every byte above 0x7f in it would become U+FFFD on the way.
     // --base: the version this was revised from, so an update over somebody's
     // newer save is refused instead of replacing it (SPEC §19).
-    const base = typeof flags.base === "string" && flags.base ? flags.base : undefined;
+    const base = selectedBase;
     const result = isArchive(file, bytes)
       ? await uploadFile(origin, token, file, { update: id, k: doc.k, base })
       : await callTool(origin, token, "update_document", {
@@ -527,10 +545,30 @@ async function update(flags, [ref, path]) {
   if (flags.watch) await watchFile(file, once);
 }
 
+/** The published history, paged by the deployment rather than guessed from ids. */
+async function versions(flags, [ref, ...rest]) {
+  if (!ref || rest.length) fail("usage: bikeshed versions <id> [--limit N] [--cursor …] [--all] [--json]");
+  const { origin, token } = resolveAuth(flags);
+  const limit = flags.limit === undefined ? 20 : Number(flags.limit);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 50) fail("--limit must be an integer from 1 to 50");
+  let cursor = flags.cursor;
+  const rows = [];
+  let result;
+  do {
+    result = await callTool(origin, token, "list_versions", { ...docArgs(ref), limit, ...(cursor ? { cursor } : {}) });
+    rows.push(...result.versions);
+    cursor = result.nextCursor;
+  } while (flags.all && cursor);
+  out(flags.json, { ...result, versions: rows }, () => {
+    for (const row of rows) console.log(`${row.isCurrent ? "*" : " "} ${row.version}  ${row.publishedAt ?? ""}  ${row.label}  ${row.url ?? ""}`);
+    if (cursor) console.log(`… more: bikeshed versions ${ref} --cursor ${cursor}`);
+  });
+}
+
 async function get(flags, [ref]) {
   if (!ref) fail("usage: bikeshed get <id>");
   const { origin, token } = resolveAuth(flags);
-  const doc = docArgs(ref);
+  const doc = docArgs(ref, flags);
   const result = await callTool(origin, token, "get_document", doc);
   // The tool cuts a long source at a fixed length. Printed as it came, the cut
   // copy exited 0 and looked complete, and `update` with an edit of it
@@ -555,9 +593,7 @@ async function comments(flags, [ref]) {
   if (!ref) fail("usage: bikeshed comments <id>");
   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.
+    ...docArgs(ref, flags),
     ...(typeof flags.version === "string" ? { version: flags.version } : {}),
     includeResolved: Boolean(flags.all),
   });
@@ -603,7 +639,7 @@ async function comment(flags, [ref, ...rest]) {
   if (typeof flags.body !== "string" || !flags.body.trim()) fail(usage);
   const { origin, token } = resolveAuth(flags);
   const result = await callTool(origin, token, "add_comment", {
-    ...docArgs(ref),
+    ...docArgs(ref, flags),
     exact,
     body: flags.body,
     ...(typeof flags.prefix === "string" ? { prefix: flags.prefix } : {}),
@@ -617,7 +653,7 @@ async function reply(flags, [ref, threadId, ...rest]) {
   if (!ref || !threadId || !body) fail("usage: bikeshed reply <id> <thread> <text>");
   const { origin, token } = resolveAuth(flags);
   const result = await callTool(origin, token, "reply_to_comment", {
-    ...docArgs(ref),
+    ...docArgs(ref, flags),
     threadId,
     body,
   });
@@ -641,7 +677,7 @@ async function reopenThread(flags, args) {
 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 });
+  const result = await callTool(origin, token, `${verb}_thread`, { ...docArgs(ref, flags), threadId });
   out(flags.json, result, () => console.log(`${verb === "resolve" ? "resolved" : "reopened"} ${threadId}`));
 }
 
@@ -657,7 +693,7 @@ async function suggest(flags, [ref, ...rest]) {
   const replacement = replacementFrom(flags, usage);
   const { origin, token } = resolveAuth(flags);
   const result = await callTool(origin, token, "suggest_edit", {
-    ...docArgs(ref),
+    ...docArgs(ref, flags),
     exact,
     replacement,
     ...(typeof flags.note === "string" ? { note: flags.note } : {}),
@@ -689,7 +725,7 @@ async function revise(flags, [ref, threadId, ...rest]) {
   const replacement = replacementFrom(flags, usage);
   const { origin, token } = resolveAuth(flags);
   const result = await callTool(origin, token, "revise_suggestion", {
-    ...docArgs(ref),
+    ...docArgs(ref, flags),
     threadId,
     replacement,
     ...(typeof flags.note === "string" ? { note: flags.note } : {}),
@@ -705,8 +741,9 @@ async function revise(flags, [ref, threadId, ...rest]) {
 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 });
+  const { id, version } = docArgs(ref, flags);
+  // Deciding still takes a real role; a version is only a precondition.
+  const result = await callTool(origin, token, "accept_suggestion", { id, ...(version ? { version } : {}), threadId });
   out(flags.json, result, () => console.log(`accepted ${threadId}; the change is in the draft — \`bikeshed commit\` publishes it`));
 }
 
@@ -714,7 +751,8 @@ async function accept(flags, [ref, threadId, ...rest]) {
 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 });
+  const { id, version } = docArgs(ref, { version: flags.base });
+  const result = await callTool(origin, token, "commit_draft", { id, ...(version ? { baseVersion: version } : {}) });
   out(flags.json, result, () =>
     console.log(result.deduped ? `nothing new: the draft is ${result.versionId} already` : `published ${result.versionId}`),
   );
@@ -728,9 +766,10 @@ async function commit(flags, [ref, ...rest]) {
 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 { id, version } = docArgs(ref, flags);
+  // Deciding still takes a real role; a version is only a precondition.
   const result = await callTool(origin, token, "reject_suggestion", {
-    id: docArgs(ref).id,
+    id, ...(version ? { version } : {}),
     threadId,
     ...(typeof flags.reason === "string" ? { reason: flags.reason } : {}),
   });
@@ -741,7 +780,7 @@ async function reject(flags, [ref, threadId, ...rest]) {
 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 });
+  const result = await callTool(origin, token, "withdraw_suggestion", { ...docArgs(ref, flags), threadId });
   out(flags.json, result, () => console.log(`withdrew ${threadId}`));
 }
 
@@ -781,20 +820,51 @@ function describeAccess(result) {
   const where = result.filedIn ? `filed in ${result.filedIn.path}` : "at the root";
   const who = access.readers === 1 ? "only you can read it" : `${access.readers} people can read it`;
   const also = access.alsoReadableBy ? `, and ${access.alsoReadableBy}` : "";
-  return `${where}: ${who}${also}`;
+  // A folder's link or public level reaches what is filed beneath it; say which.
+  const through = access.throughFolders?.length
+    ? ` (through ${access.throughFolders.map((f) => f.path).join(", ")})`
+    : "";
+  return `${where}: ${who}${also}${through}`;
+}
+
+/**
+ * A folder's id, and its key when what was pasted is the folder's link,
+ * `…/folder/<id>?k=<key>` (SPEC §17 "A folder's reach").
+ */
+function folderArgs(ref) {
+  if (!/^https?:\/\//i.test(ref)) return { id: ref };
+  let url;
+  try { url = new URL(ref); } catch { fail(`not a folder link: ${ref}`); }
+  const match = url.pathname.match(/^\/folder\/([^/]+)\/?$/);
+  if (!match) fail(`not a folder link: ${ref}`);
+  const k = url.searchParams.get("k");
+  return { id: decodeURIComponent(match[1]), ...(k ? { k } : {}) };
 }
 
 /** Who can read one folder: and so who can read anything filed in it. */
-async function folder(flags, [id]) {
-  if (!id) fail("usage: bikeshed folder <id>");
+async function folder(flags, [ref]) {
+  if (!ref) fail("usage: bikeshed folder <id|link>");
   const { origin, token } = resolveAuth(flags);
-  const result = await callTool(origin, token, "get_folder", { id });
+  const result = await callTool(origin, token, "get_folder", folderArgs(ref));
+  // Opened by its link: what it holds, to read, and nothing about who reads it.
+  if (result.viaLink) {
+    out(flags.json, result, () => {
+      console.log(`${result.path.map((p) => p.name).join("/")}  ${result.folderId}  (read-only, through its link)`);
+      for (const f of result.folders) console.log(`  ${f.name}/  ${f.folderId}`);
+      for (const d of result.documents) console.log(`  ${d.title}  ${d.url ?? d.docId}`);
+      if (result.truncated) console.log("  (more than can be listed at once)");
+    });
+    return;
+  }
   out(flags.json, result, () => {
     console.log(`${result.path}  ${result.id}${result.canWrite ? "" : "  (read-only)"}`);
     console.log(`${result.readers} can read it${result.readers === 1 ? " (only you)" : ""}:`);
     for (const person of result.people) console.log(`  ${person}`);
     if (result.morePeople > 0) console.log(`  and ${result.morePeople} more`);
     if (result.teams.length) console.log(`teams: ${result.teams.join(", ")}`);
+    for (const f of result.throughFolders ?? []) {
+      console.log(`also ${f.visibility === "public" ? "anyone" : "anyone with the link"}, through ${f.path}${f.expiresAt === null ? "" : ` until ${new Date(f.expiresAt).toISOString()}`}`);
+    }
     console.log(`can edit: ${[...result.editors, ...(result.moreEditors ? [`and ${result.moreEditors} more`] : [])].join(", ")}`);
   });
 }
@@ -805,11 +875,18 @@ function printManagedAccess(result) {
   for (const [role, people] of Object.entries(result.direct)) console.log(`${role}: ${people.join(", ") || "none"}`);
   for (const grant of result.inherited) console.log(`inherited ${grant.role}: ${grant.principal} via ${grant.path}`);
   for (const [role, people] of Object.entries(result.effective)) console.log(`${role}: ${people.join(", ") || "none"}`);
+  for (const r of result.inheritedReach ?? []) {
+    console.log(`readable by ${r.visibility === "public" ? "anyone" : "anyone with the folder's link"} through ${r.path}${r.expiresAt === null ? "" : `, until ${new Date(r.expiresAt).toISOString()}`}`);
+  }
   if (result.visibility !== undefined) printVisibility(result);
 }
 
 function printVisibility(result) {
-  console.log(`visibility: ${result.visibility}; open editing: ${result.publicEdit ? "on" : "off"}; expires: ${result.expiresAt === null ? "never" : new Date(result.expiresAt).toISOString()}`);
+  const expires = result.expiresAt === null ? "never" : new Date(result.expiresAt).toISOString();
+  // A folder has no open editing, and its date ends only its link.
+  console.log(result.publicEdit === undefined
+    ? `visibility: ${result.visibility}; link ends: ${expires}`
+    : `visibility: ${result.visibility}; open editing: ${result.publicEdit ? "on" : "off"}; expires: ${expires}`);
   console.log(result.url);
 }
 
@@ -832,9 +909,16 @@ async function access(flags, [kind, ref, ...rest]) {
   out(flags.json, result, () => printManagedAccess(result));
 }
 
-async function visibility(flags, [ref, level, ...rest]) {
-  if (!ref || rest.length || (level !== undefined && !["private", "unlisted", "public"].includes(level))) fail("usage: bikeshed visibility <id> [private|unlisted|public] [--public-edit true|false] [--expires <ISO timestamp|none>]");
-  const args = { id: docArgs(ref).id };
+async function visibility(flags, positionals) {
+  // `visibility folder <id> …` and `visibility document <id> …` name the kind;
+  // a bare `visibility <id>` is a document, as it always was.
+  const named = ["folder", "document"].includes(positionals[0]) && positionals.length > 1;
+  const kind = named ? positionals[0] : "document";
+  const [ref, level, ...rest] = named ? positionals.slice(1) : positionals;
+  const usage = "usage: bikeshed visibility [folder|document] <id> [private|unlisted|public] [--public-edit true|false] [--expires <ISO timestamp|none>]";
+  if (!ref || rest.length || (level !== undefined && !["private", "unlisted", "public"].includes(level))) fail(usage);
+  if (kind === "folder" && flags["public-edit"] !== undefined) fail("a folder has no open editing: what its link opens is read-only");
+  const args = { id: kind === "folder" ? folderArgs(ref).id : docArgs(ref).id };
   if (level !== undefined) args.visibility = level;
   if (flags["public-edit"] !== undefined) {
     if (!["true", "false"].includes(flags["public-edit"])) fail("--public-edit must be true or false");
@@ -848,7 +932,11 @@ async function visibility(flags, [ref, level, ...rest]) {
     }
   }
   const { origin, token } = resolveAuth(flags);
-  const result = await callTool(origin, token, Object.keys(args).length > 1 ? "set_document_visibility" : "get_document_access", args);
+  const changing = Object.keys(args).length > 1;
+  const tool = kind === "folder"
+    ? (changing ? "set_folder_visibility" : "get_folder_access")
+    : (changing ? "set_document_visibility" : "get_document_access");
+  const result = await callTool(origin, token, tool, args);
   out(flags.json, result, () => printVisibility(result));
 }
 
@@ -942,7 +1030,7 @@ function printChanges(flags, result) {
 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);
+  const args = docArgs(ref, flags);
   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;
@@ -1094,8 +1182,8 @@ async function open(flags, [ref]) {
   const { origin } = resolveAuth(flags);
   // 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)}` : ""}`;
+  const { id, k, version } = docArgs(ref, flags);
+  const url = `${origin}/d/${encodeURIComponent(id)}${version ? `/${encodeURIComponent(version)}` : ""}${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.
@@ -1134,6 +1222,7 @@ const COMMANDS = {
   fork,
   lineage,
   get,
+  versions,
   comments,
   changes,
   comment,
@@ -1218,6 +1307,10 @@ async function main() {
     return;
   }
 
+  const versionCommands = new Set(["get", "comments", "fork", "open", "comment", "reply", "resolve", "reopen", "suggest", "revise", "withdraw", "accept", "reject"]);
+  if (values.version !== undefined && !versionCommands.has(name)) fail(`--version is not supported by ${name}; update and commit use --base`);
+  if (values.base !== undefined && !["update", "commit"].includes(name)) fail(`--base is not supported by ${name}`);
+
   const command = COMMANDS[name];
   if (!command) fail(`unknown command: ${name}\n\n${USAGE}`);