@taprootio/site-authoring 0.6.3 → 0.7.0

package/src/transport.js

@@ -22,7 +22,7 @@ import {
   ROLLOUT_REFUSAL_FIELD,
 } from "./constants.js";
 import { validateApiBaseUrl } from "./config.js";
-import { hasControlCharacter, SiteAuthoringError } from "./errors.js";
+import { hasControlCharacter, sanitizeDiagnostic, SiteAuthoringError } from "./errors.js";
 
 // Every method the authoring verbs need. `pages push` updates with PATCH, page
 // deletion is DELETE, and `nav push` replaces the whole tree with PUT.
@@ -401,15 +401,24 @@ export class ApiError extends SiteAuthoringError {
     const grpcCode = Number.isSafeInteger(body?.code) ? body.code : undefined;
     const fields = fieldViolations(body);
     const capability = capabilityRefusal(body);
+    // Only the known upgrade refusal may supply a human message. Other server
+    // errors can contain internal diagnostics and retain their generic output.
+    const upgradeMessage = fields.includes(CLI_UPGRADE_REFUSAL_FIELD)
+      && typeof body?.message === "string"
+      && body.message.length > 0
+      && body.message.length <= LIMITS.diagnosticScalars
+      && !hasControlCharacter(body.message)
+      ? sanitizeDiagnostic(body.message, "")
+      : undefined;
     super(
       "api.request_rejected",
-      fields.length > 0
+      upgradeMessage || (fields.length > 0
         ? `Taproot rejected the request field '${fields[0]}'.`
         : capability !== undefined
         ? `Taproot refused the request: this credential does not carry a capability granting '${
           capability.permission
         }'.`
-        : `Taproot rejected the request with HTTP ${httpStatus}.`,
+        : `Taproot rejected the request with HTTP ${httpStatus}.`),
       {
         // `fields` stays exactly what the wire named. The capability field is
         // the CLI's own label for a refusal that carries no field violation at

package/src/verbs/deploy.js

@@ -3,22 +3,17 @@ import {
   DEPLOYMENT_ENVIRONMENT_STAGING,
   DEPLOYMENT_STATUS_COMPLETED,
   deploySite,
+  getDeploySelection,
   getPublishingReadiness,
-  getStagingPreviewStatus,
   listDeployments,
-  listSitePages,
-  PAGE_STATUS_APPROVED,
+  mintStagingPreviewHandoff,
   waitForDeployment,
   withRefusalGuidance,
 } from "../api.js";
-import {
-  DEPLOY_TARGET_PRODUCTION,
-  DEPLOY_TARGET_STAGING,
-  VERB_DEPLOY,
-} from "../constants.js";
+import { DEPLOY_TARGET_PRODUCTION, DEPLOY_TARGET_STAGING, VERB_DEPLOY } from "../constants.js";
 import { SiteAuthoringError } from "../errors.js";
 import { boundedList, openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
-import { CANDIDATE_SELECTABLE_SETTINGS_TYPES } from "../settings-catalog.js";
+import { checkStagingRedirects } from "../staging-check.js";
 import { readManifest, writeManifest } from "../workspace.js";
 
 /**
@@ -46,7 +41,7 @@ const REDIRECT_PROPAGATION_NOTE =
  * completion.
  *
  * Staging publishes a *candidate*: approved pages, navigation, and the
- * candidate-selectable settings groups. The server refuses an empty candidate,
+ * changed candidate-selectable settings groups. The server refuses an empty candidate,
  * so the CLI refuses it first and says what to do about it.
  *
  * Production is a promotion and only a promotion. `DeploySite` rejects a
@@ -68,7 +63,6 @@ const REDIRECT_PROPAGATION_NOTE =
  */
 
 const MAXIMUM_REPORTED_BLOCKERS = 50;
-const STAGING_ROUTE_PROBE_MILLISECONDS = 5_000;
 // Staged page ids ride in the readiness query string, so a very large candidate
 // is checked at site level instead of pushing an unbounded URL at the API.
 const MAXIMUM_READINESS_PAGE_IDS = 100;
@@ -91,13 +85,6 @@ function explicitSelection(invocation) {
   return { stagedPageIds, selectedSettingsTypes, includeNavigation, present };
 }
 
-function manifestSettingsTypes(manifest) {
-  const pulled = Array.isArray(manifest?.settings)
-    ? manifest.settings.map((entry) => entry?.settingsType).filter((value) => typeof value === "string")
-    : [];
-  return CANDIDATE_SELECTABLE_SETTINGS_TYPES.filter((type) => pulled.includes(type));
-}
-
 async function recordDeployment(config, manifest, key, deployment) {
   if (manifest === undefined) return;
   manifest.deployments = { ...(manifest.deployments ?? {}) };
@@ -139,78 +126,35 @@ function reportReadiness(readiness) {
     selectedPageCount: readiness.selectedPageCount,
     blockedPageCount: readiness.blockedPageCount,
     hasCandidateChanges: readiness.hasCandidateChanges,
+    hasSuccessfulStagingDeployment: readiness.hasSuccessfulStagingDeployment,
     blockers: blockers.items,
     ...(blockers.truncated ? { blockersTruncated: true } : {}),
   };
 }
 
-function stagingWarning(message) {
-  return { routeCheck: "unresolved", warning: message };
-}
-
-async function inspectStagingPreview(client, siteId, onProgress) {
-  let status;
+async function inspectStagingPreview(client, siteId, onProgress, now) {
+  let checks;
   try {
-    status = await getStagingPreviewStatus(client, siteId);
-  } catch {
-    const warning = "The staging deployment completed, but Taproot could not report its staging URL."
-      + " Check the site's staging-host configuration before treating the deployment as viewable.";
-    onProgress(`Warning: ${warning}`);
-    return { url: "", ...stagingWarning(warning) };
-  }
-  if (!status.ready) {
-    const warning = "The staging deployment completed, but Taproot does not report a ready staging URL.";
-    onProgress(`Warning: ${warning}`);
-    return { url: "", ...stagingWarning(warning) };
-  }
-
-  const stagingUrl = status.stagingUrl;
-  onProgress(`Staging URL: ${stagingUrl}`);
-  let response;
-  try {
-    const timeout = client.timeoutSignal(STAGING_ROUTE_PROBE_MILLISECONDS);
-    const signal = client.signal ? AbortSignal.any([client.signal, timeout]) : timeout;
-    response = await client.fetch(stagingUrl, {
-      method: "GET",
-      redirect: "manual",
-      signal,
-      headers: {
-        accept: "text/html",
-        "user-agent": "taproot-site/staging-route-check",
-      },
-    });
+    checks = await checkStagingRedirects(client, siteId, onProgress, now);
+    if (!checks.redirects.verified) {
+      onProgress(
+        "Warning: staging redirects are not all verified. Edge propagation may still be pending; run 'taproot-site redirects check' again.",
+      );
+    }
   } catch {
-    const warning = `The staging deployment completed at ${stagingUrl}, but the host could not be reached.`;
-    onProgress(`Warning: ${warning}`);
-    return { url: stagingUrl, ...stagingWarning(warning) };
+    onProgress(
+      "Warning: the deployment completed, but authenticated staging redirect checks could not finish. Run 'taproot-site redirects check' again.",
+    );
+    checks = { routeCheck: "unresolved", redirects: { verified: false, covered: false } };
   }
-
-  const location = response.headers.get("location");
-  await response.body?.cancel().catch(() => {});
-  let handoff;
   try {
-    handoff = location ? new URL(location, stagingUrl) : undefined;
+    // Mint after checks so the final single-use URL has never been consumed.
+    const handoff = await mintStagingPreviewHandoff(client, siteId, { now });
+    return { ...checks, ...handoff };
   } catch {
-    handoff = undefined;
+    onProgress("Warning: the deployment completed, but a staging handoff could not be minted.");
+    return { ...checks, url: "", warning: "Staging handoff unavailable; run redirects check to retry." };
   }
-  const stagingHost = new URL(stagingUrl).hostname;
-  const resolvesToSite = response.status >= 300
-    && response.status < 400
-    && handoff?.protocol === "https:"
-    && handoff.username === ""
-    && handoff.password === ""
-    && handoff.hash === ""
-    && handoff.pathname === "/api/v1/staging-preview/handoff"
-    && handoff.searchParams.getAll("siteId").length === 1
-    && handoff.searchParams.get("siteId") === siteId
-    && handoff.searchParams.getAll("host").length === 1
-    && handoff.searchParams.get("host") === stagingHost;
-  if (resolvesToSite) return { url: stagingUrl, routeCheck: "resolved" };
-
-  const warning = `The staging deployment completed at ${stagingUrl}, but the host returned HTTP ${response.status}`
-    + " instead of this site's staging gate. The deployment artifacts are complete, but the URL is not viewable.";
-  onProgress(`Warning: ${warning}`);
-  return { url: stagingUrl, ...stagingWarning(warning) };
 }
 
 export async function deploy(invocation) {
@@ -248,6 +192,7 @@ export async function deploy(invocation) {
         siteId,
         environment: DEPLOYMENT_ENVIRONMENT_PRODUCTION,
         stagingDeploymentId,
+        ...(invocation.allowFailedPreview === true ? { allowFailedPreview: true } : {}),
       });
       onProgress(`Production deployment ${created.id} accepted; waiting for it to complete.`);
       const completed = await waitForDeployment(client, {
@@ -268,28 +213,16 @@ export async function deploy(invocation) {
       });
     }
 
-    onProgress("Listing approved pages for the staging candidate.");
-    const { pages, truncated } = await listSitePages(client, siteId, { onProgress });
-    if (truncated) {
-      // The candidate is built from this list, so a partial one silently
-      // publishes a subset of what was approved — and the deployment that
-      // follows reports success.
-      throw new SiteAuthoringError(
-        "deploy.live_list_truncated",
-        "The site has more pages than this CLI can enumerate, so the staging candidate would omit approved "
-          + "pages without saying so. Nothing was deployed.",
-        { field: "stagedPageIds" },
-      );
-    }
-    const stagedPageIds = selection.stagedPageIds
-      ?? pages.filter((summary) => summary.status === PAGE_STATUS_APPROVED).map((summary) => summary.pageId);
-    const selectedSettingsTypes = selection.selectedSettingsTypes ?? manifestSettingsTypes(manifest);
-    const includeNavigation = selection.includeNavigation ?? manifest?.navigation !== undefined;
+    onProgress("Reading the changed release set shown on the Deployments page.");
+    const defaults = await getDeploySelection(client, siteId);
+    const stagedPageIds = selection.stagedPageIds ?? defaults.stagedPageIds;
+    const selectedSettingsTypes = selection.selectedSettingsTypes ?? defaults.selectedSettingsTypes;
+    const includeNavigation = selection.includeNavigation ?? defaults.includeNavigation;
     if (stagedPageIds.length === 0 && selectedSettingsTypes.length === 0 && !includeNavigation) {
       throw new SiteAuthoringError(
         "deploy.empty_selection",
         "A staging deployment needs at least one approved page, settings group, or navigation change. "
-          + "Run 'taproot-site approve' (and 'taproot-site pull' to pick up navigation and settings) first.",
+          + "Run 'taproot-site approve' or change staged settings/navigation first.",
         { field: "Candidate" },
       );
     }
@@ -301,8 +234,8 @@ export async function deploy(invocation) {
     };
     onProgress(
       `Checking publishing readiness for ${stagedPageIds.length} page(s), `
-      + `${selectedSettingsTypes.length} settings group(s), `
-      + `navigation ${includeNavigation ? "included" : "excluded"}.`,
+        + `${selectedSettingsTypes.length} settings group(s), `
+        + `navigation ${includeNavigation ? "included" : "excluded"}.`,
     );
     const readiness = await getPublishingReadiness(client, siteId, {
       ...candidate,
@@ -325,6 +258,7 @@ export async function deploy(invocation) {
       siteId,
       environment: DEPLOYMENT_ENVIRONMENT_STAGING,
       ...candidate,
+      ...(invocation.allowFailedPreview === true ? { allowFailedPreview: true } : {}),
     });
     onProgress(`Staging deployment ${created.id} accepted; waiting for it to complete.`);
     const completed = await waitForDeployment(client, {
@@ -335,7 +269,7 @@ export async function deploy(invocation) {
       now,
     });
     await recordDeployment(config, manifest, "staging", completed);
-    const stagingPreview = await inspectStagingPreview(client, siteId, onProgress);
+    const stagingPreview = await inspectStagingPreview(client, siteId, onProgress, now);
     onProgress(REDIRECT_PROPAGATION_NOTE);
     return successResult(VERB_DEPLOY, siteId, {
       target,
@@ -348,7 +282,7 @@ export async function deploy(invocation) {
       deployment: completed,
       readiness: reportReadiness(readiness),
       stagingPreview,
-      nextStep: "deploy --production",
+      nextStep: stagingPreview.redirects?.verified === true ? "deploy --production" : "redirects check",
     });
   });
 }

package/src/verbs/index.js

@@ -11,6 +11,7 @@ import {
   VERB_PREVIEW_PAGE,
   VERB_PREVIEW_REVOKE,
   VERB_PULL,
+  VERB_REDIRECTS_CHECK,
   VERB_REDIRECTS_PULL,
   VERB_REDIRECTS_PUSH,
   VERB_SITES,
@@ -29,9 +30,10 @@ import { logout } from "./logout.js";
 import { mediaUpload } from "./media-upload.js";
 import { navPush } from "./nav-push.js";
 import { pagesPush } from "./pages-push.js";
-import { pull } from "./pull.js";
 import { previewPage } from "./preview-page.js";
 import { previewRevoke } from "./preview-revoke.js";
+import { pull } from "./pull.js";
+import { redirectsCheck } from "./redirects-check.js";
 import { redirectsPull } from "./redirects-pull.js";
 import { redirectsPush } from "./redirects-push.js";
 import { sites } from "./sites.js";
@@ -114,6 +116,7 @@ export const VERB_HANDLERS = Object.freeze({
   [VERB_PULL]: pull,
   [VERB_PAGES_PUSH]: pagesPush,
   [VERB_NAV_PUSH]: navPush,
+  [VERB_REDIRECTS_CHECK]: redirectsCheck,
   [VERB_REDIRECTS_PULL]: redirectsPull,
   [VERB_REDIRECTS_PUSH]: redirectsPush,
   [VERB_THEME_PUSH]: themePush,

package/src/verbs/pull.js

@@ -46,19 +46,19 @@ import {
   PAGE_WORKSPACE_MODE_EDITABLE,
   PAGE_WORKSPACE_MODE_METADATA_ONLY,
   PAGE_WORKSPACE_MODE_READ_ONLY,
+  PAGES_DIRECTORY,
   pageSourceFormat,
   pageSourceRegistry,
-  PAGES_DIRECTORY,
   readObservedPageRecord,
   readWorkspaceFile,
   readWorkspaceJson,
   SETTINGS_DIRECTORY,
   SYSTEM_PAGE_NOT_FOUND_PATH,
   walkWorkspaceFiles,
+  WORKSPACE_LIMITS,
   workspaceContentHash,
   workspaceFileExists,
   workspaceFileNameForPage,
-  WORKSPACE_LIMITS,
   writeManifest,
   writeWorkspaceFile,
   writeWorkspaceJson,
@@ -171,7 +171,8 @@ function describeDifferenceSummary(differences) {
 }
 
 /**
- * Whether a workspace file still holds exactly the site's document.
+ * Whether a workspace file still holds exactly the site's document, or
+ * `undefined` when parsing failed and no comparison could be completed.
  *
  * Compared the way `remoteHash` is computed — canonically — and deliberately
  * not byte for byte. `FreeFormData.body` is a `google.protobuf.Struct`, so two
@@ -187,7 +188,7 @@ function holdsRemoteDocument(sourceBytes, remoteHash) {
   try {
     return canonicalDocumentHash(JSON.parse(sourceBytes.toString("utf8"))) === remoteHash;
   } catch {
-    return false;
+    return undefined;
   }
 }
 
@@ -652,6 +653,7 @@ export async function pull(invocation) {
     const trackedPlans = new Map();
     const conflicts = [];
     let bufferedBytes = 0;
+    let revisionsRecordedWithoutBodyComparison = 0;
     for (const summary of freeForm) {
       const source = tracked.get(summary.pageId);
       if (source === undefined) continue;
@@ -742,9 +744,18 @@ export async function pull(invocation) {
       // one at all. There is nothing to protect and nothing to compare, so an
       // unrecorded hash simply establishes itself.
       const localKnown = source.baseline?.sourceHash !== undefined;
+      const sourceMatchesRemote = !localKnown && !markdown ? holdsRemoteDocument(sourceBytes, remoteHash) : undefined;
       const localChanged = localKnown
         ? source.baseline.sourceHash !== sourceHash
-        : !markdown && !holdsRemoteDocument(sourceBytes, remoteHash);
+        : !markdown && sourceMatchesRemote !== true;
+      // A first revision bypasses the old remote hash. Only the unbaselined
+      // ProseMirror path above can compare this source with the site's body;
+      // a failed parse completes no comparison, and sourceHash merely checks
+      // local edits against earlier local bytes.
+      // Report the adoption only after the whole pull writes its manifest.
+      if (revision !== undefined && source.baseline?.revision === undefined && sourceMatchesRemote === undefined) {
+        revisionsRecordedWithoutBodyComparison += 1;
+      }
       const keepLocal = markdown || localChanged;
       const conflicted = markdown ? remoteChanged : localChanged && remoteChanged;
       trackedPlans.set(summary.pageId, {
@@ -1012,6 +1023,11 @@ export async function pull(invocation) {
     };
     await writeManifest(config.workspaceDir, manifest);
     onProgress(`Wrote ${MANIFEST_FILE_NAME} describing ${manifestPages.length} pages.`);
+    if (revisionsRecordedWithoutBodyComparison > 0) {
+      onProgress(
+        `revision recorded for ${revisionsRecordedWithoutBodyComparison} pages that had none; bodies were not compared`,
+      );
+    }
     if (truncated) {
       onProgress("The page list was bounded before the site was fully enumerated; the manifest is partial.");
     }
@@ -1037,6 +1053,7 @@ export async function pull(invocation) {
         // receiving a freshly written one. A caller that expected an authored
         // Markdown page to survive the pull can assert on it.
         tracked: tracked.size,
+        revisionsRecordedWithoutBodyComparison,
         readOnly: manifestPages.filter((entry) => entry.workspaceMode === PAGE_WORKSPACE_MODE_READ_ONLY).length,
         truncated,
         items: reported.items,

package/src/verbs/redirects-check.js

@@ -0,0 +1,18 @@
+import { mintStagingPreviewHandoff, withRefusalGuidance } from "../api.js";
+import { VERB_REDIRECTS_CHECK } from "../constants.js";
+import { openSession, successResult } from "../session.js";
+import { checkStagingRedirects } 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 checks = await checkStagingRedirects(client, siteId, onProgress, now);
+    if (!checks.redirects.verified) {
+      onProgress(
+        "Warning: staging redirects are not verified. Check the reported mismatches and retry after edge propagation.",
+      );
+    }
+    const handoff = await mintStagingPreviewHandoff(client, siteId, { now });
+    return successResult(VERB_REDIRECTS_CHECK, siteId, { stagingPreview: { ...checks, ...handoff } });
+  });
+}

package/src/verbs/status.js

@@ -1,11 +1,14 @@
 import {
+  getDeploySelection,
   getPublishingReadiness,
+  getSiteBrokenReferences,
   IMAGE_PROCESSING_STATE_COMPLETE,
   IMAGE_PROCESSING_STATE_FAILED,
   listDeployments,
   listSiteImages,
   withRefusalGuidance,
 } from "../api.js";
+import { isBehindLatest } from "../cli-release.js";
 import {
   CLI_UPGRADE_COMMAND,
   CLI_VERSION,
@@ -16,26 +19,17 @@ import {
   REFUSAL_PLATFORM_PAUSED,
   VERB_STATUS,
 } from "../constants.js";
-import { isBehindLatest } from "../cli-release.js";
 import { boundedList, openSession, successResult } from "../session.js";
 
 /**
- * `status` — the platform authoring switch, the CLI release, deployments,
- * publishing readiness, and image processing.
- *
- * Broken references are deliberately absent. `GetSiteBrokenReferences` is
- * session-only under TR00602's read list, and TR00604 adds no server surface,
- * so there is no key-authorized way to read them. The verb says that out loud —
- * on the human channel and as a field in the JSON result — rather than
- * reporting a clean site and implying a coverage it does not have.
+ * `status` — the platform authoring switch, CLI release, deployments,
+ * publishing readiness, image processing, and broken-reference pages.
  */
-
 const MAXIMUM_DEPLOYMENTS = 20;
 const MAXIMUM_FAILED_IMAGES = 50;
 const MAXIMUM_BLOCKERS = 50;
-
-const BROKEN_REFERENCES_NOTE =
-  "GetSiteBrokenReferences is session-only on the shipped contract, so a key-authorized CLI cannot read it.";
+const MAXIMUM_BROKEN_REFERENCE_PAGES = 50;
+const MAXIMUM_MISSING_TARGETS = 50;
 
 const PLATFORM_UNKNOWN_NOTE =
   "Taproot never reported the platform authoring switch on this run: either no sign-in token exchange happened "
@@ -109,14 +103,18 @@ function reportPlatform(platform, onProgress) {
 export async function status(invocation) {
   const { client, siteId, platform, release, onProgress } = await openSession(invocation);
   // Said first, and before any wire read: an operator running `status` because
-  // writes are being refused should not have to wait on three network calls to
+  // writes are being refused should not have to wait on network calls to
   // learn that the platform is paused — and this answer needs none of them.
   const platformReport = reportPlatform(platform, onProgress);
   const cliReleaseReport = reportCliRelease(release, onProgress);
 
   return await withRefusalGuidance(onProgress, "status check", async () => {
     onProgress("Reading publishing readiness.");
-    const readiness = await getPublishingReadiness(client, siteId);
+    const selection = await getDeploySelection(client, siteId);
+    const readiness = await getPublishingReadiness(client, siteId, {
+      ...selection,
+      stagedPageIds: selection.stagedPageIds.length > 100 ? undefined : selection.stagedPageIds,
+    });
     onProgress("Reading the deployment log.");
     const {
       deployments,
@@ -124,6 +122,20 @@ export async function status(invocation) {
     } = await listDeployments(client, siteId, { pageSize: MAXIMUM_DEPLOYMENTS });
     onProgress("Reading image processing state.");
     const { images, summary, truncated } = await listSiteImages(client, siteId);
+    onProgress("Reading broken references.");
+    const brokenReferencePages = await getSiteBrokenReferences(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 byState = {};
     for (const image of images) {
@@ -142,7 +154,7 @@ export async function status(invocation) {
     const reportedDeployments = boundedList(deployments, MAXIMUM_DEPLOYMENTS);
     const blockers = boundedList(readiness.blockers, MAXIMUM_BLOCKERS);
 
-    onProgress(`Broken references are not reported: ${BROKEN_REFERENCES_NOTE}`);
+    onProgress(`Broken references: ${brokenReferencePages.length} page(s) with missing targets.`);
 
     return successResult(VERB_STATUS, siteId, {
       platform: platformReport,
@@ -175,7 +187,12 @@ export async function status(invocation) {
         ...(failedImages.truncated ? { failedItemsTruncated: true } : {}),
         ...(truncated ? { listTruncated: true } : {}),
       },
-      brokenReferences: { covered: false, reason: BROKEN_REFERENCES_NOTE },
+      brokenReferences: {
+        covered: true,
+        totalPages: brokenReferencePages.length,
+        pages: brokenPages,
+        ...(reportedBrokenPages.truncated ? { pagesTruncated: true } : {}),
+      },
     });
   });
 }

package/src/verbs/theme-push.js

@@ -1,13 +1,14 @@
 import { getSettingsGroup, saveSiteFooterSettings, setSetting, withRefusalGuidance } from "../api.js";
 import {
+  APPEARANCE_SCALAR_FIELDS,
   applyFooterColors,
   buildAppearanceScalarOperations,
   footerColorOverlay,
 } from "../appearance-contract.js";
 import { VERB_THEME_PUSH } from "../constants.js";
 import { SiteAuthoringError } from "../errors.js";
-import { computeFooterDraftHash } from "../footer-draft-hash.js";
 import { projectFooterSettingsForWorkspace } from "../footer-contract.js";
+import { computeFooterDraftHash } from "../footer-draft-hash.js";
 import {
   advanceFooterManifest,
   readAppearanceWorkspaceContext,
@@ -20,9 +21,7 @@ import {
   SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES,
   SETTINGS_TYPE_TAPROOT_STYLES,
 } from "../settings-catalog.js";
-import {
-  validateAndEncodeThemePair,
-} from "../theme-validation.js";
+import { missingThemeFields, validateAndEncodeThemePair } from "../theme-validation.js";
 import {
   readWorkspaceJson,
   SETTINGS_DIRECTORY,
@@ -94,13 +93,49 @@ export async function validateThemeWorkspace(workspaceDir, siteId, knownImageIds
       expectedEntityIds?.get(SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES),
     ),
   ]);
+  const documents = {
+    [SETTINGS_TYPE_TAPROOT_STYLES]: style,
+    [SETTINGS_TYPE_BRAND]: brand,
+    [SETTINGS_TYPE_SITE_HEADER]: header,
+  };
+  // Preflight the complete required-key inventory before any value validator
+  // can stop at a malformed value in an earlier group. Optional footer color
+  // leaves retain their existing empty-color fallback.
+  const missing = [];
+  for (const scheme of ["light", "dark"]) {
+    const name = `${scheme}Theme`;
+    if (!Object.hasOwn(style, name)) missing.push(name);
+    else missing.push(...missingThemeFields(style[name], scheme));
+  }
+  for (const definition of APPEARANCE_SCALAR_FIELDS) {
+    if (!Object.hasOwn(documents[definition.settingsType], definition.name)) {
+      missing.push(definition.path);
+    }
+  }
+  if (!Object.hasOwn(publishing, "footerSettings")) {
+    missing.push("site-publishing-preferences.footerSettings");
+  } else if (isPlainObject(publishing.footerSettings)) {
+    for (const scheme of ["light", "dark"]) {
+      if (!Object.hasOwn(publishing.footerSettings, scheme)) missing.push(`footerSettings.${scheme}`);
+    }
+  }
+  if (missing.length > 0) {
+    throw new SiteAuthoringError(
+      "theme.settings_missing",
+      "Required settings keys are missing. Run 'taproot-site pull' to update this workspace's contract.",
+      {
+        field: missing[0],
+        details: missing.map((field) => ({
+          code: "theme.setting_missing",
+          field,
+          message: `${field} is missing (added in a later contract; run taproot-site pull)`,
+        })),
+      },
+    );
+  }
   const themes = validateAndEncodeThemePair(style.lightTheme, style.darkTheme);
   const scalarOperations = buildAppearanceScalarOperations(
-    {
-      [SETTINGS_TYPE_TAPROOT_STYLES]: style,
-      [SETTINGS_TYPE_BRAND]: brand,
-      [SETTINGS_TYPE_SITE_HEADER]: header,
-    },
+    documents,
     knownImageIds,
   );
   const footerColors = footerColorOverlay(publishing.footerSettings);