bikeshed-now 0.1.0 → 0.3.0

package/README.md

@@ -34,6 +34,16 @@ Publishing identical bytes is a no-op: the bundle is hashed, and a matching hash
 mints no new version. So `update` is safe in a loop, in CI, or after a change you
 are not sure you made.
 
+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
+```
+
+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 --help` lists the rest — listing documents, folders, and installing the
 agent skills a deployment serves.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bikeshed-now",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "license": "Apache-2.0",
   "type": "module",
   "description": "Publish and revise documents on a Bikeshed deployment from the terminal.",
@@ -23,7 +23,7 @@
     "url": "https://github.com/DeputyHumans/bikeshed-now/issues"
   },
   "bin": {
-    "bikeshed": "./src/index.mjs"
+    "bikeshed": "src/index.mjs"
   },
   "engines": {
     "node": ">=20"

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.1.0";
+export const CLIENT_NAME = "bikeshed-cli/0.3.0";
 
 /**
  * Two surfaces, and the split is deliberate rather than untidy.
@@ -80,11 +80,12 @@ export async function callTool(origin, token, name, args = {}) {
 }
 
 /** Upload a file as a NEW document, exactly as the browser uploader does. */
-export async function uploadFile(origin, token, path, { title, folder } = {}) {
+export async function uploadFile(origin, token, path, { title, folder, id } = {}) {
   const bytes = readFileSync(path);
   const params = new URLSearchParams({ filename: basename(path) });
   if (title) params.set("title", title);
   if (folder) params.set("folderId", folder);
+  if (id) params.set("id", id);
 
   const res = await fetch(`${origin}/publish?${params}`, {
     method: "POST",

package/src/index.mjs

@@ -49,8 +49,12 @@ Skills
 Options
   --json                 machine-readable output
   --title <text>         title for publish
+  --id <id>              with publish: the address, /d/<id> (default: from the title)
   --folder <id>          destination folder for publish
   --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
   --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
@@ -104,9 +108,28 @@ async function login(flags) {
 
 async function list(flags) {
   const { origin, token } = resolveAuth(flags);
-  const result = await callTool(origin, token, "list_documents", {
-    limit: Number(flags.limit) || 20,
-  });
+  const page = (limit, cursor) => {
+    const args = { limit };
+    if (cursor) args.cursor = cursor;
+    return callTool(origin, token, "list_documents", args);
+  };
+
+  let result;
+  if (flags.all) {
+    // Pages at the server's cap (LIST_LIMIT), which is the fewest round trips.
+    // The result keeps one page's shape, so `--json` needs no second parser.
+    const documents = [];
+    let cursor = flags.cursor;
+    do {
+      const next = await page(50, cursor);
+      documents.push(...next.documents);
+      cursor = next.nextCursor;
+    } while (cursor);
+    result = { documents, nextCursor: null };
+  } else {
+    result = await page(Number(flags.limit) || 20, flags.cursor);
+  }
+
   out(flags.json, result, () => {
     if (result.documents.length === 0) {
       console.log("Nothing yet. `bikeshed publish <file>` to start.");
@@ -122,6 +145,7 @@ async function list(flags) {
 
 async function publish(flags, [path]) {
   if (!path) fail("usage: bikeshed publish <file>");
+  if (flags.id === true) fail("usage: bikeshed publish <file> --id <id>");
   const { origin, token } = resolveAuth(flags);
   const file = resolve(path);
 
@@ -129,7 +153,14 @@ async function publish(flags, [path]) {
     const result = await uploadFile(origin, token, file, {
       title: flags.title,
       folder: flags.folder,
+      id: flags.id,
     });
+    // A taken id still publishes, under a suffix. Said on stderr so `--json`
+    // stays parseable; "not available" also covers a deployment too old to
+    // know the parameter, which ignores it.
+    if (flags.id && result.docId !== flags.id) {
+      console.error(`${flags.id} was not available; published at ${result.docId}`);
+    }
     // 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}` }, () =>
@@ -369,6 +400,7 @@ async function main() {
       all: { type: "boolean", default: false },
       help: { type: "boolean", default: false },
       title: { type: "string" },
+      id: { type: "string" },
       folder: { type: "string" },
       parent: { type: "string" },
       origin: { type: "string" },