bikeshed-now 0.14.1 → 0.16.0

package/README.md

@@ -38,14 +38,16 @@ be using the same one: revoke it at `/account` once nothing needs it.
 bikeshed publish proposal.md --title "Storage migration"
 # published storage-migration v1 — https://bikeshed.now/d/storage-migration
 
-# Somebody highlights a sentence and says what is wrong with it.
+# Somebody highlights a sentence and says what is wrong with it. Wait for it:
+# the cursor comes from `publish --json`, and every `changes` prints the next one.
+bikeshed changes storage-migration --since <cursor> --wait
 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
+bikeshed update storage-migration proposal.md --base v1   # refused if somebody published since
 
 # Given "Can suggest" rather than "Can edit"? Propose the change instead, for a
 # person to accept or reject.
@@ -77,8 +79,21 @@ bikeshed publish platform.md --id 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
-random characters, and the CLI says so on stderr.
+`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.
+
+Ids are shared by the whole deployment and never change, so choose one every
+time: put the date first on something time-bound
+(`2026-10-09-storage-migration-review`), and the project on something that
+lives on (`billing-storage-migration`, not `migration`). 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.
+
+`bikeshed open <link>` opens a document in your browser, an unlisted one's key
+included. It opens the browser on the machine that runs it, so an agent in CI
+or a container should hand you the link instead.
 
 A rename changes the title and leaves the address alone, so links already sent
 keep working:
@@ -116,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
 

package/package.json

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

package/src/client.mjs

@@ -95,7 +95,7 @@ export async function callTool(origin, token, name, args = {}) {
  * with `update`, as a new version of that document, with `k` for an unlisted
  * one.
  */
-export async function uploadFile(origin, token, path, { title, folder, id, update, k } = {}) {
+export async function uploadFile(origin, token, path, { title, folder, id, update, k, base } = {}) {
   const bytes = readFileSync(path);
   const params = new URLSearchParams({ filename: basename(path) });
   if (title) params.set("title", title);
@@ -103,6 +103,7 @@ export async function uploadFile(origin, token, path, { title, folder, id, updat
   if (id) params.set("id", id);
   if (update) params.set("update", update);
   if (k) params.set("k", k);
+  if (base) params.set("baseVersion", base);
 
   const res = await fetch(`${origin}/publish?${params}`, {
     method: "POST",

package/src/index.mjs

@@ -54,6 +54,9 @@ const USAGE = `bikeshed ${VERSION} — publish and revise documents
   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 changes <id> --since <cursor|last|all>
+                                       what happened since a cursor; --wait to
+                                       keep checking until something does
   bikeshed comment <id> <text> --body <comment>
                                        start a thread on a passage
   bikeshed reply <id> <thread> <text>  reply in a thread
@@ -79,11 +82,23 @@ const USAGE = `bikeshed ${VERSION} — publish and revise documents
   document you are not a member of needs the link: its key is in it.
 
 Organising
-  bikeshed folders                     the folder tree, with ids
+  bikeshed folders                     the folder tree, with ids and readers
+  bikeshed folder <id>                 who can read a folder, and so what is in it
   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
 
+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
@@ -113,6 +128,16 @@ Options
   --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
+  --since <cursor>       with changes: a cursor publish, fork, get --json or
+                         changes printed; "last" where this sign-in left off;
+                         or "all"
+  --wait                 with changes: keep checking until something happens
+  --interval <s>         with changes --wait: seconds between checks (default
+                         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
+                         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
   --delete               with suggest or revise: propose deleting the passage
@@ -449,9 +474,11 @@ async function publish(flags, [path]) {
     }
     // The address is in the human line already; `--json` carried only the id, so
     // anything reading it had to know how to build a URL out of a docId.
-    out(flags.json, { ...result, url: result.url ?? `${origin}/d/${result.docId}` }, () =>
-      console.log(`published ${result.docId} ${result.versionId} — ${origin}/d/${result.docId}`),
-    );
+    out(flags.json, { ...result, url: result.url ?? `${origin}/d/${result.docId}` }, () => {
+      console.log(`published ${result.docId} ${result.versionId} — ${origin}/d/${result.docId}`);
+      const where = describeAccess(result);
+      if (where) console.log(where);
+    });
     return result;
   };
 
@@ -476,9 +503,16 @@ async function update(flags, [ref, path]) {
     const bytes = readFileSync(file);
     // An archive goes up as bytes, to the one endpoint that takes them. Read as
     // 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 result = isArchive(file, bytes)
-      ? await uploadFile(origin, token, file, { update: id, k: doc.k })
-      : await callTool(origin, token, "update_document", { ...doc, content: bytes.toString("utf8") });
+      ? await uploadFile(origin, token, file, { update: id, k: doc.k, base })
+      : await callTool(origin, token, "update_document", {
+          ...doc,
+          content: bytes.toString("utf8"),
+          ...(base ? { baseVersion: base } : {}),
+        });
     out(flags.json, { ...result, url: result.url ?? `${origin}/d/${id}` }, () =>
       console.log(
         result.deduped
@@ -726,7 +760,9 @@ async function folders(flags) {
       const depth = folder.path.split("/").length - 1;
       const label = `${"  ".repeat(depth)}${folder.name}`;
       const note = folder.canWrite ? "" : "  (read-only)";
-      console.log(`${label.padEnd(40)} ${folder.id}${note}`);
+      // Filing a document here shares it with everyone counted, and emails nobody.
+      const readers = typeof folder.readers === "number" ? `  ${folder.readers} can read` : "";
+      console.log(`${label.padEnd(40)} ${folder.id}${readers}${note}`);
     }
     if (result.truncated) {
       console.log("\nThere are more folders than this listing shows.");
@@ -734,6 +770,170 @@ async function folders(flags) {
   });
 }
 
+/**
+ * Where a published document is filed and who can read it there, from what the
+ * server read after the write, for a person to be told. Empty for a deployment
+ * too old to say.
+ */
+function describeAccess(result) {
+  const access = result.access;
+  if (!access) return "";
+  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}`;
+}
+
+/** 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>");
+  const { origin, token } = resolveAuth(flags);
+  const result = await callTool(origin, token, "get_folder", { id });
+  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(", ")}`);
+    console.log(`can edit: ${[...result.editors, ...(result.moreEditors ? [`and ${result.moreEditors} more`] : [])].join(", ")}`);
+  });
+}
+
+/** 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. */
+const MIN_INTERVAL_S = 30;
+
+/**
+ * What happened on a document since a cursor (SPEC §19, ADR 0016).
+ *
+ * `--since` is required: a check that starts from nowhere in particular
+ * reports nothing, and nothing reads as nothing happened. Every page is read
+ * before anything is printed, and the cursor printed last is the one to pass
+ * next time: replace whatever you held with it.
+ *
+ * `--wait` keeps checking until something happens, then prints it and exits 0.
+ * A harness that wakes an agent when a background command ends (Claude Code
+ * does) gets watching from one command. On timeout it exits 3 and still prints
+ * the cursor, so the next wait resumes rather than restarts.
+ */
+async function changes(flags, [ref]) {
+  const usage = "usage: bikeshed changes <id> --since <cursor|last|all> [--wait] [--interval <s>] [--timeout <s>]";
+  if (!ref) fail(usage);
+  if (typeof flags.since !== "string" || !flags.since) {
+    fail(`${usage}\n--since is required: a cursor that publish, fork, get --json or changes printed; "last", where this sign-in left off; or "all"`);
+  }
+  const interval = Math.max(MIN_INTERVAL_S, flags.interval === undefined ? 60 : Number(flags.interval) || 0);
+  const timeout = flags.timeout === undefined ? 3600 : Number(flags.timeout);
+  if (!Number.isFinite(timeout) || timeout < 0) fail(usage);
+  const { origin, token } = resolveAuth(flags);
+  const doc = docArgs(ref);
+  const started = Date.now();
+  let since = flags.since;
+  const events = [];
+  for (;;) {
+    const result = await callTool(origin, token, "get_changes", { ...doc, since });
+    since = result.cursor;
+    events.push(...result.events);
+    if (result.more) continue;
+    const waitFor = Math.max(interval, Number(result.retryAfter) || 0);
+    if (!flags.wait || events.length > 0) return printChanges(flags, { ...result, events });
+    if ((Date.now() - started) / 1000 + waitFor > timeout) {
+      process.exitCode = WAIT_TIMED_OUT;
+      return printChanges(flags, { ...result, events, timedOut: true });
+    }
+    await new Promise((r) => setTimeout(r, waitFor * 1000));
+  }
+}
+
+function printChanges(flags, result) {
+  out(flags.json, result, () => {
+    if (result.timedOut) console.log("nothing new before the timeout");
+    for (const e of result.events) {
+      const quote = e.quote ? ` “${e.quote}”` : "";
+      const words = e.body ? `: ${e.body}` : e.replacement !== undefined ? ` → “${e.replacement}”` : "";
+      const via = e.channel && e.channel !== "web" ? ` [via ${e.channel}]` : "";
+      console.log(`${e.at}  ${e.type}  ${e.by ?? ""}${via}${e.threadId ? `  (${e.threadId})` : ""}${quote}${words}`);
+    }
+    if (result.needsReply?.length) console.log(`waiting on a reply: ${result.needsReply.join(", ")}`);
+    console.log(`next: --since ${result.cursor}`);
+  });
+}
+
 /**
  * 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,
@@ -935,6 +1135,7 @@ const COMMANDS = {
   lineage,
   get,
   comments,
+  changes,
   comment,
   reply,
   resolve: resolveThread,
@@ -946,7 +1147,13 @@ const COMMANDS = {
   reject,
   commit,
   open,
+  access,
+  visibility,
+  "rename-folder": renameFolder,
+  "move-folder": moveFolder,
+  "delete-folder": deleteFolder,
   folders,
+  folder,
   mkdir,
   mv,
   rename,
@@ -962,6 +1169,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 },
@@ -984,6 +1196,11 @@ async function main() {
       body: { type: "string" },
       prefix: { type: "string" },
       suffix: { type: "string" },
+      since: { type: "string" },
+      wait: { type: "boolean", default: false },
+      interval: { type: "string" },
+      timeout: { type: "string" },
+      base: { type: "string" },
     },
   });