@taprootio/site-authoring 0.8.4 → 0.8.5

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

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