@taprootio/site-authoring 0.1.0

package/src/footer-draft-hash.js

@@ -0,0 +1,203 @@
+import { createHash } from "node:crypto";
+
+import { SiteAuthoringError } from "./errors.js";
+import { FOOTER_COLOR_TOKENS } from "./theme-validation.js";
+
+// The ten scheme colors theme push owns — light/dark times the color-token
+// registry — so a new footer color changes one executable registry, not a
+// hand-copied list. Every other footer field is footer-push content.
+const THEME_OWNED_SCHEME_COLORS = Object.freeze(Object.keys(FOOTER_COLOR_TOKENS));
+
+// Matches the package's document-depth convention (CONTENT_LIMITS.documentDepth):
+// the baseline hashes raw hand-editable JSON, and unbounded nesting would
+// otherwise exhaust the stack into an undiagnosable generic failure.
+const MAXIMUM_CONTENT_DEPTH = 64;
+
+/**
+ * The pull baseline over everything `footer push` owns: a stable, type- and
+ * shape-preserving JSON hash of the raw footer document with exactly the ten
+ * scheme colors `theme push` overlays removed. The draft hash's canonical
+ * form deliberately normalizes types and shapes the way the server does, so
+ * it cannot see a hand-edit such as `enabled: "true"` or `bottomLinks: {}`;
+ * this baseline must, because `theme push` would otherwise silently discard
+ * that edit. Formatting-only differences — whitespace, key order — still
+ * hash identically. This hash is CLI-local workspace bookkeeping, not a
+ * server concurrency token.
+ */
+export function computeFooterContentHash(settings = {}) {
+  requireBoundedDepth(settings);
+  let content = settings;
+  if (isContentObject(settings)) {
+    content = structuredClone(settings);
+    for (const scheme of ["light", "dark"]) {
+      if (isContentObject(content[scheme])) {
+        for (const color of THEME_OWNED_SCHEME_COLORS) delete content[scheme][color];
+      }
+    }
+  }
+  return createHash("sha256").update(`footer-content-v2${stableJson(content)}`, "utf8").digest("hex");
+}
+
+function isContentObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+// Iterative breadth-first walk: bounds both the structuredClone and the
+// stableJson recursion below without itself being recursive.
+function requireBoundedDepth(value) {
+  let frontier = [value];
+  for (let depth = 0; frontier.length > 0; depth += 1) {
+    if (depth > MAXIMUM_CONTENT_DEPTH) {
+      throw new SiteAuthoringError(
+        "footer.document_too_deep",
+        `settings/site-publishing-preferences.json nests JSON deeper than ${MAXIMUM_CONTENT_DEPTH} levels. `
+          + "Flatten the footer document before pushing.",
+        { field: "settings/site-publishing-preferences.json" },
+      );
+    }
+    const next = [];
+    for (const entry of frontier) {
+      if (entry === null || typeof entry !== "object") continue;
+      const children = Array.isArray(entry) ? entry : Object.values(entry);
+      for (const child of children) next.push(child);
+    }
+    frontier = next;
+  }
+}
+
+/** Deterministic JSON: sorted object keys, JSON.stringify value semantics. */
+function stableJson(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value) ?? "null";
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => stableJson(entry === undefined ? null : entry)).join(",")}]`;
+  }
+  return `{${
+    Object.keys(value)
+      .sort()
+      .filter((key) => value[key] !== undefined)
+      .map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`)
+      .join(",")
+  }}`;
+}
+
+// Byte-for-byte port of FooterDraftConcurrency.ComputeHash. The token protects
+// the whole footer document while theme push overlays only its ten scheme color
+// fields onto a fresh read. Response-only image URLs deliberately do not enter
+// the canonical form.
+export function computeFooterDraftHash(settings = {}) {
+  const canonical = [];
+  append(canonical, "footer-draft-v3");
+  append(canonical, settings.enabled === true);
+  append(canonical, settings.showBrand ?? true);
+  append(canonical, settings.showBrandText ?? true);
+
+  const columns = Array.isArray(settings.linkColumns) ? settings.linkColumns : [];
+  append(canonical, columns.length);
+  for (const column of columns) {
+    append(canonical, normalizeId(column?.id));
+    const groups = Array.isArray(column?.groups) ? column.groups : [];
+    append(canonical, groups.length);
+    for (const group of groups) {
+      append(canonical, normalizeId(group?.id));
+      append(canonical, group?.heading ?? "");
+      appendLinks(canonical, group?.links);
+    }
+  }
+
+  appendRichText(canonical, settings.asideHeadingContent);
+  appendRichText(canonical, settings.asideBodyContent);
+  const hasAsideCta = settings.asideCta !== undefined && settings.asideCta !== null;
+  append(canonical, hasAsideCta);
+  if (hasAsideCta) appendLink(canonical, settings.asideCta);
+  appendRichText(canonical, settings.bottomContent);
+  appendLinks(canonical, settings.bottomLinks);
+  appendScheme(canonical, settings.light);
+  appendScheme(canonical, settings.dark);
+
+  const hasFeatureImage = settings.featureImage !== undefined && settings.featureImage !== null;
+  append(canonical, hasFeatureImage);
+  if (hasFeatureImage) {
+    append(canonical, normalizeId(settings.featureImage.imageId));
+    append(canonical, settings.featureImage.alt ?? "");
+  }
+
+  return createHash("sha256").update(canonical.join(""), "utf8").digest("hex");
+}
+
+function appendLinks(canonical, rawLinks) {
+  const links = Array.isArray(rawLinks) ? rawLinks : [];
+  append(canonical, links.length);
+  for (const link of links) appendLink(canonical, link);
+}
+
+// Coalesce rather than default so the canonical form stays total even for a
+// null entry: a parameter default covers only undefined.
+function appendLink(canonical, rawLink) {
+  const link = rawLink ?? {};
+  append(canonical, normalizeId(link.id));
+  append(canonical, link.label ?? "");
+  appendTarget(canonical, link);
+}
+
+function appendTarget(canonical, link = {}) {
+  const external = Object.hasOwn(link, "externalUrl");
+  append(canonical, external ? 2 : 1);
+  append(canonical, external ? "" : normalizeId(link.pageResourceId));
+  append(canonical, external ? link.externalUrl ?? "" : "");
+}
+
+function appendRichText(canonical, richText) {
+  const paragraphs = Array.isArray(richText?.paragraphs) ? richText.paragraphs : [];
+  append(canonical, paragraphs.length);
+  for (const paragraph of paragraphs) {
+    const runs = Array.isArray(paragraph?.runs) ? paragraph.runs : [];
+    append(canonical, runs.length);
+    for (const run of runs) {
+      append(canonical, run?.text ?? "");
+      append(canonical, run?.bold === true);
+      append(canonical, run?.italic === true);
+      append(canonical, run?.underline === true);
+      const hasLink = run?.link !== undefined && run.link !== null;
+      append(canonical, hasLink);
+      if (hasLink) appendTarget(canonical, run.link);
+    }
+  }
+}
+
+function appendScheme(canonical, rawScheme) {
+  const scheme = rawScheme ?? {};
+  append(canonical, scheme.backgroundColor ?? "");
+  append(canonical, scheme.textColor ?? "");
+  append(canonical, scheme.headingColor ?? "");
+  append(canonical, scheme.linkColor ?? "");
+  append(canonical, scheme.linkHoverColor ?? "");
+  append(canonical, normalizeId(scheme.backgroundImageId));
+  append(canonical, doubleBits(scheme.backgroundImageOpacity ?? 1));
+  append(canonical, presentationValue(scheme.backgroundPresentation));
+  append(canonical, scheme.backgroundFade === "FOOTER_FADE_MODE_BOTTOM" ? 1 : 0);
+  append(canonical, scheme.backgroundRepeatHeightPx || 160);
+  append(canonical, doubleBits(scheme.additionalTopPaddingRem ?? 0));
+}
+
+function presentationValue(value) {
+  if (value === "FOOTER_BACKGROUND_PRESENTATION_REPEAT_X") return 1;
+  if (value === "FOOTER_BACKGROUND_PRESENTATION_COVER") return 2;
+  return 0;
+}
+
+function doubleBits(value) {
+  const buffer = new ArrayBuffer(8);
+  new DataView(buffer).setFloat64(0, value === 0 ? 0 : value, false);
+  return Array.from(new Uint8Array(buffer), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+function normalizeId(value) {
+  return typeof value === "string" ? value.toLowerCase() : "";
+}
+
+function append(canonical, value) {
+  const token = typeof value === "boolean" ? (value ? "1" : "0") : String(value);
+  canonical.push(`${token.length}:${token}`);
+}

package/src/footer-workspace.js

@@ -0,0 +1,136 @@
+import { isCanonicalUuid, SiteAuthoringError } from "./errors.js";
+import { appearanceImageIds } from "./appearance-contract.js";
+import { footerImageIds } from "./footer-contract.js";
+import { computeFooterContentHash, computeFooterDraftHash } from "./footer-draft-hash.js";
+import { readManifest, readMediaManifest, writeManifest } from "./workspace.js";
+
+export const FOOTER_SETTINGS_FILE = "settings/site-publishing-preferences.json";
+const SHA256 = /^[0-9a-f]{64}$/u;
+
+function invalid(message, field) {
+  throw new SiteAuthoringError("footer.pull_required", message, { field });
+}
+
+function requireFooterMetadata(manifest) {
+  const footer = manifest.footer;
+  if (footer === null || typeof footer !== "object" || Array.isArray(footer)) {
+    invalid("The pull manifest does not record a footer baseline. Run 'taproot-site pull' again.", "footer");
+  }
+  if (footer.file !== FOOTER_SETTINGS_FILE || !SHA256.test(footer.expectedDraftHash ?? "")) {
+    invalid(
+      "The pull manifest has an invalid footer concurrency baseline. Run 'taproot-site pull' again.",
+      "footer.expectedDraftHash",
+    );
+  }
+  if (!Array.isArray(footer.imageIds) || footer.imageIds.some((id) => !isCanonicalUuid(id))) {
+    invalid("The pull manifest has invalid footer image identities. Run 'taproot-site pull' again.", "footer.imageIds");
+  }
+  return footer;
+}
+
+function requireAppearanceMetadata(manifest, { required = true, code = "theme.pull_required" } = {}) {
+  const appearance = manifest.appearance;
+  if (appearance === undefined && !required) return undefined;
+  if (appearance === null || typeof appearance !== "object" || Array.isArray(appearance)) {
+    throw new SiteAuthoringError(
+      code,
+      "The pull manifest does not record an appearance image baseline. Run 'taproot-site pull' again.",
+      { field: "appearance" },
+    );
+  }
+  if (!Array.isArray(appearance.imageIds) || appearance.imageIds.some((id) => !isCanonicalUuid(id))) {
+    throw new SiteAuthoringError(
+      code,
+      "The pull manifest has invalid appearance image identities. Run 'taproot-site pull' again.",
+      { field: "appearance.imageIds" },
+    );
+  }
+  return appearance;
+}
+
+export async function readFooterWorkspaceContext(workspaceDir, siteId) {
+  const manifest = await readManifest(workspaceDir, siteId);
+  const footer = requireFooterMetadata(manifest);
+  const mediaManifest = await readMediaManifest(workspaceDir, siteId);
+  const knownPageResourceIds = new Set(
+    manifest.pages.map((page) => page?.resourceId).filter((id) => isCanonicalUuid(id)),
+  );
+  const appearance = requireAppearanceMetadata(manifest, { required: false, code: "footer.pull_required" });
+  const knownImageIds = new Set([...footer.imageIds, ...(appearance?.imageIds ?? [])]);
+  for (const value of Object.values(mediaManifest.media)) {
+    if (isCanonicalUuid(value?.imageId)) knownImageIds.add(value.imageId);
+  }
+  return { manifest, footer, knownPageResourceIds, knownImageIds };
+}
+
+export async function readAppearanceWorkspaceContext(workspaceDir, siteId) {
+  const context = await readFooterWorkspaceContext(workspaceDir, siteId);
+  const appearance = requireAppearanceMetadata(context.manifest);
+  return {
+    ...context,
+    appearance,
+    knownImageIds: new Set([...context.knownImageIds, ...appearance.imageIds]),
+  };
+}
+
+export async function advanceFooterManifest(workspaceDir, siteId, footerSettings, expectedDraftHash) {
+  const manifest = await readManifest(workspaceDir, siteId);
+  const prior = requireFooterMetadata(manifest);
+  const hash = expectedDraftHash ?? computeFooterDraftHash(footerSettings);
+  if (!SHA256.test(hash)) {
+    throw new SiteAuthoringError(
+      "api.footer_settings_contract",
+      "Taproot returned a footer document whose draft hash could not be recorded.",
+      { field: "footerDraftHash" },
+    );
+  }
+  manifest.footer = {
+    file: FOOTER_SETTINGS_FILE,
+    expectedDraftHash: hash,
+    expectedContentHash: computeFooterContentHash(footerSettings),
+    imageIds: [...new Set([...prior.imageIds, ...footerImageIds(footerSettings)])].sort(),
+  };
+  await writeManifest(workspaceDir, manifest);
+  return hash;
+}
+
+export function footerManifestEntry(footerSettings) {
+  return {
+    file: FOOTER_SETTINGS_FILE,
+    expectedDraftHash: computeFooterDraftHash(footerSettings),
+    expectedContentHash: computeFooterContentHash(footerSettings),
+    imageIds: footerImageIds(footerSettings),
+  };
+}
+
+/**
+ * `theme push` begins with a fresh server read that replaces the workspace
+ * footer document, so an unpushed footer-content edit would be silently lost.
+ * Refuse while the workspace footer's content hash differs from the recorded
+ * pull baseline. The ten scheme colors `theme push` overlays are excluded
+ * from the comparison, so a colour-only edit passes. A manifest that predates
+ * the baseline cannot prove the workspace is clean and refuses toward pull:
+ * assuming "unchanged" is exactly the data loss this guard exists to stop.
+ */
+export function requireFooterContentPushed(footer, workspaceFooterSettings) {
+  if (!SHA256.test(footer.expectedContentHash ?? "")) {
+    throw new SiteAuthoringError(
+      "theme.pull_required",
+      "The pull manifest predates the footer-content baseline. Run 'taproot-site footer push' to save the local "
+        + "footer and record it, or 'taproot-site pull' to discard local edits and re-record it, then retry 'theme push'.",
+      { field: "footer.expectedContentHash" },
+    );
+  }
+  if (computeFooterContentHash(workspaceFooterSettings) !== footer.expectedContentHash) {
+    throw new SiteAuthoringError(
+      "theme.unpushed_footer_content",
+      `${FOOTER_SETTINGS_FILE} carries footer-content edits that 'theme push' would overwrite with the server's copy. `
+        + "Run 'taproot-site footer push' to save them first, or 'taproot-site pull' to discard them.",
+      { field: FOOTER_SETTINGS_FILE },
+    );
+  }
+}
+
+export function appearanceManifestEntry(documents) {
+  return { imageIds: appearanceImageIds(documents) };
+}

package/src/image-metadata.js

@@ -0,0 +1,169 @@
+import { createHash } from "node:crypto";
+
+import { SiteAuthoringError } from "./errors.js";
+
+/**
+ * Content hashing and pixel-dimension sniffing for `media upload`.
+ *
+ * `RequestImageUpload` wants the SHA-256 (for the dedup short-circuit) and the
+ * width and height before a single byte is uploaded, and the repo's zero
+ * runtime dependency rule means the client reads them out of the container
+ * header itself. The sniffer is deliberately a *header* reader: it inspects a
+ * fixed, bounded prefix of each container and never walks pixel data, so a
+ * hostile file cannot turn dimension discovery into a decode.
+ *
+ * Only the four raster containers the image service accepts are recognized.
+ * Everything else — SVG above all, which is a script-execution surface, not a
+ * raster — is refused with a stable code rather than uploaded and discovered
+ * server-side.
+ */
+
+export const IMAGE_CONTENT_TYPES = Object.freeze({
+  png: "image/png",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+});
+
+// One JPEG can carry a long run of metadata segments before its frame header.
+// The scan is bounded so a crafted file cannot spin here.
+const MAXIMUM_JPEG_SEGMENTS = 256;
+const MAXIMUM_DIMENSION = 65_535;
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const JPEG_SOI = Buffer.from([0xff, 0xd8]);
+
+function unsupportedFormat(fileName) {
+  return new SiteAuthoringError(
+    "media.unsupported_format",
+    `'${fileName}' is not a PNG, JPEG, GIF, or WebP image. Taproot accepts raster uploads only.`,
+    { field: fileName },
+  );
+}
+
+function unreadableDimensions(fileName) {
+  return new SiteAuthoringError(
+    "media.dimensions_unreadable",
+    `The image header in '${fileName}' is truncated or malformed, so its dimensions cannot be read.`,
+    { field: fileName },
+  );
+}
+
+function startsWithAscii(bytes, text, offset = 0) {
+  if (bytes.byteLength < offset + text.length) return false;
+  for (let index = 0; index < text.length; index += 1) {
+    if (bytes[offset + index] !== text.charCodeAt(index)) return false;
+  }
+  return true;
+}
+
+function pngDimensions(bytes, fileName) {
+  // Length (4) + "IHDR" (4) + width (4) + height (4) after the 8-byte signature.
+  if (bytes.byteLength < 24 || !startsWithAscii(bytes, "IHDR", 12)) throw unreadableDimensions(fileName);
+  return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
+}
+
+function gifDimensions(bytes, fileName) {
+  if (bytes.byteLength < 10) throw unreadableDimensions(fileName);
+  return { width: bytes.readUInt16LE(6), height: bytes.readUInt16LE(8) };
+}
+
+function isJpegFrameMarker(marker) {
+  // SOF0-SOF15 minus DHT (0xC4), JPG (0xC8), and DAC (0xCC), none of which
+  // carry frame dimensions.
+  return marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+}
+
+function jpegDimensions(bytes, fileName) {
+  let offset = 2;
+  for (let segment = 0; segment < MAXIMUM_JPEG_SEGMENTS; segment += 1) {
+    // Segments may be padded with any number of 0xFF fill bytes.
+    while (offset < bytes.byteLength && bytes[offset] === 0xff) offset += 1;
+    if (offset >= bytes.byteLength) throw unreadableDimensions(fileName);
+    const marker = bytes[offset];
+    offset += 1;
+    // Standalone markers carry no length field.
+    if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd9)) continue;
+    if (offset + 2 > bytes.byteLength) throw unreadableDimensions(fileName);
+    const length = bytes.readUInt16BE(offset);
+    if (length < 2) throw unreadableDimensions(fileName);
+    if (isJpegFrameMarker(marker)) {
+      // length (2) + sample precision (1) + height (2) + width (2).
+      if (offset + 7 > bytes.byteLength) throw unreadableDimensions(fileName);
+      return { height: bytes.readUInt16BE(offset + 3), width: bytes.readUInt16BE(offset + 5) };
+    }
+    offset += length;
+    // A 0xDA (start of scan) hands off to entropy-coded data, which this
+    // reader must never walk.
+    if (marker === 0xda) break;
+  }
+  throw unreadableDimensions(fileName);
+}
+
+function webpDimensions(bytes, fileName) {
+  // RIFF (4) + file size (4) + WEBP (4), then one chunk header of fourcc (4)
+  // and size (4), so chunk payloads begin at 20.
+  if (bytes.byteLength < 30) throw unreadableDimensions(fileName);
+  if (startsWithAscii(bytes, "VP8X", 12)) {
+    // Flags (1) + reserved (3), then two 24-bit little-endian "minus one" values.
+    const width = (bytes[24] | (bytes[25] << 8) | (bytes[26] << 16)) + 1;
+    const height = (bytes[27] | (bytes[28] << 8) | (bytes[29] << 16)) + 1;
+    return { width, height };
+  }
+  if (startsWithAscii(bytes, "VP8L", 12)) {
+    if (bytes[20] !== 0x2f) throw unreadableDimensions(fileName);
+    const packed = bytes.readUInt32LE(21);
+    return { width: (packed & 0x3fff) + 1, height: ((packed >>> 14) & 0x3fff) + 1 };
+  }
+  if (startsWithAscii(bytes, "VP8 ", 12)) {
+    // Frame tag (3), sync code 0x9D 0x01 0x2A (3), then two 14-bit dimensions.
+    if (bytes[23] !== 0x9d || bytes[24] !== 0x01 || bytes[25] !== 0x2a) throw unreadableDimensions(fileName);
+    return { width: bytes.readUInt16LE(26) & 0x3fff, height: bytes.readUInt16LE(28) & 0x3fff };
+  }
+  throw unreadableDimensions(fileName);
+}
+
+/** The SHA-256 the dedup short-circuit is keyed on. */
+export function contentHash(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+/**
+ * Reads the container type and pixel dimensions out of an image's header.
+ * Returns `{ contentType, width, height }`; throws `media.unsupported_format`
+ * for a container Taproot does not accept and `media.dimensions_unreadable`
+ * for a recognized container whose header does not hold usable dimensions.
+ */
+export function inspectImageBytes(bytes, fileName = "image") {
+  if (!Buffer.isBuffer(bytes)) {
+    throw new SiteAuthoringError("media.unreadable", "The image bytes could not be inspected.", { field: fileName });
+  }
+  let contentType;
+  let dimensions;
+  if (bytes.byteLength >= 8 && bytes.subarray(0, 8).equals(PNG_SIGNATURE)) {
+    contentType = IMAGE_CONTENT_TYPES.png;
+    dimensions = pngDimensions(bytes, fileName);
+  } else if (bytes.byteLength >= 2 && bytes.subarray(0, 2).equals(JPEG_SOI)) {
+    contentType = IMAGE_CONTENT_TYPES.jpeg;
+    dimensions = jpegDimensions(bytes, fileName);
+  } else if (startsWithAscii(bytes, "GIF87a") || startsWithAscii(bytes, "GIF89a")) {
+    contentType = IMAGE_CONTENT_TYPES.gif;
+    dimensions = gifDimensions(bytes, fileName);
+  } else if (startsWithAscii(bytes, "RIFF") && startsWithAscii(bytes, "WEBP", 8)) {
+    contentType = IMAGE_CONTENT_TYPES.webp;
+    dimensions = webpDimensions(bytes, fileName);
+  } else {
+    throw unsupportedFormat(fileName);
+  }
+  if (
+    !Number.isSafeInteger(dimensions.width)
+    || !Number.isSafeInteger(dimensions.height)
+    || dimensions.width <= 0
+    || dimensions.height <= 0
+    || dimensions.width > MAXIMUM_DIMENSION
+    || dimensions.height > MAXIMUM_DIMENSION
+  ) {
+    throw unreadableDimensions(fileName);
+  }
+  return { contentType, width: dimensions.width, height: dimensions.height };
+}

package/src/index.js

@@ -0,0 +1,16 @@
+export { runCli } from "./cli.js";
+export { SiteAuthoringError } from "./errors.js";
+export {
+  getComponentReference,
+  getPageTypeReference,
+  listComponentTypeReferences,
+  listPageTypeReferences,
+  PAGE_TYPES,
+  REFERENCE_TOPICS,
+  REFERENCE_VERSION,
+} from "./reference-help.js";
+export {
+  getAppearanceReference,
+  getFooterReference,
+  getThemeReference,
+} from "./presentation-reference.js";

package/src/json-guard.js

@@ -0,0 +1,111 @@
+import { SiteAuthoringError } from "./errors.js";
+
+const QUOTE = "\"";
+
+/**
+ * A JSON parser that refuses a duplicated object key, shared by the
+ * configuration and the machine settings (TR00645).
+ *
+ * `JSON.parse` silently keeps the last of two identical keys. For a file a
+ * person can edit — and the settings file is one — that means the value the
+ * file *visibly* declares first is not the value the CLI acts on: a settings
+ * file with `apiBaseUrl` twice reads as production at the top and routes a
+ * credential to local, or the reverse, and a `TAPROOT_SITE_KEY` would follow
+ * it there. The only safe reading of an ambiguous target is to refuse it.
+ *
+ * Extracted from the configuration loader, which has needed the same guard
+ * for `siteId` since it was written; parameterized on the two errors each
+ * caller owns rather than copied, so there is one parser to review.
+ */
+export function parseJsonWithDuplicateGuard(text, { onDuplicate, onInvalid }) {
+  let offset = 0;
+  const whitespace = () => {
+    while (/[\t\n\r ]/u.test(text[offset] ?? "")) offset += 1;
+  };
+  const string = () => {
+    if (text[offset] !== QUOTE) throw new Error("Expected a JSON string.");
+    const start = offset;
+    offset += 1;
+    while (offset < text.length) {
+      const character = text[offset];
+      if (character === QUOTE) {
+        offset += 1;
+        return JSON.parse(text.slice(start, offset));
+      }
+      if (character === "\\") {
+        offset += 1;
+        if (text[offset] === "u") offset += 4;
+      }
+      offset += 1;
+    }
+    throw new Error("Unterminated JSON string.");
+  };
+  const value = (depth = 0) => {
+    if (depth > 16) throw new Error("JSON nesting is too deep.");
+    whitespace();
+    if (text[offset] === QUOTE) return string();
+    if (text[offset] === "{") {
+      offset += 1;
+      whitespace();
+      const result = Object.create(null);
+      const keys = new Set();
+      if (text[offset] === "}") {
+        offset += 1;
+        return result;
+      }
+      while (offset < text.length) {
+        whitespace();
+        const key = string();
+        if (keys.has(key)) throw onDuplicate(key);
+        keys.add(key);
+        whitespace();
+        if (text[offset] !== ":") throw new Error("Expected ':' after a JSON key.");
+        offset += 1;
+        result[key] = value(depth + 1);
+        whitespace();
+        if (text[offset] === "}") {
+          offset += 1;
+          return result;
+        }
+        if (text[offset] !== ",") throw new Error("Expected ',' between JSON fields.");
+        offset += 1;
+      }
+      throw new Error("Unterminated JSON object.");
+    }
+    if (text[offset] === "[") {
+      offset += 1;
+      whitespace();
+      const result = [];
+      if (text[offset] === "]") {
+        offset += 1;
+        return result;
+      }
+      while (offset < text.length) {
+        result.push(value(depth + 1));
+        whitespace();
+        if (text[offset] === "]") {
+          offset += 1;
+          return result;
+        }
+        if (text[offset] !== ",") throw new Error("Expected ',' between JSON values.");
+        offset += 1;
+      }
+      throw new Error("Unterminated JSON array.");
+    }
+    const remaining = text.slice(offset);
+    const token = /^(?:true|false|null|-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?)/u.exec(remaining)?.[0];
+    if (!token) throw new Error("Invalid JSON value.");
+    offset += token.length;
+    return JSON.parse(token);
+  };
+
+  try {
+    const parsed = value();
+    whitespace();
+    if (offset !== text.length) throw new Error("Unexpected data after the JSON value.");
+    return parsed;
+  } catch (error) {
+    if (error instanceof SiteAuthoringError) throw error;
+    throw onInvalid();
+  }
+}