@taprootio/site-authoring 0.2.0 → 0.4.0

package/src/credentials.js

@@ -6,6 +6,7 @@ import path from "node:path";
 import { atomicWriteFile } from "./atomic-file.js";
 import { readBoundedFile } from "./bounded-file.js";
 import { SITE_AUTHORING_CAPABILITIES } from "./capabilities.js";
+import { parseCliVersion } from "./cli-release.js";
 
 import {
   CANONICAL_TIMESTAMP,
@@ -63,6 +64,11 @@ export const KEY_PREFIX = /^[\w.-]{1,64}$/u;
 const PROJECTION_UUID = "00000000-0000-4000-8000-000000000000";
 const PROJECTION_TIMESTAMP = "2000-01-01T00:00:00.000Z";
 const PROJECTION_KEY_PREFIX_LENGTH = 64;
+// A version string as long as the reader admits (MAXIMUM_VERSION_LENGTH in
+// cli-release.js, 64 characters), for the same reason the prefix above is
+// padded: the projection is an upper bound on the record a first exchange will
+// write (TR00703).
+const PROJECTION_LATEST_CLI_VERSION = `999999.999999.999999-${"a".repeat(43)}`;
 
 function usableDirectory(value) {
   return typeof value === "string"
@@ -134,9 +140,17 @@ function normalizeEntry(entry) {
     "A stored credential record has an invalid createdAt.",
   );
   // What the last exchange produced. Entirely non-secret — a site id, the
-  // capabilities that exchange asked for, and when the credential it returned
-  // dies — and the only way `whoami` can answer "what can this actually do"
-  // without a network round trip. Absent before the first exchange.
+  // capabilities that exchange asked for, when the credential it returned dies,
+  // when the exchange happened, and what Taproot then said about the
+  // platform-wide authoring switch — and the only way `whoami` can answer "what
+  // can this actually do" without a network round trip. Absent before the first
+  // exchange.
+  //
+  // `at` and `externalWritesEnabled` are optional on top of that (TR00692), and
+  // `latestCliVersion` on top of those (TR00703): a record written by an
+  // earlier version carries none of them, and a server that predates either
+  // field carries no value for it. Refusing those would make a routine upgrade
+  // look like a corrupt store.
   requireStoreShape(
     entry.lastExchange === undefined
       || (entry.lastExchange !== null
@@ -146,7 +160,16 @@ function normalizeEntry(entry) {
         && Array.isArray(entry.lastExchange.capabilities)
         && entry.lastExchange.capabilities.every((value) => typeof value === "string")
         && typeof entry.lastExchange.expiresAt === "string"
-        && CANONICAL_TIMESTAMP.test(entry.lastExchange.expiresAt)),
+        && CANONICAL_TIMESTAMP.test(entry.lastExchange.expiresAt)
+        && (entry.lastExchange.at === undefined
+          || (typeof entry.lastExchange.at === "string" && CANONICAL_TIMESTAMP.test(entry.lastExchange.at)))
+        && (entry.lastExchange.externalWritesEnabled === undefined
+          || typeof entry.lastExchange.externalWritesEnabled === "boolean")
+        // Only a version this side can compare is admitted, because the value's
+        // whole job is to be compared: a record carrying something unparseable
+        // could never gate anything, so storing it would be storing noise.
+        && (entry.lastExchange.latestCliVersion === undefined
+          || parseCliVersion(entry.lastExchange.latestCliVersion) !== undefined)),
     "A stored credential record has an invalid lastExchange.",
   );
   return Object.freeze({
@@ -161,6 +184,13 @@ function normalizeEntry(entry) {
         siteId: entry.lastExchange.siteId,
         capabilities: Object.freeze([...entry.lastExchange.capabilities]),
         expiresAt: entry.lastExchange.expiresAt,
+        ...(entry.lastExchange.at === undefined ? {} : { at: entry.lastExchange.at }),
+        ...(entry.lastExchange.externalWritesEnabled === undefined
+          ? {}
+          : { externalWritesEnabled: entry.lastExchange.externalWritesEnabled }),
+        ...(entry.lastExchange.latestCliVersion === undefined
+          ? {}
+          : { latestCliVersion: entry.lastExchange.latestCliVersion }),
       }),
     }),
     createdAt: entry.createdAt,
@@ -469,6 +499,11 @@ export async function assertCredentialCapacity(environment, apiOrigin) {
       siteId: PROJECTION_UUID,
       capabilities: [...SITE_AUTHORING_CAPABILITIES],
       expiresAt: PROJECTION_TIMESTAMP,
+      at: PROJECTION_TIMESTAMP,
+      // `false` rather than `true`: it serializes one byte longer, and the
+      // projection's whole job is to be an upper bound on the real record.
+      externalWritesEnabled: false,
+      latestCliVersion: PROJECTION_LATEST_CLI_VERSION,
     },
     createdAt: PROJECTION_TIMESTAMP,
   });

package/src/errors.js

@@ -112,6 +112,31 @@ export class SiteAuthoringError extends Error {
     return this;
   }
 
+  /**
+   * Attach the JSON paths at which two documents differ.
+   *
+   * Separate from `alternatives`, which is the bounded list of other values or
+   * targets a caller can act on — the files in a pull conflict, but equally the
+   * help topics, page types, or revisions another failure offers. These name
+   * locations inside one document, decide nothing, and exist so a conflict can
+   * be triaged without re-fetching both sides by hand.
+   *
+   * A list and no list are different facts, so anything that is not a list
+   * leaves the field unset rather than becoming an empty one: `[]` means the
+   * documents were compared and found identical, and absent means there was
+   * nothing to compare them against. Collapsing the second into the first would
+   * tell an agent the body is unchanged for a comparison that never ran.
+   */
+  withDifferences(paths) {
+    this.differences = Array.isArray(paths)
+      ? paths
+        .filter((value) => typeof value === "string")
+        .slice(0, 100)
+        .map((value) => sanitizeDiagnostic(value, "path"))
+      : undefined;
+    return this;
+  }
+
   /** Attach the non-secret identity needed to inspect or revoke a created preview. */
   withPreviewRecovery(preview) {
     const recovery = normalizePreviewRecovery(preview);

package/src/fixture-contract.js

@@ -0,0 +1,64 @@
+import { fileURLToPath } from "node:url";
+
+/**
+ * The offline authoring-fixture contract (TR00647).
+ *
+ * `validate` enforces this; `help fixture` states it. Both read the constants
+ * below rather than restating them, so a change to what the verb requires
+ * cannot leave the reference describing the previous contract. The one thing
+ * this module deliberately does not own is the *page* entry's key set: a
+ * fixture page entry is a `pull` manifest entry, and `validate` reads the
+ * fields it needs rather than closing the shape, so a fixture written by a
+ * newer `pull` is not refused for carrying a field this release ignores.
+ */
+
+export const FIXTURE_MANIFEST_FILE_NAME = "manifest.fixture.json";
+export const FIXTURE_CONTRACT_VERSION = 1;
+
+/** Root fields whose absence or wrong value fails validation. */
+export const FIXTURE_REQUIRED_ROOT_FIELDS = Object.freeze([
+  "manifestVersion",
+  "siteId",
+  "pages",
+  "pagesTruncated",
+  "navigation",
+  "redirects",
+  "settings",
+  "settingsSkipped",
+  "fixture",
+]);
+
+/**
+ * Root fields `pull` writes that a fixture may carry unchanged. They are
+ * accepted and read for nothing: a fixture proves local structure, and neither
+ * the snapshot time nor a recorded deployment can be checked without a server.
+ */
+export const FIXTURE_OPTIONAL_ROOT_FIELDS = Object.freeze(["pulledAt", "deployments"]);
+
+/** Every root field the manifest may declare. Anything else is refused. */
+export const FIXTURE_ROOT_FIELDS = Object.freeze(
+  [...FIXTURE_REQUIRED_ROOT_FIELDS, ...FIXTURE_OPTIONAL_ROOT_FIELDS].sort(),
+);
+
+/** Every field the versioned `fixture` block may declare. All are required. */
+export const FIXTURE_METADATA_FIELDS = Object.freeze(["contractVersion", "imageIds", "deliveryOrigins"]);
+
+/**
+ * Delivery origins are restricted to the reserved example domain rather than
+ * merely to HTTPS. A fixture is example data that ships and is copied; a real
+ * delivery host in one would be a live reference in every copy of it.
+ */
+export const FIXTURE_DELIVERY_ORIGIN_DOMAIN = "example.test";
+export const FIXTURE_MAXIMUM_DELIVERY_ORIGINS = 100;
+
+/** The complete example fixture this package ships. */
+export const SHIPPED_FIXTURE_NAME = "riverbend-wellness";
+
+/**
+ * The absolute path of the shipped fixture, resolved from this module rather
+ * than from the caller's directory, so it is correct for a global install as
+ * well as a checkout. `help fixture` reports it and `validate` accepts it.
+ */
+export function shippedFixtureDirectory() {
+  return fileURLToPath(new URL(`../examples/${SHIPPED_FIXTURE_NAME}/`, import.meta.url)).replace(/[\\/]$/u, "");
+}

package/src/footer-contract.js

@@ -1,3 +1,8 @@
+import {
+  CONTACT_OR_WEB_URL_MAX_LENGTH,
+  CONTACT_OR_WEB_URL_REQUIREMENT,
+  isContactOrWebUrl,
+} from "./contact-url.js";
 import { hasControlCharacter, isCanonicalUuid, SiteAuthoringError } from "./errors.js";
 import { FOOTER_COLOR_TOKENS, requireAppearanceColor } from "./theme-validation.js";
 
@@ -15,7 +20,7 @@ export const FOOTER_LIMITS = Object.freeze({
   linkLabelLength: 120,
   bottomTextLength: 500,
   featureImageAltLength: 300,
-  externalUrlLength: 2_048,
+  externalUrlLength: CONTACT_OR_WEB_URL_MAX_LENGTH,
   backgroundRepeatHeightMinimum: 64,
   backgroundRepeatHeightMaximum: 512,
   backgroundRepeatHeightStep: 16,
@@ -198,33 +203,17 @@ function stableId(value, path, seen, label) {
   return value;
 }
 
+// A `tel:` or `mailto:` target is returned exactly as authored: the number's
+// punctuation and the address's plus-tag are content, and `URL.toString()`
+// re-encodes both. Only the whitespace the server would strip is removed.
 function safeExternalUrl(value, path, tolerateStoredValues) {
   if (typeof value !== "string") {
-    fail("footer.url_invalid", `${path} must be a bounded absolute http or https URL.`, path);
+    fail("footer.url_invalid", `${path} ${CONTACT_OR_WEB_URL_REQUIREMENT}.`, path);
   }
   const normalized = trimLikeServer(value);
   if (tolerateStoredValues) return normalized;
-  if (
-    normalized.length === 0
-    || normalized.length > FOOTER_LIMITS.externalUrlLength
-    || hasControlCharacter(normalized)
-    || normalized.includes("\\")
-  ) {
-    fail("footer.url_invalid", `${path} must be a bounded absolute http or https URL.`, path);
-  }
-  let parsed;
-  try {
-    parsed = new URL(normalized);
-  } catch {
-    fail("footer.url_invalid", `${path} must be an absolute http or https URL.`, path);
-  }
-  if (
-    (parsed.protocol !== "http:" && parsed.protocol !== "https:")
-    || parsed.username !== ""
-    || parsed.password !== ""
-    || parsed.hostname === ""
-  ) {
-    fail("footer.url_invalid", `${path} must use http or https without embedded credentials.`, path);
+  if (!isContactOrWebUrl(normalized, FOOTER_LIMITS.externalUrlLength)) {
+    fail("footer.url_invalid", `${path} ${CONTACT_OR_WEB_URL_REQUIREMENT}.`, path);
   }
   return normalized;
 }
@@ -618,16 +607,25 @@ export function footerImageIds(value) {
 export const FOOTER_EXAMPLE = Object.freeze({
   enabled: true,
   showBrand: true,
+  // The aside CTA is where a local business puts the thing a visitor came for.
+  // A phone number is a `tel:` target, emitted verbatim so it stays dialable.
   asideCta: Object.freeze({
     id: "103e726d-3152-49c8-bf14-c947b1bd8a14",
-    label: "Talk with us",
-    externalUrl: "https://example.com/contact",
+    label: "Call the studio",
+    externalUrl: "tel:+15555550123",
   }),
-  bottomLinks: Object.freeze([Object.freeze({
-    id: "28363e08-b341-42fc-bc83-8dd73fa87904",
-    label: "Privacy",
-    externalUrl: "https://example.com/privacy",
-  })]),
+  bottomLinks: Object.freeze([
+    Object.freeze({
+      id: "28363e08-b341-42fc-bc83-8dd73fa87904",
+      label: "Privacy",
+      externalUrl: "https://example.com/privacy",
+    }),
+    Object.freeze({
+      id: "9e2d1f04-4bb0-4a2d-9d1a-6d3b0d0a4c77",
+      label: "Email us",
+      externalUrl: "mailto:hello@example.com",
+    }),
+  ]),
   light: Object.freeze({
     backgroundColor: "--esp-color-layer-1",
     textColor: "--esp-color-text",

package/src/json-path-diff.js

@@ -0,0 +1,167 @@
+/**
+ * Says *what* differs between two page documents, in JSON paths.
+ *
+ * A conflict that only says "this page changed on the site" leaves the operator
+ * with a choice nobody can make well: re-push identical content, or abandon the
+ * local source. On the SHY production home page (2026-09-03) the entire
+ * difference was `$.content[0].attrs.decoration.image.src` and the sibling
+ * `.urls` — two fields the API re-projects on every read from live image state
+ * — and a list of paths would have shown that in one line.
+ *
+ * This decides nothing. The revision comparison decides; this explains it. So
+ * it is deliberately generous about what counts as a difference and strictly
+ * bounded in what it will spend finding out: a diagnostic that hangs on a
+ * hostile document is worse than one that says "and more".
+ */
+
+/** How many differing paths one report carries before it says "and more". */
+export const JSON_DIFFERENCE_LIMIT = 20;
+
+/**
+ * How deep the comparison descends. `canonicalDocumentHash` refuses a document
+ * nesting deeper than this, and every document compared here has already been
+ * through it, so the bound is unreachable for real content. A subtree at the
+ * bound is reported as differing rather than skipped in silence: over-reporting
+ * a diagnostic is safe, and quietly not comparing is not.
+ */
+const MAXIMUM_DEPTH = 100;
+
+/**
+ * A ceiling on total work, because both sides are documents this process did
+ * not author: one is the site's, the other a file on disk.
+ */
+const MAXIMUM_VISITS = 200_000;
+
+/** How much of one object key a path segment carries. */
+const MAXIMUM_SEGMENT_SCALARS = 64;
+
+/** How long one rendered path may be before its middle is elided. */
+const MAXIMUM_PATH_SCALARS = 200;
+
+const PLAIN_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+
+function boundSegment(key) {
+  const scalars = [...key];
+  return scalars.length <= MAXIMUM_SEGMENT_SCALARS
+    ? key
+    : `${scalars.slice(0, MAXIMUM_SEGMENT_SCALARS).join("")}…`;
+}
+
+function childPath(path, key) {
+  const segment = boundSegment(key);
+  return PLAIN_KEY.test(segment) ? `${path}.${segment}` : `${path}[${JSON.stringify(segment)}]`;
+}
+
+function indexPath(path, index) {
+  return `${path}[${index}]`;
+}
+
+function boundPath(path) {
+  const scalars = [...path];
+  if (scalars.length <= MAXIMUM_PATH_SCALARS) return path;
+  const head = scalars.slice(0, MAXIMUM_PATH_SCALARS - 20).join("");
+  const tail = scalars.slice(-19).join("");
+  return `${head}…${tail}`;
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * The paths at which two parsed JSON values differ.
+ *
+ * Returns `{ paths, truncated }`. `paths` is empty when the two documents are
+ * structurally identical — which, on a page whose revision moved, is the useful
+ * answer: the stored state changed in a field this comparison does not cover.
+ *
+ * `truncated` means the walk stopped early — either more than `limit`
+ * differences exist, or the documents are large enough to have exhausted the
+ * work ceiling — so the list is a sample rather than the whole story.
+ */
+export function describeJsonDifferences(left, right, { limit = JSON_DIFFERENCE_LIMIT } = {}) {
+  const bound = Number.isSafeInteger(limit) && limit > 0 ? limit : JSON_DIFFERENCE_LIMIT;
+  // One past the reported bound. Stopping *at* the bound could not tell "these
+  // are all of them" from "there were more", and a sample presented as a
+  // complete list is the kind of diagnostic that sends someone looking in the
+  // wrong place.
+  const cap = bound + 1;
+  const paths = [];
+  let exhausted = false;
+  let visits = 0;
+
+  const record = (path) => {
+    paths.push(boundPath(path));
+  };
+
+  const walk = (leftValue, rightValue, path, depth) => {
+    if (paths.length >= cap || exhausted) return;
+    visits += 1;
+    if (visits > MAXIMUM_VISITS) {
+      exhausted = true;
+      return;
+    }
+    if (depth > MAXIMUM_DEPTH) {
+      record(path);
+      return;
+    }
+
+    if (Array.isArray(leftValue) && Array.isArray(rightValue)) {
+      const shared = Math.min(leftValue.length, rightValue.length);
+      for (let index = 0; index < shared; index += 1) {
+        walk(leftValue[index], rightValue[index], indexPath(path, index), depth + 1);
+        if (paths.length >= cap || exhausted) return;
+      }
+      // An added or removed element is named by its own index rather than by
+      // the array, so "one section was appended" reads differently from "every
+      // section moved".
+      for (let index = shared; index < Math.max(leftValue.length, rightValue.length); index += 1) {
+        record(indexPath(path, index));
+        if (paths.length >= cap || exhausted) return;
+      }
+      return;
+    }
+
+    if (isPlainObject(leftValue) && isPlainObject(rightValue)) {
+      // Sorted so two runs over the same pair of documents report the same
+      // paths in the same order, whatever order the members arrived in.
+      const keys = [...new Set([...Object.keys(leftValue), ...Object.keys(rightValue)])].sort();
+      for (const key of keys) {
+        const inLeft = Object.hasOwn(leftValue, key);
+        const inRight = Object.hasOwn(rightValue, key);
+        if (!inLeft || !inRight) {
+          record(childPath(path, key));
+        } else {
+          walk(leftValue[key], rightValue[key], childPath(path, key), depth + 1);
+        }
+        if (paths.length >= cap || exhausted) return;
+      }
+      return;
+    }
+
+    // Different kinds, or two scalars. `Object.is` rather than `===` so two
+    // NaN bodies do not read as a difference; JSON has no NaN, but these
+    // documents reach here through `JSON.parse` of untrusted bytes and a
+    // caller may hand over something else.
+    if (!Object.is(leftValue, rightValue)) record(path);
+  };
+
+  walk(left, right, "$", 0);
+  return { paths: paths.slice(0, bound), truncated: exhausted || paths.length > bound };
+}
+
+/**
+ * The paths a conflict may claim, or `undefined` when no claim is honest.
+ *
+ * An empty list is the statement "compared, and the body is identical", which
+ * an agent reads as "look at the title, path, or description instead". That
+ * statement cannot be made when nothing was compared, and it cannot be made
+ * when the walk exhausted its budget before it reached a difference: two
+ * documents that agree for the first two hundred thousand nodes and differ
+ * afterwards are different, not identical.
+ */
+export function reportableDifferencePaths(differences) {
+  if (differences === undefined) return undefined;
+  if (differences.paths.length === 0 && differences.truncated) return undefined;
+  return differences.paths;
+}

package/src/output.js

@@ -42,6 +42,15 @@ export function failureResult(error) {
   if (Array.isArray(error.completedWrites) && error.completedWrites.length > 0) {
     result.error.completedWrites = error.completedWrites;
   }
+  // Three states, and an agent acts differently on each. Absent: the two
+  // documents were never compared, because this workspace kept no copy of the
+  // site's previous version. Empty: they were compared and the body is
+  // identical, so the change that raised the conflict is in the page's title,
+  // path, or description. Non-empty: the JSON paths at which they differ.
+  // Suppressing the empty array would collapse the first two into one.
+  if (Array.isArray(error.differences)) {
+    result.error.differences = error.differences;
+  }
   const previewRecovery = normalizePreviewRecovery(error.previewRecovery);
   if (previewRecovery) result.error.preview = previewRecovery;
   const refusal = typeof error.refusalKind === "function" ? error.refusalKind() : undefined;

package/src/presentation-reference.js

@@ -412,7 +412,7 @@ const FOOTER_FIELD_DETAILS = Object.freeze({
   "FooterLink.label": { type: "plain-text", required: true, maximumLength: FOOTER_LIMITS.linkLabelLength },
   "FooterLink.pageResourceId": { type: "tracked-page-resource-uuid", exclusiveWith: "externalUrl" },
   "FooterLink.externalUrl": {
-    type: "absolute-http-or-https-url",
+    type: "contact-or-web-url",
     exclusiveWith: "pageResourceId",
     maximumLength: FOOTER_LIMITS.externalUrlLength,
   },
@@ -425,7 +425,7 @@ const FOOTER_FIELD_DETAILS = Object.freeze({
   "FooterRichTextRun.link": { type: "FooterInlineLink|null", default: null },
   "FooterInlineLink.pageResourceId": { type: "tracked-page-resource-uuid", exclusiveWith: "externalUrl" },
   "FooterInlineLink.externalUrl": {
-    type: "absolute-http-or-https-url",
+    type: "contact-or-web-url",
     exclusiveWith: "pageResourceId",
     maximumLength: FOOTER_LIMITS.externalUrlLength,
   },
@@ -507,7 +507,9 @@ export function getFooterReference() {
     totalGroupMaximum: FOOTER_LIMITS.linkGroups,
     totalRichTextRunsMaximum: FOOTER_LIMITS.richTextRuns,
     targetRule:
-      "Each link has exactly one target: a tracked pageResourceId, or an absolute credential-free http/https externalUrl.",
+      "Each link has exactly one target: a tracked pageResourceId, or an externalUrl that is an absolute "
+      + "credential-free http/https URL, or a mailto:/tel: contact URL such as tel:+15555550123. A contact URL is "
+      + "published exactly as authored, so write the number the way it should be dialled.",
     imageRule:
       "Image ids come from pull or media upload. Feature images require alt text; background art is decorative.",
     readOnlyProjections: FOOTER_READ_ONLY_FIELDS,