@taprootio/site-authoring 0.19.0 → 0.21.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,12 @@ 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; 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 +209,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"],
@@ -239,7 +263,9 @@ const VERBS = Object.freeze([
       + "and announced on the human channel. New downloads and compared bodies are excluded. "
       + "A page Taproot generates (a tag, an archive, a place, a folder) is pulled as an update-only '.pm.json' "
       + "(template 'generated'): you edit its custom title, breadcrumb title, custom description and introduction, "
-      + "and the manifest keeps the title and description the site reports.",
+      + "and the manifest keeps the title and description the site reports. "
+      + "A form a page places is written back by its key, the name 'forms/<key>.json' uses, though the site stores "
+      + "the form's id.",
   },
   {
     name: VERB_PAGES_META_SET,
@@ -305,6 +331,8 @@ const VERBS = Object.freeze([
     positionals: "pagePaths",
     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. "
       + "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 "
@@ -394,7 +422,7 @@ const VERBS = Object.freeze([
     capabilities: [CAPABILITY_CONTENT, CAPABILITY_DESIGN],
     tokens: ["plan"],
     summary: "Check the whole workspace against the live site and order what is left to send. Writes nothing.",
-    note: "Runs every check the pushes run — each page against the site's pages, revisions and videos; media that "
+    note: "Runs every check the pushes run — each page against the site's pages, revisions, videos and forms; media that "
       + "pages reference and media upload has not sent; the theme, appearance and footer colors against the site's "
       + "presentation revision; the footer against its draft; navigation against the live page list — and lists "
       + "every problem with its area, file, code and field. It then orders the steps that remain: media upload, "
@@ -436,9 +464,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,
@@ -585,11 +616,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,
@@ -649,20 +688,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.",
   },
 ]);
@@ -729,7 +771,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.
 
@@ -813,6 +856,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.
@@ -903,7 +958,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}
 `;
 }
 
@@ -964,6 +1019,7 @@ function parseReferenceArguments(arguments_) {
       || topic === "preview"
       || topic === "theme"
       || topic === "appearance"
+      || topic === "settings"
       || topic === "footer"
       || topic === "fixture"
       || topic === "redirects"
@@ -1066,6 +1122,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:
@@ -1245,6 +1303,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;
@@ -1310,6 +1371,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;
@@ -1390,6 +1487,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",
@@ -1503,6 +1610,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 }),
@@ -1595,6 +1705,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/content/components.js

@@ -352,11 +352,14 @@ const SPACER = Object.freeze({
 
 /**
  * A form defined under Site → Forms (or with `forms push`), placed by key. The
- * key is checked against the site's forms when the page is published, not here:
- * this table only knows the shape.
+ * workspace names a form by its key so the same files push to any site; the site
+ * stores the form's id, and `pages push` and `pages pull` translate between the
+ * two (TR01216). The key is checked against the site's forms when the page is
+ * pushed, not here: this table only knows the shape.
  */
 const FORM = Object.freeze({
-  formKey: str(),
+  // Required: a placement with no form chosen can never publish, so it is refused here, not at deploy.
+  formKey: str({ required: true, nonWhitespace: true }),
 });
 
 function deepFreeze(value) {
@@ -648,9 +651,9 @@ const COMPONENT_DEFINITIONS = Object.freeze({
     FORM,
     "Form",
     "A form from Site → Forms that visitors fill in and submit.",
-    { formKey: "" },
+    {},
     [
-      "Set formKey to the key of an existing form ('forms push' creates it); an unknown or archived key fails the publish.",
+      "Set formKey to the key of an existing form ('forms push' creates it); 'pages push' refuses an unknown or archived key, and the site stores the form's id, not the key.",
       "The button text and what happens after a response is sent belong to the form, not the page: set submit_label and after_submit in the form's file (see 'help forms').",
       "The form's field labels are its accessible names; write each so it makes sense out of context.",
     ],

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/form-references.js

@@ -0,0 +1,103 @@
+import { listSiteForms } from "./forms-api.js";
+import { contentDocuments, parseComponentData } from "./typed-pages.js";
+
+/**
+ * Where the workspace and the site spell a placed form differently (TR01216).
+ *
+ * A workspace names a form by its key, as `forms/<key>.json` and the Markdown
+ * `form` fence do, so the same workspace can be pushed to a fresh site whose
+ * ids all differ. A page stored on the site names the form by its id. `pages
+ * push` turns keys into ids on the way out and `pages pull` turns ids back
+ * into keys, the way a form's `page_path` and `page_resource_id` already
+ * translate. The translation is block-scoped: a `formKey` anywhere but a `form`
+ * component block is author prose.
+ */
+
+const FORM_COMPONENT = "form";
+
+/** Each `form` component block in the document's content documents, with its parsed data. */
+function formBlocks(document_) {
+  const found = [];
+  const visit = (value) => {
+    if (Array.isArray(value)) {
+      value.forEach(visit);
+    } else if (value !== null && typeof value === "object") {
+      if (value.type === "componentBlock" && value.attrs?.componentType === FORM_COMPONENT) {
+        const data = typeof value.attrs.componentData === "string"
+          ? parseComponentData(value.attrs.componentData)
+          : undefined;
+        if (data !== null && typeof data === "object" && !Array.isArray(data)) found.push({ attrs: value.attrs, data });
+        return;
+      }
+      Object.values(value).forEach(visit);
+    }
+  };
+  for (const { doc } of contentDocuments(document_)) visit(doc);
+  return found;
+}
+
+/** The distinct form keys a workspace document places, in document order. */
+export function placedFormKeys(document_) {
+  const keys = [];
+  for (const { data } of formBlocks(document_)) {
+    if (typeof data.formKey === "string" && data.formKey !== "" && !keys.includes(data.formKey)) keys.push(data.formKey);
+  }
+  return keys;
+}
+
+/** Whether a document read from the site places any form by id. */
+export function placesFormIds(document_) {
+  return formBlocks(document_).some(({ data }) => typeof data.formId === "string");
+}
+
+/**
+ * A copy of the document with every placed form named by id, for the wire. A key
+ * the index does not know is left as it is: `placedFormProblems` has already
+ * refused the push for it, so nothing sends it.
+ */
+export function withFormIds(document_, idByKey) {
+  return translate(document_, (data) => {
+    const id = typeof data.formKey === "string" ? idByKey.get(data.formKey) : undefined;
+    if (id === undefined) return undefined;
+    const rest = { ...data };
+    delete rest.formKey;
+    return { ...rest, formId: id };
+  });
+}
+
+/**
+ * A copy of a document read from the site with every placed form named by key,
+ * for the workspace. An id the site no longer has stays an id: pull must not hide
+ * what the site holds, and a push of that file is refused until the author picks a form.
+ */
+export function withFormKeys(document_, keyById) {
+  return translate(document_, (data) => {
+    const key = typeof data.formId === "string" ? keyById.get(data.formId) : undefined;
+    if (key === undefined) return undefined;
+    const rest = { ...data };
+    delete rest.formId;
+    return { ...rest, formKey: key };
+  });
+}
+
+function translate(document_, convert) {
+  const copy = structuredClone(document_);
+  for (const { attrs, data } of formBlocks(copy)) {
+    const converted = convert(data);
+    if (converted !== undefined) attrs.componentData = JSON.stringify(converted);
+  }
+  return copy;
+}
+
+/** The site's forms by key and by id, archived ones marked. One request serves a whole push or pull. */
+export async function readFormIndex(client, siteId) {
+  const idByKey = new Map();
+  const keyById = new Map();
+  const archivedKeys = new Set();
+  for (const form of await listSiteForms(client, siteId)) {
+    keyById.set(form.id, form.key);
+    if (form.archived) archivedKeys.add(form.key);
+    else idByKey.set(form.key, form.id);
+  }
+  return { idByKey, keyById, archivedKeys };
+}

package/src/forms-workspace.js

@@ -49,9 +49,33 @@ export async function readWorkspaceForms(workspaceDir, keys, validationOptions =
     const document_ = await readWorkspaceJson(workspaceDir, file, FORM_LIMITS.fileBytes);
     forms.push({ key, file, document: validateFormDocument(document_, key, validationOptions) });
   }
+  requireDistinctNames(forms);
   return forms;
 }
 
+/** A form name as the site compares it: trimmed, ignoring case (TR01216). */
+export function comparableFormName(name) {
+  return String(name).trim().toLowerCase();
+}
+
+/** Names are unique per site, so two files in one push cannot share one. */
+function requireDistinctNames(forms) {
+  const seen = new Map();
+  for (const form of forms) {
+    const name = comparableFormName(form.document.name);
+    const other = seen.get(name);
+    if (other !== undefined) {
+      throw new SiteAuthoringError(
+        "forms.name_duplicate",
+        `${form.file} and ${other} both name the form '${form.document.name}'. A form name is unique on a site, `
+          + "ignoring case; rename one of them.",
+        { field: `${form.file}:name` },
+      );
+    }
+    seen.set(name, form.file);
+  }
+}
+
 /**
  * The forms baseline in the pull manifest (TR01061).
  *

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;
 }