@augurworks/augur 0.15.1

package/scripts/lib/draft.mjs

@@ -0,0 +1,385 @@
+// draft.mjs — the CLI half of drafts that land, as functions over an injected client.
+//
+// Every verb here is `do<Verb>({client, dir, …}) → result`, and the entry points in
+// scripts/{open,save,land,sync,close}.mjs only print the result. The client is the small
+// object `unitClient` returns, so a test can stand in a fake instance and drive the whole
+// loop on disk without a network. See docs/drafts-that-land.md §4 and §7.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { merge3 } from "./merge3.mjs";
+
+export const STATE_FILE = ".augur/draft.json";
+export const THEIRS_DIR = ".augur/theirs";
+// The machine-wide registry of open draft folders. `AUGUR_DRAFTS_REGISTRY` exists for the
+// test suite, which must never write into the developer's own home folder.
+export const REGISTRY = path.join(os.homedir(), ".config", "augur", "drafts.json");
+const registryPath = () => process.env.AUGUR_DRAFTS_REGISTRY || REGISTRY;
+
+const MIME = {
+  html: "text/html; charset=utf-8", htm: "text/html; charset=utf-8", css: "text/css; charset=utf-8",
+  js: "application/javascript; charset=utf-8", mjs: "application/javascript; charset=utf-8",
+  json: "application/json; charset=utf-8", txt: "text/plain; charset=utf-8", md: "text/markdown; charset=utf-8",
+  svg: "image/svg+xml", png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", webp: "image/webp", gif: "image/gif",
+  ico: "image/x-icon", woff: "font/woff", woff2: "font/woff2", ttf: "font/ttf", otf: "font/otf",
+  mp3: "audio/mpeg", mp4: "video/mp4", webm: "video/webm", pdf: "application/pdf", wasm: "application/wasm",
+};
+export const mimeOf = (name) => MIME[path.extname(name).slice(1).toLowerCase()] || "application/octet-stream";
+export const hashBytes = (buf) => createHash("sha256").update(buf).digest("hex");
+export const relOf = (unit, urlPath) => urlPath.slice(unit.length);
+export const urlOf = (unit, rel) => unit + rel;
+
+export function scanFolder(dir) {
+  const out = {};
+  const walk = (d, rel) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      if (rel === "" && e.name === ".augur") continue;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(path.join(d, e.name), r);
+      else if (e.isFile()) {
+        const buf = fs.readFileSync(path.join(d, e.name));
+        out[r] = { h: hashBytes(buf), ct: mimeOf(e.name), s: buf.length };
+      }
+    }
+  };
+  walk(dir, "");
+  return out;
+}
+
+export function readState(dir) {
+  try { return JSON.parse(fs.readFileSync(path.join(dir, STATE_FILE), "utf8")); } catch (e) { return null; }
+}
+export function writeState(dir, state) {
+  fs.mkdirSync(path.join(dir, ".augur"), { recursive: true });
+  const p = path.join(dir, STATE_FILE);
+  fs.writeFileSync(p + ".tmp", JSON.stringify(state, null, 2));
+  fs.renameSync(p + ".tmp", p);
+}
+
+export function changesBetween(unit, savedTable, localScan) {
+  const changes = [];
+  const seen = new Set();
+  for (const [rel, f] of Object.entries(localScan)) {
+    const p = urlOf(unit, rel);
+    seen.add(p);
+    const prior = savedTable[p];
+    if (prior && prior.h === f.h) continue;
+    changes.push({ path: p, h: f.h, ct: f.ct, s: f.s, baseHash: prior ? prior.h : null });
+  }
+  for (const [p, f] of Object.entries(savedTable)) if (!seen.has(p)) changes.push({ path: p, baseHash: f.h, delete: true });
+  return changes.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+// ── the machine-wide registry of open draft folders ──────────────────────────
+function readRegistry() {
+  try { return JSON.parse(fs.readFileSync(registryPath(), "utf8")); } catch (e) { return { drafts: [] }; }
+}
+function writeRegistry(reg) {
+  const p = registryPath();
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p + ".tmp", JSON.stringify(reg, null, 2));
+  fs.renameSync(p + ".tmp", p);
+}
+export function registryAdd(entry) {
+  const reg = readRegistry();
+  reg.drafts = reg.drafts.filter((d) => d.dir !== entry.dir).concat([entry]);
+  writeRegistry(reg);
+}
+export function registryRemove(dir) {
+  const reg = readRegistry();
+  reg.drafts = reg.drafts.filter((d) => d.dir !== dir);
+  writeRegistry(reg);
+}
+export const registryList = () => readRegistry().drafts;
+
+// ── the client ───────────────────────────────────────────────────────────────
+/**
+ * `fetchJson(url, init)` is fetch with the bearer header added; the unit routes live at
+ * `/__unit/<verb>` and blobs at `/__publish/<space>/blob/<hash>`. Non-2xx answers come back
+ * as `{status, ...body}` rather than throwing, because a 409 is an answer, not a failure.
+ */
+export function unitClient({ origin, token, space, session }) {
+  const headers = { Authorization: `Bearer ${token}`, "X-Augur-Session": session || "" };
+  const post = async (verb, body) => {
+    const r = await fetch(`${origin}/__unit/${verb}`, { method: "POST", headers: { ...headers, "content-type": "application/json" }, body: JSON.stringify(body) });
+    const out = await r.json().catch(() => ({}));
+    return r.ok ? out : { status: r.status, ...out };
+  };
+  const get = async (verb, unit) => {
+    const r = await fetch(`${origin}/__unit/${verb}?unit=${encodeURIComponent(unit)}`, { headers });
+    const out = await r.json().catch(() => ({}));
+    return r.ok ? out : { status: r.status, ...out };
+  };
+  return {
+    open: (b) => post("open", b), save: (b) => post("save", b), land: (b) => post("land", b),
+    sync: (b) => post("sync", b), discard: (b) => post("discard", b), presence: (unit) => get("presence", unit),
+    main: (unit) => get("main", unit),
+    async blobPut(h, body) {
+      const r = await fetch(`${origin}/__publish/${space}/blob/${h}`, { method: "PUT", headers, body });
+      if (!r.ok && r.status !== 204) throw new Error(`blob upload failed: ${r.status}`);
+    },
+    async blobGet(h) {
+      const r = await fetch(`${origin}/__publish/${space}/blob/${h}`, { headers });
+      if (!r.ok) throw new Error(`blob fetch failed: ${r.status}`);
+      return Buffer.from(await r.arrayBuffer());
+    },
+  };
+}
+
+// ── the verbs ────────────────────────────────────────────────────────────────
+// `blobPut`/`blobGet` throw on a non-2xx answer, and a raw `fetch` can reject outright
+// (offline, DNS, a dropped connection mid-transfer) — a transient failure anywhere inside
+// a verb must come back as a result, not an unhandled rejection. `guarded` is that catch,
+// applied once to each `do<Verb>` export rather than five times: whatever the body threw
+// becomes `{ok: false, error: "network", message}`, and since nothing here writes state
+// until its work has actually succeeded, disk is left exactly as it was at the failure —
+// a retry reprocesses safely.
+function guarded(fn) {
+  return async (...args) => {
+    try { return await fn(...args); }
+    catch (err) { return { ok: false, error: "network", message: String((err && err.message) || err) }; }
+  };
+}
+
+async function materialise(client, unit, table, dir) {
+  for (const [p, f] of Object.entries(table)) {
+    const dest = path.join(dir, relOf(unit, p));
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, await client.blobGet(f.h));
+  }
+}
+
+async function doOpenImpl({ client, unit, dir, origin, space, session, now, isNew = false }) {
+  if (fs.existsSync(dir) && fs.readdirSync(dir).length) return { ok: false, error: "folder-not-empty", dir };
+  const createdFolder = !fs.existsSync(dir);
+  const o = await client.open({ unit });
+  if (o.status) return { ok: false, ...o };
+  // A unit with no files is one that does not exist yet. Creating one is a decision the
+  // caller states with `isNew`; without it, a typo would quietly open an empty draft on a
+  // prototype that was never there. Either mismatch hands the draft straight back.
+  const exists = Object.keys(o.table || {}).length > 0;
+  if (exists !== !isNew) {
+    try { await client.discard({ unit, draftId: o.draftId }); } catch (e) { /* best-effort */ }
+    return { ok: false, error: exists ? "unit-exists" : "unknown-unit", unit };
+  }
+  // From here the server-side draft exists, so any failure below must both undo what we
+  // wrote to disk and tell the server to drop the orphan — otherwise a retry finds a
+  // half-materialised folder (`folder-not-empty`) and the draft it opened is never freed.
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    await materialise(client, unit, o.table, dir);
+    // `table` is what the DRAFT last saved (the per-file bases a save is checked against);
+    // `baseTable` is what MAIN held at the draft's base revision (what a sync merges from).
+    const state = { origin, space, unit, address: o.address, draftId: o.draftId, session, baseRevision: o.baseRevision, draftRevision: 0, table: o.table, baseTable: o.table, openedAt: now };
+    writeState(dir, state);
+    registryAdd({ dir, unit, draftId: o.draftId, origin, openedAt: now });
+  } catch (err) {
+    // When we created `dir` ourselves, the whole thing is ours to remove. When it
+    // pre-existed, the empty-folder check above guarantees everything under it now is
+    // ALSO ours (nothing else can have written there since) — so every entry goes, not
+    // just the ones named in `o.table`, leaving the pre-existing folder itself in place.
+    if (createdFolder) fs.rmSync(dir, { recursive: true, force: true });
+    else for (const e of fs.readdirSync(dir)) fs.rmSync(path.join(dir, e), { recursive: true, force: true });
+    try { await client.discard({ unit, draftId: o.draftId }); } catch (e) { /* best-effort */ }
+    throw err;
+  }
+  const others = (o.presence || []).filter((d) => d.id !== o.draftId);
+  return { ok: true, draftId: o.draftId, address: `${origin}${o.address}`, files: Object.keys(o.table).length, others, isNew: !exists };
+}
+
+async function doSaveImpl({ client, dir, baseRevision, baseTable }) {
+  const st = readState(dir);
+  if (!st) return { ok: false, error: "not-a-draft", dir };
+  const local = scanFolder(dir);
+  const changes = changesBetween(st.unit, st.table, local);
+  if (!changes.length && baseRevision === undefined) return { ok: true, changed: [], draftRevision: st.draftRevision };
+  for (const c of changes) if (!c.delete) await client.blobPut(c.h, fs.readFileSync(path.join(dir, relOf(st.unit, c.path))));
+  const r = await client.save({ unit: st.unit, draftId: st.draftId, draftRevision: st.draftRevision, changes, ...(baseRevision !== undefined ? { baseRevision } : {}) });
+  if (r.status) return { ok: false, ...r };
+  // A caller mid-sync (`doSyncImpl`) hands its advanced `baseTable` in here rather than
+  // writing state itself, so the whole revision — `draftRevision`, `table`, `baseRevision`
+  // and `baseTable` — lands in the ONE `writeState` below, only once the server has
+  // actually accepted the save. A failure anywhere above this line leaves the file on disk
+  // byte-identical to before the call, whatever advanced state a caller was carrying.
+  st.draftRevision = r.draftRevision; st.table = r.table;
+  if (baseRevision !== undefined) st.baseRevision = baseRevision;
+  if (baseTable !== undefined) st.baseTable = baseTable;
+  writeState(dir, st);
+  return { ok: true, changed: changes.map((c) => relOf(st.unit, c.path)), draftRevision: r.draftRevision };
+}
+
+async function doLandImpl({ client, dir, note }) {
+  const st = readState(dir);
+  if (!st) return { ok: false, error: "not-a-draft", dir };
+  const saved = await doSave({ client, dir });
+  if (!saved.ok) return saved;
+  const r = await client.land({ unit: st.unit, draftId: st.draftId, baseRevision: st.baseRevision, note: note || "" });
+  if (r.status) return { ok: false, ...r };
+  st.landed = true; st.landedRevision = r.revision;
+  writeState(dir, st);
+  registryRemove(dir);
+  // `recorded: false` means the bytes are live and the history entry is not — the server
+  // wrote the manifest and could not tell the unit's object about it. Carried through so
+  // the command can say so; the landing itself happened either way.
+  return { ok: true, url: r.url, revision: r.revision, version: r.version,
+    recorded: r.recorded !== false, warning: r.warning || null };
+}
+
+async function doSyncImpl({ client, dir }) {
+  const st = readState(dir);
+  if (!st) return { ok: false, error: "not-a-draft", dir };
+  const r = await client.sync({ unit: st.unit, draftId: st.draftId });
+  if (r.status) return { ok: false, ...r };
+  const local = scanFolder(dir);
+  const baseTable = st.baseTable || {};
+  const nextBase = { ...baseTable };
+  const taken = [], merged = [], conflicts = [], kept = [];
+  const isText = (ct) => /^text\//.test(ct) || /javascript|json|svg/.test(ct);
+  for (const c of r.changed) {
+    const rel = relOf(st.unit, c.path);
+    const base = baseTable[c.path] || null;             // what main held when this draft was based
+    nextBase[c.path] = { h: c.h, ct: c.ct, s: c.s };
+    if (base && base.h === c.h) continue;                // main's file is what my base already had
+    const mine = local[rel] || null;
+    const theirBytes = await client.blobGet(c.h);
+    const dest = path.join(dir, rel);
+    if (!mine && base) {                                  // absent locally but the base had it: I deleted it.
+      // main changed it too (we would have `continue`d above otherwise) — that's a real
+      // conflict, not a resurrection: leave the file gone, drop theirs beside it.
+      // `nextBase[c.path]` above already advanced to main's version despite the conflict staying open, so a later land is possible once the agent has decided; landing without deciding lands the draft's table (this file absent) as it stands.
+      writeTheirs(dir, rel, theirBytes);
+      conflicts.push({ rel, hunks: [], deleted: true });
+      continue;
+    }
+    if (!mine || (base && mine.h === base.h)) {          // new on main, or I did not touch it: take theirs
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, theirBytes);
+      taken.push(rel);
+      continue;
+    }
+    if (mine.h === c.h) { kept.push(rel); continue; }    // we made the same change
+    if (!base || !isText(c.ct)) {                        // no common base, or binary: theirs beside, mine stays
+      writeTheirs(dir, rel, theirBytes); conflicts.push({ rel, hunks: [] }); continue;
+    }
+    const baseBytes = await client.blobGet(base.h);
+    const m = merge3(baseBytes.toString("utf8"), fs.readFileSync(dest, "utf8"), theirBytes.toString("utf8"));
+    if (m.ok) { fs.writeFileSync(dest, m.text); merged.push(rel); }
+    else { writeTheirs(dir, rel, theirBytes); conflicts.push({ rel, hunks: m.conflicts }); }
+  }
+  for (const p of r.removed) {
+    const rel = relOf(st.unit, p);
+    const base = baseTable[p], mine = local[rel];
+    delete nextBase[p];
+    if (mine && base && mine.h === base.h) { fs.rmSync(path.join(dir, rel), { force: true }); taken.push(rel); }
+    else if (mine) kept.push(rel);
+  }
+  // The draft is now based on main's current revision. Do not write that here: hand
+  // `nextBase` to `doSave` and let it land in the SAME `writeState` the trailing save
+  // already does after the server accepts it — a save that fails on the network must
+  // leave `.augur/draft.json` exactly as it was before this sync, not holding an advanced
+  // `baseTable` alongside a stale `table`/`baseRevision`.
+  const saved = await doSave({ client, dir, baseRevision: r.mainRevision, baseTable: nextBase });
+  if (!saved.ok) return saved;
+  return { ok: true, mainRevision: r.mainRevision, taken, merged, kept, conflicts };
+}
+
+function writeTheirs(dir, rel, bytes) {
+  const dest = path.join(dir, THEIRS_DIR, rel);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.writeFileSync(dest, bytes);
+}
+
+async function doCloseImpl({ client, dir, discard }) {
+  const st = readState(dir);
+  if (!st) {
+    // A read-only copy has no state file; the registry is what says it is ours to remove.
+    const copy = registryList().find((e) => e.readOnly && path.resolve(e.dir) === path.resolve(dir));
+    if (!copy) return { ok: false, error: "not-a-draft", dir };
+    registryRemove(copy.dir);
+    fs.rmSync(dir, { recursive: true, force: true });
+    return { ok: true, readOnly: true };
+  }
+  if (!st.landed && !discard) return { ok: false, error: "draft-still-open", draftId: st.draftId, address: st.address };
+  if (!st.landed && discard) {
+    const r = await client.discard({ unit: st.unit, draftId: st.draftId });
+    if (r.status && r.status !== 404) return { ok: false, ...r };
+  }
+  registryRemove(dir);
+  fs.rmSync(dir, { recursive: true, force: true });
+  return { ok: true, discarded: !st.landed };
+}
+
+// ── read-only copies (§7 `read`) ─────────────────────────────────────────────
+// A unit materialised for CONTEXT, not for editing: beside the draft folders under `_read/`,
+// files with no write bit, and a registry row the deny hook reads so an editor that ignores
+// the mode is refused with the reason. No `.augur/draft.json` — a copy is not a draft.
+export const READ_DIR = "_read";
+export const readDirFor = (unit) => path.join(READ_DIR, ...unit.split("/").filter(Boolean));
+
+async function doReadImpl({ client, unit, dir, origin, now }) {
+  if (fs.existsSync(dir) && fs.readdirSync(dir).length) return { ok: false, error: "folder-not-empty", dir };
+  const m = await client.main(unit);
+  if (m.status) return { ok: false, ...m };
+  fs.mkdirSync(dir, { recursive: true });
+  await materialise(client, unit, m.table || {}, dir);
+  for (const p of Object.keys(m.table || {})) fs.chmodSync(path.join(dir, relOf(unit, p)), 0o444);
+  registryAdd({ dir, unit, origin, readOnly: true, openedAt: now, revision: m.revision });
+  return { ok: true, dir, files: Object.keys(m.table || {}).length, revision: m.revision };
+}
+
+// ── the watch loop (§7 `watch`) ──────────────────────────────────────────────
+// For people editing by hand in an editor that runs no hooks: every burst of changes is one
+// save. `fs.watch` with `recursive` is what every platform this repo supports offers; the
+// state file's own writes are ignored or a save would trigger the next.
+export function watchFolder(dir, onSettle, { debounceMs = 300 } = {}) {
+  let timer = null;
+  const watcher = fs.watch(dir, { recursive: true }, (_ev, name) => {
+    const rel = String(name || "");
+    if (rel === ".augur" || rel.startsWith(".augur" + path.sep) || rel.startsWith(".augur/")) return;
+    clearTimeout(timer);
+    timer = setTimeout(() => { timer = null; onSettle(); }, debounceMs);
+  });
+  return { close() { clearTimeout(timer); watcher.close(); } };
+}
+
+// ── does the instance serve drafts at all (§10) ───────────────────────────────
+// Read from the public well-known file, so it needs no token and answers before anything
+// is committed or built. False on ANY failure: an instance that cannot be asked is treated
+// as one that does not serve drafts, which is the path that already works everywhere.
+export async function draftsServed(origin, { timeoutMs = 2500 } = {}) {
+  if (!origin) return false;
+  try {
+    const r = await fetch(`${String(origin).replace(/\/+$/, "")}/.well-known/augur.json`, {
+      signal: AbortSignal.timeout(timeoutMs), headers: { Accept: "application/json" },
+    });
+    if (!r.ok) return false;
+    const j = await r.json();
+    return !!(j && j.drafts && j.drafts.enabled === true);
+  } catch (e) { return false; }
+}
+
+// ── what is open on this machine (§4 `status`) ───────────────────────────────
+export function draftsReport(entries, presenceByUnit = {}) {
+  const out = [];
+  for (const e of entries || []) {
+    if (!e || e.readOnly) continue;
+    out.push(`${e.unit.replace(/^\/|\/$/g, "")}  draft ${e.draftId}  ${e.dir}`);
+    for (const d of presenceByUnit[e.unit] || []) {
+      if (d.id === e.draftId) continue;
+      out.push(`    also here: ${d.name ? d.name + " · " : ""}${d.session || "someone"} (${d.active ? "active" : "idle"})`);
+    }
+  }
+  return out;
+}
+
+// Each verb's public surface is its body wrapped in `guarded` — see the comment above
+// `guarded` itself. Internal callers (`doLandImpl` → `doSave`, `doSyncImpl` → `doSave`) go
+// through the same wrapped export, so a blob failure partway through a land or a sync comes
+// back as the same `{ok: false, error: "network"}` shape a bare save would return.
+export const doOpen = guarded(doOpenImpl);
+export const doSave = guarded(doSaveImpl);
+export const doLand = guarded(doLandImpl);
+export const doSync = guarded(doSyncImpl);
+export const doClose = guarded(doCloseImpl);
+export const doRead = guarded(doReadImpl);

package/scripts/lib/graduate.mjs

@@ -0,0 +1,276 @@
+// Graduation — take ONE prototype out, standing on its own, with nothing of this
+// engine left in it.
+//
+// `F-graduate-path`. `augur clone` already turns a whole workspace back into an editable
+// tree, and `augur migrate` already moves a whole workspace between instances. Neither is
+// the thing observed usage asks for: a single tool inside a research workspace acquires a
+// stable audience that is not the team, and then it needs to LEAVE — one artifact, not the
+// workspace around it. Without a doorway it stays, and the research workspace quietly
+// becomes a production host for somebody's customer-facing tool.
+//
+// So this is a doorway, not a policy. Everything here answers one question: what does a
+// person need so that the folder they end up with can be served by anything, from anywhere,
+// forever, with this engine deleted?
+//
+// THREE THINGS HAVE TO HAPPEN, and only the first is obvious.
+//
+//   1. RE-ROOT. A prototype lives at `<project>/prototypes/<name>/` in a repo and at
+//      `/<project>/<name>/` on the site. Standalone it lives at `/`. Its files move up,
+//      and the `../../../skills/<ds>/` references its author wrote have to move with them.
+//      `stripBuildDecorations` already reverses that depth rewrite exactly (it is the peel
+//      the adopt path uses), so re-rooting is that same peel with the new relative dir.
+//
+//   2. BRING THE DESIGN SYSTEM. A prototype is self-contained HTML except for the one
+//      thing it deliberately shares: the workspace's UI skill. Left behind, the graduated
+//      copy is an unstyled page. So the skill folders the prototype REFERENCES come too —
+//      whole folders, not the files a scan happened to see, because a stylesheet reaches
+//      its own fonts and a component script reaches its own assets by paths no reference
+//      scan will find.
+//
+//   3. PROVE IT. "No Augur dependency" is not a claim to make by reading the diff. Every
+//      written file is scanned afterwards: an injected-chrome marker, an engine `/__…`
+//      route or a page global is FATAL (the peel failed, and the copy would call home from
+//      somebody else's domain); a reference that resolves to nothing in the folder is a
+//      warning with the file and the line, because off its old origin it is a 404 that the
+//      original site quietly answered.
+//
+// Pure functions only — the fetching and the writing live in the command. That split is
+// what lets the whole decision be tested against a real built manifest instead of mocked.
+
+import path from "node:path";
+import { stripBuildDecorations } from "./publish-conflict.mjs";
+
+/** Text the reference scanner reads. Anything else is bytes and is copied through. */
+const TEXT_EXT = new Set([".html", ".htm", ".css", ".js", ".mjs", ".json", ".svg", ".txt", ".md", ".webmanifest", ".map"]);
+export const isText = (p) => TEXT_EXT.has(path.posix.extname(String(p)).toLowerCase());
+
+/**
+ * Files a skill folder carries that are this engine's contract with itself, not assets a
+ * page loads. A published manifest never has them (a skill ships what its skill.json
+ * declares); a source tree does, and copying them would put engine vocabulary into a
+ * folder whose whole point is that the engine is gone.
+ */
+const SKILL_INTERNAL = new Set(["skill.json", "graph.js"]);
+export const isSkillInternal = (rel) => {
+  const base = path.posix.basename(rel);
+  return SKILL_INTERNAL.has(base) || base.toLowerCase().endsWith(".md");
+};
+
+/**
+ * Whatever a person typed → the `publicPrefixes` entry it means.
+ *
+ * They will type the URL they know (`/garden/seed-swap/`), the repo path they edit
+ * (`garden/prototypes/seed-swap`), or just the name (`seed-swap`). All three resolve; an
+ * ambiguous bare name lists the candidates rather than picking one, because picking one
+ * graduates the wrong tool and nothing about the result would say so.
+ */
+export function resolveUnit(arg, prefixes = []) {
+  const list = prefixes.filter((p) => typeof p === "string" && p.startsWith("/"));
+  const norm = String(arg || "").trim().replace(/^\/+|\/+$/g, "").replace(/\/prototypes\//, "/");
+  if (!norm) throw new Error("name a prototype: --prototype <project>/<name>");
+
+  const exact = list.find((p) => p === `/${norm}/`);
+  if (exact) return { prefix: exact, name: exact.replace(/^\/+|\/+$/g, "").split("/").pop() };
+
+  const byName = list.filter((p) => p.replace(/^\/+|\/+$/g, "").split("/").pop() === norm);
+  if (byName.length === 1) return { prefix: byName[0], name: norm };
+  if (byName.length > 1) {
+    throw new Error(`"${norm}" names ${byName.length} prototypes — say which: ${byName.join(" ")}`);
+  }
+  throw new Error(`no published prototype "${norm}". Published: ${list.join(" ") || "(none)"}`);
+}
+
+/** Every published prototype, for a listing. */
+export const publishedUnits = (manifest) =>
+  ((manifest && manifest.routing && manifest.routing.publicPrefixes) || []).slice().sort();
+
+/**
+ * The unit's own files, from a published manifest → where each lands in the standalone
+ * folder. The unit's URL prefix is stripped, so `/garden/seed-swap/index.html` becomes
+ * `index.html` — the page a domain's root serves.
+ */
+export function unitFilesFromManifest(manifest, prefix) {
+  const out = [];
+  for (const [url, meta] of Object.entries((manifest && manifest.files) || {}).sort(([a], [b]) => (a < b ? -1 : 1))) {
+    if (!url.startsWith(prefix)) continue;
+    const rel = url.slice(prefix.length);
+    if (!rel) continue;
+    out.push({ url, out: rel, h: meta && meta.h, s: (meta && meta.s) || 0 });
+  }
+  return out;
+}
+
+/**
+ * The skill folders a set of files references. Reads the DIST form (`../../skills/x/`) and
+ * the repo form (`../../../skills/x/`) identically — the depth is exactly what differs
+ * between them, and it is not what is being asked here.
+ */
+export function skillDirsReferenced(texts) {
+  const found = new Set();
+  const re = /(?:\.\.\/)*skills\/([A-Za-z0-9._-]+)\//g;
+  for (const t of texts) {
+    let m;
+    while ((m = re.exec(String(t)))) found.add(m[1]);
+  }
+  return [...found].sort();
+}
+
+/** Everything those skill folders published, at the same path in the standalone folder. */
+export function skillFilesFromManifest(manifest, dirs) {
+  const out = [];
+  for (const [url, meta] of Object.entries((manifest && manifest.files) || {}).sort(([a], [b]) => (a < b ? -1 : 1))) {
+    const m = /^\/skills\/([^/]+)\/(.+)$/.exec(url);
+    if (!m || !dirs.includes(m[1])) continue;
+    if (isSkillInternal(m[2])) continue;
+    out.push({ url, out: `skills/${m[1]}/${m[2]}`, h: meta && meta.h, s: (meta && meta.s) || 0 });
+  }
+  return out;
+}
+
+/**
+ * The peel, aimed at the standalone folder rather than at a repo.
+ *
+ * Same transformer the adopt path uses — marker chrome out, og/twitter meta out, the
+ * linked-assets stamp out, the title emoji off — with the skills depth rewritten for where
+ * this file now SITS, which for the page at the root of a domain is no depth at all.
+ * A file already in authored form (graduating straight from a repo) passes through it
+ * unchanged except for that depth, which is exactly the one thing that has to change.
+ */
+export function rerootHtml(text, outPath) {
+  const dir = path.posix.dirname(outPath);
+  const relDir = dir === "." ? "" : dir;
+  return stripBuildDecorations(String(text), relDir)
+    .replace(/\n[ \t]*\n(\s*<\/head>)/g, "\n$1")
+    .replace(/\n[ \t]*\n(\s*<\/body>)/g, "\n$1");
+}
+
+// ── the proof ────────────────────────────────────────────────────────────────
+
+/**
+ * What this engine leaves behind if the peel misses, in the two shapes that cannot be
+ * anything else. A marker is the peel's own output — one surviving means the peel failed.
+ * A page global is state this engine assigns; a graduated page has no business holding one.
+ */
+const ENGINE_TRACES = [
+  [/<!--gv-[a-z0-9-]+-(?:start|end)/i, "an injected-chrome marker the peel should have removed"],
+  [/window\.__GV_[A-Z_]+/, "a page global this engine sets"],
+];
+
+/** A path only this engine serves. As a REFERENCE it is a request home; as prose it is prose. */
+const ENGINE_PATH = /^\/(?:__|piti\.js|sw\.js|_chrome\.|_build\.json)/i;
+
+/**
+ * The same shape found loose in the text — a fetch inside a script, or a sentence about
+ * how publishing works. ⚠️ THE SCANNER CANNOT TELL THOSE APART, and it must not pretend to.
+ *
+ * The first version of this failed the command on any line containing them, which read
+ * correctly against a prototype full of markup and refused outright the first real
+ * documentation-shaped one it met — a page whose PROSE names engine routes and the
+ * instance's own hostname, dozens of times, and which depends on neither. A doorway that
+ * is a wall for a whole class of artifact is not a doorway, and "add an override flag"
+ * would have made the refusal meaningless for the case it exists for.
+ *
+ * So: a reference is decided, loose text is REPORTED. The report says which it might be.
+ */
+const ENGINE_MENTION = /[/"'(\s]\/__[a-z][a-z0-9-]*\//i;
+
+const SKIP_REF = /^(?:#|data:|mailto:|tel:|javascript:|blob:|about:)/i;
+const ABSOLUTE_REF = /^(?:[a-z][a-z0-9+.-]*:)?\/\//i;
+
+/** Every reference a page or stylesheet makes, with the line it is on. */
+export function referencesIn(text, ext) {
+  const refs = [];
+  const push = (raw, line) => { if (raw) refs.push({ ref: raw.trim(), line }); };
+  const lines = String(text).split("\n");
+  const patterns = [
+    /\b(?:href|src|poster|action|data-src)\s*=\s*["']([^"']*)["']/gi,
+    /\bsrcset\s*=\s*["']([^"']*)["']/gi,
+    /url\(\s*(['"]?)([^'")]+)\1\s*\)/gi,
+    /@import\s+(['"])([^'"]+)\1/gi,
+  ];
+  const wanted = ext === ".html" || ext === ".htm" ? patterns : patterns.slice(2);
+  lines.forEach((text_, i) => {
+    for (const re of wanted) {
+      re.lastIndex = 0;
+      let m;
+      while ((m = re.exec(text_))) {
+        const raw = m[2] != null ? m[2] : m[1];
+        if (re.source.startsWith("\\bsrcset")) {
+          for (const part of raw.split(",")) push(part.trim().split(/\s+/)[0], i + 1);
+        } else push(raw, i + 1);
+      }
+    }
+  });
+  return refs;
+}
+
+/**
+ * Scan the whole written folder. `files` is [{path, text}] for text files plus the set of
+ * every path present, so a reference can be resolved against what is actually there.
+ *
+ * Returns findings, each `{level, path, line, ref, why}`:
+ *
+ *   fatal     the copy still depends on this engine. The command refuses — a graduation
+ *             that silently keeps calling home is the failure this item exists to prevent.
+ *   suspect   an engine-shaped string that is not a reference. Could be a fetch in a
+ *             script; could be a sentence. Reported, never refused. See ENGINE_MENTION.
+ *   dangling  a reference that resolves to nothing here. The old origin answered it.
+ *   external  a request to another origin. Reported so nobody is surprised by it later.
+ */
+export function residualFindings(files, present, { sourceHost = "" } = {}) {
+  const have = present instanceof Set ? present : new Set(present || []);
+  const findings = [];
+
+  for (const f of files) {
+    const ext = path.posix.extname(f.path).toLowerCase();
+    const decided = new Set(); // lines a reference already settled, so prose is not double-reported
+
+    for (const { ref, line } of referencesIn(f.text, ext)) {
+      if (!ref || SKIP_REF.test(ref)) continue;
+      if (ABSOLUTE_REF.test(ref)) {
+        let host = "";
+        try { host = new URL(ref, "https://placeholder.invalid").host; } catch (e) {}
+        if (sourceHost && host === sourceHost) {
+          decided.add(line);
+          findings.push({ level: "fatal", path: f.path, line, ref, why: `a request back to ${sourceHost}, the instance this came from` });
+        } else {
+          findings.push({ level: "external", path: f.path, line, ref, why: "a request to another origin — it will follow this copy wherever it goes" });
+        }
+        continue;
+      }
+      const clean = ref.split("#")[0].split("?")[0];
+      if (!clean) continue;
+      if (ENGINE_PATH.test(clean)) {
+        decided.add(line);
+        findings.push({ level: "fatal", path: f.path, line, ref, why: "a request to a route only this engine serves" });
+        continue;
+      }
+      const dir = path.posix.dirname(f.path);
+      let resolved = clean.startsWith("/")
+        ? clean.replace(/^\/+/, "")
+        : path.posix.normalize(path.posix.join(dir === "." ? "" : dir, clean));
+      if (resolved.startsWith("..")) {
+        findings.push({ level: "dangling", path: f.path, line, ref, why: "points outside the folder" });
+        continue;
+      }
+      if (resolved.endsWith("/") || resolved === "") resolved += "index.html";
+      if (!have.has(resolved) && !have.has(resolved.replace(/\/$/, "")) && !have.has(`${resolved}/index.html`)) {
+        findings.push({ level: "dangling", path: f.path, line, ref, why: "nothing in the folder answers this" });
+      }
+    }
+
+    String(f.text).split("\n").forEach((line, i) => {
+      const n = i + 1;
+      for (const [re, why] of ENGINE_TRACES) {
+        if (re.test(line)) findings.push({ level: "fatal", path: f.path, line: n, ref: line.trim().slice(0, 120), why });
+      }
+      if (decided.has(n)) return;
+      if (ENGINE_MENTION.test(line)) {
+        findings.push({ level: "suspect", path: f.path, line: n, ref: line.trim().slice(0, 120), why: "an engine route in the text — prose about it is fine, a request to it is not" });
+      } else if (sourceHost && line.includes(sourceHost)) {
+        findings.push({ level: "suspect", path: f.path, line: n, ref: line.trim().slice(0, 120), why: `names ${sourceHost} in the text — prose about it is fine, a request to it is not` });
+      }
+    });
+  }
+  return findings.sort((a, b) => (a.path === b.path ? a.line - b.line : a.path < b.path ? -1 : 1));
+}