@taprootio/site-authoring 0.20.0 → 0.21.0

package/src/verbs/deploy.js

@@ -15,6 +15,7 @@ import {
 import {
   DEPLOY_TARGET_PRODUCTION,
   DEPLOY_TARGET_STAGING,
+  LIMITS,
   REFUSAL_CAPABILITY_MISSING,
   REFUSAL_CREDENTIAL_REJECTED,
   REFUSAL_UNCLASSIFIED,
@@ -23,23 +24,28 @@ import {
 } from "../constants.js";
 import { SiteAuthoringError } from "../errors.js";
 import { boundedList, openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
-import { inspectStagingPreview } from "../staging-check.js";
+import { HANDOFF_NOT_REQUESTED_PROGRESS, handoffNotRequested, inspectStagingPreview } from "../staging-check.js";
+import { confirmStagingServed, readStagingReleaseBefore, unverifiedStagingServed } from "../staging-served.js";
 import { ApiError } from "../transport.js";
 import { readManifest, writeManifest } from "../workspace.js";
 
 /**
- * When a redirect goes live (TR00702, TR00968).
+ * When a redirect goes live (TR00702, TR00968, TR01236).
  *
  * A redirect or gone entry is a file inside the release this deploy publishes.
  * It goes live with that release and no other way: staging shows it as soon as
  * the staged release is served, production shows it when the release is
- * promoted. There is no separate store to wait on, so a check that does not see
- * an entry is looking at a release that does not carry it yet.
+ * promoted. The release itself reaches the edge after the deployment reports
+ * completed: Cloudflare propagates the route and the Worker caches it, so the
+ * previous release can answer for about two minutes (the note below quotes the
+ * ceiling). A check that does not see an entry is looking at a release that is
+ * not served yet.
  */
 const REDIRECT_ACTIVATION_NOTE =
   "Redirect and gone entries live inside the release this deploy publishes: staging serves them with the staged "
-  + "release and production serves them once that release is promoted. There is no separate propagation delay; "
-  + "an entry a check does not see belongs to a release that is not being served yet.";
+  + "release and production serves them once that release is promoted. The edge can keep serving the previous "
+  + `release for up to ${LIMITS.stagingPropagationCeilingSeconds} seconds after a deployment completes, so an entry a `
+  + "check does not see may belong to a release the edge has not switched to yet.";
 
 /**
  * `deploy --staging` / `deploy --production` — readiness, deploy, poll to
@@ -208,9 +214,9 @@ function presentationHandoffUnavailable(error) {
  * It is minted after the deployment completed, bound by the server to the
  * site's exact acknowledged staging host, and single-use like every other.
  */
-async function mintPresentationStagingHandoff(client, siteId, onProgress, now) {
+async function mintPresentationStagingHandoff(client, siteId, onProgress, now, returnPath) {
   try {
-    const handoff = await mintStagingPreviewHandoff(client, siteId, { now });
+    const handoff = await mintStagingPreviewHandoff(client, siteId, { now, returnPath });
     onProgress(`Staging review handoff minted for ${handoff.stagingUrl}. ${PRESENTATION_REVIEW_GUIDANCE}`);
     return { ...handoff, review: PRESENTATION_REVIEW_GUIDANCE };
   } catch (error) {
@@ -387,6 +393,9 @@ export async function deploy(invocation) {
       }
     }
 
+    // The release staging serves now, so the wait after completion can tell when the new one replaces it
+    // (TR01236). A managed Docs site's pages carry no release stamp, so it is not read there.
+    const servedBefore = presentationOnly ? undefined : await readStagingReleaseBefore(client, siteId, now);
     const created = await deploySite(client, siteId, {
       siteId,
       environment: DEPLOYMENT_ENVIRONMENT_STAGING,
@@ -405,8 +414,22 @@ export async function deploy(invocation) {
       now,
     });
     await recordDeployment(config, manifest, "staging", completed);
+    const stagingServed = presentationOnly
+      ? unverifiedStagingServed(now(), "A managed Docs site's staging is not checked for the served release.")
+      : await confirmStagingServed(client, siteId, {
+        before: servedBefore,
+        deploymentId: created.id,
+        coalesced: created.outcome === DEPLOYMENT_REQUEST_OUTCOME_COALESCED,
+        onProgress,
+        now,
+      });
+    if (stagingServed.state !== "served") onProgress(`Warning: ${stagingServed.message}`);
     if (presentationOnly) {
-      const stagingPreview = await mintPresentationStagingHandoff(client, siteId, onProgress, now);
+      // The review URL is a live credential, so it is minted only when asked for (TR01233).
+      if (invocation.handoff !== true) onProgress(HANDOFF_NOT_REQUESTED_PROGRESS);
+      const stagingPreview = invocation.handoff === true
+        ? await mintPresentationStagingHandoff(client, siteId, onProgress, now, invocation.reviewPath)
+        : handoffNotRequested();
       return successResult(VERB_DEPLOY, siteId, {
         target,
         environment: DEPLOYMENT_ENVIRONMENT_STAGING,
@@ -419,11 +442,15 @@ export async function deploy(invocation) {
         deployment: completed,
         outcome: created.outcome,
         readiness: reportReadiness(readiness),
+        stagingServed,
         stagingPreview,
         nextStep: stagingPreview.url === "" ? "staging review" : "deploy --production",
       });
     }
-    const { routeCheck, redirects, stagingPreview } = await inspectStagingPreview(client, siteId, onProgress, now);
+    const { routeCheck, redirects, stagingPreview } = await inspectStagingPreview(client, siteId, onProgress, now, {
+      handoff: invocation.handoff === true,
+      returnPath: invocation.reviewPath,
+    });
     onProgress(REDIRECT_ACTIVATION_NOTE);
     return successResult(VERB_DEPLOY, siteId, {
       target,
@@ -436,6 +463,7 @@ export async function deploy(invocation) {
       deployment: completed,
       outcome: created.outcome,
       readiness: reportReadiness(readiness),
+      stagingServed,
       routeCheck,
       redirects,
       stagingPreview,

package/src/verbs/index.js

@@ -5,6 +5,7 @@ import {
   VERB_AUTHORS_LIST,
   VERB_DELIVERY_CHECK,
   VERB_DEPLOY,
+  VERB_CHANGELOG,
   VERB_ENV,
   VERB_FOOTER_PUSH,
   VERB_FORMS_PULL,
@@ -38,6 +39,7 @@ import {
 } from "../constants.js";
 import { approve } from "./approve.js";
 import { authorsAdd, authorsList } from "./authors.js";
+import { changelog } from "./changelog.js";
 import { deliveryCheck } from "./delivery-check.js";
 import { deploy } from "./deploy.js";
 import { env } from "./env.js";
@@ -174,6 +176,7 @@ export const VERB_HANDLERS = Object.freeze({
   [VERB_USE]: use,
   [VERB_WHOAMI]: whoami,
   [VERB_ENV]: env,
+  [VERB_CHANGELOG]: changelog,
   [VERB_STATUS]: status,
   [VERB_DELIVERY_CHECK]: deliveryCheck,
   [VERB_STAGING_REVIEW]: stagingReview,

package/src/verbs/nav-push.js

@@ -23,6 +23,7 @@ import {
   readWorkspaceJson,
   workspaceFileExists,
   WORKSPACE_LIMITS,
+  writeWorkspaceJson,
 } from "../workspace.js";
 
 /**
@@ -52,7 +53,9 @@ const MAXIMUM_REPORTED = 100;
 const MAXIMUM_ITEMS = 1_000;
 const MAXIMUM_TITLE_LENGTH = 200;
 const MAXIMUM_URL_LENGTH = CONTACT_OR_WEB_URL_MAX_LENGTH;
-const ITEM_KEYS = new Set(["id", "kind", "title", "resourceId", "externalUrl", "children"]);
+// The item keys in the order the workspace file spells them; validation and projection share this list.
+const NAVIGATION_ITEM_KEY_ORDER = Object.freeze(["id", "kind", "title", "resourceId", "externalUrl", "children"]);
+const ITEM_KEYS = new Set(NAVIGATION_ITEM_KEY_ORDER);
 
 // `SaveSiteNavigation` maps both `id` and `resourceId` through
 // `RequestValidation.RequireGuid`. A value that is not a GUID comes back as a
@@ -182,6 +185,36 @@ function validateItem(item, itemPath, depth, seenIds, counters) {
   };
 }
 
+/**
+ * The one workspace spelling of a navigation tree (TR01232): the item keys in a
+ * fixed order, with the fields that only carry a default left out. The API prints
+ * proto3 defaults (`externalUrl: ""`, `children: []`) and `nav push` validates into
+ * the same full shape, so without this a pull after a push rewrote nav.json with
+ * values nobody wrote. Both `pull` and `nav push` write this form, and either form
+ * is accepted on the way in.
+ */
+export function projectNavigationForWorkspace(items) {
+  if (!Array.isArray(items)) return items;
+  return items.map((item) => {
+    if (item === null || typeof item !== "object" || Array.isArray(item)) return item;
+    const projected = {};
+    const keys = [
+      ...NAVIGATION_ITEM_KEY_ORDER.filter((key) => Object.hasOwn(item, key)),
+      ...Object.keys(item).filter((key) => !NAVIGATION_ITEM_KEY_ORDER.includes(key)),
+    ];
+    for (const key of keys) {
+      const value = item[key];
+      if ((key === "resourceId" || key === "externalUrl") && value === "") continue;
+      if (key === "children" && Array.isArray(value)) {
+        if (value.length > 0) projected.children = projectNavigationForWorkspace(value);
+        continue;
+      }
+      projected[key] = value;
+    }
+    return projected;
+  });
+}
+
 function collectIds(items, into = new Set()) {
   for (const item of items) {
     if (item === null || typeof item !== "object") continue;
@@ -325,6 +358,21 @@ export async function navPush(invocation) {
 
     const saved = await saveNavigation(client, siteId, navItems);
     onProgress(`Replaced the navigation tree with ${validated.items} items.`);
+    try {
+      // The file now holds what the site stored, in the form pull writes, so the next pull is byte-identical.
+      const stored = saved.length > 0 || navItems.length === 0 ? saved : navItems;
+      // siteId and navItems first, in pull's order; any other key the author kept follows.
+      const { siteId: _siteId, navItems: _navItems, ...extras } = parsed;
+      await writeWorkspaceJson(config.workspaceDir, NAVIGATION_FILE_NAME, {
+        siteId,
+        navItems: projectNavigationForWorkspace(stored),
+        ...extras,
+      });
+    } catch (error) {
+      // The site already holds the new tree; only the local file is stale, so say the tree was replaced.
+      if (error instanceof SiteAuthoringError) throw error.withCompletedWrites(["navigationTree"]);
+      throw error;
+    }
 
     const removedReport = boundedList(removed, MAXIMUM_REPORTED);
     const addedReport = boundedList(added, MAXIMUM_REPORTED);

package/src/verbs/pull.js

@@ -23,6 +23,7 @@ import { appearanceManifestEntry, footerManifestEntry, presentationManifestEntry
 import { describeJsonDifferences, reportableDifferencePaths } from "../json-path-diff.js";
 import { projectRedirectMapForWorkspace, REDIRECTS_FILE_NAME } from "../redirects-contract.js";
 import { redirectsManifestEntry } from "../redirects-workspace.js";
+import { projectNavigationForWorkspace } from "./nav-push.js";
 import { boundedList, openSession, successResult } from "../session.js";
 import {
   projectSettingsGroup,
@@ -1314,7 +1315,10 @@ export async function pull(invocation) {
     if (!presentationOnly) {
       onProgress("Reading the navigation tree.");
       navItems = await getNavigation(client, siteId);
-      await writeWorkspaceJson(config.workspaceDir, NAVIGATION_FILE_NAME, { siteId, navItems });
+      await writeWorkspaceJson(config.workspaceDir, NAVIGATION_FILE_NAME, {
+        siteId,
+        navItems: projectNavigationForWorkspace(navItems),
+      });
     }
 
     if (redirectMap !== undefined) {

package/src/verbs/redirects-check.js

@@ -6,7 +6,10 @@ import { inspectStagingPreview } from "../staging-check.js";
 export async function redirectsCheck(invocation) {
   const { client, siteId, onProgress, now } = await openSession(invocation);
   return await withRefusalGuidance(onProgress, "staging redirects", async () => {
-    const { routeCheck, redirects, stagingPreview } = await inspectStagingPreview(client, siteId, onProgress, now);
+    const { routeCheck, redirects, stagingPreview } = await inspectStagingPreview(client, siteId, onProgress, now, {
+      handoff: invocation.handoff === true,
+      returnPath: invocation.reviewPath,
+    });
     return successResult(VERB_REDIRECTS_CHECK, siteId, { routeCheck, redirects, stagingPreview });
   });
 }

package/src/verbs/staging-review.js

@@ -20,7 +20,7 @@ export async function stagingReview(invocation) {
   const { client, siteId, now, onProgress } = await openSession(invocation);
   return await withRefusalGuidance(onProgress, "staging review", async () => {
     onProgress("Minting a fresh single-use staging review handoff.");
-    const handoff = await mintStagingPreviewHandoff(client, siteId, { now });
+    const handoff = await mintStagingPreviewHandoff(client, siteId, { now, returnPath: invocation.reviewPath });
     onProgress(`Staging review handoff minted for ${handoff.stagingUrl}. ${STAGING_REVIEW_GUIDANCE}`);
     return successResult(VERB_STAGING_REVIEW, siteId, {
       stagingPreview: { ...handoff, review: STAGING_REVIEW_GUIDANCE },

package/src/verbs/status.js

@@ -1,15 +1,17 @@
 import {
   getDeploySelection,
   getPublishingReadiness,
-  getSiteBrokenReferences,
+  getSiteHealth,
   IMAGE_PROCESSING_STATE_COMPLETE,
   IMAGE_PROCESSING_STATE_FAILED,
   listDeployments,
   listSiteImages,
   withRefusalGuidance,
 } from "../api.js";
+import { installedWhatsNew } from "../changelog.js";
 import { isBehindLatest } from "../cli-release.js";
 import {
+  changelogCommandSince,
   CLI_UPGRADE_COMMAND,
   CLI_VERSION,
   EXTERNAL_WRITES_SETTING_KEY,
@@ -24,13 +26,12 @@ import { boundedList, openSession, successResult } from "../session.js";
 
 /**
  * `status` — the platform authoring switch, CLI release, deployments,
- * publishing readiness, image processing, and broken-reference pages.
+ * publishing readiness, image processing, and the site checks' findings.
  */
 const MAXIMUM_DEPLOYMENTS = 20;
 const MAXIMUM_FAILED_IMAGES = 50;
 const MAXIMUM_BLOCKERS = 50;
-const MAXIMUM_BROKEN_REFERENCE_PAGES = 50;
-const MAXIMUM_MISSING_TARGETS = 50;
+const MAXIMUM_HEALTH_FINDINGS = 100;
 
 const PLATFORM_UNKNOWN_NOTE =
   "Taproot never reported the platform authoring switch on this run: either no sign-in token exchange happened "
@@ -61,9 +62,15 @@ const CLI_RELEASE_UNKNOWN_NOTE =
  */
 function reportCliRelease(release, onProgress) {
   const latestVersion = release?.latestVersion;
+  // The installed release's one-line note, from the same record `changelog` prints.
+  const whatsNew = installedWhatsNew();
+  const whatsNewField = whatsNew === undefined ? {} : { whatsNew };
+  if (whatsNew !== undefined) {
+    onProgress(`What's new in ${CLI_VERSION}: ${whatsNew.note} ('${changelogCommandSince("<version>")}' lists the details.)`);
+  }
   if (latestVersion === undefined) {
     onProgress(`CLI release: ${CLI_VERSION}. Latest not known on this run. ${CLI_RELEASE_UNKNOWN_NOTE}`);
-    return { version: CLI_VERSION, latestKnown: false, reason: CLI_RELEASE_UNKNOWN_NOTE };
+    return { version: CLI_VERSION, latestKnown: false, reason: CLI_RELEASE_UNKNOWN_NOTE, ...whatsNewField };
   }
   const behind = isBehindLatest(latestVersion);
   onProgress(
@@ -71,9 +78,16 @@ function reportCliRelease(release, onProgress) {
       ? `CLI release: ${CLI_VERSION} is BEHIND the latest published release ${latestVersion}, and Taproot accepts `
         + `only the latest, so every online verb is refused (refusal=${REFUSAL_CLI_OUTDATED}). Upgrade with: `
         + CLI_UPGRADE_COMMAND
+        + `. Once upgraded, run '${changelogCommandSince(CLI_VERSION)}' to see what changed.`
       : `CLI release: ${CLI_VERSION}; latest published release ${latestVersion}.`,
   );
-  return { version: CLI_VERSION, latestVersion, behind };
+  return {
+    version: CLI_VERSION,
+    latestVersion,
+    behind,
+    ...whatsNewField,
+    ...(behind ? { changelogCommand: changelogCommandSince(CLI_VERSION) } : {}),
+  };
 }
 
 /**
@@ -104,12 +118,12 @@ function reportPlatform(platform, onProgress) {
 /**
  * What a managed Docs site's status leaves out (TR00790), said the same way
  * the platform switch says "unknown": by shape. The image library and the
- * broken-reference report are page-authoring reads a Docs site refuses, so
+ * site-health read are page-authoring reads a Docs site refuses, so
  * they are reported as not covered rather than as empty — an automation
  * reading `failed: 0` off a report that was never made would be reading a lie.
  */
 const DOCS_SITE_NOT_COVERED_NOTE =
-  "This is a managed Docs site: its pages come from the Docs artifact, so the image library and broken-reference "
+  "This is a managed Docs site: its pages come from the Docs artifact, so the image library and site-health "
   + "reads do not apply and were not made.";
 
 export async function status(invocation) {
@@ -144,25 +158,14 @@ export async function status(invocation) {
     let images = [];
     let summary = { totalImages: 0, processingImages: 0 };
     let truncated = false;
-    let brokenReferencePages = [];
+    let health = { findings: [], errorCount: 0, warningCount: 0, pageCount: 0, truncated: false };
     if (!presentationOnly) {
       onProgress("Reading image processing state.");
       ({ images, summary, truncated } = await listSiteImages(client, siteId));
-      onProgress("Reading broken references.");
-      brokenReferencePages = await getSiteBrokenReferences(client, siteId);
+      onProgress("Reading site health.");
+      health = await getSiteHealth(client, siteId);
     }
-    const reportedBrokenPages = boundedList(brokenReferencePages, MAXIMUM_BROKEN_REFERENCE_PAGES);
-    const brokenPages = reportedBrokenPages.items.map((page) => {
-      const images = boundedList(page.missingImageIds, MAXIMUM_MISSING_TARGETS);
-      const paths = boundedList(page.missingPagePaths, MAXIMUM_MISSING_TARGETS);
-      return {
-        ...page,
-        missingImageIds: images.items,
-        missingPagePaths: paths.items,
-        ...(images.truncated ? { missingImageIdsTruncated: true } : {}),
-        ...(paths.truncated ? { missingPagePathsTruncated: true } : {}),
-      };
-    });
+    const reportedFindings = boundedList(health.findings, MAXIMUM_HEALTH_FINDINGS);
 
     const byState = {};
     for (const image of images) {
@@ -182,7 +185,9 @@ export async function status(invocation) {
     const blockers = boundedList(readiness.blockers, MAXIMUM_BLOCKERS);
 
     if (!presentationOnly) {
-      onProgress(`Broken references: ${brokenReferencePages.length} page(s) with missing targets.`);
+      onProgress(
+        `Site health: ${health.errorCount} problem(s) and ${health.warningCount} warning(s) on ${health.pageCount} page(s).`,
+      );
     }
 
     return successResult(VERB_STATUS, siteId, {
@@ -221,11 +226,13 @@ export async function status(invocation) {
         ...(failedImages.truncated ? { failedItemsTruncated: true } : {}),
         ...(truncated ? { listTruncated: true } : {}),
       },
-      brokenReferences: presentationOnly ? { covered: false, reason: DOCS_SITE_NOT_COVERED_NOTE } : {
+      siteHealth: presentationOnly ? { covered: false, reason: DOCS_SITE_NOT_COVERED_NOTE } : {
         covered: true,
-        totalPages: brokenReferencePages.length,
-        pages: brokenPages,
-        ...(reportedBrokenPages.truncated ? { pagesTruncated: true } : {}),
+        errors: health.errorCount,
+        warnings: health.warningCount,
+        pages: health.pageCount,
+        findings: reportedFindings.items,
+        ...(reportedFindings.truncated || health.truncated ? { findingsTruncated: true } : {}),
       },
     });
   });

package/src/verbs/validate.js

@@ -22,6 +22,7 @@ import { authorWarnings, descriptionWarnings } from "../page-metadata.js";
 import { CHECK_AREA, collectProblems, refuseProblems } from "../problems.js";
 import { isRedirectMapRevision, REDIRECT_KIND_GONE, REDIRECTS_FILE_NAME } from "../redirects-contract.js";
 import { boundedList, successResult } from "../session.js";
+import { evaluateOfflineSiteChecks } from "../site-check-findings.js";
 import { SETTINGS_GROUPS } from "../settings-catalog.js";
 import { checkWorkspace } from "../workspace-check.js";
 import {
@@ -648,6 +649,20 @@ function pageHints(checked, onProgress) {
   return hints;
 }
 
+/**
+ * The offline site checks (TR01085) over the planned pages: the rules the shared
+ * catalogue lists for `validate`, with the rest named as checked by the site.
+ */
+function offlineSiteChecks(checked, manifest, onProgress) {
+  if (checked.settingsOnly) return {};
+  return evaluateOfflineSiteChecks({
+    planned: checked.pages?.planned,
+    pagePaths: manifest.pages.map((entry) => normalizePagePath(entry?.path)).filter((value) => value !== undefined),
+    pagesComplete: manifest.pagesTruncated !== true,
+    onProgress,
+  });
+}
+
 export async function validateFixture(invocation = {}) {
   if (invocation.init) return await initializeFixture(invocation, validateFixture);
   const onProgress = typeof invocation.onProgress === "function" ? invocation.onProgress : () => {};
@@ -736,6 +751,7 @@ export async function validateFixture(invocation = {}) {
     ...autolinkWarnings(checked.pages?.planned, onProgress),
     ...descriptionWarnings(checked.pages?.planned, onProgress),
     ...authorWarnings(checked.pages?.planned, onProgress),
+    ...offlineSiteChecks(checked, manifest, onProgress),
   };
   onProgress(
     `Validated ${validatedPages.length} page(s), ${checked.navigation.items} navigation item(s), two themes, appearance, and footer without credentials or mutation.`,
@@ -765,6 +781,8 @@ export async function validateFixture(invocation = {}) {
       "credential authorization or live site ownership",
       "remote concurrency or current revisions",
       "server normalization and pull round trips",
+      "the site checks listed in siteChecks.checkedBySite (images, forms), which 'taproot-site status' reports under "
+        + "siteHealth, or siteChecks.checkedAtDeploy, which only a deploy applies",
       "preview or published rendering",
     ],
     nextStep: "Run a real pull and authorized preview before approval or deployment.",
@@ -801,6 +819,7 @@ async function validatePulledWorkspace(workspaceDir, siteId, invocation, onProgr
       ...autolinkWarnings(checked.pages.planned, onProgress),
       ...descriptionWarnings(checked.pages.planned, onProgress),
       ...authorWarnings(checked.pages.planned, onProgress),
+      ...offlineSiteChecks(checked, manifest, onProgress),
     };
   onProgress(
     checked.settingsOnly
@@ -826,6 +845,8 @@ async function validatePulledWorkspace(workspaceDir, siteId, invocation, onProgr
       "credential authorization or live site ownership",
       "pages, revisions, or videos that changed on the site since the pull",
       "server normalization and pull round trips",
+      "the site checks listed in siteChecks.checkedBySite (images, forms), which 'taproot-site status' reports under "
+        + "siteHealth, or siteChecks.checkedAtDeploy, which only a deploy applies",
       "preview or published rendering",
     ],
     nextStep: "Run 'taproot-site plan' to check the workspace against the live site and see the ordered apply.",