@apisurf/canonui 0.1.1

package/dist/bin.js

@@ -0,0 +1,1925 @@
+#!/usr/bin/env node
+
+// src/bin.ts
+import { parseArgs } from "node:util";
+
+// src/build.ts
+import { mkdirSync as mkdirSync2, rmSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { tmpdir } from "node:os";
+import { dirname as dirname3, isAbsolute as isAbsolute2, join, resolve as resolve3 } from "node:path";
+
+// ../core/src/time.ts
+function formatTimestamp(value) {
+  return `${new Date(value).toISOString().slice(0, 19)}Z`;
+}
+
+// ../core/src/bundle.ts
+var MAX_HEADING = 6;
+function bundleDocument(snapshot, options = {}) {
+  const meta = options.meta ?? true;
+  const { document, blocks } = snapshot;
+  const parts = [];
+  if (meta) parts.push(frontMatter(snapshot));
+  parts.push(`# ${document.title}`);
+  if (document.description) parts.push(document.description);
+  if (options.toc) {
+    const toc = contents(blocks);
+    if (toc) parts.push(toc);
+  }
+  for (const block of blocks) parts.push(renderBlock(block, 2));
+  if (blocks.length === 0) parts.push("_This document has no content yet._");
+  return `${parts.join("\n\n")}
+`;
+}
+function frontMatter(snapshot) {
+  const d = snapshot.document;
+  const lines = [
+    "---",
+    `document: ${yaml(d.slug)}`,
+    `title: ${yaml(d.title)}`,
+    ...d.description ? [`description: ${yaml(d.description)}`] : [],
+    `blocks: ${snapshot.blocks.length}`,
+    `updated: ${formatTimestamp(d.updatedAt)}`,
+    `generated: ${formatTimestamp(snapshot.generatedAt)}`,
+    "---"
+  ];
+  return lines.join("\n");
+}
+function yaml(value) {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function contents(blocks) {
+  const lines = blocks.filter((b) => b.title).map((b) => `- ${b.title}`);
+  return lines.length > 0 ? ["## Contents", "", ...lines].join("\n") : null;
+}
+function renderBlock(block, level) {
+  const parts = [];
+  if (block.title) parts.push(`${"#".repeat(Math.min(level, MAX_HEADING))} ${block.title}`);
+  const body = block.content.trim();
+  switch (block.type) {
+    case "markdown":
+      parts.push(shiftHeadings(body, block.title ? level : level - 1));
+      break;
+    case "text":
+      parts.push(body);
+      break;
+    case "html":
+      parts.push(fence(body, "html"));
+      break;
+    case "mermaid":
+      parts.push(fence(body, "mermaid"));
+      break;
+    case "img": {
+      const alt = typeof block.attrs.alt === "string" ? block.attrs.alt : "";
+      const caption = typeof block.attrs.caption === "string" && block.attrs.caption ? `
+_${block.attrs.caption}_` : "";
+      parts.push(`![${alt}](${body})${caption}`);
+      break;
+    }
+    default:
+      parts.push(fence(body, String(block.type)));
+  }
+  return parts.filter(Boolean).join("\n\n");
+}
+function fence(body, language) {
+  const longest = [...body.matchAll(/`+/g)].reduce((max, m) => Math.max(max, m[0].length), 0);
+  const ticks = "`".repeat(Math.max(3, longest + 1));
+  return `${ticks}${language}
+${body}
+${ticks}`;
+}
+function shiftHeadings(markdown, by) {
+  if (by <= 0) return markdown;
+  let open2 = null;
+  return markdown.split("\n").map((line) => {
+    const marker = /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1];
+    if (open2 !== null) {
+      if (marker && marker[0] === open2[0] && marker.length >= open2.length) open2 = null;
+      return line;
+    }
+    if (marker) {
+      open2 = marker;
+      return line;
+    }
+    const heading = /^(#{1,6})(\s|$)/.exec(line);
+    if (!heading) return line;
+    const hashes = heading[1];
+    return `${"#".repeat(Math.min(hashes.length + by, MAX_HEADING))}${line.slice(hashes.length)}`;
+  }).join("\n");
+}
+
+// ../db/src/open.ts
+import { dirname, isAbsolute, resolve } from "node:path";
+import { homedir } from "node:os";
+import { existsSync, mkdirSync } from "node:fs";
+import Database from "better-sqlite3";
+
+// ../db/src/schema.ts
+var MIGRATIONS = [
+  // ---------------------------------------------------------------------------
+  // 001 — the schema
+  // ---------------------------------------------------------------------------
+  `
+  -- The unit of publishing: one document builds into one page.
+  CREATE TABLE documents (
+    id          INTEGER PRIMARY KEY,
+    uid         TEXT    NOT NULL UNIQUE,       -- stable external id
+    slug        TEXT    NOT NULL UNIQUE,       -- URL-safe name, and how a human refers to it
+    title       TEXT    NOT NULL,
+    description TEXT,
+    created_at  INTEGER NOT NULL,              -- epoch ms
+    updated_at  INTEGER NOT NULL
+  );
+  CREATE INDEX idx_documents_updated ON documents (updated_at DESC);
+  CREATE INDEX idx_documents_created ON documents (created_at DESC);
+  -- NOCASE so "list documents titled like Api" does not depend on how it was typed.
+  CREATE INDEX idx_documents_title   ON documents (title COLLATE NOCASE);
+
+  -- One renderable chunk. \`content\` is the payload for every type -- the
+  -- markdown, the prose, the HTML, the mermaid source, or the image src -- so
+  -- that one column means one thing no matter what is being rendered.
+  -- Everything type-specific (alt text, a caption, a width) goes in \`attrs\`.
+  CREATE TABLE blocks (
+    id          INTEGER PRIMARY KEY,
+    uid         TEXT    NOT NULL UNIQUE,
+    document_id INTEGER NOT NULL REFERENCES documents (id) ON DELETE CASCADE,
+    position    INTEGER NOT NULL,              -- order within the document, 1..N contiguous
+    type        TEXT    NOT NULL,              -- 'markdown' | 'text' | 'html' | 'img' | 'mermaid'
+    title       TEXT,                          -- optional heading or caption
+    content     TEXT    NOT NULL DEFAULT '',
+    attrs       TEXT,                          -- JSON object, or NULL
+    created_at  INTEGER NOT NULL,
+    updated_at  INTEGER NOT NULL
+  );
+  CREATE INDEX idx_blocks_document ON blocks (document_id, position, id);
+  CREATE INDEX idx_blocks_type     ON blocks (type);
+
+  -- Full-text over block content and titles. Query it directly:
+  --   SELECT block_id FROM block_fts WHERE block_fts MATCH 'retry'
+  CREATE VIRTUAL TABLE block_fts USING fts5(
+    content,
+    title,
+    block_id UNINDEXED,
+    tokenize = 'unicode61'
+  );
+
+  -- Kept in sync by trigger rather than by the writer: an index that can be
+  -- forgotten at one call site is an index nobody can trust.
+  CREATE TRIGGER blocks_fts_insert AFTER INSERT ON blocks BEGIN
+    INSERT INTO block_fts (block_id, content, title)
+    VALUES (new.id, new.content, COALESCE(new.title, ''));
+  END;
+  CREATE TRIGGER blocks_fts_update AFTER UPDATE ON blocks BEGIN
+    DELETE FROM block_fts WHERE block_id = old.id;
+    INSERT INTO block_fts (block_id, content, title)
+    VALUES (new.id, new.content, COALESCE(new.title, ''));
+  END;
+  CREATE TRIGGER blocks_fts_delete AFTER DELETE ON blocks BEGIN
+    DELETE FROM block_fts WHERE block_id = old.id;
+  END;
+
+  -- ---------------------------------------------------------------------------
+  -- Views: the denormalized surface. Normalization is for the query planner;
+  -- these are what get, ls and the build snapshot read.
+  -- ---------------------------------------------------------------------------
+
+  CREATE VIEW v_documents AS
+  SELECT
+    d.id,
+    d.uid,
+    d.slug,
+    d.title,
+    d.description,
+    (SELECT COUNT(*) FROM blocks b WHERE b.document_id = d.id) AS block_count,
+    d.created_at,
+    d.updated_at
+  FROM documents d;
+
+  -- \`seq\` is the ordinal computed on read; \`position\` is what is stored and what
+  -- sorts. The store keeps positions contiguous, so the two agree -- but only
+  -- \`seq\` promises to.
+  CREATE VIEW v_blocks AS
+  SELECT
+    b.id,
+    b.uid,
+    b.document_id,
+    d.slug AS document_slug,
+    ROW_NUMBER() OVER (PARTITION BY b.document_id ORDER BY b.position, b.id) AS seq,
+    b.position,
+    b.type,
+    b.title,
+    b.content,
+    b.attrs,
+    LENGTH(b.content) AS size,
+    b.created_at,
+    b.updated_at
+  FROM blocks b
+  JOIN documents d ON d.id = b.document_id;
+  `
+];
+var SCHEMA_VERSION = MIGRATIONS.length;
+
+// ../db/src/open.ts
+var DEFAULT_DB_SEGMENTS = [".apisurf", "canon"];
+var DEFAULT_DB_FILENAME = "canon.sqlite";
+var DB_ENV_VAR = "CANON_DB";
+function resolveDbPath(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const raw = options.path ?? process.env[DB_ENV_VAR];
+  if (!raw) return resolve(homedir(), ...DEFAULT_DB_SEGMENTS, DEFAULT_DB_FILENAME);
+  return isAbsolute(raw) ? raw : resolve(cwd, raw);
+}
+function openDb(options = {}) {
+  const file = resolveDbPath(options);
+  if (options.mustExist && !existsSync(file)) {
+    throw new Error(
+      `No database at ${file}. Run \`canon new document <title>\` first, or pass --db <path>.`
+    );
+  }
+  if (!options.mustExist) mkdirSync(dirname(file), { recursive: true });
+  const db = new Database(file);
+  db.pragma("journal_mode = WAL");
+  db.pragma("synchronous = NORMAL");
+  db.pragma("temp_store = MEMORY");
+  db.pragma("cache_size = -65536");
+  db.pragma("foreign_keys = ON");
+  if (options.skipMigrations) assertMigrated(db, file);
+  else applyMigrations(db);
+  return db;
+}
+function assertMigrated(db, file) {
+  const current = db.pragma("user_version", { simple: true });
+  if (current === MIGRATIONS.length) return;
+  db.close();
+  if (current > MIGRATIONS.length) {
+    throw new Error(
+      `Database schema version ${current} is newer than this build of canon understands (${MIGRATIONS.length}). Upgrade the CLI.`
+    );
+  }
+  throw new Error(
+    `${file} is at schema version ${current}; this build of canon reads ${MIGRATIONS.length}. Reads do not migrate. Run any write against it to bring it forward \u2014 \`canon set document <ref> --db <path>\` will do.`
+  );
+}
+function applyMigrations(db) {
+  const current = db.pragma("user_version", { simple: true });
+  if (current > MIGRATIONS.length) {
+    throw new Error(
+      `Database schema version ${current} is newer than this build of canon understands (${MIGRATIONS.length}). Upgrade the CLI.`
+    );
+  }
+  for (let version = current; version < MIGRATIONS.length; version++) {
+    const sql = MIGRATIONS[version];
+    if (!sql) continue;
+    db.exec(`BEGIN; ${sql} PRAGMA user_version = ${version + 1}; COMMIT;`);
+  }
+}
+
+// ../db/src/entities.ts
+var COMPUTED_TYPES = {
+  "v_documents.block_count": "INTEGER",
+  "v_blocks.seq": "INTEGER",
+  "v_blocks.size": "INTEGER"
+};
+function describeRelation(db, name) {
+  const rows = db.prepare(`SELECT name, type FROM pragma_table_info(?) ORDER BY cid`).all(name);
+  return rows.map((r) => {
+    const declared = r.type.trim();
+    if (declared) return { name: r.name, type: declared, computed: false };
+    return {
+      name: r.name,
+      type: COMPUTED_TYPES[`${name}.${r.name}`] ?? "",
+      computed: true
+    };
+  });
+}
+var ENTITIES = [
+  {
+    name: "document",
+    plural: "documents",
+    view: "v_documents",
+    key: "id",
+    nameKey: "slug",
+    defaultFields: ["id", "slug", "title", "block_count", "created_at", "updated_at"],
+    description: "One document: an ordered list of blocks. Builds into one site.",
+    filters: {
+      title: {
+        column: "title",
+        mode: "like",
+        value: "string",
+        help: "Match the title. Substring by default; % and _ work"
+      },
+      // Creation, to match the order. A window that selected on one date and
+      // sorted on another would put rows in an order the filter cannot explain.
+      since: {
+        column: "created_at",
+        mode: "gte",
+        value: "number",
+        help: "Created at or after this date. YYYY-MM-DD, or epoch ms"
+      },
+      until: {
+        column: "created_at",
+        mode: "lte",
+        value: "number",
+        help: "Created at or before this date"
+      }
+    },
+    // Newest document first. A document's identity is when it started, not when
+    // it was last touched -- editing an old one should not move it to the top.
+    // The id breaks ties, because two documents created in the same millisecond
+    // would otherwise come back in whatever order the planner chose.
+    order: "created_at DESC, id DESC",
+    derived: {}
+  },
+  {
+    name: "block",
+    plural: "blocks",
+    view: "v_blocks",
+    key: "id",
+    // A block has no name. It is the seq-th thing in a document, and that is
+    // an address rather than an identity — it changes the moment one moves.
+    nameKey: null,
+    defaultFields: ["id", "document_id", "seq", "type", "title", "size", "preview"],
+    description: "One renderable chunk of a document.",
+    filters: {
+      document: {
+        column: "document_id",
+        mode: "eq",
+        value: "number",
+        help: "Only blocks in this document. Takes an id or a slug"
+      },
+      type: {
+        column: "type",
+        mode: "eq",
+        value: "string",
+        help: "markdown | text | html | img | mermaid"
+      }
+    },
+    order: "document_id DESC, position, id",
+    derived: { preview: "content" }
+  }
+];
+function findEntity(name) {
+  const wanted = name.toLowerCase();
+  return ENTITIES.find((e) => e.name === wanted || e.plural === wanted || e.view === wanted) ?? null;
+}
+function entityFields(db, entity) {
+  const columns2 = describeRelation(db, entity.view).map((c) => c.name);
+  return [...columns2, ...Object.keys(entity.derived)];
+}
+var UnknownFieldError = class extends Error {
+  constructor(entity, field, available2) {
+    super(`unknown field "${field}" on ${entity.name}`);
+    this.entity = entity;
+    this.field = field;
+    this.available = available2;
+    this.name = "UnknownFieldError";
+  }
+};
+var PREVIEW_CHARS = 120;
+function assertFieldsExist(entity, fields, available2) {
+  for (const field of fields) {
+    if (!available2.includes(field)) {
+      throw new UnknownFieldError(entity, field, available2);
+    }
+  }
+}
+function columnsFor(entity, fields) {
+  const columns2 = /* @__PURE__ */ new Set();
+  for (const field of fields) {
+    columns2.add(entity.derived[field] ?? field);
+  }
+  if (columns2.size === 0) columns2.add(entity.key);
+  return [...columns2];
+}
+function idClause(entity, ids) {
+  const numeric2 = (ids ?? []).filter((id) => typeof id === "number");
+  const named2 = (ids ?? []).filter((id) => typeof id === "string");
+  const clauses = [];
+  const params = [];
+  if (numeric2.length > 0) {
+    clauses.push(`"${entity.key}" IN (${numeric2.map(() => "?").join(", ")})`);
+    params.push(...numeric2);
+  }
+  if (named2.length > 0 && entity.nameKey) {
+    clauses.push(`"${entity.nameKey}" IN (${named2.map(() => "?").join(", ")})`);
+    params.push(...named2);
+  }
+  return { sql: clauses.length > 0 ? `(${clauses.join(" OR ")})` : "0", params };
+}
+function whereClause(entity, options) {
+  const where = [];
+  const params = [];
+  if (options.ids && options.ids.length > 0) {
+    const clause = idClause(entity, options.ids);
+    where.push(clause.sql);
+    params.push(...clause.params);
+  }
+  for (const applied of options.filters ?? []) {
+    const def = entity.filters[applied.name];
+    if (!def) continue;
+    where.push(filterClause(def));
+    params.push(applied.value);
+  }
+  return { where, params };
+}
+function selectEntity(db, entity, options) {
+  const available2 = entityFields(db, entity);
+  assertFieldsExist(entity, options.fields, available2);
+  const columns2 = columnsFor(entity, options.fields);
+  const { where, params } = whereClause(entity, options);
+  const order = orderClause(entity, options, available2);
+  const sql = `SELECT ${columns2.map((c) => `"${c}"`).join(", ")} FROM "${entity.view}"` + (where.length ? ` WHERE ${where.join(" AND ")}` : "") + ` ORDER BY ${order}` + (options.limit !== void 0 && options.limit > 0 ? ` LIMIT ${Number(options.limit)}` : "");
+  const rows = db.prepare(sql).all(...params);
+  return rows.map((row) => {
+    const out = {};
+    for (const field of options.fields) {
+      const source = entity.derived[field];
+      out[field] = source === void 0 ? row[field] : preview(row[source]);
+    }
+    return out;
+  });
+}
+function filterClause(def) {
+  switch (def.mode) {
+    case "like":
+      return `"${def.column}" LIKE ? ESCAPE '\\'`;
+    case "gte":
+      return `"${def.column}" >= ?`;
+    case "lte":
+      return `"${def.column}" <= ?`;
+    default:
+      return `"${def.column}" = ?`;
+  }
+}
+function orderClause(entity, options, available2) {
+  if (options.sort) {
+    if (!available2.includes(options.sort)) {
+      throw new UnknownFieldError(entity, options.sort, available2);
+    }
+    return `"${options.sort}" ${options.desc ? "DESC" : "ASC"}`;
+  }
+  const scoped = (options.filters ?? []).some((f) => f.name === "document");
+  if (entity.name === "block" && scoped) return "position, id";
+  return entity.order;
+}
+function preview(value) {
+  if (value === null || value === void 0) return null;
+  const text = typeof value === "string" ? value : String(value);
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length <= PREVIEW_CHARS ? flat : `${flat.slice(0, PREVIEW_CHARS)}\u2026`;
+}
+
+// ../db/src/store.ts
+var StoreError = class extends Error {
+  constructor(message, hint) {
+    super(message);
+    this.hint = hint;
+    this.name = "StoreError";
+  }
+};
+var now = () => Date.now();
+function isId(ref) {
+  return typeof ref === "number" || /^\d+$/.test(ref);
+}
+function findDocument(db, ref) {
+  const sql = isId(ref) ? `SELECT * FROM v_documents WHERE id = ?` : `SELECT * FROM v_documents WHERE slug = ?`;
+  return db.prepare(sql).get(isId(ref) ? Number(ref) : ref) ?? null;
+}
+function requireDocument(db, ref) {
+  const row = findDocument(db, ref);
+  if (!row) throw new StoreError(`no document "${ref}"`, "canon ls documents");
+  return row;
+}
+function parseAttrs(raw) {
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function snapshotDocument(db, documentId) {
+  const document = db.prepare(`SELECT * FROM v_documents WHERE id = ?`).get(documentId);
+  if (!document) throw new StoreError(`no document ${documentId}`);
+  const blocks = db.prepare(`SELECT * FROM blocks WHERE document_id = ? ORDER BY position, id`).all(documentId);
+  return {
+    version: 7,
+    generatedAt: now(),
+    document: {
+      uid: document.uid,
+      slug: document.slug,
+      title: document.title,
+      description: document.description,
+      createdAt: document.created_at,
+      updatedAt: document.updated_at
+    },
+    blocks: blocks.map((block, index) => ({
+      uid: block.uid,
+      seq: index + 1,
+      type: block.type,
+      title: block.title,
+      content: block.content,
+      attrs: parseAttrs(block.attrs)
+    }))
+  };
+}
+
+// src/db.ts
+function dbPathOf(options) {
+  return resolveDbPath({ ...options.db ? { path: options.db } : {}, cwd: options.cwd });
+}
+function openRead(options) {
+  const path = dbPathOf(options);
+  try {
+    return openDb({ path, mustExist: true, skipMigrations: true });
+  } catch (err) {
+    process.stderr.write(
+      `canonui: ${err instanceof Error ? err.message : String(err)}
+
+Content is created with canon:
+  canon new document "Retry Guide"
+`
+    );
+    return null;
+  }
+}
+function describeStoreError(err) {
+  return err.hint ? `${err.message}
+Try: ${err.hint}
+` : `${err.message}
+`;
+}
+
+// src/format.ts
+function renderJson(value) {
+  return JSON.stringify(value, null, 2);
+}
+function plural(count, noun) {
+  return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+function isoDateTime(epochMs) {
+  return new Date(epochMs).toISOString().slice(0, 16).replace("T", " ");
+}
+function columns(rows, right = []) {
+  const width = [];
+  for (const row of rows) {
+    row.forEach((cell, i) => {
+      width[i] = Math.max(width[i] ?? 0, cell.length);
+    });
+  }
+  const flush = new Set(right);
+  return rows.map(
+    (row) => row.map((cell, i) => flush.has(i) ? cell.padStart(width[i] ?? 0) : cell.padEnd(width[i] ?? 0)).join("  ").trimEnd()
+  );
+}
+
+// src/render.ts
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname as dirname2, resolve as resolve2 } from "node:path";
+import { fileURLToPath } from "node:url";
+var PACKAGE_ROOT = resolve2(dirname2(fileURLToPath(import.meta.url)), "..");
+function render(options) {
+  const astro = astroBin();
+  if (!astro) {
+    process.stderr.write(
+      "canonui: astro is not installed next to this package, so there is nothing to build with.\nReinstall @apisurf/canonui.\n"
+    );
+    return Promise.resolve(1);
+  }
+  return run(
+    astro,
+    {
+      CANON_SITE_DATA: options.data,
+      CANON_OUT_DIR: options.out,
+      ...options.base ? { CANON_BASE: options.base } : {},
+      ...options.site ? { CANON_SITE_URL: options.site } : {}
+    },
+    options.verbose === true
+  );
+}
+function astroBin() {
+  try {
+    const require2 = createRequire(import.meta.url);
+    const manifestPath = require2.resolve("astro/package.json");
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+    const entry = typeof manifest.bin === "string" ? manifest.bin : manifest.bin?.astro;
+    if (!entry) return null;
+    return resolve2(dirname2(manifestPath), entry);
+  } catch {
+    return null;
+  }
+}
+function run(bin, env, verbose) {
+  const child = spawn(process.execPath, [bin, "build"], {
+    cwd: PACKAGE_ROOT,
+    stdio: verbose ? "inherit" : ["ignore", "ignore", "inherit"],
+    env: { ...process.env, ...env, FORCE_COLOR: process.env.FORCE_COLOR ?? "0" }
+  });
+  return new Promise((done) => {
+    child.on("error", (err) => {
+      process.stderr.write(`canonui: could not start astro \u2014 ${err.message}
+`);
+      done(1);
+    });
+    child.on("exit", (code) => done(code ?? 0));
+  });
+}
+
+// src/build.ts
+var BUILDS_DIR = "builds";
+async function build(options) {
+  return (await buildSite(options)).code;
+}
+async function buildSite(options) {
+  const prepared = prepare(options);
+  if (typeof prepared === "number") return { code: prepared, out: "" };
+  const { snapshot, out, snapshotPath } = prepared;
+  const blocks = snapshot.blocks.length;
+  if (options.snapshotOnly) {
+    report(options, { snapshot, out: snapshotPath, snapshotPath, blocks, rendered: false });
+    return { code: 0, out };
+  }
+  if (options.global && !options.out) rmSync(out, { recursive: true, force: true });
+  const code = await render({
+    data: snapshotPath,
+    out,
+    ...options.base ? { base: options.base } : {},
+    ...options.site ? { site: options.site } : {},
+    ...options.verbose ? { verbose: true } : {}
+  });
+  if (code !== 0) {
+    process.stderr.write(
+      `canonui: the build failed (exit ${code}).` + (options.verbose ? "\n" : " Rerun with --verbose to see why.\n") + `canonui: the snapshot it failed on is at ${snapshotPath}
+`
+    );
+    return { code, out };
+  }
+  writeMarkdown(snapshot, out);
+  if (!options.snapshot) rmSync(snapshotPath, { force: true });
+  report(options, { snapshot, out, snapshotPath, blocks, rendered: true });
+  return { code: 0, out };
+}
+function writeMarkdown(snapshot, out) {
+  writeFileSync(
+    join(out, "index.md"),
+    bundleDocument(snapshot, { toc: true, meta: false }),
+    "utf8"
+  );
+}
+function prepare(options) {
+  const db = openRead(options);
+  if (!db) return 1;
+  try {
+    const document = requireDocument(db, options.document);
+    const snapshot = snapshotDocument(db, document.id);
+    if (snapshot.blocks.length === 0) {
+      process.stderr.write(
+        `canonui: ${document.slug} has no blocks to build
+
+  canon new block --document ${document.slug} --file intro.md
+`
+      );
+      return 1;
+    }
+    const out = options.out ? absolute(options.out, options.cwd) : options.global ? join(dirname3(dbPathOf(options)), BUILDS_DIR, document.slug) : absolute(join("dist", document.slug), options.cwd);
+    const snapshotPath = options.snapshot ? absolute(options.snapshot, options.cwd) : join(tmpdir(), "canonui-build", `${document.slug}-${randomUUID()}.json`);
+    mkdirSync2(dirname3(snapshotPath), { recursive: true });
+    writeFileSync(snapshotPath, `${renderJson(snapshot)}
+`, "utf8");
+    return { snapshot, out, snapshotPath };
+  } catch (err) {
+    if (err instanceof StoreError) {
+      process.stderr.write(`canonui: ${describeStoreError(err)}`);
+      return 1;
+    }
+    throw err;
+  } finally {
+    db.close();
+  }
+}
+function report(options, result) {
+  if (options.json) {
+    const payload = {
+      document: result.snapshot.document.slug,
+      out: result.out,
+      blocks: result.blocks,
+      snapshot: result.snapshotPath
+    };
+    process.stdout.write(`${renderJson(payload)}
+`);
+    return;
+  }
+  const what = result.rendered ? "built" : "wrote snapshot for";
+  const slug = result.snapshot.document.slug;
+  process.stdout.write(
+    `
+  ${what} ${slug}
+
+  blocks  ${result.blocks}
+  output  ${result.out}
+
+` + (result.rendered && !options.serving ? `  Serve it:  canonui serve ${slug}
+
+` : "\n")
+  );
+}
+function absolute(path, cwd) {
+  return isAbsolute2(path) ? path : resolve3(cwd, path);
+}
+
+// src/howto.ts
+var INDEX_BANNER = `  These are worked examples, not your data. The names in them are
+  invented \u2014 substitute your own. Nothing here reads or writes your
+  database.`;
+var PAGE_BANNER = `  A worked example, not your data. The names in it are invented \u2014
+  substitute your own. Nothing on this page has been run, and reading
+  it changed nothing.`;
+var HOWTOS = [
+  {
+    name: "preview",
+    summary: "Look at a document in a browser while writing it",
+    body: `The loop is two shells: one writing with canon, one looking with canonui.
+
+1. See what there is to build
+  canonui ls
+
+  Prints every document, the slug each answers to and how many blocks
+  it holds. canonui's own \u2014 nothing here needs the other command.
+
+2. Build it and open it
+  canonui serve retry-guide
+
+  With only one document in the database, the slug can be left off \u2014
+  canonui serve says which one it picked. With several, it prints the
+  list instead of an error.
+
+  Builds into ~/.apisurf/canon/builds/retry-guide, then serves it on
+  http://127.0.0.1:3000 \u2014 or the next free port above it \u2014 and holds
+  the terminal until Ctrl-C.
+
+  Loopback only. --host is there for when putting it on the network
+  is on purpose.
+
+3. Change something, in another shell
+  canon set block 12 --file ./retry-guide.md
+  canon mv block 12 --to 1
+
+4. See the change
+  Ctrl-C, then canonui serve retry-guide again.
+
+  There is no watcher. Nothing is cached either, so a build into the
+  same folder in a third shell shows up on the next refresh without
+  restarting this:
+  canonui build retry-guide --out ~/.apisurf/canon/builds/retry-guide
+
+Serving what is already built
+  canonui open
+  canonui open ./public
+
+  A command of its own, because it is a different question: it takes
+  a folder rather than a document and never opens the database. This
+  is how to look at output somebody else produced, and how to check
+  that what you are about to upload is what you think it is.
+
+  With nothing after it, it takes the one site under ./dist.
+
+A busy port
+  canonui serve retry-guide --port 4000
+
+  Without --port, 3000 through 3020 are tried in turn, so another dev
+  server holding 3000 moves this to 3001 rather than failing.
+
+Then
+  canonui howto publish       putting the folder somewhere
+  canonui help sites          what the folder holds
+  canonui help ls             listing, in full`
+  },
+  {
+    name: "publish",
+    summary: "Build a folder and put it on a host",
+    body: `The output is static files with no server requirement, so publishing
+is a copy. What needs deciding first is where the page will live,
+because one of the two answers has to be baked in at build time.
+
+At the root of a domain
+  canonui build retry-guide --site https://docs.example.com
+
+  Writes ./dist/retry-guide. Upload the contents. --site only fills in
+  the URLs that cannot be relative \u2014 canonical tags and the like \u2014 so
+  leaving it off still produces a working site.
+
+Under a sub-path
+  canonui build retry-guide --base /docs --site https://example.com
+
+  Bakes the prefix into every internal href. This is a build-time
+  decision, not a serving one: a site built without --base and then
+  served under /docs has a broken stylesheet.
+
+  Check it before uploading, mounted at the same prefix:
+
+  canonui serve retry-guide --base /docs
+  canonui open ./dist/retry-guide --base /docs
+
+  Without --base the server would put the folder at the root, where
+  the stylesheet starts with /docs and 404s \u2014 which is the failure
+  this is worth checking for.
+
+Somewhere in particular
+  canonui build retry-guide --out ./public
+
+  --out defaults to ./dist/<document-slug>. Point it at whatever
+  directory the host expects and there is nothing to move afterwards.
+
+In CI
+  canonui ls --json
+  canonui build retry-guide --json
+
+  The first is the list of documents as objects, for a job that builds
+  each in turn. The second prints the document, the output path and
+  the block count, and exits 0 or non-zero. --verbose adds Astro's own
+  output, which is what to turn on when a build fails.
+
+  The database is one file, so a pipeline that builds from a checkout
+  wants CANON_DB pointing into it:
+
+  CANON_DB=./docs.sqlite canonui build retry-guide --out ./public
+
+What gets built
+  Every block in the document. There is no draft state and nothing to
+  mark first \u2014 a block that should not ship belongs in another
+  document.  canon help documents
+
+Then
+  canonui help sites          base paths and the markdown twin
+  canonui howto snapshot      rendering with something else`
+  },
+  {
+    name: "snapshot",
+    summary: "Render the content with something other than this theme",
+    body: `A build has two halves that meet at a JSON file. The first reads the
+database and reduces one document to a snapshot; the second reads the
+snapshot and writes the site. Only the first half needs SQLite, and
+only the second half needs Astro.
+
+Get the snapshot
+  canonui build retry-guide --snapshot-only --snapshot ./doc.json
+
+  Writes the file and stops. Nothing is rendered, and the theme is
+  never started \u2014 so this works the same on a machine that has no
+  intention of building a site.
+
+What is in it
+  The document, and every block in reading order with its type, its
+  title, its body and its attributes. Plus a version field, so a
+  renderer can refuse a shape it does not know rather than guess.
+
+  Read it back with anything: jq, a script, another generator.
+
+Keep it from a real build
+  canonui build retry-guide --snapshot ./doc.json
+
+  Renders as usual and leaves the snapshot behind instead of deleting
+  it. A build that fails does the same without being asked, at the
+  path the error names \u2014 the exact input, to look at.
+
+The other way out
+  canon cat retry-guide > retry-guide.md
+
+  When what you want is the prose rather than the data. Front matter,
+  then the content, in one markdown document.
+
+Then
+  canonui help snapshot       the seam, in more detail
+  canon help cat              the markdown side`
+  }
+];
+var WIDTH = Math.max(...HOWTOS.map((h) => h.name.length));
+var HOWTO_INDEX = `canonui howto <name> \u2014 worked examples of whole tasks, start to finish.
+
+${INDEX_BANNER}
+
+Tasks
+${HOWTOS.map((h) => `  ${h.name.padEnd(WIDTH)}  ${h.summary}`).join("\n")}
+
+Usage
+  canonui howto <name>        print one of them
+  canonui howto               this list
+
+For a command's flags rather than a task, use canonui help <command>.
+Writing the content, rather than rendering it, is canon howto.
+`;
+var HOWTO_NAMES = HOWTOS.map((h) => h.name);
+function howtoPage(name) {
+  const found = HOWTOS.find((h) => h.name === name);
+  if (!found) return null;
+  return `canonui howto ${found.name} \u2014 ${lowerFirst(found.summary)}.
+
+${PAGE_BANNER}
+
+${found.body}
+`;
+}
+function lowerFirst(text) {
+  return text.charAt(0).toLowerCase() + text.slice(1);
+}
+
+// src/help.ts
+var ROOT_HELP = `canonui \u2014 build and preview the documents that canon holds.
+
+Usage
+  canonui <command> [options]
+
+Commands
+  ls                   What is here, and what to build. Start with this.
+  build <document>     Render a document into a folder of static HTML.
+  serve <document>     Build it and serve it over HTTP.
+  open [dir]           Serve a folder that is already built.
+  howto [name]         Worked examples of whole tasks, start to finish.
+  help [command]       One command's flags, or a topic.
+
+Model
+  canonui reads; canon writes. Both open the same file, and this one opens it
+  read-only and unmigrated \u2014 nothing here can change the content it renders.
+
+  document \u2192 block. One document builds into one page: its blocks top to
+  bottom, in the order canon mv block sets, with a contents rail drawn from
+  their titles.
+
+Next
+  canonui ls                  the documents, and what each one holds
+  canonui howto               do a thing, start to finish
+  canonui help open           looking at a folder without the database
+  canonui help sites          what the built site is, and what it needs
+  canonui help snapshot       the JSON seam, for another renderer
+  canonui <command> --help    one command's flags
+
+  build and serve name the only document when there is only one, and print the
+  list to choose from when there is more than one. So canonui ls first is a
+  habit, not a requirement.
+
+Writing the content
+  Everything that creates or edits content is canon, not this:
+
+  canon new document "Retry Guide"
+  canon new block --document retry-guide --file intro.md
+  canon help
+
+Global options
+  --db <path>      Database file. Default $CANON_DB, else ~/.apisurf/canon/canon.sqlite
+  -h, --help       Show help for the command
+  -v, --version    Print this build's version. --json for the parts
+`;
+var LS_HELP = `canonui ls \u2014 what is in the database, and what to build.
+
+Usage
+  canonui ls                      Every document
+  canonui ls documents            The same
+
+The first command to run, and the answer to "what can I build". Prints the
+slugs the other commands take, and ends with the line that acts on them.
+
+Not a query. canon ls is the projected, filtered, bounded listing \u2014 --fields,
+--limit, --since, and a row per record. This is a short list to pick from, so
+it takes none of that and prints all of it: a listing you cannot trust to be
+complete is not one you can choose from.
+
+Options
+  --db <path>      Database file. Default $CANON_DB, else ~/.apisurf/canon/canon.sqlite
+  --json           Emit an array of objects. Prefer this when parsing
+  -h, --help       Show this help
+
+Examples
+  canonui ls
+  canonui ls --json
+
+Then
+  canonui build retry-guide
+  canonui serve retry-guide
+  canon ls blocks --document retry-guide     what is inside one document
+`;
+var BUILD_HELP = `canonui build \u2014 render a document into a static site.
+
+Usage
+  canonui build <document> [options]
+
+Reads the document out of the database, reduces it to a JSON snapshot, and
+hands that to the bundled Astro theme, which writes HTML, CSS and \u2014 only where a
+block needs it \u2014 JavaScript. The result has no server requirement: open
+index.html, or point any static file server at the folder.
+
+Every block in the document is built. There is no draft state and nothing to
+mark first; what canon holds is what ships. A document with no blocks is
+refused, since there would be nothing on the page.
+
+The document may be left off when there is only one \u2014 it is named on stderr so
+there is no doubt which was picked. With more than one, the list is printed to
+choose from rather than a usage error.
+
+Options
+  --db <path>       Database file. Default $CANON_DB, else ~/.apisurf/canon/canon.sqlite
+  --out <dir>       Where to write the site. Default ./dist/<document-slug>
+  --base <path>     Sub-path the site will be served under, e.g. /docs
+  --site <url>      Canonical origin, for absolute URLs in the output
+  --snapshot <path> Keep the snapshot at this path instead of a temporary one
+  --snapshot-only   Write the snapshot and stop. No rendering, no Astro
+  --json            Print the result as an object
+  --verbose         Show Astro's own build output
+  -h, --help        Show this help
+
+Examples
+  canonui build retry-guide
+  canonui build retry-guide --out ./public
+  canonui build retry-guide --base /docs --site https://example.com
+  canonui build retry-guide --snapshot-only --snapshot ./doc.json
+
+Then
+  canonui serve retry-guide       look at it
+  canonui open ./public           look at a folder without rebuilding
+  canonui help sites              what the folder holds
+`;
+var SERVE_HELP = `canonui serve \u2014 build a document and serve it.
+
+Usage
+  canonui serve <document> [options]
+
+Builds the document, then serves the folder over HTTP from 127.0.0.1 and holds
+the terminal until Ctrl-C. Nothing is cached, so a rebuild in another shell
+shows up on the next refresh. The default browser opens on it once it is
+listening; --no-open skips that.
+
+Always builds. To serve a folder that already exists \u2014 output somebody else
+produced, or the thing you are about to upload \u2014 use canonui open, which takes a
+directory and never opens the database.
+
+Interactive: this command does not exit. To render a site programmatically use
+canonui build, which writes the folder and returns.
+
+There is no watcher. Content changes through canon, in another shell, and the way
+to see it is to rerun this \u2014 which is a second of build time and no state to
+lose.
+
+The document may be left off when there is only one. With more than one, the
+list is printed to choose from. canonui ls shows it at any time.
+
+Options
+  --db <path>      Database file. Default $CANON_DB, else ~/.apisurf/canon/canon.sqlite
+  --out <dir>      Folder to build into and serve. Default builds/<document-slug>
+                   beside the database, replaced on every run
+  --port <n>       Port to serve on. Default 3000. Without --port, the next free
+                   port up to 3020 is used instead of failing
+  --host <addr>    Interface to bind. Default 127.0.0.1 \u2014 loopback only
+  --base <path>    Sub-path the site is built for and served under, e.g. /docs
+  --verbose        Show Astro's own build output
+  --no-open        Don't open the browser
+  -h, --help       Show this help
+
+Examples
+  canonui serve retry-guide
+  canonui serve retry-guide --port 4000
+  canonui serve retry-guide --base /docs
+  canonui serve retry-guide --out ./public
+
+Then
+  canonui open ./public           the same folder, without rebuilding
+  canonui howto preview           the write-and-look loop
+`;
+var OPEN_HELP = `canonui open \u2014 serve a folder that is already built.
+
+Usage
+  canonui open [dir] [options]
+
+Serves a folder of static files over HTTP from 127.0.0.1 and holds the terminal
+until Ctrl-C. Nothing is built and the database is never opened, so this works
+on output somebody else produced, on a checkout with no content in it, and on
+the folder you are about to upload.
+
+The counterpart to canonui serve, which takes a document and always builds. This
+takes a directory, and that is the whole difference: one needs the content, the
+other needs only the files.
+
+With no directory it looks in ./dist, where builds land. One site there is not
+a choice worth asking about, so it is used and named; more than one prints the
+list.
+
+Options
+  --port <n>       Port to serve on. Default 3000. Without --port, the next free
+                   port up to 3020 is used instead of failing
+  --host <addr>    Interface to bind. Default 127.0.0.1 \u2014 loopback only
+  --base <path>    Sub-path the folder was built for, e.g. /docs. Mount it there
+  -h, --help       Show this help
+
+Examples
+  canonui open
+  canonui open ./public
+  canonui open ./dist/retry-guide --port 4000
+  canonui open ./public --base /docs
+
+A folder built with --base
+  Its links and its stylesheet all start with the prefix, so serving it at the
+  root 404s on everything. Pass the same --base and it is mounted there instead
+  \u2014 which is how to check a sub-path build before it goes anywhere.
+
+Then
+  canonui serve retry-guide       build first, then serve
+  canonui help sites              what the folder holds
+`;
+var SITES_HELP = `canonui sites \u2014 what a built site is, and what it needs.
+
+The folder
+  index.html          the document: its title, description and every block
+  index.md            the same document as markdown
+  404.html            served for anything else
+  _astro/             the stylesheet, and scripts only where a block needs one
+
+  No server behaviour, no build step of its own, no runtime configuration. Open
+  index.html from the filesystem, or hand the folder to any static host.
+
+The page
+  Blocks render top to bottom in the order canon ls blocks shows. Beside them a
+  contents rail lists the titled blocks and the headings inside markdown
+  blocks, and follows the reader down the page. The rail steps aside on a
+  narrow screen, or when the reader widens the page.
+
+  canon ls blocks --document retry-guide     the order, as it will build
+  canon mv block 12 --to 1
+
+Links
+  A markdown block's links pass through untouched. Each block and each heading
+  has an anchor, so a link to a section of the page is #<id>.
+
+Serving it under a sub-path
+  canonui build retry-guide --base /docs
+
+  Bakes the prefix into every internal href. A site built without it and then
+  served under /docs has a broken stylesheet, so this is a build-time decision
+  rather than a serving one. Pass the same --base to canonui serve.
+
+Absolute URLs
+  canonui build retry-guide --site https://example.com
+
+  Only needed for the things that cannot be relative \u2014 canonical tags and the
+  like.
+
+The markdown twin
+  /index.md is the document canon cat prints, with a contents list and
+  without the front matter. It is what the copy button under the title puts
+  on the clipboard, and what curl gets you without one.
+
+  The button fetches what it copies, so it wants the site served rather than
+  opened off the disk \u2014 canonui open is enough, and so is any host. Everything
+  else on the page works either way.
+
+Offline
+  A document holding a mermaid block loads mermaid from a copy bundled into the
+  site, not from a CDN, so the output works with no network. Only documents
+  that hold one pay for the library.
+
+A note on trust
+  html blocks pass through unsanitized and markdown is rendered with inline
+  HTML allowed, because the database is yours and the build runs on your
+  machine. Do not point canonui build at a database somebody else wrote.
+
+Then
+  canonui howto publish           putting the folder somewhere
+`;
+var SNAPSHOT_HELP = `canonui snapshot \u2014 the JSON seam, for another renderer.
+
+A build has two halves. The first reads the database and reduces one document
+to a snapshot: the document, and every block in order with its type, its title,
+its body and its attributes. The second reads that snapshot and writes the
+site, and never opens SQLite at all.
+
+Normally the seam is invisible \u2014 the snapshot goes to a temporary file and is
+deleted when the build succeeds. Two flags expose it:
+
+  canonui build retry-guide --snapshot ./doc.json
+      Render as usual, and keep the snapshot.
+
+  canonui build retry-guide --snapshot-only --snapshot ./doc.json
+      Write the snapshot and stop. Nothing is rendered and Astro never runs.
+
+The shape
+  {
+    "version": 7,
+    "generatedAt": <epoch ms>,
+    "document": { uid, slug, title, description, createdAt, updatedAt },
+    "blocks": [ { uid, seq, type, title, content, attrs }, ... ]
+  }
+
+What it is for
+  Rendering with something that is not this theme. The snapshot is a plain
+  document with a version field on it, so a renderer can refuse a shape it does
+  not know rather than guess at one.
+
+  It is also what a failed build leaves behind \u2014 the exact input, at the path
+  the error names.
+
+What it is not
+  A backup, and not an export format. The database is the record, and it is one
+  file you can copy. For the content as prose rather than as data, canon cat gives
+  you one markdown document, and a built site serves the same one at /index.md.
+
+Then
+  canon help cat                  the content, as markdown
+  canonui howto snapshot          rendering it elsewhere
+`;
+var COMMAND_HELP = {
+  build: BUILD_HELP,
+  howto: HOWTO_INDEX,
+  ls: LS_HELP,
+  open: OPEN_HELP,
+  serve: SERVE_HELP,
+  sites: SITES_HELP,
+  snapshot: SNAPSHOT_HELP
+};
+function usageLines(command) {
+  const page = COMMAND_HELP[command];
+  if (!page) return [];
+  const lines = page.split("\n");
+  const start = lines.indexOf("Usage");
+  if (start === -1) return [];
+  const out = [];
+  for (const line of lines.slice(start + 1)) {
+    if (line.trim() === "") break;
+    out.push(line);
+  }
+  return out;
+}
+var COMMANDS = ["ls", "build", "serve", "open", "howto"];
+var HELP_TOPICS = ["sites", "snapshot"];
+
+// src/list.ts
+function list(options) {
+  const entity = options.entity ?? "documents";
+  if (entity !== "documents") {
+    process.stderr.write(
+      `canonui: there is nothing called "${entity}" to list. Try documents.
+
+  canonui ls
+
+Blocks are the level canonui never addresses on its own \u2014 canon ls blocks.
+`
+    );
+    return 1;
+  }
+  const db = openRead(options);
+  if (!db) return 1;
+  try {
+    return listDocuments(db, options);
+  } catch (err) {
+    if (err instanceof StoreError) {
+      process.stderr.write(`canonui: ${describeStoreError(err)}`);
+      return 1;
+    }
+    throw err;
+  } finally {
+    db.close();
+  }
+}
+function listDocuments(db, options) {
+  const rows = documentRows(db);
+  if (options.json) {
+    process.stdout.write(`${renderJson(rows)}
+`);
+    return 0;
+  }
+  if (rows.length === 0) {
+    process.stdout.write(
+      '\n  no documents yet\n\n  Content is created with canon:\n\n    canon new document "Retry Guide"\n\n'
+    );
+    return 0;
+  }
+  const grid = rows.map((r, i) => [
+    String(rows.length - i),
+    isoDateTime(Number(r.created_at)),
+    String(r.slug),
+    plural(Number(r.block_count), "block")
+  ]);
+  process.stdout.write(
+    `
+  ${plural(rows.length, "document")}
+
+${columns(grid, [0]).map((line) => `  ${line}`).join("\n")}
+
+  Newest first, by the date each document was created.
+
+  Build one:  canonui build <slug>
+
+`
+  );
+  return 0;
+}
+function documentRows(db) {
+  const entity = findEntity("documents");
+  if (!entity) throw new Error("canonui: the documents entity is missing from @canon/db");
+  return selectEntity(db, entity, {
+    fields: ["slug", "title", "block_count", "created_at", "updated_at"]
+  });
+}
+function resolveDocument(options, command) {
+  const db = openRead(options);
+  if (!db) return null;
+  try {
+    const rows = documentRows(db);
+    if (rows.length === 1) {
+      const only = String(rows[0]?.slug);
+      process.stderr.write(`canonui: the only document is ${only}
+`);
+      return only;
+    }
+    if (rows.length === 0) {
+      process.stderr.write(
+        `canonui: there are no documents to ${command}
+
+  canon new document "Retry Guide"
+
+Content is written with canon; canonui renders it.
+`
+      );
+      return null;
+    }
+    const grid = rows.map((r) => [
+      String(r.slug),
+      String(r.title),
+      plural(Number(r.block_count), "block")
+    ]);
+    const usage = usageLines(command);
+    process.stderr.write(
+      `canonui: there are ${rows.length} documents \u2014 name the one to ${command}
+
+${columns(grid).map((line) => `  ${line}`).join("\n")}
+` + (usage.length > 0 ? `
+Usage
+${usage.join("\n")}
+` : "") + `
+Run canonui help ${command} for everything ${command} takes.
+`
+    );
+    return null;
+  } finally {
+    db.close();
+  }
+}
+
+// src/open.ts
+import { existsSync as existsSync3, readdirSync, statSync as statSync2 } from "node:fs";
+import { isAbsolute as isAbsolute3, join as join3, relative, resolve as resolve5 } from "node:path";
+
+// src/http.ts
+import { spawn as spawn2 } from "node:child_process";
+import { createReadStream, existsSync as existsSync2, statSync } from "node:fs";
+import { createServer as createHttpServer } from "node:http";
+import { createServer as createSocketServer } from "node:net";
+import { extname, join as join2, normalize, resolve as resolve4, sep } from "node:path";
+var DEFAULT_HOST = "127.0.0.1";
+var DEFAULT_PORT = 3e3;
+var PORT_SCAN = 20;
+var CONTENT_TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".txt": "text/plain; charset=utf-8",
+  ".md": "text/markdown; charset=utf-8",
+  ".xml": "application/xml",
+  ".pdf": "application/pdf"
+};
+function contentType(file) {
+  return CONTENT_TYPES[extname(file).toLowerCase()] ?? "application/octet-stream";
+}
+async function serveDirectory(options) {
+  const { root } = options;
+  const base = normalizeBase(options.base);
+  const host = options.host ?? DEFAULT_HOST;
+  const wanted = options.port ?? DEFAULT_PORT;
+  const listening = await freePort(host, wanted, options.port === void 0 ? PORT_SCAN : 0);
+  if (listening === null) {
+    process.stderr.write(
+      options.port === void 0 ? `canonui: ports ${wanted}-${wanted + PORT_SCAN} are all in use. Pass --port <n> to pick one.
+` : `canonui: port ${wanted} is already in use.
+`
+    );
+    return 1;
+  }
+  const server = createHttpServer((req, res) => {
+    const requested = pathOf(req.url ?? "/");
+    if (requested === null) {
+      notFound(root, res);
+      return;
+    }
+    if (base && (requested === "/" || requested === base)) {
+      res.writeHead(302, { location: `${base}/` });
+      res.end();
+      return;
+    }
+    const unprefixed = unmount(requested, base);
+    const target = unprefixed === null ? null : resolveRequest(root, unprefixed);
+    if (!target) {
+      notFound(root, res);
+      return;
+    }
+    const stats = statSync(target);
+    res.writeHead(200, {
+      "content-type": contentType(target),
+      "content-length": stats.size,
+      // A preview that caches is a preview that lies after the next build.
+      "cache-control": "no-store"
+    });
+    if (req.method === "HEAD") {
+      res.end();
+      return;
+    }
+    createReadStream(target).pipe(res);
+  });
+  await new Promise((done) => server.listen(listening, host, done));
+  process.stdout.write(
+    `
+  canonui ${options.command}
+
+  open       http://${host}:${listening}${base}/
+  serving    ${root}
+
+  Ctrl-C to stop.
+
+`
+  );
+  if (options.launch) launchBrowser(`http://${browsable(host)}:${listening}${base}/`);
+  return new Promise(() => {
+  });
+}
+function browsable(host) {
+  return host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
+}
+function launchBrowser(url) {
+  const [cmd, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+  try {
+    const child = spawn2(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
+}
+function normalizeBase(base) {
+  if (!base) return "";
+  const trimmed = base.replace(/^\/+|\/+$/g, "");
+  return trimmed ? `/${trimmed}` : "";
+}
+function pathOf(url) {
+  try {
+    return decodeURIComponent(new URL(url, "http://localhost").pathname);
+  } catch {
+    return null;
+  }
+}
+function unmount(pathname, base) {
+  if (!base) return pathname;
+  if (!pathname.startsWith(`${base}/`)) return null;
+  return pathname.slice(base.length);
+}
+function resolveRequest(root, pathname) {
+  const target = resolve4(root, `.${normalize(pathname)}`);
+  if (target !== root && !target.startsWith(root + sep)) return null;
+  const candidates = [target, join2(target, "index.html"), `${target}.html`];
+  for (const candidate of candidates) {
+    if (existsSync2(candidate) && statSync(candidate).isFile()) return candidate;
+  }
+  return null;
+}
+function notFound(root, res) {
+  const page = join2(root, "404.html");
+  if (existsSync2(page)) {
+    res.writeHead(404, { "content-type": CONTENT_TYPES[".html"] });
+    createReadStream(page).pipe(res);
+    return;
+  }
+  res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+  res.end("404 Not Found\n");
+}
+async function freePort(host, from, span) {
+  for (let candidate = from; candidate <= from + span; candidate++) {
+    if (await available(host, candidate)) return candidate;
+  }
+  return null;
+}
+function available(host, candidate) {
+  return new Promise((done) => {
+    const probe = createSocketServer();
+    probe.once("error", () => done(false));
+    probe.listen(candidate, host, () => probe.close(() => done(true)));
+  });
+}
+
+// src/open.ts
+var DEFAULT_ROOT = "dist";
+async function open(options) {
+  const root = resolveRoot(options);
+  if (root === null) return 1;
+  return serveDirectory({
+    root,
+    command: "open",
+    ...options.host !== void 0 ? { host: options.host } : {},
+    ...options.port !== void 0 ? { port: options.port } : {},
+    ...options.base !== void 0 ? { base: options.base } : {}
+  });
+}
+function resolveRoot(options) {
+  return options.dir === void 0 ? discover(options.cwd) : named(options.dir, options.cwd);
+}
+function named(dir, cwd) {
+  const root = isAbsolute3(dir) ? dir : resolve5(cwd, dir);
+  if (!existsSync3(root)) {
+    process.stderr.write(
+      `canonui: there is no folder at ${root}
+
+  canonui build <document> --out ${dir}
+`
+    );
+    return null;
+  }
+  if (!isSite(root)) {
+    process.stderr.write(
+      `canonui: ${root} has no index.html, so there is no site in it
+
+  canonui build <document> --out ${dir}
+
+open serves a folder that is already built; canonui serve builds one first.
+`
+    );
+    return null;
+  }
+  return root;
+}
+function discover(cwd) {
+  const dist = resolve5(cwd, DEFAULT_ROOT);
+  if (!existsSync3(dist)) {
+    process.stderr.write(
+      `canonui: nothing to open \u2014 there is no ${DEFAULT_ROOT}/ here
+
+  canonui build <document>
+
+Or name a folder:  canonui open ./public
+`
+    );
+    return null;
+  }
+  if (isSite(dist)) return dist;
+  const sites = readdirSync(dist).map((entry) => join3(dist, entry)).filter((path) => statSync2(path).isDirectory() && isSite(path));
+  if (sites.length === 1) {
+    const only = sites[0];
+    process.stderr.write(`canonui: the only site under ${DEFAULT_ROOT}/ is ${here(cwd, only)}
+`);
+    return only;
+  }
+  if (sites.length === 0) {
+    process.stderr.write(`canonui: ${dist} holds no built site
+
+  canonui build <document>
+`);
+    return null;
+  }
+  process.stderr.write(
+    `canonui: there are ${sites.length} built sites under ${DEFAULT_ROOT}/ \u2014 name one
+
+${sites.map((path) => `  canonui open ${here(cwd, path)}`).join("\n")}
+`
+  );
+  return null;
+}
+function here(cwd, path) {
+  const short = relative(cwd, path);
+  return short && !short.startsWith("..") ? short : path;
+}
+function isSite(root) {
+  return existsSync3(join3(root, "index.html"));
+}
+
+// src/serve.ts
+async function serve(options) {
+  const { code, out: root } = await buildSite({
+    document: options.document,
+    cwd: options.cwd,
+    ...options.db !== void 0 ? { db: options.db } : {},
+    ...options.out !== void 0 ? { out: options.out } : { global: true },
+    ...options.base !== void 0 ? { base: options.base } : {},
+    ...options.verbose ? { verbose: true } : {},
+    serving: true
+  });
+  if (code !== 0) return code;
+  return serveDirectory({
+    root,
+    command: "serve",
+    launch: !options.noOpen,
+    ...options.host !== void 0 ? { host: options.host } : {},
+    ...options.port !== void 0 ? { port: options.port } : {},
+    ...options.base !== void 0 ? { base: options.base } : {}
+  });
+}
+
+// src/version.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+function readPackageVersion() {
+  try {
+    const manifest = readFileSync2(new URL("../package.json", import.meta.url), "utf8");
+    const parsed = JSON.parse(manifest);
+    return typeof parsed.version === "string" ? parsed.version : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+function versionInfo() {
+  return {
+    version: readPackageVersion(),
+    schema: SCHEMA_VERSION,
+    node: process.versions.node
+  };
+}
+function formatVersion(info) {
+  return `canonui ${info.version} (schema ${info.schema}, node v${info.node})`;
+}
+
+// src/bin.ts
+var GLOBAL = {
+  db: { type: "string" },
+  help: { type: "boolean", short: "h" }
+};
+var CANON_COMMANDS = ["new", "get", "cat", "find", "set", "rm", "mv"];
+async function main(argv) {
+  const [command, ...rest] = argv;
+  if (!command) {
+    process.stdout.write(ROOT_HELP);
+    return 1;
+  }
+  if (command === "-v" || command === "--version" || command === "version") {
+    const info = versionInfo();
+    process.stdout.write(
+      rest.includes("--json") ? `${JSON.stringify(info, null, 2)}
+` : `${formatVersion(info)}
+`
+    );
+    return 0;
+  }
+  if (command === "-h" || command === "--help" || command === "help") {
+    const topic = rest[0];
+    if (topic && COMMAND_HELP[topic]) {
+      process.stdout.write(COMMAND_HELP[topic]);
+      return 0;
+    }
+    if (topic) {
+      process.stderr.write(
+        `canonui: no help for "${topic}". Commands: ${COMMANDS.join(", ")}
+Topics: ${HELP_TOPICS.join(", ")}
+Worked examples: canonui howto
+`
+      );
+      return 1;
+    }
+    process.stdout.write(ROOT_HELP);
+    return 0;
+  }
+  switch (command) {
+    case "ls":
+      return runList(rest);
+    case "build":
+      return runBuild(rest);
+    case "serve":
+      return runServe(rest);
+    case "open":
+      return runOpen(rest);
+    case "howto":
+      return runHowto(rest);
+    default:
+      if (CANON_COMMANDS.includes(command)) {
+        process.stderr.write(
+          `canonui: "${command}" is a canon command \u2014 canonui renders content, canon writes it.
+
+  canon ${[command, ...rest].join(" ")}
+
+Run canon help ${command} for what it takes.
+`
+        );
+        return 1;
+      }
+      process.stderr.write(
+        `canonui: unknown command "${command}". Commands: ${[...COMMANDS, "help"].join(", ")}
+Run canonui --help
+`
+      );
+      return 1;
+  }
+}
+function runHowto(argv) {
+  const [name] = argv;
+  if (!name || name === "-h" || name === "--help") {
+    process.stdout.write(HOWTO_INDEX);
+    return 0;
+  }
+  const page = howtoPage(name);
+  if (!page) {
+    process.stderr.write(
+      `canonui: no worked example called "${name}". There is one for: ${HOWTO_NAMES.join(", ")}
+Run canonui howto for what each covers.
+`
+    );
+    return 1;
+  }
+  process.stdout.write(page);
+  return 0;
+}
+function runList(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: { ...GLOBAL, json: { type: "boolean" } }
+    });
+  } catch (err) {
+    return usageError(err, "ls");
+  }
+  if (parsed.values.help) {
+    process.stdout.write(COMMAND_HELP.ls ?? ROOT_HELP);
+    return 0;
+  }
+  const [entity] = parsed.positionals;
+  return list({
+    cwd: process.cwd(),
+    ...entity !== void 0 ? { entity } : {},
+    ...pick(parsed.values, ["db", "json"])
+  });
+}
+async function runBuild(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        ...GLOBAL,
+        out: { type: "string" },
+        base: { type: "string" },
+        site: { type: "string" },
+        snapshot: { type: "string" },
+        "snapshot-only": { type: "boolean" },
+        json: { type: "boolean" },
+        verbose: { type: "boolean" }
+      }
+    });
+  } catch (err) {
+    return usageError(err, "build");
+  }
+  if (parsed.values.help) {
+    process.stdout.write(COMMAND_HELP.build ?? ROOT_HELP);
+    return 0;
+  }
+  const document = parsed.positionals[0] ?? resolveDocument(dbOf(parsed.values), "build");
+  if (!document) return 1;
+  return build({
+    document,
+    cwd: process.cwd(),
+    ...pick(parsed.values, ["db", "out", "base", "site", "snapshot", "json", "verbose"]),
+    ...parsed.values["snapshot-only"] ? { snapshotOnly: true } : {}
+  });
+}
+async function runServe(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        ...GLOBAL,
+        out: { type: "string" },
+        port: { type: "string" },
+        host: { type: "string" },
+        base: { type: "string" },
+        "no-build": { type: "boolean" },
+        verbose: { type: "boolean" },
+        "no-open": { type: "boolean" }
+      }
+    });
+  } catch (err) {
+    return usageError(err, "serve");
+  }
+  if (parsed.values.help) {
+    process.stdout.write(COMMAND_HELP.serve ?? ROOT_HELP);
+    return 0;
+  }
+  if (parsed.values["no-build"]) {
+    const dir = parsed.values.out ?? "./dist/<document>";
+    process.stderr.write(
+      `canonui: --no-build is now canonui open, which takes a folder instead of a document.
+
+  canonui open ${dir}
+
+Run canonui help open for what it takes.
+`
+    );
+    return 1;
+  }
+  const document = parsed.positionals[0] ?? resolveDocument(dbOf(parsed.values), "serve");
+  if (!document) return 1;
+  const port = numeric(parsed.values.port, "--port");
+  if (port === null) return 1;
+  if (port !== void 0 && (!Number.isInteger(port) || port < 1 || port > 65535)) {
+    process.stderr.write(`canonui: --port expects a number between 1 and 65535 (got "${port}")
+`);
+    return 1;
+  }
+  return serve({
+    document,
+    cwd: process.cwd(),
+    ...pick(parsed.values, ["db", "out", "host", "base", "verbose", "no-open"]),
+    ...port !== void 0 ? { port } : {}
+  });
+}
+async function runOpen(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        help: { type: "boolean", short: "h" },
+        port: { type: "string" },
+        host: { type: "string" },
+        base: { type: "string" }
+      }
+    });
+  } catch (err) {
+    return usageError(err, "open");
+  }
+  if (parsed.values.help) {
+    process.stdout.write(COMMAND_HELP.open ?? ROOT_HELP);
+    return 0;
+  }
+  const port = numeric(parsed.values.port, "--port");
+  if (port === null) return 1;
+  if (port !== void 0 && (!Number.isInteger(port) || port < 1 || port > 65535)) {
+    process.stderr.write(`canonui: --port expects a number between 1 and 65535 (got "${port}")
+`);
+    return 1;
+  }
+  const dir = parsed.positionals[0];
+  return open({
+    cwd: process.cwd(),
+    ...dir !== void 0 ? { dir } : {},
+    ...pick(parsed.values, ["host", "base"]),
+    ...port !== void 0 ? { port } : {}
+  });
+}
+function dbOf(values) {
+  return { cwd: process.cwd(), ...values.db !== void 0 ? { db: values.db } : {} };
+}
+function pick(values, keys) {
+  const out = {};
+  for (const key of keys) {
+    const value = values[key];
+    if (value !== void 0) out[camel(key)] = value;
+  }
+  return out;
+}
+var camel = (flag) => flag.replace(/-(\w)/g, (_, c) => c.toUpperCase());
+function numeric(raw, flag) {
+  if (raw === void 0) return void 0;
+  const value = Number(raw);
+  if (Number.isNaN(value)) {
+    process.stderr.write(`canonui: ${flag} expects a number (got "${raw}")
+`);
+    return null;
+  }
+  return value;
+}
+function usageError(err, command) {
+  process.stderr.write(
+    `canonui: ${err instanceof Error ? err.message : String(err)}
+Run canonui help ${command} for the options ${command} takes.
+`
+  );
+  return 1;
+}
+main(process.argv.slice(2)).then((code) => {
+  process.exitCode = code;
+}).catch((err) => {
+  process.stderr.write(
+    `canonui: ${err instanceof Error ? err.stack ?? err.message : String(err)}
+`
+  );
+  process.exitCode = 1;
+});
+//# sourceMappingURL=bin.js.map