bikeshed-now 0.15.0 → 0.17.0

package/README.md

@@ -131,10 +131,26 @@ 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
-expiry. Those are decisions a person makes in the interface, deliberately.
+## Manage access and folders
+
+`bikeshed access document <id>` and `bikeshed access folder <id>` show the
+owner, direct grants, inherited grants and effective membership. Add or change
+a direct role with `--add email@example.com,team:design --role editor`; revoke
+with `--remove email@example.com`. All four roles are supported. The owner
+cannot be removed, and inherited grants must be changed at their source.
+Newly effective readers receive an invitation when email is enabled.
+
+`bikeshed visibility <id>` shows settings. Add `private`, `unlisted` or `public`
+to change visibility, `--public-edit true|false` to change open editing, or
+`--expires <ISO-8601 timestamp with timezone|none>` to set or clear expiry.
+Omitted settings stay unchanged. These commands are owner-only, including on
+expired documents; the returned URL includes an unlisted key when needed.
+
+`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
+root, and access is recomputed. No documents are deleted. All commands support
+`--json`. Existing sign-ins work without reconnecting.
 
 ## For agents
 
@@ -150,3 +166,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.15.0",
+  "version": "0.17.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>
@@ -88,6 +89,17 @@ Organising
   bikeshed mv <id> <folder|root>       move a document
   bikeshed rename <id> <title>         change a document's title; its address stays
 
+Management
+  bikeshed access <document|folder> <id>  inspect direct and inherited permissions
+    --add <principals> --role <role>    grant/change roles (emails or team:<id>, comma-separated)
+    --remove <principals>              revoke direct grants; inherited access remains
+  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 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
+
 Skills
   bikeshed skills                      skills this deployment publishes
   bikeshed skills install <dir>        write them into an agent's skills directory
@@ -111,9 +123,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
@@ -125,7 +137,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
@@ -164,18 +176,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");
+  }
+  // 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 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 } : {}) };
+  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]);
@@ -485,7 +510,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 () => {
@@ -494,7 +519,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", {
@@ -516,10 +541,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
@@ -544,9 +589,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),
   });
@@ -592,7 +635,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 } : {}),
@@ -606,7 +649,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,
   });
@@ -630,7 +673,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}`));
 }
 
@@ -646,7 +689,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 } : {}),
@@ -678,7 +721,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 } : {}),
@@ -694,8 +737,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`));
 }
 
@@ -703,7 +747,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}`),
   );
@@ -717,9 +762,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 } : {}),
   });
@@ -730,7 +776,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}`));
 }
 
@@ -788,6 +834,80 @@ async function folder(flags, [id]) {
   });
 }
 
+/** Complete owner-visible grants, including why a removed direct grant may still read. */
+function printManagedAccess(result) {
+  console.log(`${result.kind} ${result.id} — owner: ${result.owner}`);
+  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"}`);
+  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()}`);
+  console.log(result.url);
+}
+
+async function access(flags, [kind, ref, ...rest]) {
+  if (!["document", "folder"].includes(kind) || !ref || rest.length) fail("usage: bikeshed access <document|folder> <id> [--add <principals> --role <role>] [--remove <principals>]");
+  const args = { id: kind === "document" ? docArgs(ref).id : ref };
+  const list = raw => {
+    if (typeof raw !== "string" || !raw.trim()) fail("principal list must not be empty");
+    const values = raw.split(",").map(p => p.trim());
+    if (values.some(p => !p)) fail("principal list contains an empty entry");
+    return values;
+  };
+  if (flags.add !== undefined) {
+    if (!["viewer", "suggester", "editor", "approver"].includes(flags.role)) fail("--add requires --role viewer|suggester|editor|approver");
+    args.add = list(flags.add).map(principal => ({ principal, role: flags.role }));
+  } else if (flags.role !== undefined) fail("--role requires --add");
+  if (flags.remove !== undefined) args.remove = list(flags.remove);
+  const { origin, token } = resolveAuth(flags);
+  const result = await callTool(origin, token, `${args.add || args.remove ? "set" : "get"}_${kind}_access`, args);
+  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 };
+  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");
+    args.publicEdit = flags["public-edit"] === "true";
+  }
+  if (flags.expires !== undefined) {
+    if (flags.expires === "none") args.expiresAt = null;
+    else {
+      if (typeof flags.expires !== "string" || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?(?:Z|[+-]\d{2}:\d{2})$/.test(flags.expires) || !Number.isFinite(Date.parse(flags.expires))) fail("--expires must be an ISO-8601 timestamp with a timezone, or none");
+      args.expiresAt = Date.parse(flags.expires);
+    }
+  }
+  const { origin, token } = resolveAuth(flags);
+  const result = await callTool(origin, token, Object.keys(args).length > 1 ? "set_document_visibility" : "get_document_access", args);
+  out(flags.json, result, () => printVisibility(result));
+}
+
+async function renameFolder(flags, [id, name, ...rest]) {
+  if (!id || !name || rest.length) fail("usage: bikeshed rename-folder <id> <name>");
+  const { origin, token } = resolveAuth(flags);
+  const result = await callTool(origin, token, "rename_folder", { id, name });
+  out(flags.json, result, () => console.log(`renamed ${id}: ${result.path}`));
+}
+
+async function moveFolder(flags, [id, parent, ...rest]) {
+  if (!id || !parent || rest.length) fail("usage: bikeshed move-folder <id> <folder|root>");
+  const { origin, token } = resolveAuth(flags);
+  const result = await callTool(origin, token, "move_folder", { id, ...(parent === "root" ? {} : { parent }) });
+  out(flags.json, result, () => console.log(`moved ${id}: ${result.path}; ${result.access.readers} can read it`));
+}
+
+async function deleteFolder(flags, [id, ...rest]) {
+  if (!id || rest.length) fail("usage: bikeshed delete-folder <id>");
+  const { origin, token } = resolveAuth(flags);
+  const result = await callTool(origin, token, "delete_folder", { id });
+  out(flags.json, result, () => console.log(`deleted ${id}; moved ${result.reparented.folders} folders and ${result.reparented.documents} documents to ${result.parent ?? "root"}`));
+}
+
 /** Exit status when `changes --wait` gives up: distinct from 1, an error. */
 const WAIT_TIMED_OUT = 3;
 /** The shortest wait between checks: each one reads the log and the document. */
@@ -857,7 +977,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;
@@ -1009,8 +1129,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.
@@ -1049,6 +1169,7 @@ const COMMANDS = {
   fork,
   lineage,
   get,
+  versions,
   comments,
   changes,
   comment,
@@ -1062,6 +1183,11 @@ const COMMANDS = {
   reject,
   commit,
   open,
+  access,
+  visibility,
+  "rename-folder": renameFolder,
+  "move-folder": moveFolder,
+  "delete-folder": deleteFolder,
   folders,
   folder,
   mkdir,
@@ -1079,6 +1205,11 @@ async function main() {
     allowPositionals: true,
     strict: false,
     options: {
+      add: { type: "string" },
+      remove: { type: "string" },
+      role: { type: "string" },
+      "public-edit": { type: "string" },
+      expires: { type: "string" },
       json: { type: "boolean", default: false },
       watch: { type: "boolean", default: false },
       all: { type: "boolean", default: false },
@@ -1123,6 +1254,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}`);