@augurworks/augur 0.15.1

package/scripts/lib/refine-png.mjs

@@ -0,0 +1,149 @@
+// refine-png — the smallest PNG reader/writer the refine harness needs, and no dependency.
+//
+// WHY NOT A LIBRARY. The comparison has to run in `npm test`, on a machine with no
+// browser downloaded and no network. A pixel comparator that needs a canvas needs a
+// browser; an image library is a new engine dependency, and every dependency this repo
+// takes is one every instance takes at its next pin bump. The subset below is small
+// enough to read in one sitting: 8-bit, non-interlaced PNG, which is the only thing a
+// browser screenshot ever is.
+//
+// WHAT IT REFUSES, LOUDLY. 16-bit samples, interlaced (Adam7) images, and palette
+// images all throw by name rather than decoding to something plausible — a comparator
+// fed a silently wrong decode reports a silently wrong number, which is the one failure
+// this whole harness exists to prevent.
+
+import zlib from "node:zlib";
+
+const SIG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+const CRC_TABLE = (() => {
+  const t = new Int32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    t[n] = c;
+  }
+  return t;
+})();
+
+function crc32(buf) {
+  let c = -1;
+  for (let i = 0; i < buf.length; i++) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ -1) >>> 0;
+}
+
+/** Bytes per pixel for the colour types this reader accepts. */
+const CHANNELS = { 0: 1, 2: 3, 4: 2, 6: 4 };
+
+function paeth(a, b, c) {
+  const p = a + b - c;
+  const pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+  if (pa <= pb && pa <= pc) return a;
+  return pb <= pc ? b : c;
+}
+
+/**
+ * Decode a PNG buffer to `{width, height, data}` where `data` is RGBA, 8 bits per
+ * sample, row-major — the same shape a canvas ImageData carries.
+ */
+export function decodePng(buf) {
+  if (!Buffer.isBuffer(buf) || buf.length < 8 || !buf.subarray(0, 8).equals(SIG)) {
+    throw new Error("not a PNG (bad signature)");
+  }
+  let off = 8;
+  let ihdr = null;
+  const idat = [];
+  while (off + 8 <= buf.length) {
+    const len = buf.readUInt32BE(off);
+    const type = buf.toString("latin1", off + 4, off + 8);
+    const body = buf.subarray(off + 8, off + 8 + len);
+    if (type === "IHDR") {
+      ihdr = {
+        width: body.readUInt32BE(0),
+        height: body.readUInt32BE(4),
+        bitDepth: body[8],
+        colorType: body[9],
+        compression: body[10],
+        filter: body[11],
+        interlace: body[12],
+      };
+    } else if (type === "IDAT") {
+      idat.push(Buffer.from(body));
+    } else if (type === "IEND") {
+      break;
+    }
+    off += 12 + len;
+  }
+  if (!ihdr) throw new Error("PNG has no IHDR chunk");
+  if (ihdr.bitDepth !== 8) throw new Error(`PNG bit depth ${ihdr.bitDepth} unsupported — this reader is 8-bit only`);
+  if (ihdr.interlace !== 0) throw new Error("interlaced PNG unsupported — this reader reads non-interlaced only");
+  if (!CHANNELS[ihdr.colorType]) throw new Error(`PNG colour type ${ihdr.colorType} unsupported (0, 2, 4 and 6 only)`);
+
+  const { width, height, colorType } = ihdr;
+  const ch = CHANNELS[colorType];
+  const raw = zlib.inflateSync(Buffer.concat(idat));
+  const stride = width * ch;
+  if (raw.length < (stride + 1) * height) throw new Error("PNG pixel data is short — truncated file");
+
+  // Unfilter in place into one contiguous buffer of native-channel samples.
+  const flat = Buffer.alloc(stride * height);
+  let prev = Buffer.alloc(stride);
+  for (let y = 0; y < height; y++) {
+    const ft = raw[y * (stride + 1)];
+    const line = raw.subarray(y * (stride + 1) + 1, (y + 1) * (stride + 1));
+    const out = flat.subarray(y * stride, (y + 1) * stride);
+    for (let i = 0; i < stride; i++) {
+      const x = line[i];
+      const a = i >= ch ? out[i - ch] : 0;
+      const b = prev[i];
+      const c = i >= ch ? prev[i - ch] : 0;
+      let v;
+      switch (ft) {
+        case 0: v = x; break;
+        case 1: v = x + a; break;
+        case 2: v = x + b; break;
+        case 3: v = x + ((a + b) >> 1); break;
+        case 4: v = x + paeth(a, b, c); break;
+        default: throw new Error(`PNG filter type ${ft} is not one of the five defined ones`);
+      }
+      out[i] = v & 0xff;
+    }
+    prev = out;
+  }
+
+  // Widen to RGBA.
+  const data = Buffer.alloc(width * height * 4);
+  for (let p = 0; p < width * height; p++) {
+    const s = p * ch, d = p * 4;
+    if (colorType === 6) { data[d] = flat[s]; data[d + 1] = flat[s + 1]; data[d + 2] = flat[s + 2]; data[d + 3] = flat[s + 3]; }
+    else if (colorType === 2) { data[d] = flat[s]; data[d + 1] = flat[s + 1]; data[d + 2] = flat[s + 2]; data[d + 3] = 255; }
+    else if (colorType === 0) { data[d] = data[d + 1] = data[d + 2] = flat[s]; data[d + 3] = 255; }
+    else { data[d] = data[d + 1] = data[d + 2] = flat[s]; data[d + 3] = flat[s + 1]; }
+  }
+  return { width, height, data };
+}
+
+function chunk(type, body) {
+  const out = Buffer.alloc(body.length + 12);
+  out.writeUInt32BE(body.length, 0);
+  out.write(type, 4, "latin1");
+  body.copy(out, 8);
+  out.writeUInt32BE(crc32(out.subarray(4, 8 + body.length)), 8 + body.length);
+  return out;
+}
+
+/** Encode `{width, height, data}` (RGBA) back to a PNG buffer. Used for diff images and test fixtures. */
+export function encodePng({ width, height, data }) {
+  const stride = width * 4;
+  const raw = Buffer.alloc((stride + 1) * height);
+  for (let y = 0; y < height; y++) {
+    raw[y * (stride + 1)] = 0; // filter: none — these images are written once and read once
+    data.copy ? data.copy(raw, y * (stride + 1) + 1, y * stride, (y + 1) * stride)
+      : Buffer.from(data.subarray(y * stride, (y + 1) * stride)).copy(raw, y * (stride + 1) + 1);
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8; ihdr[9] = 6; ihdr[10] = 0; ihdr[11] = 0; ihdr[12] = 0;
+  return Buffer.concat([SIG, chunk("IHDR", ihdr), chunk("IDAT", zlib.deflateSync(raw)), chunk("IEND", Buffer.alloc(0))]);
+}

package/scripts/lib/seed-pack-build.mjs

@@ -0,0 +1,141 @@
+// Build the seed pack: `seed/` composed by the real build, folded into ONE document.
+//
+// `F-seed-pack-at-provision`. The pack is what a freshly provisioned workspace is furnished
+// with, and it is built ONCE PER ENGINE PIN rather than composed per signup: build.js calls
+// this on every engine-only build (what a deploy shell runs) and writes the result to
+// `dist/__seed/pack.json`, beside `__config/`, sealed from external requests like it.
+// `node scripts/build-seed-pack.mjs` builds the same document by hand.
+//
+// HOW: a CHILD build of build.js with `GV_SPACES_ROOT` pointed at `seed/` and `GV_DIST` at
+// a scratch directory — the same composition `augur publish` runs over a clone of the seed,
+// so the pages a workspace is born with are byte-for-byte what a person would have published
+// from the same tree with the same engine. The child gets NO identity file and NO deploy
+// config, whatever the parent build was handed: a shell's deploy config is that instance's
+// (vanity redirects, sentinels, its runtime-chrome switch) and none of it belongs in content
+// that ships to every workspace on every instance. Then `__manifests/<space>.json` is read
+// back, every file it names is inlined base64, and the two seed documents that are not
+// files — `threads.json` and the connect-page slot — are carried beside it.
+//
+// WHAT IS STRIPPED, deliberately. build.js stamps every authored file with git's answer to
+// "who last changed this" (`by`, a one-way person id; `editedAt`). For the seed that would
+// be the engine author's id, written into every customer's workspace as the author of the
+// welcome content — the exact leak the reserved actor namespace exists to prevent. The
+// pack carries neither; provisioning stamps `editedAt` with its own instant and no `by`.
+//
+// WHAT IS ASSERTED, because the failure it catches is silent. A prototype folder the build
+// did not discover (nested one level wrong — the trap `augur init` documents) builds a pack
+// with five prototypes instead of six and reports success; the connect page losing its
+// `CONNECT_COMMAND` slot builds a pack that provisioning can no longer fill. Both throw here.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { SEED_CONNECT_SLOT, SEED_PACK_FORMAT, validateSeedPack } from "../../src/seed-pack.mjs";
+
+const ENGINE_ROOT = fileURLToPath(new URL("../..", import.meta.url));
+
+/** The page carrying the connect slot, as the site path the build emits it at. */
+export const SEED_CONNECT_FILE = "/start-here/connect-your-terminal/index.html";
+
+/** Every prototype the seed tree declares: `<project>/prototypes/<name>/index.html`. */
+export function seedPrototypes(seedRoot) {
+  const out = [];
+  for (const proj of fs.readdirSync(seedRoot, { withFileTypes: true })) {
+    if (!proj.isDirectory()) continue;
+    const protos = path.join(seedRoot, proj.name, "prototypes");
+    if (!fs.existsSync(protos)) continue;
+    for (const p of fs.readdirSync(protos, { withFileTypes: true })) {
+      if (p.isDirectory() && fs.existsSync(path.join(protos, p.name, "index.html"))) {
+        out.push(`/${proj.name}/${p.name}/index.html`);
+      }
+    }
+  }
+  return out.sort();
+}
+
+/**
+ * Compose `seed/` with the real build and return the pack document.
+ * @param {{engineRoot?: string, seedRoot?: string, env?: object, node?: string}} opts
+ */
+export function buildSeedPack({ engineRoot = ENGINE_ROOT, seedRoot = null, env = process.env, node = process.execPath } = {}) {
+  const seed = seedRoot || path.join(engineRoot, "seed");
+  const spaceJson = JSON.parse(fs.readFileSync(path.join(seed, "space.json"), "utf8"));
+  const spaceId = String(spaceJson.id || "");
+  if (!/^[a-z0-9-]+$/.test(spaceId)) throw new Error(`seed/space.json has no usable id (${JSON.stringify(spaceJson.id)})`);
+
+  const out = fs.mkdtempSync(path.join(os.tmpdir(), "augur-seed-pack-"));
+  try {
+    // Nothing GV_/AUGUR_-shaped is inherited: the parent's flags describe the parent's
+    // build. The child is told exactly two things — where the seed is and where to write.
+    const childEnv = {};
+    for (const [k, v] of Object.entries(env)) if (!/^(GV_|AUGUR_)/.test(k)) childEnv[k] = v;
+    childEnv.GV_SPACES_ROOT = seed;
+    childEnv.GV_DIST = out;
+    childEnv.GV_SEED_PACK = "0"; // never recurse
+    execFileSync(node, [path.join(engineRoot, "build.js")], {
+      cwd: engineRoot, env: childEnv, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
+      maxBuffer: 64 * 1024 * 1024,
+    });
+
+    const manifestPath = path.join(out, "__manifests", `${spaceId}.json`);
+    if (!fs.existsSync(manifestPath)) throw new Error(`the seed build emitted no manifest for space "${spaceId}"`);
+    const m = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+
+    const files = {};
+    for (const [p, f] of Object.entries(m.files || {})) {
+      const bytes = fs.readFileSync(path.join(out, p.slice(1)));
+      const { by: _by, editedAt: _editedAt, ...entry } = f;
+      files[p] = { ...entry, s: bytes.length, b64: bytes.toString("base64") };
+    }
+
+    // Every prototype the tree declares is in the pack, at the path the site serves it.
+    const declared = seedPrototypes(seed);
+    const missing = declared.filter((p) => !(p in files));
+    if (!declared.length) throw new Error("seed/ declares no prototypes");
+    if (missing.length) throw new Error(`the seed build did not emit ${missing.join(", ")} — is the folder at <project>/prototypes/<name>/?`);
+
+    // The connect page still carries the slot provisioning fills, exactly once.
+    const connect = files[SEED_CONNECT_FILE];
+    if (!connect) throw new Error(`the seed build did not emit ${SEED_CONNECT_FILE}`);
+    const html = Buffer.from(connect.b64, "base64").toString("utf8");
+    const slots = html.split(SEED_CONNECT_SLOT).length - 1;
+    if (slots !== 1) throw new Error(`${SEED_CONNECT_FILE} carries the CONNECT_COMMAND slot ${slots} times; provisioning fills exactly one`);
+
+    const threadsPath = path.join(seed, "threads.json");
+    const threads = fs.existsSync(threadsPath) ? JSON.parse(fs.readFileSync(threadsPath, "utf8")) : {};
+    delete threads._comment;
+    for (const p of Object.keys(threads)) {
+      if (!p.startsWith("/") || !Array.isArray(threads[p])) throw new Error(`seed/threads.json: "${p}" is not a page path with a list of threads`);
+      if (!(`${p}index.html` in files)) throw new Error(`seed/threads.json names ${p}, which the seed build did not emit`);
+    }
+
+    const pack = {
+      format: SEED_PACK_FORMAT,
+      builtAt: new Date().toISOString(),
+      engine: (m.builtWith && m.builtWith.engine) || null,
+      space: m.space || { id: spaceId },
+      routing: m.routing || {},
+      ...(m.builtWith ? { builtWith: m.builtWith } : {}),
+      connectCommandFile: SEED_CONNECT_FILE,
+      files,
+      threads,
+    };
+    const why = validateSeedPack(pack);
+    if (why) throw new Error(`the built seed pack does not validate: ${why}`);
+    return pack;
+  } finally {
+    fs.rmSync(out, { recursive: true, force: true });
+  }
+}
+
+/** Build and write the pack to `<dist>/__seed/pack.json`. Returns the path written. */
+export function writeSeedPack(dist, opts = {}) {
+  const pack = buildSeedPack(opts);
+  const dir = path.join(dist, "__seed");
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, "pack.json");
+  fs.writeFileSync(file, JSON.stringify(pack));
+  return { file, pack };
+}

package/scripts/lib/state-compare.mjs

@@ -0,0 +1,68 @@
+// state-compare.mjs — how `augur migrate` judges whether a family arrived.
+//
+// Split out of migrate.mjs so the judgement can be tested without spawning the runner:
+// the script is a top-level program with two instances on the other end of it, and the
+// comparison is a pure function whose edge cases are exactly the ones a live migration
+// finds.
+//
+// ⚠️ THE COMPARISON IS STRUCTURAL, NOT BYTEWISE, AND THAT IS NOT LENIENCY. The two sides
+// of a migration answer the SAME documents in DIFFERENT KEY ORDERS: a KV-backed export
+// hands a family back in insertion order, and the workspace object hands it back sorted
+// (its read is a SELECT). `JSON.stringify(a) === JSON.stringify(b)` therefore reported
+// "differ" on a correct copy, and a correct migration failed its own verification. So
+// both sides are rendered as canonical JSON — object keys sorted at every depth — before
+// they are compared. Arrays are left in order, because order in an array IS content: a
+// comment thread with its messages reversed is a different thread.
+import { inventoryEntry } from "../../src/state-inventory.mjs";
+
+/** JSON with object keys sorted at every depth. `undefined` renders as `null`. */
+export function canonicalJson(value) {
+  return JSON.stringify(canonicalise(value === undefined ? null : value));
+}
+
+function canonicalise(v) {
+  if (Array.isArray(v)) return v.map(canonicalise);
+  if (v && typeof v === "object") {
+    const out = {};
+    for (const k of Object.keys(v).sort()) {
+      if (v[k] === undefined) continue; // JSON.stringify would drop it too
+      out[k] = canonicalise(v[k]);
+    }
+    return out;
+  }
+  return v;
+}
+
+// ⚠️ EMPTY AND ABSENT ARE THE SAME ANSWER FOR ONE KIND OF FAMILY AND NOT FOR THE OTHER, and
+// a comparison that does not know the difference fails on correct data in one direction and
+// passes over a blind copy in the other. Both happened.
+//
+//   A `key` FAMILY is one document. It is there or it is not, and "not there" is exactly
+//   "holds nothing" — there is no third state either end could be in. So absent on one side
+//   and `{}` on the other is a MATCH, and refusing it is refusing a workspace where nobody
+//   has ever set a status.
+//
+//   A `prefix` FAMILY is a set of documents, and an empty set is `{}`. Absent therefore does
+//   NOT mean empty here: it means that export could not enumerate the family at all, which
+//   is a copy nobody can judge and the one report that must fail. This is not hypothetical
+//   tidying — `pins:` reported absent from the workspace-object backing whether it held two
+//   sidebars or none, so every KV→object migration failed this step on correct data, ABOVE
+//   the board move, which is the step that reads a board from the room that owns it.
+//   The export keeps the invariant now (see `exportState`); this refuses rather than
+//   assuming, because the next family to break it would otherwise be copied blind.
+//
+// AND NOTHING WITH CONTENT IN IT IS EVER FLATTENED. Both sides have to hold nothing before
+// the kind is even consulted, so no amount of leniency here can make two different families
+// compare equal — which is the failure mode of "just make it pass".
+export const holdsNothing = (v) => v === null || v === undefined
+  || (Array.isArray(v) ? v.length === 0
+    : typeof v === "object" && Object.keys(v).length === 0);
+
+/** `match` — the two agree. `differ` — they do not. `blind` — both empty, but one side could not enumerate it. */
+export function compareFamily(id, a, b, lookup = inventoryEntry) {
+  if (canonicalJson(a) === canonicalJson(b)) return "match";
+  if (!holdsNothing(a) || !holdsNothing(b)) return "differ";
+  const entry = lookup(id);
+  if (entry && entry.kind === "key") return "match";
+  return "blind";
+}

package/scripts/lib/store.mjs

@@ -0,0 +1,122 @@
+// store.mjs — how a CLI script finds the instance it should talk to, and how it
+// talks to the bundle store's HTTP API.
+//
+// Extracted from publish.mjs so publish / export / restore / status all resolve the
+// same target the same way. Credential resolution that drifts between tools is how
+// you end up backing up one instance and restoring another.
+//
+// Target origin, in order: AUGUR_ORIGIN env · the engine's .env.deploy · the deploy
+// shell's deploy.config.json `siteOrigin` · the cwd space's space.json `siteOrigin`
+// (the collaborator layout: a lone space clone with no shell anywhere — the one
+// public fact a space repo knows about its instance).
+//
+// Token, in order: AUGUR_TOKEN env · .env.deploy · the credential `augur login`
+// saved for this origin.
+
+import { existsSync, readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { deployConfig, originHost } from "./instance.mjs";
+
+export const ENGINE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+export function readEnvFile(p) {
+  const out = {};
+  try {
+    for (const line of readFileSync(p, "utf8").split("\n")) {
+      const m = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/);
+      if (m) out[m[1]] = m[2].trim();
+    }
+  } catch (e) {}
+  return out;
+}
+
+export function resolveOrigin(root = ENGINE_ROOT) {
+  const env = readEnvFile(path.join(root, ".env.deploy"));
+  let cwdSpaceOrigin = "";
+  try {
+    cwdSpaceOrigin = JSON.parse(readFileSync(path.join(process.cwd(), "space.json"), "utf8")).siteOrigin || "";
+  } catch (e) {}
+  return (process.env.AUGUR_ORIGIN || env.AUGUR_ORIGIN ||
+    deployConfig(root, originHost(cwdSpaceOrigin)).siteOrigin || cwdSpaceOrigin || "")
+    .replace(/\/+$/, "");
+}
+
+export function resolveToken(origin, root = ENGINE_ROOT) {
+  const env = readEnvFile(path.join(root, ".env.deploy"));
+  let token = process.env.AUGUR_TOKEN || env.AUGUR_TOKEN || "";
+  if (!token && origin) {
+    try {
+      const saved = JSON.parse(readFileSync(path.join(os.homedir(), ".config", "augur", "tokens.json"), "utf8"));
+      token = (saved[new URL(origin).host] || {}).token || "";
+    } catch (e) {}
+  }
+  return token;
+}
+
+// Both, with the failure messages a human can act on. `needToken: false` for the
+// read-only paths that only touch the public build stamp.
+export function target({ root = ENGINE_ROOT, needToken = true } = {}) {
+  const origin = resolveOrigin(root);
+  if (!origin) {
+    throw new Error('no target origin — set AUGUR_ORIGIN, or add "siteOrigin" to space.json.');
+  }
+  const token = resolveToken(origin, root);
+  if (needToken && !token) {
+    throw new Error("no publish token — run `augur connect` (or `augur login`, which uses your web credentials) once.");
+  }
+  return { origin, token };
+}
+
+// One fetch wrapper for the whole publish API: bearer auth, non-2xx throws with
+// enough of the body to diagnose, 204 tolerated.
+export function apiClient(origin, token) {
+  const headers = { Authorization: `Bearer ${token}` };
+  return async function req(pathPart, init = {}) {
+    const url = `${origin}/__publish/${pathPart}`;
+    const r = await fetch(url, { ...init, headers: { ...headers, ...(init.headers || {}) } });
+    if (!r.ok && r.status !== 204) {
+      const body = await r.text().catch(() => "");
+      throw new Error(`${init.method || "GET"} ${url} → ${r.status} ${body.slice(0, 300)}`);
+    }
+    return r;
+  };
+}
+
+// The public build stamp — the one read that needs no credential at all. Always
+// cache-busted: the CDN serves this stale for a minute or two after a publish, and
+// a stale read is how you "confirm" the previous state.
+export async function buildStamp(origin) {
+  const r = await fetch(`${origin}/_build.json?t=${Date.now()}`, { headers: { Accept: "application/json" } });
+  if (!r.ok) throw new Error(`GET ${origin}/_build.json → ${r.status}`);
+  return r.json();
+}
+
+// Every publishable id at this instance: the spaces plus the engine-chrome
+// pseudo-space, which the stamp reports separately.
+export const idsFromStamp = (stamp) => [...Object.keys(stamp.spaces || {}).sort(), "_engine"];
+
+export const ENGINE_ID = "_engine";
+
+// The publish protocol this CLI speaks, declared on every commit as `clientProtocol`.
+// One source for every client that commits (publish, restore) — two copies would drift,
+// and a client that MISDECLARES its protocol is worse than one that declares nothing:
+// the server would wave through guards it cannot actually honour.
+//
+// Bump this when the CLI learns a new commit-side guard, not when the worker does.
+//   1  the original digest protocol
+//   2  unpublish guard (`allowUnpublish`)
+//   3  revert guard (`baseVersion` + per-unit reconciliation)
+//   4  safe adoption: the reconcile writes AUTHORED bytes back into the tree (full
+//      build-decoration peel) and never deletes internal files live can't testify
+//      about. A protocol-3 reconcile wrote dist-baked pages into a space repo as one
+//      person's authorship and deleted research material — an instance that has seen
+//      that once sets `minClientProtocol: 4` and old clients self-update on contact.
+//   5  composed publish: the live manifest is the base and the client ships per-unit
+//      fast-forwards only (git evidence), so adoption and tree writes are GONE — a
+//      stale checkout can no longer revert, unpublish, or fork what it never edited.
+//      The protocol-4 reconcile still mass-forked under a cache base (the 2026-08-22
+//      cascade: 392 false -conflict- units live); a pre-5 client re-litters, so the
+//      reference instance floors at 5.
+export const CLIENT_PROTOCOL = 5;

package/scripts/login.mjs

@@ -0,0 +1,84 @@
+// login.mjs — `augur login`: trade your existing web credentials for a publish
+// token, saved to ~/.config/augur/tokens.json (keyed by origin host). Run once;
+// `augur publish` picks the token up automatically after that.
+//
+//   augur login [--origin https://…]
+//
+// Credentials: AUGUR_EMAIL / AUGUR_PASSWORD env vars, else an interactive
+// prompt (password input is muted). The token is never printed.
+
+import { createInterface } from "node:readline";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { deployConfig, originHost } from "./lib/instance.mjs";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const log = (msg) => console.error(`\x1b[32m[login]\x1b[0m ${msg}`);
+const opt = (f) => { const i = process.argv.indexOf(f); return i > 0 ? process.argv[i + 1] : null; };
+
+const cwdSpaceOrigin = (() => {
+  try { return JSON.parse(readFileSync(path.join(process.cwd(), "space.json"), "utf8")).siteOrigin || ""; }
+  catch (e) { return ""; }
+})();
+const ORIGIN = (opt("--origin") || process.env.AUGUR_ORIGIN ||
+  deployConfig(ROOT, originHost(cwdSpaceOrigin)).siteOrigin || cwdSpaceOrigin || "").replace(/\/+$/, "");
+if (!ORIGIN) { log("no origin — pass --origin https://<your instance> (or add \"siteOrigin\" to space.json)"); process.exit(1); }
+// Said up front, because the usual reader of this line is an agent deciding which door to
+// use: this one wants a password typed into a terminal, and the other one does not.
+log("login is for CI and scripts. People and agents run `augur connect` instead — it pairs a signed-in browser and never sees a password.");
+
+function ask(question, mute) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+    if (mute) {
+      // Mute the echo after the prompt prints: overwrite the output hook.
+      const write = rl._writeToOutput.bind(rl);
+      rl._writeToOutput = (s) => { if (s.includes(question)) write(s); };
+    }
+    rl.question(question, (answer) => { rl.close(); if (mute) process.stderr.write("\n"); resolve(answer.trim()); });
+  });
+}
+
+const email = process.env.AUGUR_EMAIL || (await ask("Email: "));
+const password = process.env.AUGUR_PASSWORD || (await ask("Password: ", true));
+if (!email || !password) { log("email + password required."); process.exit(1); }
+
+const r = await fetch(`${ORIGIN}/__publish/_login/token`, {
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify({ email, password }),
+});
+if (!r.ok) {
+  const err = await r.text().catch(() => "");
+  // The server distinguishes "wrong password" from "this account was reset". Surface the
+  // second as prose — otherwise a reset user reads `bad-credentials` and goes hunting for
+  // a typo in a password that no longer exists.
+  let parsed = null;
+  try { parsed = JSON.parse(err); } catch {}
+  if (parsed && parsed.message) log(parsed.message);
+  else log(`login failed (${r.status}): ${err.slice(0, 200)}`);
+  process.exit(1);
+}
+const { token, space, expiresAt } = await r.json();
+
+const dir = path.join(os.homedir(), ".config", "augur");
+mkdirSync(dir, { recursive: true });
+const file = path.join(dir, "tokens.json");
+let all = {};
+try { all = JSON.parse(readFileSync(file, "utf8")); } catch (e) {}
+// `expiresAt` is stored as well as printed: a line in a terminal is gone by the time it
+// matters, and the file is what a later command can read to say "this ran out yesterday"
+// instead of "forbidden". An older instance sends none, and none means it does not expire.
+all[new URL(ORIGIN).host] = {
+  token, space, email, at: new Date().toISOString(),
+  ...(expiresAt ? { expiresAt } : {}),
+};
+writeFileSync(file, JSON.stringify(all, null, 2), { mode: 0o600 });
+log(`signed in as ${email} — publish access: ${space === "*" ? "all spaces" : space}`);
+console.log(`ready — \`augur publish\` will now use this login for ${ORIGIN}`);
+if (expiresAt) {
+  const days = Math.max(0, Math.round((Date.parse(expiresAt) - Date.now()) / 86400000));
+  console.log(`\x1b[2mit expires in ${days} days (${expiresAt.slice(0, 10)}) — run \`augur login\` again then\x1b[0m`);
+}