bikeshed-now 0.3.0 → 0.4.1

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
@@ -34,16 +36,28 @@ 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.
 
+A document of several files is a `.zip` with `index.html` or `index.md` at its
+root. `update` with a `.zip` replaces every file; `update` with one `.md` or
+`.html` replaces the entry and keeps the images and stylesheets beside it.
+
 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
 random characters, and the CLI says so on stderr.
 
+Wherever a command takes an id, it also takes the link you were sent. An
+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://bikeshed.now/d/build-estimate?k=…'
+```
+
 `bikeshed --help` lists the rest — listing documents, folders, and installing the
 agent skills a deployment serves.
 
@@ -54,8 +68,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.3.0",
+  "version": "0.4.1",
   "license": "Apache-2.0",
   "type": "module",
   "description": "Publish and revise documents on a Bikeshed deployment from the terminal.",

package/src/client.mjs

@@ -4,23 +4,27 @@
 import { readFileSync } from "node:fs";
 import { basename } from "node:path";
 
-export const CLIENT_NAME = "bikeshed-cli/0.3.0";
+export const CLIENT_NAME = "bikeshed-cli/0.4.1";
 
 /**
- * Two surfaces, and the split is deliberate rather than untidy.
+ * Three surfaces, and the split is deliberate rather than untidy.
  *
  *   POST /publish   takes RAW BYTES, so it is the only way to send a .zip
  *                   bundle without base64-inflating it through JSON. It is
- *                   also the exact endpoint the browser uploader calls.
+ *                   also the exact endpoint the browser uploader calls. With
+ *                   `update=<id>` it revises that document instead, which is
+ *                   how `update` sends a .zip.
  *   POST /mcp       is the API for everything else — list, read, update,
  *                   comments, reply — because those tools already exist and
  *                   adding a parallel REST surface would mean two
  *                   implementations of the same six operations.
+ *   GET /content    the byte path a browser reads a document through. Only
+ *                   `get` uses it, and only for a source get_document cut.
  *
- * Both carry the same Bearer token, and both stamp provenance server-side. The
- * `X-Bikeshed-Client` and `X-Bikeshed-Agent` headers are self-reported and are
- * recorded as such: they are for a human reading an activity feed, not for
- * anything that makes a decision.
+ * All three carry the same Bearer token, and provenance is stamped
+ * server-side. The `X-Bikeshed-Client` and `X-Bikeshed-Agent` headers are
+ * self-reported and are recorded as such: they are for a human reading an
+ * activity feed, not for anything that makes a decision.
  */
 
 function headers(token, extra = {}) {
@@ -79,13 +83,19 @@ export async function callTool(origin, token, name, args = {}) {
   return result?.structuredContent ?? result;
 }
 
-/** Upload a file as a NEW document, exactly as the browser uploader does. */
-export async function uploadFile(origin, token, path, { title, folder, id } = {}) {
+/**
+ * Upload a file as a NEW document, exactly as the browser uploader does — or,
+ * 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 } = {}) {
   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);
+  if (update) params.set("update", update);
+  if (k) params.set("k", k);
 
   const res = await fetch(`${origin}/publish?${params}`, {
     method: "POST",
@@ -102,6 +112,27 @@ export async function uploadFile(origin, token, path, { title, folder, id } = {}
   return res.json();
 }
 
+/**
+ * A document's whole source file, as bytes.
+ *
+ * get_document cuts a long source, because its result lands in an agent's
+ * context. A command's output lands in a file or a pipe, and a `get` that
+ * prints part of a file is a broken `cat`. So the cut source is read again
+ * here, through the path a browser uses: the same object, behind the same
+ * read, key and expiry checks.
+ */
+export async function fetchSource(origin, token, { id, version, sourceFile, k }) {
+  const path = [id, version, ...String(sourceFile).split("/")].map(encodeURIComponent).join("/");
+  const query = k ? `?${new URLSearchParams({ k })}` : "";
+  const res = await fetch(`${origin}/content/${path}${query}`, { headers: headers(token) });
+  if (!res.ok) {
+    throw new CliError(
+      `${id} is longer than one response, and reading the rest failed (${res.status}). Nothing was printed.`,
+    );
+  }
+  return Buffer.from(await res.arrayBuffer());
+}
+
 /**
  * The skills a deployment publishes, and their text.
  *

package/src/index.mjs

@@ -8,7 +8,15 @@ import { basename, join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 
 import { CONFIG_PATH, readConfig, resolveAuth, writeConfig } from "./config.mjs";
-import { CliError, callTool, fetchSkill, listSkills, uploadFile, whoami } from "./client.mjs";
+import {
+  CliError,
+  callTool,
+  fetchSkill,
+  fetchSource,
+  listSkills,
+  uploadFile,
+  whoami,
+} from "./client.mjs";
 
 /**
  * This is the END-USER tool, and it is deliberately not the same thing as the
@@ -36,6 +44,9 @@ const USAGE = `bikeshed — publish and revise documents
   bikeshed reply <id> <thread> <text>  reply in a thread
   bikeshed open <id>                   open it in a browser
 
+  Where a command takes <id> it also takes the link you were sent. An unlisted
+  document you are not a member of needs the link: its key is in it.
+
 Organising
   bikeshed folders                     the folder tree, with ids
   bikeshed mkdir <name> [--parent <id>]  create a folder
@@ -46,6 +57,19 @@ Skills
   bikeshed skills install <dir>        write them into an agent's skills directory
                                        (Claude Code: ~/.claude/skills)
 
+What you can publish
+  .md .markdown          rendered to HTML on the server; get returns the Markdown
+  .html .htm             stored as written
+  .zip                   several files, index.html or index.md at the root
+  Up to 25 MB. An update keeps the format: a .zip replaces every file, one .md
+  or .html replaces the entry and keeps the files beside it.
+  Scripts run once a person trusts the document in the app: its owner for
+  everyone, any reader for themselves. Each update sandboxes it again. Images,
+  stylesheets and fonts from other sites load either way. Markdown is
+  CommonMark with tables, strikethrough and task lists: Mermaid, math,
+  footnotes and front matter show as typed. The deployment's /llms.txt has the
+  full list.
+
 Options
   --json                 machine-readable output
   --title <text>         title for publish
@@ -81,6 +105,33 @@ function out(json, value, human) {
   human();
 }
 
+/**
+ * A document as a person holds it: its id, or the link they were sent. The link
+ * is the only place an unlisted document's key exists, so a pasted one is read
+ * 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}`);
+  }
+  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 ZIP_MAGIC = Buffer.from([0x50, 0x4b, 0x03, 0x04]);
+
+/** A .zip by name, or by the bytes the deployment itself sniffs for. */
+function isArchive(path, bytes) {
+  return /\.zip$/i.test(path) || bytes.subarray(0, 4).equals(ZIP_MAGIC);
+}
+
 // --- Commands --------------------------------------------------------------
 
 async function login(flags) {
@@ -179,14 +230,20 @@ async function publish(flags, [path]) {
   }
 }
 
-async function update(flags, [id, path]) {
-  if (!id || !path) fail("usage: bikeshed update <id> <file>");
+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 { id } = doc;
 
   const once = async () => {
-    const content = readFileSync(file, "utf8");
-    const result = await callTool(origin, token, "update_document", { id, content });
+    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.
+    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") });
     out(flags.json, { ...result, url: result.url ?? `${origin}/d/${id}` }, () =>
       console.log(
         result.deduped
@@ -201,18 +258,35 @@ async function update(flags, [id, path]) {
   if (flags.watch) await watchFile(file, once);
 }
 
-async function get(flags, [id]) {
-  if (!id) fail("usage: bikeshed get <id>");
+async function get(flags, [ref]) {
+  if (!ref) fail("usage: bikeshed get <id>");
   const { origin, token } = resolveAuth(flags);
-  const result = await callTool(origin, token, "get_document", { id });
-  out(flags.json, result, () => process.stdout.write(result.source));
+  const doc = docArgs(ref);
+  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
+  // published a version missing everything past the cut. So a cut source is
+  // read whole, or nothing is printed.
+  const whole = result.truncated
+    ? await fetchSource(origin, token, {
+        id: doc.id,
+        version: result.version,
+        sourceFile: result.sourceFile,
+        k: doc.k,
+      })
+    : null;
+  out(
+    flags.json,
+    whole ? { ...result, truncated: false, source: whole.toString("utf8") } : result,
+    () => process.stdout.write(whole ?? result.source),
+  );
 }
 
-async function comments(flags, [id]) {
-  if (!id) fail("usage: bikeshed comments <id>");
+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", {
-    id,
+    ...docArgs(ref),
     includeResolved: Boolean(flags.all),
   });
   out(flags.json, result, () => {
@@ -234,11 +308,15 @@ async function comments(flags, [id]) {
   });
 }
 
-async function reply(flags, [id, threadId, ...rest]) {
+async function reply(flags, [ref, threadId, ...rest]) {
   const body = rest.join(" ");
-  if (!id || !threadId || !body) fail("usage: bikeshed reply <id> <thread> <text>");
+  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", { id, threadId, body });
+  const result = await callTool(origin, token, "reply_to_comment", {
+    ...docArgs(ref),
+    threadId,
+    body,
+  });
   out(flags.json, result, () => console.log(`replied in ${threadId}`));
 }