@taprootio/site-authoring 0.8.3 → 0.8.5

package/src/theme-projection.js

@@ -0,0 +1,213 @@
+import {
+  buildTaprootDarkTheme,
+  buildTaprootLightTheme,
+  DEFAULT_DARK_THEME,
+  DEFAULT_LIGHT_THEME,
+  encodeTheme,
+  layerThemes,
+  mergePartials,
+  mergeTheme,
+  parseTheme,
+} from "@taprootio/espalier/shared/theme";
+
+import { SiteAuthoringError } from "./errors.js";
+import { missingThemeFields } from "./theme-validation.js";
+
+/**
+ * Project one stored scheme theme to the complete theme a consumer actually
+ * renders (TR00775).
+ *
+ * Taproot stores what was written. A site whose theme was seeded or written
+ * before a key existed keeps a sparse document, and every consumer — the
+ * app's preview, the generator, the published runtime — resolves it by
+ * layering the same defaults underneath: Espalier's scheme defaults plus,
+ * for a theme Taproot still manages, the Taproot house theme with an empty
+ * page background. A theme the CLI manages (`*ThemeManagedExternally`) is
+ * rendered as stored over Espalier's defaults alone. `pull` writes exactly
+ * that effective theme, so a fresh workspace validates and a designer edits
+ * every group with its authoritative value instead of reconstructing it.
+ *
+ * Semantic mappings are the one group that is *not* filled from defaults.
+ * Espalier compiles them from `roles` at merge time; a mapping stored in
+ * `semanticMappings` pins that token and shadows whatever the roles would
+ * have produced. Copying the defaults' twenty-three mappings into the
+ * document would therefore freeze them and make later role changes inert
+ * — the failure a complete seeded theme already exhibits. The projection
+ * keeps only the mappings that are authored pins: those the stored marker
+ * names, plus any mapping whose value differs from the effective default
+ * (a pin added by hand without updating the marker). It writes the marker
+ * for exactly that set, so `theme push` stores pins only and roles compile
+ * for everything else.
+ *
+ * Layering alone is not rendering parity: `mergeTheme` also lets an
+ * unpinned type-role ink inherit a customized `text` mapping, and lets a
+ * `chroma.text` override flow into the type-role chroma bands the document
+ * did not set. Filling those groups from the defaults, or dropping a
+ * cached mapping that was holding a token at its default, would change
+ * what the site renders. So the projection is reconciled against Espalier
+ * itself: the stored theme is resolved exactly the way its consumers resolve
+ * it, the projected document is resolved the same way, and every difference
+ * is written back as the rendered value (a mapping pin, a chroma band). The
+ * result validates, keeps the author's pins, and renders what the site
+ * rendered before the pull.
+ */
+
+const SCHEME_DEFAULTS = Object.freeze({
+  light: { defaults: DEFAULT_LIGHT_THEME, house: buildTaprootLightTheme },
+  dark: { defaults: DEFAULT_DARK_THEME, house: buildTaprootDarkTheme },
+});
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function sameMapping(left, right) {
+  return isPlainObject(left) && isPlainObject(right)
+    && left.source === right.source && left.lightness === right.lightness
+    && Object.keys(left).length === Object.keys(right).length;
+}
+
+/**
+ * The complete theme a consumer layers a stored theme onto: Espalier's
+ * scheme defaults, and — unless the theme is managed externally — the
+ * Taproot house theme with the empty page background both the BFF and the
+ * generator clear before rendering.
+ */
+export function effectiveThemeBase(scheme, { managedExternally = false } = {}) {
+  const { defaults, house } = SCHEME_DEFAULTS[scheme];
+  const houseTheme = parseTheme(house("")) ?? {};
+  if (managedExternally) {
+    // Espalier's defaults carry no page background at all; the stored
+    // contract requires both keys. No image is the rendered truth, and the
+    // opacity of an absent image is neutral, so the house value fills it.
+    return {
+      ...defaults,
+      pageBackgroundImage: "",
+      pageBackgroundImageOpacity: houseTheme.pageBackgroundImageOpacity,
+    };
+  }
+  return { ...mergePartials(defaults, houseTheme), pageBackgroundImage: "" };
+}
+
+export function projectPulledTheme(stored, scheme, { managedExternally = false } = {}) {
+  const source = isPlainObject(stored) ? stored : {};
+  const base = effectiveThemeBase(scheme, { managedExternally });
+  const { semanticMappings: _baseMappings, ...layerable } = base;
+  // The marker is set on the base so mergePartials treats every stored
+  // mapping as authored; the pin filter below then decides which survive.
+  const merged = mergePartials({ ...layerable, semanticMappings: {}, explicitMappingTokens: [] }, source);
+
+  const marker = Array.isArray(source.explicitMappingTokens)
+    ? new Set(source.explicitMappingTokens.filter((token) => typeof token === "string"))
+    : undefined;
+  const pins = {};
+  if (isPlainObject(source.semanticMappings)) {
+    for (const [token, mapping] of Object.entries(source.semanticMappings)) {
+      const cachedDefault = sameMapping(mapping, base.semanticMappings?.[token]);
+      if (marker?.has(token) || !cachedDefault) pins[token] = mapping;
+    }
+  }
+  const projected = reconcileWithRendering(
+    { ...merged, semanticMappings: pins, explicitMappingTokens: Object.keys(pins) },
+    source,
+    scheme,
+    managedExternally,
+  );
+
+  requireProjectedThemeComplete(projected, scheme);
+  return projected;
+}
+
+/** What a consumer renders for a stored theme: the partial it layers, resolved over Espalier's defaults. */
+function renderedTheme(stored, scheme, managedExternally) {
+  const { defaults, house } = SCHEME_DEFAULTS[scheme];
+  const layered = managedExternally
+    ? layerThemes(encodeTheme(stored))
+    : layerThemes(house(""), encodeTheme({ pageBackgroundImage: "" }), encodeTheme(stored));
+  return mergeTheme(defaults, parseTheme(layered) ?? {});
+}
+
+function canonicalJson(value) {
+  if (Array.isArray(value)) return JSON.stringify(value.map((entry) => JSON.parse(canonicalJson(entry))));
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  return JSON.stringify(Object.fromEntries(Object.keys(value).sort().map((key) => [key, JSON.parse(canonicalJson(value[key]))])));
+}
+
+/**
+ * Bring the projected document to rendering parity with the stored theme.
+ * Two passes suffice: a mapping pin can change what a companion token
+ * inherits, so the comparison runs again after the first corrections.
+ *
+ * One deliberate exception: a cached default mapping on a token the stored
+ * theme's own roles would move is the shadowing pin TR00801 documents and
+ * warns about. Restoring it would keep the roles inert, so it stays dropped
+ * and the role-compiled value is accepted as the rendering the author asked
+ * for. Every other difference is written back.
+ */
+function reconcileWithRendering(projected, stored, scheme, managedExternally) {
+  const { defaults } = SCHEME_DEFAULTS[scheme];
+  let rendered;
+  let roleCompiled;
+  try {
+    rendered = renderedTheme(stored, scheme, managedExternally);
+    const declaresRoles = isPlainObject(stored.roles) && Object.keys(stored.roles).length > 0;
+    roleCompiled = declaresRoles
+      ? mergeTheme(defaults, { ...stored, semanticMappings: {}, explicitMappingTokens: [] }).semanticMappings
+      : undefined;
+  } catch {
+    // An invalid stored theme cannot be rendered for comparison; validation
+    // reports it, and the layered projection is the best available document.
+    return projected;
+  }
+  let current = projected;
+  for (let pass = 0; pass < 2; pass += 1) {
+    let candidate;
+    try {
+      candidate = mergeTheme(defaults, current);
+    } catch {
+      return current;
+    }
+    let changed = false;
+    for (const key of Object.keys(rendered)) {
+      if (key === "explicitMappingTokens") continue;
+      if (canonicalJson(rendered[key]) === canonicalJson(candidate[key])) continue;
+      changed = true;
+      if (key === "semanticMappings") {
+        const pins = { ...current.semanticMappings };
+        for (const [token, mapping] of Object.entries(rendered.semanticMappings)) {
+          if (canonicalJson(mapping) === canonicalJson(candidate.semanticMappings[token])) continue;
+          const storedMapping = isPlainObject(stored.semanticMappings) ? stored.semanticMappings[token] : undefined;
+          const cachedDefaultTheRolesMove = roleCompiled !== undefined
+            && sameMapping(storedMapping, defaults.semanticMappings[token])
+            && canonicalJson(candidate.semanticMappings[token]) === canonicalJson(roleCompiled[token]);
+          if (cachedDefaultTheRolesMove) continue;
+          pins[token] = structuredClone(mapping);
+        }
+        current = { ...current, semanticMappings: pins, explicitMappingTokens: Object.keys(pins) };
+      } else {
+        current = { ...current, [key]: structuredClone(rendered[key]) };
+      }
+    }
+    if (!changed) break;
+  }
+  return current;
+}
+
+/**
+ * The refusal for a projection that still lacks required fields. Reachable
+ * only when Espalier's defaults and the server response together omit a key
+ * this CLI requires — a contract drift between releases, never a stale
+ * workspace — so the remedy is a report, not another pull. Exported so the
+ * refusal itself is testable without an incomplete default to hand.
+ */
+export function requireProjectedThemeComplete(projected, scheme) {
+  const missing = missingThemeFields(projected, scheme);
+  if (missing.length === 0) return;
+  throw new SiteAuthoringError(
+    "theme.projection_incomplete",
+    "Taproot's settings response and the Espalier defaults this CLI ships still omit required theme fields. "
+      + "This is a contract problem between the server projection and this CLI release, not a stale workspace: "
+      + "repeating taproot-site pull cannot supply them. Report the listed paths with the CLI and server versions.",
+    { field: missing[0], alternatives: missing },
+  );
+}

package/src/theme-validation.js

@@ -1,4 +1,12 @@
-import { encodeTheme, LIGHTNESS_KEYS, SEMANTIC_COLOR_NAMES, validateThemePair } from "@taprootio/espalier/shared/theme";
+import {
+  DEFAULT_DARK_THEME,
+  DEFAULT_LIGHT_THEME,
+  encodeTheme,
+  LIGHTNESS_KEYS,
+  mergeTheme,
+  SEMANTIC_COLOR_NAMES,
+  validateThemePair,
+} from "@taprootio/espalier/shared/theme";
 
 import { hasControlCharacter, sanitizeDiagnostic, SiteAuthoringError } from "./errors.js";
 
@@ -286,6 +294,53 @@ function refuseAgentStylesheets(theme, scheme) {
   }
 }
 
+const SCHEME_DEFAULTS = Object.freeze({ light: DEFAULT_LIGHT_THEME, dark: DEFAULT_DARK_THEME });
+
+function sameMapping(left, right) {
+  return isPlainObject(left) && isPlainObject(right)
+    && left.source === right.source && left.lightness === right.lightness;
+}
+
+/**
+ * Roles compile the semantic mappings at render time, and any mapping present
+ * in `semanticMappings` pins its token over that compilation (TR00801). A pin
+ * that merely repeats Espalier's default on a token the declared roles would
+ * have moved is the one an author never meant: it came from a copied example
+ * or a pre-projection pull, and it silently keeps the role from reaching the
+ * token — the accepted-but-gray link WTFM saw. Which tokens the roles move is
+ * asked of Espalier itself, by compiling the same roles with no pins at all;
+ * a token the roles leave at its default, or one the marker names as a
+ * deliberate pin, is never reported. It is a warning rather than a refusal
+ * because the pair still renders exactly as declared; Espalier validation
+ * owns the invalid cases.
+ */
+export function shadowedRoleMappingWarnings(theme, scheme) {
+  if (!isPlainObject(theme) || !isPlainObject(theme.roles) || Object.keys(theme.roles).length === 0) return [];
+  if (!isPlainObject(theme.semanticMappings)) return [];
+  const defaults = SCHEME_DEFAULTS[scheme];
+  let compiled;
+  try {
+    compiled = mergeTheme(defaults, { ...theme, semanticMappings: {}, explicitMappingTokens: [] }).semanticMappings;
+  } catch {
+    // An invalid theme is Espalier validation's finding, not this one's.
+    return [];
+  }
+  const deliberate = new Set(Array.isArray(theme.explicitMappingTokens) ? theme.explicitMappingTokens : []);
+  const warnings = [];
+  for (const [token, mapping] of Object.entries(theme.semanticMappings)) {
+    if (deliberate.has(token)) continue;
+    const fallback = defaults.semanticMappings[token];
+    if (sameMapping(mapping, fallback) && !sameMapping(compiled[token], fallback)) {
+      warnings.push(
+        `${scheme}: semanticMappings.${token} repeats the Espalier default and pins the token, so the declared roles `
+          + `never reach it; remove the pin to let the roles compile ${token}, or list it in explicitMappingTokens `
+          + `if the default is the intent.`,
+      );
+    }
+  }
+  return warnings;
+}
+
 export function validateAndEncodeThemePair(lightTheme, darkTheme) {
   requireCompleteTheme(lightTheme, "light");
   requireCompleteTheme(darkTheme, "dark");
@@ -317,7 +372,12 @@ export function validateAndEncodeThemePair(lightTheme, darkTheme) {
   }
   refuseAgentStylesheets(lightTheme, "light");
   refuseAgentStylesheets(darkTheme, "dark");
-  const warnings = result.warnings
+  const allWarnings = [
+    ...result.warnings,
+    ...shadowedRoleMappingWarnings(lightTheme, "light"),
+    ...shadowedRoleMappingWarnings(darkTheme, "dark"),
+  ];
+  const warnings = allWarnings
     .slice(0, MAXIMUM_THEME_WARNINGS)
     .map((warning) =>
       [...sanitizeDiagnostic(warning, "Theme validation warning.")]
@@ -328,8 +388,8 @@ export function validateAndEncodeThemePair(lightTheme, darkTheme) {
     light,
     dark,
     warnings,
-    warningCount: result.warnings.length,
-    warningsTruncated: result.warnings.length > warnings.length,
+    warningCount: allWarnings.length,
+    warningsTruncated: allWarnings.length > warnings.length,
   };
 }
 

package/src/verbs/delivery-check.js

@@ -0,0 +1,185 @@
+import {
+  DEPLOYMENT_ENVIRONMENT_PRODUCTION,
+  DEPLOYMENT_ENVIRONMENT_STAGING,
+  DEPLOYMENT_STATUS_COMPLETED,
+  getStagingPreviewStatus,
+  listDeployments,
+  mintStagingPreviewHandoff,
+  withRefusalGuidance,
+} from "../api.js";
+import { DEPLOY_TARGET_PRODUCTION, DEPLOY_TARGET_STAGING, VERB_DELIVERY_CHECK } from "../constants.js";
+import { probeDeliveryWithBrowser } from "../delivery-browser.js";
+import { checkDelivery, DELIVERY_LIMITS } from "../delivery-check.js";
+import { SiteAuthoringError } from "../errors.js";
+import { openSession, successResult } from "../session.js";
+import { authorizeStagingHandoff } from "../staging-check.js";
+import { readManifest } from "../workspace.js";
+
+/**
+ * `delivery check (--staging | --production)` — verify what a visitor
+ * receives after a deployment completed (TR00824).
+ *
+ * The deployment log says the job finished. This verb reads the target the
+ * way a visitor does and reports three dimensions separately: the completed
+ * deployment (from the site's deployment log and the workspace record), HTTP
+ * delivery of the authored routes, their assets and the declared runtime, and
+ * — only when a browser is available — what a fresh and a returning browser
+ * actually loaded. Nothing is purged, republished, rolled back or mutated.
+ */
+
+function usageError(code, message, field) {
+  return new SiteAuthoringError(code, message, { field, exitCode: 2 });
+}
+
+function environmentFor(target) {
+  return target === DEPLOY_TARGET_STAGING ? DEPLOYMENT_ENVIRONMENT_STAGING : DEPLOYMENT_ENVIRONMENT_PRODUCTION;
+}
+
+async function resolveTarget(client, siteId, target, invocation, onProgress, now) {
+  if (typeof invocation.deliveryUrl === "string" && invocation.deliveryUrl !== "") {
+    if (target === DEPLOY_TARGET_STAGING) {
+      // The staging edge serves only an authorized preview session bound to
+      // the acknowledged host, so another origin could not be checked as
+      // staging; refusing is truer than an unauthenticated probe.
+      throw usageError(
+        "delivery.url_not_for_staging",
+        "--url applies to --production; --staging always checks the site's acknowledged staging host with an "
+          + "authorized preview session.",
+        "url",
+      );
+    }
+    return { baseUrl: invocation.deliveryUrl, source: "option" };
+  }
+  if (target === DEPLOY_TARGET_STAGING) {
+    const status = await getStagingPreviewStatus(client, siteId);
+    if (!status.ready) {
+      throw new SiteAuthoringError(
+        "delivery.staging_unavailable",
+        "The site has no acknowledged staging host yet, so there is nothing a visitor could receive. Wait for the "
+          + "staging hostname to become ready (taproot-site status), then run delivery check again.",
+        { field: "stagingUrl" },
+      );
+    }
+    // The staging edge serves nothing without the preview cookie; the
+    // handoff is consumed here, once, and the cookie never leaves this run.
+    onProgress("Authorizing a staging preview session for the check.");
+    const handoff = await mintStagingPreviewHandoff(client, siteId, { now });
+    const cookie = await authorizeStagingHandoff(client, handoff, client.timeoutSignal(90_000));
+    // The cookie is bound to the host the handoff was minted for; if the
+    // acknowledged host moved between the status read and the mint, that
+    // host — not the earlier status — is the only origin the cookie may reach.
+    if (handoff.stagingUrl !== status.stagingUrl) {
+      onProgress(`The acknowledged staging host changed to ${handoff.stagingUrl} while the check started; checking that host.`);
+    }
+    return { baseUrl: handoff.stagingUrl, source: "staging-status", cookie };
+  }
+  throw usageError(
+    "delivery.production_url_required",
+    "delivery check --production needs the site's public origin: pass --url https://<published-domain>/ using the "
+      + "primaryDomain that 'taproot-site sites' reports. A site-authoring key cannot read hosting configuration, so "
+      + "the CLI does not guess it.",
+    "url",
+  );
+}
+
+export async function deliveryCheck(invocation) {
+  const target = invocation.deployTarget;
+  if (target !== DEPLOY_TARGET_STAGING && target !== DEPLOY_TARGET_PRODUCTION) {
+    throw usageError("delivery.target_missing", "delivery check requires exactly one of --staging or --production.", "deployTarget");
+  }
+  const session = await openSession(invocation);
+  const { client, config, siteId, now, onProgress } = session;
+  const environment = environmentFor(target);
+  const manifest = await readManifest(config.workspaceDir, siteId, { required: false });
+  const recorded = manifest?.deployments?.[target];
+
+  return await withRefusalGuidance(onProgress, "delivery check", async () => {
+    onProgress("Reading the deployment log.");
+    const { deployments } = await listDeployments(client, siteId, { environment });
+    const completed = deployments.find((deployment) => deployment.status === DEPLOYMENT_STATUS_COMPLETED);
+    if (completed === undefined) {
+      throw new SiteAuthoringError(
+        "delivery.no_completed_deployment",
+        `No completed ${target} deployment exists for this site, so there is no delivery to verify. Run `
+          + `'taproot-site deploy --${target}' first.`,
+        { field: "deploymentId" },
+      );
+    }
+    const deployment = {
+      id: completed.id,
+      completedAt: completed.completedAt,
+      recordedInWorkspace: typeof recorded?.id === "string" ? recorded.id === completed.id : undefined,
+      ...(typeof recorded?.id === "string" && recorded.id !== completed.id ? { workspaceRecordedId: recorded.id } : {}),
+    };
+    if (deployment.recordedInWorkspace === false) {
+      onProgress(
+        `Note: the workspace recorded ${target} deployment ${recorded.id}, but the latest completed ${target} deployment is ${completed.id}; the latest one is what visitors receive and is what this check verifies.`,
+      );
+    }
+
+    const resolved = await resolveTarget(client, siteId, target, invocation, onProgress, now);
+    const routes = (manifest?.pages ?? [])
+      .filter((page) => page !== null && typeof page === "object" && typeof page.path === "string")
+      .map((page) => (page.path === "" ? "/" : `/${page.path.replace(/^\/+/u, "")}/`.replace(/\/\/$/u, "/")));
+    onProgress(`Checking ${resolved.baseUrl} (${Math.min(routes.length + 1, DELIVERY_LIMITS.routes)} route(s), assets, runtime).`);
+    const report = await checkDelivery({
+      fetch: client.fetch,
+      timeoutSignal: client.timeoutSignal,
+      baseUrl: resolved.baseUrl,
+      routes,
+      cookie: resolved.cookie,
+      propagationWaitSeconds: invocation.propagationWaitSeconds ?? 0,
+      now,
+    });
+    for (const failure of report.failures) onProgress(`Delivery: ${failure}`);
+
+    let browser;
+    if (invocation.browser === false) {
+      browser = { status: "unchecked", reason: "disabled", note: "Browser verification was not requested." };
+    } else {
+      onProgress("Browser dimension: probing with Playwright when it is installed.");
+      browser = await probeDeliveryWithBrowser({
+        baseUrl: resolved.baseUrl,
+        expectedEntryUrl: report.runtime.entry?.url ?? "",
+        capabilities: report.runtime.capabilities,
+        cookie: resolved.cookie,
+        importPlaywright: invocation.importPlaywright,
+      });
+    }
+    if (browser.status === "unchecked") onProgress(`Browser dimension unchecked: ${browser.reason}.`);
+    else if (browser.status === "checked" && !browser.ok) onProgress("Browser dimension: a load did not match the declared runtime or left the site origin; see browser.fresh and browser.returning.");
+    if (browser.status === "checked" && browser.returningCache?.status !== "checked") onProgress("Browser dimension: cache reuse on the returning load could not be observed; it is unchecked.");
+
+    const verdict = report.verdict === "delivered" && browser.status === "checked" && !browser.ok ? "degraded" : report.verdict;
+    onProgress(
+      verdict === "delivered"
+        ? "Delivery verified over HTTP" + (browser.status === "checked" ? " and in a browser." : "; browser behaviour unchecked.")
+        : `Delivery ${verdict}: ${report.failures.length} HTTP finding(s)` + (browser.status === "checked" && !browser.ok ? " and a browser mismatch." : "."),
+    );
+    return successResult(VERB_DELIVERY_CHECK, siteId, {
+      environment,
+      target: { ...report.target, resolvedFrom: resolved.source },
+      deployment,
+      verdict,
+      routes: report.routes,
+      assets: report.assets,
+      links: report.links,
+      localOnlyReferences: report.localOnlyReferences,
+      ...(report.localOnlyReferencesTotal === undefined ? {} : { localOnlyReferencesTotal: report.localOnlyReferencesTotal }),
+      runtime: report.runtime,
+      browser,
+      failures: report.failures,
+      ...(report.failuresTruncated ? { failuresTruncated: true, failuresTotal: report.failuresTotal } : {}),
+      propagation: report.propagation,
+      limits: report.limits,
+      checkedAt: report.checkedAt,
+      doesNotProve: [
+        "a full visual or accessibility audit",
+        "member-only content delivery, which stays behind the member boundary",
+        ...(browser.status === "checked" && browser.returningCache?.status === "checked"
+          ? []
+          : ["what a returning browser loads from its own cache"]),
+      ],
+    });
+  });
+}

package/src/verbs/deploy.js

@@ -10,10 +10,19 @@ import {
   waitForDeployment,
   withRefusalGuidance,
 } from "../api.js";
-import { DEPLOY_TARGET_PRODUCTION, DEPLOY_TARGET_STAGING, SURFACE_DOCS_PRESENTATION, VERB_DEPLOY } from "../constants.js";
+import {
+  DEPLOY_TARGET_PRODUCTION,
+  DEPLOY_TARGET_STAGING,
+  REFUSAL_CAPABILITY_MISSING,
+  REFUSAL_CREDENTIAL_REJECTED,
+  REFUSAL_UNCLASSIFIED,
+  SURFACE_DOCS_PRESENTATION,
+  VERB_DEPLOY,
+} from "../constants.js";
 import { SiteAuthoringError } from "../errors.js";
 import { boundedList, openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
 import { checkStagingRedirects } from "../staging-check.js";
+import { ApiError } from "../transport.js";
 import { readManifest, writeManifest } from "../workspace.js";
 
 /**
@@ -157,6 +166,65 @@ async function inspectStagingPreview(client, siteId, onProgress, now) {
   }
 }
 
+const PRESENTATION_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 preview a presentation change.";
+
+/**
+ * Why a managed Docs staging handoff could not be minted, as a stable reason
+ * the caller can act on. The recovery never points at production or at a host
+ * the CLI has not been told about.
+ */
+function presentationHandoffUnavailable(error) {
+  if (error instanceof ApiError) {
+    const refusal = error.refusalKind();
+    if (refusal === REFUSAL_CREDENTIAL_REJECTED || refusal === REFUSAL_CAPABILITY_MISSING) {
+      return {
+        reason: "staging.authority_denied",
+        recovery: "This credential cannot view staging for this site. Re-issue a site-authoring key that carries "
+          + "the Deployments capability, then run 'taproot-site staging review' for a handoff.",
+      };
+    }
+    if (refusal === REFUSAL_UNCLASSIFIED && error.hasField("SiteId")) {
+      return {
+        reason: "staging.surface_refused",
+        recovery: "The site no longer accepts external presentation authoring (its Docs source is prebuilt). "
+          + "Run 'taproot-site use' to re-record the site's surface; a prebuilt Docs site stages nothing.",
+      };
+    }
+    if (refusal === REFUSAL_UNCLASSIFIED && error.hasField("Host")) {
+      return {
+        reason: "staging.host_unavailable",
+        recovery: "The site has no acknowledged staging host yet. Wait for the staging hostname to become ready "
+          + "(check 'taproot-site status'), then run 'taproot-site staging review' to mint a review handoff.",
+      };
+    }
+  }
+  return {
+    reason: "staging.handoff_unavailable",
+    recovery: "Run 'taproot-site staging review' to mint a fresh review handoff; the staged presentation is "
+      + "already deployed and waits for review.",
+  };
+}
+
+/**
+ * A managed Docs site deploys settings only, so there are no page drafts or
+ * redirects to inspect on staging; the review handoff is the whole handoff.
+ * 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) {
+  try {
+    const handoff = await mintStagingPreviewHandoff(client, siteId, { now });
+    onProgress(`Staging review handoff minted for ${handoff.stagingUrl}. ${PRESENTATION_REVIEW_GUIDANCE}`);
+    return { ...handoff, review: PRESENTATION_REVIEW_GUIDANCE };
+  } catch (error) {
+    if (error instanceof SiteAuthoringError && !(error instanceof ApiError)) throw error;
+    const unavailable = presentationHandoffUnavailable(error);
+    onProgress(`Warning: the deployment completed, but a staging review handoff could not be minted (${unavailable.reason}). ${unavailable.recovery}`);
+    return { url: "", stagingUrl: "", ...unavailable };
+  }
+}
+
 export async function deploy(invocation) {
   const target = invocation.deployTarget;
   if (target !== DEPLOY_TARGET_STAGING && target !== DEPLOY_TARGET_PRODUCTION) {
@@ -298,7 +366,7 @@ export async function deploy(invocation) {
     });
     await recordDeployment(config, manifest, "staging", completed);
     if (presentationOnly) {
-      onProgress("Review the staged presentation on the site's staging host, then promote it.");
+      const stagingPreview = await mintPresentationStagingHandoff(client, siteId, onProgress, now);
       return successResult(VERB_DEPLOY, siteId, {
         target,
         environment: DEPLOYMENT_ENVIRONMENT_STAGING,
@@ -310,7 +378,8 @@ export async function deploy(invocation) {
         },
         deployment: completed,
         readiness: reportReadiness(readiness),
-        nextStep: "deploy --production",
+        stagingPreview,
+        nextStep: stagingPreview.url === "" ? "staging review" : "deploy --production",
       });
     }
     const stagingPreview = await inspectStagingPreview(client, siteId, onProgress, now);

package/src/verbs/index.js

@@ -1,5 +1,6 @@
 import {
   VERB_APPROVE,
+  VERB_DELIVERY_CHECK,
   VERB_DEPLOY,
   VERB_ENV,
   VERB_FOOTER_PUSH,
@@ -15,6 +16,7 @@ import {
   VERB_REDIRECTS_PULL,
   VERB_REDIRECTS_PUSH,
   VERB_SITES,
+  VERB_STAGING_REVIEW,
   VERB_STATUS,
   VERB_THEME_PUSH,
   VERB_USE,
@@ -22,6 +24,7 @@ import {
   VERB_WHOAMI,
 } from "../constants.js";
 import { approve } from "./approve.js";
+import { deliveryCheck } from "./delivery-check.js";
 import { deploy } from "./deploy.js";
 import { env } from "./env.js";
 import { footerPush } from "./footer-push.js";
@@ -37,6 +40,7 @@ import { redirectsCheck } from "./redirects-check.js";
 import { redirectsPull } from "./redirects-pull.js";
 import { redirectsPush } from "./redirects-push.js";
 import { sites } from "./sites.js";
+import { stagingReview } from "./staging-review.js";
 import { status } from "./status.js";
 import { themePush } from "./theme-push.js";
 import { use } from "./use.js";
@@ -131,4 +135,6 @@ export const VERB_HANDLERS = Object.freeze({
   [VERB_WHOAMI]: whoami,
   [VERB_ENV]: env,
   [VERB_STATUS]: status,
+  [VERB_DELIVERY_CHECK]: deliveryCheck,
+  [VERB_STAGING_REVIEW]: stagingReview,
 });

package/src/verbs/preview-revoke.js

@@ -1,7 +1,7 @@
 import {
   AUTHORING_PREVIEW_STATUS_REVOKED,
   revokeAuthoringPreview,
-  translateAuthoringPreviewApiError,
+  translateAuthoringPreviewRevokeApiError,
   withRefusalGuidance,
 } from "../api.js";
 import { VERB_PREVIEW_REVOKE } from "../constants.js";
@@ -56,6 +56,6 @@ export async function previewRevoke(invocation) {
       });
     });
   } catch (error) {
-    throw translateAuthoringPreviewApiError(error);
+    throw translateAuthoringPreviewRevokeApiError(error);
   }
 }