@taprootio/site-authoring 0.8.3 → 0.8.5

package/src/verbs/staging-review.js

@@ -0,0 +1,29 @@
+import { mintStagingPreviewHandoff, withRefusalGuidance } from "../api.js";
+import { VERB_STAGING_REVIEW } from "../constants.js";
+import { openSession, successResult } from "../session.js";
+
+export const STAGING_REVIEW_GUIDANCE = "Open the URL once in a browser, then switch the site's theme toggle between "
+  + "light and dark to review both schemes; no page draft is needed to review a presentation change.";
+
+/**
+ * `staging review` — mint a fresh single-use review handoff for the site's
+ * acknowledged staging host, and nothing else (TR00800 follow-up).
+ *
+ * It is the recovery `deploy --staging` names when it could not mint one,
+ * and the only such path a managed Docs site can take: `redirects check`
+ * inspects a redirect map the Docs shell does not have and needs the
+ * Standard surface. Minting is read-only for the site: the handoff is a
+ * short-lived capability bound to the current host, reported only in the
+ * final JSON and never in progress or GITHUB_OUTPUT.
+ */
+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 });
+    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/theme-push.js

@@ -6,7 +6,7 @@ import {
   footerColorOverlay,
 } from "../appearance-contract.js";
 import { VERB_THEME_PUSH } from "../constants.js";
-import { SiteAuthoringError } from "../errors.js";
+import { MISSING_SETTING_MESSAGE, SiteAuthoringError } from "../errors.js";
 import { projectFooterSettingsForWorkspace } from "../footer-contract.js";
 import { computeFooterDraftHash } from "../footer-draft-hash.js";
 import {
@@ -122,13 +122,13 @@ export async function validateThemeWorkspace(workspaceDir, siteId, knownImageIds
   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.",
+      "Required settings keys are absent from this workspace. Restore them locally, or run 'taproot-site pull' if the workspace is stale; a fresh pull that still omits them means the server projection is incomplete for the listed paths.",
       {
         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)`,
+          message: MISSING_SETTING_MESSAGE,
         })),
       },
     );