@taprootio/site-authoring 0.20.0 → 0.22.0

package/src/cli-release.js

@@ -1,4 +1,5 @@
 import {
+  changelogCommandSince,
   CLI_UPGRADE_COMMAND,
   CLI_UPGRADE_REFUSAL_FIELD,
   CLI_VERSION,
@@ -131,6 +132,11 @@ export function isBehindLatest(latestVersion, currentVersion = CLI_VERSION) {
  * `api.request_rejected`.
  */
 class CliOutdatedError extends SiteAuthoringError {
+  constructor(code, message, options, latestVersion) {
+    super(code, message, options);
+    this.latestVersion = latestVersion;
+  }
+
   refusalKind() {
     return REFUSAL_CLI_OUTDATED;
   }
@@ -146,7 +152,9 @@ export function cliOutdatedError(latestVersion) {
     `This CLI is version ${CLI_VERSION}, and the last Taproot sign-in exchange reported ${latestVersion} as the `
       + "latest published release. Taproot accepts only the latest, so every online verb is refused until this "
       + `package is upgraded. Upgrade with: ${CLI_UPGRADE_COMMAND}. If ${latestVersion} was published in the last `
-      + "few minutes, npm may not serve it yet — wait a moment and retry the upgrade.",
+      + "few minutes, npm may not serve it yet — wait a moment and retry the upgrade. Once upgraded, run "
+      + `'${changelogCommandSince(CLI_VERSION)}' to see what changed.`,
     { field: CLI_UPGRADE_REFUSAL_FIELD },
+    latestVersion,
   );
 }

package/src/cli.js

@@ -1,3 +1,5 @@
+import { normalizeStagingReviewPath } from "./api.js";
+import { parseCliVersion } from "./cli-release.js";
 import { CAPABILITY_CONTENT, CAPABILITY_DEPLOYMENTS, CAPABILITY_DESIGN } from "./capabilities.js";
 import { capabilitiesForSurface } from "./surface.js";
 import {
@@ -22,6 +24,7 @@ import {
   VERB_DELIVERY_CHECK,
   VERB_DEPLOY,
   VERB_STAGING_REVIEW,
+  VERB_CHANGELOG,
   VERB_ENV,
   VERB_FOOTER_PUSH,
   VERB_FORMS_PULL,
@@ -69,6 +72,7 @@ import {
   getDesignBlueprint,
   getFooterReference,
   getPageTypeReference,
+  getSettingsReference,
   getThemeReference,
   getWorkflowReference,
   listComponentTypeReferences,
@@ -118,7 +122,18 @@ const VERBS = Object.freeze([
       + "rather than one per run. A pulled workspace is checked offline against the pages (generated ones included, "
       + "so navigation to a section or tag page resolves), images, and baselines its manifests recorded at the pull. "
       + "A link whose address is only http(s):// plus its own text (left by older editor autolinking) is reported in "
-      + "linkWarnings without refusing; pages push reports the same for the pages it sends. This proves local structure and semantics only. It does not prove "
+      + "linkWarnings without refusing; pages push reports the same for the pages it sends. "
+      + "The site checks that can run offline are reported in findings (a rule id, severity, file, and the value "
+      + "found, such as link.page_missing for a link to a page the workspace does not have) and never refuse a "
+      + "warning. For a free-form page they include the page-structure rules: seo.h1_missing when no heading, banner "
+      + "title or hero title is the page's h1, seo.h1_demoted when a # heading is published as an h2 because the "
+      + "banner's overlay text, a hero title or an earlier # heading already is the h1 (detail names which), "
+      + "seo.heading_renumbered and seo.heading_before_title for headings published at another level, "
+      + "a11y.image_alt_missing and a11y.link_text_empty; for any page seo.title_long and seo.description_missing. "
+      + "siteChecks.checkedInEditor names the rules only the page editor evaluates (a cover, a description field, or a description's length, which descriptionWarnings reports here); "
+      + "siteChecks.checkedBySite names the rules that need the site's own records (images, forms), which "
+      + "'status' reports under siteHealth. A redirect source the site would refuse names its rule in "
+      + "error.problems[].rule. This proves local structure and semantics only. It does not prove "
       + "authorization, live site ownership, concurrency, persisted round trips, or rendering: 'plan' checks a "
       + "workspace against the live site, and 'pages push --dry-run' does that for pages alone. "
       + `See '${CLI_BINARY_NAME} help fixture' for the fixture manifest contract and for the path of the complete `
@@ -200,6 +215,21 @@ const VERBS = Object.freeze([
       + "its value. The sign-in secret is never printed; the credential is named by id and display prefix, which are "
       + "what an owner needs to revoke it.",
   },
+  {
+    name: VERB_CHANGELOG,
+    tokens: ["changelog"],
+    summary: "List what changed in each CLI release, offline.",
+    credentialFree: true,
+    configFree: true,
+    offline: true,
+    sinceOption: true,
+    note: "Only the latest CLI is accepted, so an upgrade can be forced at any time. After one, run "
+      + "'changelog --since <the version you upgraded from>' to see every release's note and the behavior it changed, "
+      + "and which help topics (help <topic>) to read again. With no --since it prints the installed release's entry. "
+      + "It reads the package's own record, needs no sign-in or site, and still runs when this CLI is outdated. "
+      + "The result lists entries newest first, each { version, note, behavior, help }; complete is false when "
+      + "--since starts before the oldest release the record covers. 'status' reports the installed release's note.",
+  },
   {
     name: VERB_ENV,
     tokens: ["env"],
@@ -308,7 +338,7 @@ const VERBS = Object.freeze([
     note:
       "Positional page paths narrow the push to those pages; with none, every workspace page is validated and sent. "
       + "A page names a form by key (formKey); the push looks each key up on the site, sends the form's id, and "
-      + "refuses a key the site does not have or has archived (pages.form_unknown, pages.form_archived) before writing. "
+      + "refuses a key the site does not have or has archived (pages.form_unknown, pages.form_archived) before writing, and says whether the key's forms/<key>.json is in the workspace. validate refuses the same key offline (rule form.key_unknown) when the workspace has a forms/ directory and no file in it is for that key. "
       + "A link in a page being sent whose address is only http(s):// plus its own text is reported in linkWarnings "
       + "(content.link_autolinked) without refusing. "
       + "A page is created without an author unless its source names one ('author:' in the front matter, or 'pages "
@@ -440,9 +470,12 @@ const VERBS = Object.freeze([
     capabilities: [CAPABILITY_CONTENT, CAPABILITY_DEPLOYMENTS],
     tokens: ["redirects", "check"],
     summary: "Check the current redirect map through the authenticated staging edge.",
+    handoffOptions: true,
     note: "Reports each entry's path, HTTP status and Location in redirects.items, and redirects.verified, without "
       + "following redirects. A redirect is live only with the release that carries it, so this reads the staged release. "
-      + "The result includes a fresh single-use staging handoff in stagingPreview.url; keep it private.",
+      + "The check authenticates with its own handoff and never reports it. The result carries no review URL unless "
+      + "you pass --handoff, which adds a fresh single-use one in stagingPreview.url (keep it private); "
+      + "'staging review' mints one at any time.",
   },
   {
     name: VERB_REDIRECTS_PULL,
@@ -589,11 +622,19 @@ const VERBS = Object.freeze([
     tokens: ["deploy"],
     summary: "Deploy to staging, or promote staging to production.",
     target: true,
-    note: "deploy --staging returns a single-use review handoff in stagingPreview.url, on a managed Docs site too, "
-      + "where it stages settings only: open the URL once, then switch the site's theme toggle to review both "
-      + "schemes before deploy --production. If no handoff could be minted, stagingPreview.reason names why and "
+    handoffOptions: true,
+    note: "deploy --staging does not report a review URL, because the URL is a live single-use credential and this "
+      + "JSON is often saved to logs. Run 'staging review' to mint one, or pass --handoff to get a fresh "
+      + "single-use one in stagingPreview.url (on a managed Docs site too, where it stages settings only): open it "
+      + "once, then switch the site's theme toggle to review both schemes before deploy --production. Without "
+      + "--handoff, stagingPreview.reason is staging.handoff_not_requested and stagingPreview.recovery names the "
+      + "command. If a requested handoff could not be minted, stagingPreview.reason names why and "
       + "stagingPreview.recovery the next step; 'staging review' mints another. On a Standard site the result also "
-      + "carries the automatic redirect check: routeCheck and redirects (see 'help redirects').",
+      + "carries the automatic redirect check: routeCheck and redirects (see 'help redirects'). The edge can keep "
+      + `serving the previous release for up to ${LIMITS.stagingPropagationCeilingSeconds} seconds after a deployment completes, so a Standard site's `
+      + "deploy --staging waits until staging serves the new release and reports stagingServed: state served, "
+      + "propagating (still the previous release at the bound) or unverified (the change cannot be attributed to this deployment, or the last read did not name the previous release), "
+      + "with the time to wait or the seconds waited.",
   },
   {
     name: VERB_PREVIEW_PAGE,
@@ -653,20 +694,23 @@ const VERBS = Object.freeze([
     capabilities: [CAPABILITY_DEPLOYMENTS],
     tokens: ["staging", "review"],
     summary: "Mint a fresh single-use review handoff for the site's staging host.",
+    reviewPath: true,
     note: "The handoff URL is reported only in the final JSON as stagingPreview.url, is single-use, and expires two "
-      + "minutes after it is minted; keep it private. Open it once, then use the site's theme toggle to review both "
-      + "schemes. This is the recovery when deploy --staging could not mint a handoff, on a managed Docs site too.",
+      + "minutes after it is minted; keep it private. --path <page> opens the review on that page instead of the "
+      + "home page: a page path as 'pull' records it ('about', '/posts/one'), optionally with a query. Open it once, then use the site's theme toggle to review both "
+      + "schemes. deploy --staging and redirects check report no review URL unless you pass --handoff, so this is "
+      + "the usual way to get one, on a managed Docs site too.",
   },
   {
     name: VERB_STATUS,
     surface: SURFACE_DOCS_PRESENTATION,
     // Readiness and the deployment log are Deployments; the image list is
-    // Content, as is the broken-reference report.
+    // Content, as is the site-health read.
     capabilities: [CAPABILITY_CONTENT, CAPABILITY_DEPLOYMENTS],
     tokens: ["status"],
     summary:
-      "Report the platform authoring switch, CLI release, deployments, readiness, image processing, and broken references.",
-    note: "Broken references list pages with missing image IDs or page paths in their latest editable body."
+      "Report the platform authoring switch, CLI release, deployments, readiness, image processing, and site health.",
+    note: "Site health lists the site checks' findings (a rule id, severity, page, and the value found) for the latest editable body of each page."
       + " Content permission is required; a refused or failed read fails status rather than reporting a clean site.",
   },
 ]);
@@ -733,7 +777,8 @@ credentials, and it expires 24 hours after it is issued.
 
 Verbs write one JSON result to stdout and human progress to stderr. validate,
 help, whoami, and env are offline and read-only. login, logout, sites, use,
-whoami, and env need no configuration and no site. The offline help family is
+whoami, and env need no configuration and no site. So does changelog, which
+also still runs when this CLI is outdated. The offline help family is
 human-readable by default; add --json for stable reference data. Exit codes: 0
 success, 1 failure, 2 usage fault.
 
@@ -817,6 +862,18 @@ function verbHelp(verb) {
   --production     Promote the completed staging deployment to production.
   --allow-failed-preview  Explicitly override the matching candidate's failed preview.`
     : "";
+  const handoffOption = verb.handoffOptions
+    ? `\n  --handoff        Also mint a fresh single-use review URL and report it in stagingPreview.url.
+  --no-handoff     Report no review URL (the default); accepted so scripts can say so explicitly.`
+    : "";
+  const sinceOption = verb.sinceOption
+    ? "\n  --since <version>  List the releases after this one, up to the installed release."
+    : "";
+  const reviewPathOption = verb.reviewPath
+    ? "\n  --path <page>    Open the review on this page instead of the home page, such as 'about' or '/posts/one'."
+    : verb.handoffOptions
+    ? "\n  --review-path <page>  With --handoff, open the review URL on this page instead of the home page."
+    : "";
   const metaOptions = verb.metaOptions
     ? `\n  --title <text>       The page's title.
   --description <text> The page's description for search results and link previews; '' clears it.
@@ -907,7 +964,7 @@ function verbHelp(verb) {
 ${verb.summary}
 ${boundary}
 
-${options}${targetOption}${deliveryTargetOption}${metaOptions}${authorOptions}${jsonOption}${dryRunOption}${planOption}${nameOption}${note}
+${options}${targetOption}${handoffOption}${reviewPathOption}${sinceOption}${deliveryTargetOption}${metaOptions}${authorOptions}${jsonOption}${dryRunOption}${planOption}${nameOption}${note}
 `;
 }
 
@@ -968,6 +1025,7 @@ function parseReferenceArguments(arguments_) {
       || topic === "preview"
       || topic === "theme"
       || topic === "appearance"
+      || topic === "settings"
       || topic === "footer"
       || topic === "fixture"
       || topic === "redirects"
@@ -1070,6 +1128,8 @@ function referenceResult(parsed) {
       return { ...result, topic: "presentation", referenceKind: "theme", reference: getThemeReference() };
     case "appearance":
       return { ...result, topic: "presentation", referenceKind: "appearance", reference: getAppearanceReference() };
+    case "settings":
+      return { ...result, topic: "presentation", referenceKind: "settings", reference: getSettingsReference() };
     case "footer":
       return { ...result, topic: "presentation", referenceKind: "footer", reference: getFooterReference() };
     default:
@@ -1249,6 +1309,9 @@ function parseArguments(arguments_) {
   let propagationWaitSeconds;
   let browser;
   let allowFailedPreview = false;
+  let handoff;
+  let reviewPath;
+  let since;
   let dryRun = false;
   let json = false;
   let keyName;
@@ -1314,6 +1377,42 @@ function parseArguments(arguments_) {
       allowFailedPreview = true;
       continue;
     }
+    if (verb.handoffOptions && (argument === "--handoff" || argument === "--no-handoff")) {
+      if (handoff !== undefined) {
+        throw usageError(
+          handoff === (argument === "--handoff") ? "cli.duplicate_option" : "cli.handoff_conflict",
+          handoff === (argument === "--handoff")
+            ? `${argument} may be supplied only once.`
+            : "--handoff and --no-handoff cannot be used together.",
+        );
+      }
+      handoff = argument === "--handoff";
+      continue;
+    }
+    if ((verb.reviewPath && argument === "--path") || (verb.handoffOptions && argument === "--review-path")) {
+      if (reviewPath !== undefined) {
+        throw usageError("cli.duplicate_option", `${argument} may be supplied only once.`);
+      }
+      // An option-like value would otherwise become the page '/--json' and mint a handoff to a 404.
+      const candidate = rest[index + 1];
+      reviewPath = normalizeStagingReviewPath(typeof candidate === "string" && candidate.startsWith("--") ? "" : candidate);
+      index += 1;
+      continue;
+    }
+    if (verb.sinceOption && argument === "--since") {
+      if (since !== undefined) throw usageError("cli.duplicate_option", "--since may be supplied only once.");
+      const candidate = rest[index + 1];
+      if (parseCliVersion(candidate) === undefined) {
+        throw usageError(
+          "changelog.since_invalid",
+          "--since requires a version such as 0.20.0 (the version you upgraded from).",
+          { field: "since" },
+        );
+      }
+      since = candidate;
+      index += 1;
+      continue;
+    }
     if (verb.dryRun && argument === "--dry-run") {
       if (dryRun) throw usageError("cli.duplicate_option", "--dry-run may be supplied only once.");
       dryRun = true;
@@ -1394,6 +1493,16 @@ function parseArguments(arguments_) {
       `${verb.tokens.join(" ")} requires exactly one of --staging or --production.`,
     );
   }
+  if (verb.handoffOptions && reviewPath !== undefined && handoff !== true) {
+    throw usageError(
+      "cli.review_path_requires_handoff",
+      "--review-path chooses the page a --handoff review URL opens on; pass --handoff with it, or use 'staging review --path'.",
+      { field: "reviewPath" },
+    );
+  }
+  if (handoff === true && verb.target && deployTarget === DEPLOY_TARGET_PRODUCTION) {
+    throw usageError("cli.handoff_target", "--handoff applies only to deploy --staging.", { field: "handoff" });
+  }
   if (verb.positionals === "fixturePath" && (positionals.length > 1 || (init && positionals.length !== 1))) {
     throw usageError(
       "validate.fixture_path_invalid",
@@ -1507,6 +1616,9 @@ function parseArguments(arguments_) {
     quiet,
     deployTarget,
     allowFailedPreview,
+    ...(handoff === undefined ? {} : { handoff }),
+    ...(reviewPath === undefined ? {} : { reviewPath }),
+    ...(since === undefined ? {} : { since }),
     ...(deliveryUrl === undefined ? {} : { deliveryUrl }),
     ...(propagationWaitSeconds === undefined ? {} : { propagationWaitSeconds }),
     ...(browser === undefined ? {} : { browser }),
@@ -1599,6 +1711,9 @@ export async function runCli({
       configPath: parsed.configPath,
       deployTarget: parsed.deployTarget,
       allowFailedPreview: parsed.allowFailedPreview,
+      ...(parsed.handoff === undefined ? {} : { handoff: parsed.handoff }),
+      ...(parsed.reviewPath === undefined ? {} : { reviewPath: parsed.reviewPath }),
+      ...(parsed.since === undefined ? {} : { since: parsed.since }),
       init: parsed.init,
       quiet: parsed.quiet,
       dryRun: parsed.dryRun,

package/src/constants.js

@@ -106,6 +106,12 @@ export const VERB_STAGING_REVIEW = "staging review";
 export const VERB_SITES = "sites";
 export const VERB_USE = "use";
 export const VERB_WHOAMI = "whoami";
+export const VERB_CHANGELOG = "changelog";
+
+/** The command that lists what changed since a version, for the CLI to name after an upgrade (TR01225). */
+export function changelogCommandSince(version) {
+  return `${CLI_BINARY_NAME} ${VERB_CHANGELOG} --since ${version}`;
+}
 export const VERB_PLAN = "plan";
 export const VERB_APPLY = "apply";
 export const VERB_PLACES_SEARCH = "places search";
@@ -256,6 +262,19 @@ export const LIMITS = Object.freeze({
   deploymentMilliseconds: 30 * 60_000,
   previewMilliseconds: 5 * 60_000,
   pollIntervalMilliseconds: 2_000,
+  // How long after a staging deployment completes the edge can still serve the
+  // previous release (TR01236): up to a minute for Workers KV to propagate the
+  // route, plus the Worker's 30-second KV read cache and 30-second isolate cache
+  // (docs/operations/published-site-worker-runbook.md, "Route resolution
+  // freshness budget"). The wait is longer than the ceiling so one slow read does
+  // not turn a propagating release into a false warning.
+  stagingPropagationCeilingSeconds: 120,
+  stagingServedMilliseconds: 180_000,
+  stagingServedPollMilliseconds: 3_000,
+  // Two reads in a row, because each read lands on one cached copy of the route.
+  stagingServedConfirmations: 2,
+  // The review notice sits at the end of the page, so the whole document is read.
+  stagingServedPageBytes: 4 * 1024 * 1024,
   requestAttempts: 4,
   uploadAttempts: 4,
   diagnosticScalars: 2_000,

package/src/errors.js

@@ -130,6 +130,8 @@ export class SiteAuthoringError extends Error {
     this.previewDiagnostic = normalizePreviewDiagnostic(options.previewDiagnostic);
     this.field = typeof options.field === "string" ? sanitizeDiagnostic(options.field, "") : undefined;
     this.status = typeof options.status === "string" ? sanitizeDiagnostic(options.status, "") : undefined;
+    // The site check rule (shared/site-check-rules.json) this refusal comes from, when it comes from one.
+    this.rule = typeof options.rule === "string" && /^[a-z0-9_.]+$/u.test(options.rule) ? options.rule : undefined;
     this.alternatives = Array.isArray(options.alternatives)
       ? options.alternatives
         .filter((value) => typeof value === "string")
@@ -191,6 +193,7 @@ export class SiteAuthoringError extends Error {
         ...(typeof problem.file === "string" ? { file: sanitizeDiagnostic(problem.file, "") } : {}),
         code: /^[a-z0-9_.-]+$/u.test(problem.code) ? problem.code : "site.failed",
         ...(typeof problem.field === "string" ? { field: sanitizeDiagnostic(problem.field, "") } : {}),
+        ...(typeof problem.rule === "string" && /^[a-z0-9_.]+$/u.test(problem.rule) ? { rule: problem.rule } : {}),
         message: sanitizeDiagnostic(problem.message),
       }));
     this.problemCount = list.length;

package/src/footer-contract.js

@@ -278,11 +278,13 @@ function richText(value, path, maximumLength, maximumParagraphs, knownPageResour
       if (text.length === 0) continue;
       totalLength += text.length;
       totalRuns += 1;
+      // A style flag that is off is left out, so a run carries only what it sets and a hand-written
+      // file matches what pull writes (TR01232).
       normalizedRuns.push({
         text,
-        bold: boolean(run.bold, false, `${runPath}.bold`),
-        italic: boolean(run.italic, false, `${runPath}.italic`),
-        underline: boolean(run.underline, false, `${runPath}.underline`),
+        ...(boolean(run.bold, false, `${runPath}.bold`) ? { bold: true } : {}),
+        ...(boolean(run.italic, false, `${runPath}.italic`) ? { italic: true } : {}),
+        ...(boolean(run.underline, false, `${runPath}.underline`) ? { underline: true } : {}),
         ...(run.link === undefined || run.link === null
           ? {}
           : { link: inlineLink(run.link, `${runPath}.link`, knownPageResourceIds, tolerateStoredValues) }),

package/src/forms-workspace.js

@@ -53,6 +53,28 @@ export async function readWorkspaceForms(workspaceDir, keys, validationOptions =
   return forms;
 }
 
+/**
+ * The keys of the form files the workspace holds, read from file names alone (TR01081), or undefined
+ * when the folder cannot be read (a name outside the safe grammar, a link, too many files): the
+ * answer is only a hint for a refusal, so a workspace that cannot say changes nothing, and
+ * `forms validate` reports the folder's problem. A file whose name is not a form key is left out.
+ */
+export async function workspaceFormKeys(workspaceDir) {
+  let files;
+  try {
+    files = await walkWorkspaceFiles(workspaceDir, FORMS_DIRECTORY, [FORM_FILE_EXTENSION]);
+  } catch (error) {
+    if (error instanceof SiteAuthoringError) return undefined;
+    throw error;
+  }
+  const keys = new Set();
+  for (const file of files) {
+    const key = file.slice(FORMS_DIRECTORY.length + 1, -FORM_FILE_EXTENSION.length);
+    if (!key.includes("/") && isFormKey(key)) keys.add(key);
+  }
+  return keys;
+}
+
 /** A form name as the site compares it: trimmed, ignoring case (TR01216). */
 export function comparableFormName(name) {
   return String(name).trim().toLowerCase();

package/src/heading-outline.js

@@ -0,0 +1,76 @@
+// Generated from shared/heading-outline.ts by scripts/sync-field-validation.mjs. Do not edit.
+/**
+ * How a published page numbers its headings (TR00929, TR00946, TR00947).
+ *
+ * The generator renders a page with this state machine, and the page-structure
+ * checks in `page-structure-checks.ts` replay the same machine over a document
+ * to tell an author which element claims the page's `<h1>` and which headings
+ * the publisher renumbers. One owner keeps what the warning says in step with
+ * what ships. The generator's `component-renderer.ts` and the site-authoring
+ * package import copies of this file; `node scripts/sync-field-validation.mjs`
+ * writes them, so edit only this file.
+ *
+ * It is dependency-free so every consumer can carry a copy.
+ */
+export function createHeadingOutlineState(options = {}) {
+    const titleOpen = options.titleOpen === true;
+    const parentLevel = options.parentLevel ?? 1;
+    return { level: parentLevel, titleOpen, titleClaimed: !titleOpen, parentLevel, open: [] };
+}
+// Not `Array.prototype.at`: the editor's TypeScript library predates it.
+function lastOpen(state) {
+    return state.open[state.open.length - 1];
+}
+/**
+ * The level to render an author heading at (TR00946). It closes the open
+ * headings at its authored level or deeper, then sits one level below the
+ * heading still open, so an h3 straight after the page's h1 becomes an h2,
+ * and so do the h3s after it until the author's own h2. A free-form page's
+ * first author h1 is its title; any other h1 is demoted.
+ */
+export function nextHeadingLevel(state, authored) {
+    if (!state)
+        return authored;
+    if (authored === 1 && !state.titleClaimed) {
+        recordFixedHeading(state, 1);
+        return 1;
+    }
+    while ((lastOpen(state)?.authored ?? 0) >= authored)
+        state.open.pop();
+    const level = Math.min(6, (lastOpen(state)?.level ?? state.parentLevel) + 1);
+    state.open.push({ authored, level });
+    state.level = level;
+    return level;
+}
+/** A heading whose level the page fixes, such as a hero title or CTA heading. */
+export function recordFixedHeading(state, level) {
+    if (level === 1)
+        state.titleClaimed = true;
+    while ((lastOpen(state)?.level ?? 0) >= level)
+        state.open.pop();
+    state.open.push({ authored: level, level });
+    state.level = level;
+}
+/**
+ * Whether an Image Banner is the page's title: it opens a free-form page,
+ * shows an image, and carries overlay text. Without an image the overlay is
+ * not drawn, so the banner carries no heading.
+ */
+export function bannerOpensPage(state, data) {
+    return state?.titleOpen === true
+        && Boolean(data.image?.src)
+        && typeof data.overlayText === "string"
+        && data.overlayText.trim() !== "";
+}
+/**
+ * The level of the heading a hero or CTA component fixes on the page, or
+ * undefined when the component carries none. A hero title is always an h1;
+ * a CTA heading is an h2.
+ */
+export function componentFixedHeadingLevel(type, data) {
+    if (type === "hero-section" && data.title)
+        return 1;
+    if (type === "cta" && data.heading)
+        return 2;
+    return undefined;
+}

package/src/index.js

@@ -14,3 +14,4 @@ export {
   getFooterReference,
   getThemeReference,
 } from "./presentation-reference.js";
+export { getSettingsReference } from "./setting-reference.js";

package/src/output.js

@@ -3,12 +3,14 @@ import { constants as fsConstants } from "node:fs";
 import { lstat, open } from "node:fs/promises";
 
 import {
+  changelogCommandSince,
   CLI_BINARY_NAME,
   CLI_NAME,
   CLI_VERSION,
   GITHUB_OUTPUT_KEY_PREFIX,
   GITHUB_OUTPUT_RESULT_KEY,
   LIMITS,
+  REFUSAL_CLI_OUTDATED,
   REFUSAL_UNCLASSIFIED,
   RESULT_SCHEMA_VERSION,
 } from "./constants.js";
@@ -37,6 +39,7 @@ export function failureResult(error) {
     error: { code: error.code },
   };
   if (error.field) result.error.field = error.field;
+  if (error.rule) result.error.rule = error.rule;
   if (error.details?.length) result.error.details = error.details;
   if (error.status) result.error.status = error.status;
   if (Array.isArray(error.alternatives) && error.alternatives.length > 0) {
@@ -67,6 +70,12 @@ export function failureResult(error) {
   if (previewRecovery) result.error.preview = previewRecovery;
   const refusal = typeof error.refusalKind === "function" ? error.refusalKind() : undefined;
   if (typeof refusal === "string" && refusal !== REFUSAL_UNCLASSIFIED) result.error.refusal = refusal;
+  if (refusal === REFUSAL_CLI_OUTDATED) {
+    const latestVersion = typeof error.latestCliVersion === "function" ? error.latestCliVersion() : error.latestVersion;
+    if (typeof latestVersion === "string") result.error.latestVersion = latestVersion;
+    // What to run once the upgrade is done, so the agent need not diff the help topics.
+    result.error.changelogCommand = changelogCommandSince(CLI_VERSION);
+  }
   return result;
 }
 

package/src/page-metadata.js

@@ -1,4 +1,5 @@
 import { SiteAuthoringError } from "./errors.js";
+import { DESCRIPTION_WARN_LENGTH } from "./page-structure-checks.js";
 import { boundedByBytes } from "./session.js";
 import { displayPagePath } from "./workspace.js";
 
@@ -7,7 +8,7 @@ import { displayPagePath } from "./workspace.js";
  * 160 characters search engines cut it off, so it is warned about; past 1000 it
  * is refused, here and by the API (TR01194).
  */
-export const DESCRIPTION_WARN_LENGTH = 160;
+export { DESCRIPTION_WARN_LENGTH };
 export const DESCRIPTION_MAXIMUM_LENGTH = 1000;
 export const PAGE_DESCRIPTION_LONG = "pages.description_long";