@taprootio/site-authoring 0.12.0 → 0.12.3

package/README.md

@@ -400,7 +400,11 @@ site.
 ## Output contract
 
 Human progress goes to stderr and `--quiet` silences it (except for `login`,
-whose approval code and URL exist only as progress). Stdout carries exactly
+whose approval code and URL exist only as progress). While a deployment is
+awaited, a terminal shows one in-place line (spinner, phase, elapsed time) that
+starts a new line only when the phase changes; a pipe or CI log never receives
+control characters, only one line per phase change plus a heartbeat at most
+every 60 seconds. Stdout carries exactly
 one JSON object per run, schema version `1`: `ok`, the CLI name and version,
 the verb, and the verb's own result on success; a stable `error.code` with an
 optional `field`, `status`, and classified `refusal` on failure. Exit codes are
@@ -501,7 +505,7 @@ fingerprint supply no gating evidence. Typed preview failure diagnostics contain
 only error class and known page/node/attribute labels, never renderer messages.
 
 Staging deploys check the current redirect map through the real staging edge.
-Run `taproot-site redirects check` to repeat after eventual edge propagation.
+Run `taproot-site redirects check` to repeat once the deployment has completed; a redirect is a file inside the release, so it is live exactly when its release is served.
 The Node CLI consumes a separate handoff, retains its short staging cookie in
 memory, and requests each map path without following redirects. Results report
 path, HTTP status and Location; `verified` requires all entries to match and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.12.0",
+  "version": "0.12.3",
   "description": "Taproot site authoring CLI: sign in once in the browser, then pull, validate, push, preview, approve, and deploy a site from the terminal",
   "type": "module",
   "license": "ISC",

package/src/api.js

@@ -1207,7 +1207,7 @@ export async function poll({
     // poll runs every few seconds for up to fifteen minutes, and a line per
     // tick scrolls the one thing the operator still needs — the code — off the
     // top of the terminal.
-    if (result.progress !== undefined) onProgress(result.progress);
+    if (result.progress !== undefined) onProgress(result.progress, result.event);
     if (now() >= deadline) break;
     await client.sleep(Math.min(intervalMilliseconds, Math.max(1, deadline - now())), client.signal);
   }
@@ -1220,8 +1220,20 @@ export async function poll({
 }
 
 export async function waitForDeployment(client, { siteId, deploymentId, environment, onProgress, now }) {
+  try {
+    return await awaitDeployment(client, { siteId, deploymentId, environment, onProgress, now });
+  } finally {
+    // The wait is over whether the deployment finished or failed; the verb's later
+    // output (staging checks, the failure text) must not sit beside a spinner.
+    onProgress?.endWait?.();
+  }
+}
+
+async function awaitDeployment(client, { siteId, deploymentId, environment, onProgress, now }) {
   let misses = 0;
   let lastEvidence;
+  let truncatedReported = false;
+  const reportedPhases = new Set();
   return await poll({
     client,
     now,
@@ -1248,6 +1260,11 @@ export async function waitForDeployment(client, { siteId, deploymentId, environm
         lastEvidence = evidence;
         if (deployment.phaseTimings.known) {
           for (const phase of deployment.phaseTimings.phases) {
+            // Each phase is reported when it is entered and again when it ends,
+            // never re-listed on every later change.
+            const key = `${phase.status}|${phase.enteredAt}|${phase.durationMilliseconds ?? ""}`;
+            if (reportedPhases.has(key)) continue;
+            reportedPhases.add(key);
             onProgress(
               `Deployment phase ${phase.status} entered ${phase.enteredAt}`
                 + (phase.durationMilliseconds === undefined
@@ -1255,7 +1272,8 @@ export async function waitForDeployment(client, { siteId, deploymentId, environm
                   : `; ${phase.durationMilliseconds}ms until ${phase.endedAt}.`),
             );
           }
-          if (deployment.phaseTimings.truncated) {
+          if (deployment.phaseTimings.truncated && !truncatedReported) {
+            truncatedReported = true;
             onProgress("Earlier deployment phase evidence was truncated by the server.");
           }
         } else onProgress("Deployment phase timings are unknown for this legacy deployment.");
@@ -1270,7 +1288,11 @@ export async function waitForDeployment(client, { siteId, deploymentId, environm
           { status: deployment.status },
         );
       }
-      return { done: false, progress: `Waiting for the deployment (${deployment.status}).` };
+      // The phase a reader sees is the latest one the server recorded, or the
+      // deployment's own status when it recorded none.
+      const phases = deployment.phaseTimings.known ? deployment.phaseTimings.phases : [];
+      const phase = phases.length > 0 ? phases[phases.length - 1].status : deployment.status;
+      return { done: false, progress: `Waiting for the deployment (${phase}).`, event: { phase } };
     },
     timeoutCode: "deploy.timeout",
   });

package/src/cli.js

@@ -47,6 +47,7 @@ import {
   SiteAuthoringError,
 } from "./errors.js";
 import { failureResult, humanFailure, serializeResult, writeGithubActionsOutput } from "./output.js";
+import { createProgressReporter } from "./progress.js";
 import {
   formatReferenceResult,
   getAppearanceReference,
@@ -251,7 +252,8 @@ const VERBS = Object.freeze([
     capabilities: [CAPABILITY_CONTENT, CAPABILITY_DEPLOYMENTS],
     tokens: ["redirects", "check"],
     summary: "Check the current redirect map through the authenticated staging edge.",
-    note: "Reports path, HTTP status and Location without following redirects. Re-run after edge propagation. "
+    note: "Reports path, HTTP status and Location without following redirects. A redirect is live only with the release "
+      + "that carries it, so this reads the staged release. "
       + "The result includes a fresh single-use staging handoff; keep it private.",
   },
   {
@@ -275,7 +277,8 @@ const VERBS = Object.freeze([
     summary: "Validate redirects.json and replace the whole redirect map.",
     note: "Run 'redirects pull' first. The whole file is validated locally by entry index — path normalization, "
       + "targets, statuses, duplicates, chains, and loops — before anything is sent, and the site refuses a "
-      + "source a live page occupies. Entries take effect on the next deploy. "
+      + "source a live page occupies or a file the site generates. An entry is a file inside the next release, so it "
+      + "goes live with that deploy: staging first, production when promoted. "
       + "See 'taproot-site help redirects'.",
   },
   {
@@ -1132,6 +1135,7 @@ export async function runCli({
   signal,
 } = {}) {
   let parsed;
+  let progress;
   let completedPreviewRecovery;
   const isReferenceInvocation = Array.isArray(arguments_)
     && (
@@ -1176,6 +1180,11 @@ export async function runCli({
     if (typeof handler !== "function") {
       throw usageError("cli.unsupported_verb", `No handler is registered for '${parsed.verb}'.`);
     }
+    progress = createProgressReporter({
+      stream: stderr,
+      interactive: stderr.isTTY === true && environment.TERM !== "dumb",
+      quiet: parsed.quiet,
+    });
     const result = await handler(Object.freeze({
       verb: parsed.verb,
       cwd,
@@ -1200,13 +1209,17 @@ export async function runCli({
             : parsed.positionals.values,
         }
         : {}),
-      onProgress: parsed.quiet ? () => {} : (message) => stderr.write(`${message}\n`),
+      // `endWait` lets a wait say it is over while the verb goes on (staging checks).
+      onProgress: Object.assign((message, event) => progress.report(message, event), {
+        endWait: () => progress.endWait(),
+      }),
       fetch,
       signal,
     }));
     if (parsed.verb === VERB_PREVIEW_PAGE && result?.ok === true) {
       completedPreviewRecovery = normalizePreviewRecovery(result);
     }
+    progress.stop();
     const json = serializeResult(result);
     if (!isValidationInvocation && environment.GITHUB_OUTPUT) {
       await writeGithubActionsOutput(environment.GITHUB_OUTPUT, result);
@@ -1214,6 +1227,7 @@ export async function runCli({
     stdout.write(`${json}\n`);
     return 0;
   } catch (unknownError) {
+    progress?.stop();
     const error = asSiteAuthoringError(unknownError);
     if (completedPreviewRecovery) error.withPreviewRecovery(completedPreviewRecovery);
     const result = failureResult(error);

package/src/progress.js

@@ -0,0 +1,142 @@
+/**
+ * Human progress for a long wait, written to stderr (stdout stays the one JSON
+ * result). Verbs report plain lines through `report(message)`; a wait reports
+ * `report(message, { phase })` once per poll, and this decides how much of that
+ * a reader should see.
+ *
+ * - On a terminal, a wait is one in-place line (spinner, phase, elapsed time)
+ *   that redraws each second, and a new line starts only when the phase changes.
+ *   Any other line clears the in-place line first, then the wait line comes back.
+ * - Off a terminal (a pipe, CI), no control characters are ever written: one line
+ *   per phase change, plus a heartbeat at most every `heartbeatMilliseconds` so a
+ *   long silent phase does not look hung.
+ */
+const SPINNER_FRAMES = ["|", "/", "-", "\\"];
+const ERASE_LINE = "\r\u001B[2K";
+
+export const PROGRESS_HEARTBEAT_MILLISECONDS = 60_000;
+const REDRAW_MILLISECONDS = 1_000;
+
+export function formatElapsed(milliseconds) {
+  const totalSeconds = Math.max(0, Math.floor(milliseconds / 1_000));
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return minutes > 0 ? `${minutes}m ${seconds}s` : `${seconds}s`;
+}
+
+/**
+ * @param {{
+ *   stream: { write(text: string): unknown, isTTY?: boolean, columns?: number },
+ *   interactive?: boolean,
+ *   quiet?: boolean,
+ *   now?: () => number,
+ *   heartbeatMilliseconds?: number,
+ *   setInterval?: typeof setInterval,
+ *   clearInterval?: typeof clearInterval,
+ * }} options
+ */
+export function createProgressReporter({
+  stream,
+  // A terminal that cannot redraw (TERM=dumb) is handled as a log, like a pipe.
+  interactive = stream.isTTY === true,
+  quiet = false,
+  now = Date.now,
+  heartbeatMilliseconds = PROGRESS_HEARTBEAT_MILLISECONDS,
+  setInterval: schedule = setInterval,
+  clearInterval: cancel = clearInterval,
+}) {
+  let phase;
+  let phaseStartedAt = 0;
+  let waitStartedAt = 0;
+  let lastLineAt = 0;
+  let frame = 0;
+  let inPlace = false;
+  let timer;
+
+  function draw() {
+    if (phase === undefined) return;
+    frame = (frame + 1) % SPINNER_FRAMES.length;
+    const short = phase.replace(/^DEPLOYMENT_STATUS_/u, "");
+    const inPhase = formatElapsed(now() - phaseStartedAt);
+    const total = formatElapsed(now() - waitStartedAt);
+    // One row only: a wrapped line would leave rows the next redraw cannot clear.
+    // The phase and both counters are what a reader needs, so the wording around
+    // them is what gives way on a narrow terminal.
+    const width = Math.max(10, (stream.columns ?? 80) - 1);
+    const candidates = [
+      `${SPINNER_FRAMES[frame]} Waiting for the deployment (${short}); ${inPhase} in this phase, ${total} total`,
+      `${SPINNER_FRAMES[frame]} ${short}: ${inPhase} in phase, ${total} total`,
+      `${SPINNER_FRAMES[frame]} ${short} ${inPhase} (${total} total)`,
+    ];
+    const text = candidates.find((candidate) => candidate.length <= width) ?? candidates.at(-1).slice(0, width);
+    stream.write(`${ERASE_LINE}${text}`);
+    inPlace = true;
+  }
+
+  function clearInPlace() {
+    if (!inPlace) return;
+    stream.write(ERASE_LINE);
+    inPlace = false;
+  }
+
+  function endWait() {
+    if (timer !== undefined) {
+      cancel(timer);
+      timer = undefined;
+    }
+    clearInPlace();
+    phase = undefined;
+  }
+
+  function line(text) {
+    stream.write(`${text}\n`);
+    lastLineAt = now();
+  }
+
+  return {
+    report(message, event) {
+      if (quiet) return;
+      if (event?.phase === undefined) {
+        // A plain line. On a terminal the wait line is wiped and redrawn by the
+        // next tick, so the message is never glued to a half-written spinner.
+        clearInPlace();
+        line(message);
+        if (interactive && phase !== undefined) draw();
+        return;
+      }
+      const at = now();
+      if (phase === undefined) waitStartedAt = at;
+      const changed = phase !== event.phase;
+      if (changed) {
+        // The finished phase stays on screen as a line of its own.
+        if (interactive && phase !== undefined) {
+          clearInPlace();
+          line(`Deployment phase ${phase} finished after ${formatElapsed(at - phaseStartedAt)}.`);
+        }
+        phase = event.phase;
+        phaseStartedAt = at;
+      }
+      if (interactive) {
+        draw();
+        if (timer === undefined) {
+          timer = schedule(draw, REDRAW_MILLISECONDS);
+          timer.unref?.();
+        }
+        return;
+      }
+      if (changed) {
+        line(message);
+      } else if (at - lastLineAt >= heartbeatMilliseconds) {
+        line(`Still waiting for the deployment (${phase}); ${formatElapsed(at - waitStartedAt)} elapsed.`);
+      }
+    },
+
+    /** Ends the wait for a deployment (it finished or failed) while the run carries on. */
+    endWait,
+
+    /** Ends any wait in progress. Safe to call more than once. */
+    stop() {
+      endWait();
+    },
+  };
+}

package/src/redirects-contract.js

@@ -42,13 +42,16 @@ export const REDIRECT_STATUSES = Object.freeze([301, 302, 307, 308]);
 
 /**
  * Bounds, mirrored from `SiteRedirectMapContract` on the server. The path bound
- * is what fits a Workers KV key beside its `redirect:{environment}:{site}:`
- * envelope; the target bound is the edge's own.
+ * is the map's own; the target bound is the edge's own, and a target must also
+ * fit as metadata on its redirect file once encoded.
  */
 export const REDIRECT_LIMITS = Object.freeze({
   entries: 2_000,
   pathBytes: 400,
   targetBytes: 2_048,
+  // Once percent-encoded, a target rides on its redirect file as object
+  // metadata; the server pins the same number (MaxMarkerTargetEncodedLength).
+  targetEncodedCharacters: 1_810,
 });
 
 // C0, DEL, and C1 — every code point the server's own `char.IsControl`
@@ -88,8 +91,7 @@ const UNSENDABLE_SPELLING = /[^!-~]|["<>`{}]|%(?![0-9a-fA-F]{2})/u;
  * between the API's .NET and the edge's WHATWG parser, so a spelling this pass
  * encoded would still not be the one the Worker computes and the layers would
  * go on comparing different strings. Write what a browser sends and every layer
- * compares it unchanged — and the byte bounds then measure the spelling the KV
- * key actually costs.
+ * compares it unchanged — and the byte bounds then measure that same spelling.
  */
 function isRequestSpelling(value) {
   return !UNSENDABLE_SPELLING.test(value);
@@ -154,6 +156,70 @@ export function normalizeRedirectPath(value) {
   return trimmed === "" ? "/" : trimmed;
 }
 
+// The root segment the published output reserves for integration data; the release
+// inventory leaves everything under it out.
+const RESERVED_INTEGRATION_DATA_SEGMENT = "integrations";
+
+// Root-level files the site generates. A redirect is a marker file inside the
+// published site (TR00968), so a source that names one has nowhere to live.
+const GENERATED_ROOT_FILES = Object.freeze(["404.html", "sitemap.xml", "robots.txt", "favicon.ico"]);
+// The longest decoded path segment a marker file name may have; the API rule and the
+// generator use the same 200 bytes.
+const MAX_MARKER_SEGMENT_BYTES = 200;
+const WINDOWS_DEVICE_STEMS = new Set(["con", "prn", "aux", "nul"]);
+
+function isWindowsDeviceSegment(segment) {
+  const stem = segment.split(".", 1)[0].toLowerCase();
+  return WINDOWS_DEVICE_STEMS.has(stem) || /^(?:com|lpt)[1-9]$/u.test(stem);
+}
+
+/**
+ * Why a normalized source path cannot be a redirect, or undefined when it can.
+ * A mirror of `SiteRedirectMapContract.SourceRefusalReason` on the server (the
+ * API is the authority; both run the same test vectors): `…/index.html` is
+ * answered by the platform for every page, the generator writes the files
+ * named above, and the marker is stored under the decoded spelling, so a path
+ * that cannot be stored once decoded (an escaped percent sign, a dot-prefixed
+ * segment, a reserved device name) is refused. The site root is left to the
+ * occupancy rule.
+ */
+export function redirectSourceRefusalReason(path) {
+  if (path === "/") return undefined;
+  // Every rule reads the decoded spelling: it is the name the marker is stored
+  // under, and the name the generator's own files use (`/%69ndex.html` is
+  // `/index.html`).
+  let decoded;
+  try {
+    decoded = path.replace(/^\/+|\/+$/gu, "").split("/").map(decodeURIComponent).join("/");
+  } catch {
+    return "it holds a percent escape that does not decode.";
+  }
+  const segments = decoded.split("/");
+  const first = segments[0].toLowerCase();
+  if (segments.some((segment) => segment.toLowerCase() === "index.html")) {
+    return "the platform already redirects every '…/index.html' address to its directory, so it cannot also be "
+      + "a redirect source, and the page or home file there is generated.";
+  }
+  if (first === RESERVED_INTEGRATION_DATA_SEGMENT) {
+    return `'/${segments[0]}' is reserved for integration data, so nothing under it can be a redirect source.`;
+  }
+  if (GENERATED_ROOT_FILES.includes(first)) {
+    return `'/${segments[0]}' is a file the site generates, so neither it nor anything under it can be a redirect source.`;
+  }
+  if (
+    decoded.includes("..")
+    || decoded !== decoded.normalize("NFC")
+    || segments.some((segment) =>
+      segment === "" || segment.startsWith(".") || /[%\\?#\u0000-\u001F\u007F-\u009F]/u.test(segment)
+      || isWindowsDeviceSegment(segment) || new TextEncoder().encode(segment).length > MAX_MARKER_SEGMENT_BYTES
+    )
+  ) {
+    return "a redirect is stored as a file in the published site, and this path cannot be one (no dot-prefixed "
+      + "segments, reserved device names, '..', escaped percent signs, or segments over 200 bytes).";
+  }
+  return undefined;
+}
+
 function looksAbsolute(value) {
   return !value.startsWith("/") && value.includes("://");
 }
@@ -235,14 +301,21 @@ function validateEntry(value, index, seen) {
       `${field}.path`,
     );
   }
-  if (seen.has(path.toLowerCase())) {
+  const sourceRefusal = redirectSourceRefusalReason(path);
+  if (sourceRefusal !== undefined) {
+    throw entryError("redirects.path_unpublishable", `'${path}': ${sourceRefusal}`, `${field}.path`);
+  }
+  // The marker is stored under the decoded spelling, so `/a%41` and `/aA` are one
+  // file, and the second would silently replace the first.
+  const markerKey = decodeURIComponent(path).toLowerCase();
+  if (seen.has(markerKey)) {
     throw entryError(
       "redirects.path_duplicate",
       `'${path}' appears more than once; one path has one entry.`,
       `${field}.path`,
     );
   }
-  seen.add(path.toLowerCase());
+  seen.add(markerKey);
 
   const kind = value.kind === undefined ? REDIRECT_KIND_REDIRECT : value.kind;
   if (!REDIRECT_KINDS.includes(kind)) {
@@ -296,6 +369,15 @@ function validateEntry(value, index, seen) {
     );
   }
 
+  if (encodeURIComponent(rawTarget).length > REDIRECT_LIMITS.targetEncodedCharacters) {
+    throw entryError(
+      "redirects.target_too_long_to_store",
+      "'target' is stored as metadata on the published site's redirect file and is too long to fit "
+        + `(${REDIRECT_LIMITS.targetEncodedCharacters} characters once percent-encoded).`,
+      `${field}.target`,
+    );
+  }
+
   let target;
   if (looksAbsolute(rawTarget)) {
     if (!isAbsoluteRedirectTarget(rawTarget)) {
@@ -341,13 +423,23 @@ function validateEntry(value, index, seen) {
   return { path, kind: REDIRECT_KIND_REDIRECT, target, status };
 }
 
+// The marker is stored under the decoded spelling, so `/%61` and `/a` are one route
+// and `/%61 -> /a` is a loop. A target's escape may not decode; it then compares raw.
+function routeIdentity(path) {
+  try {
+    return decodeURIComponent(path).toLowerCase();
+  } catch {
+    return path.toLowerCase();
+  }
+}
+
 function assertNoChains(entries) {
-  const sources = new Set(entries.map((entry) => entry.path.toLowerCase()));
+  const sources = new Set(entries.map((entry) => routeIdentity(entry.path)));
   entries.forEach((entry, index) => {
     const targetPath = internalRedirectTargetPath(entry);
-    if (targetPath === undefined || !sources.has(targetPath.toLowerCase())) return;
+    if (targetPath === undefined || !sources.has(routeIdentity(targetPath))) return;
     const field = `entries[${index}].target`;
-    if (targetPath.toLowerCase() === entry.path.toLowerCase()) {
+    if (routeIdentity(targetPath) === routeIdentity(entry.path)) {
       throw entryError("redirects.loop", `'${entry.path}' redirects to itself.`, field);
     }
     throw entryError(

package/src/reference-help.js

@@ -602,8 +602,8 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "a separate staging handoff and checks the current map at the real edge, using an in-memory cookie and "
       + "manual redirects. It reports each path, HTTP status and Location without following targets.",
       "verified is true only if every entry matched and the map revision stayed unchanged during the check. "
-      + "The check proves the current map at staging, not a historical deployment. A mismatch can be propagation "
-      + "delay; re-run redirects check before promoting. Requests are bounded to 90 seconds, eight at a time; "
+      + "The check proves the current map at staging, not a historical deployment. A mismatch means the staged "
+      + "release does not carry the entry (yet); re-run redirects check after the deployment completes, before promoting. Requests are bounded to 90 seconds, eight at a time; "
       + "large JSON lists are truncated explicitly with failed entries first. Human output reports every entry.",
       "stagingPreview.url is a fresh, single-use two-minute handoff, minted after checks. It is emitted only "
       + "in final JSON, excluded from progress and GITHUB_OUTPUT; keep it private. The staging cookie lasts "
@@ -654,10 +654,15 @@ const WORKFLOW_REFERENCES = Object.freeze({
       "Converting an engagement's CSV into this file is the agent's job. The CLI's contract is JSON, on "
       + "purpose: a real migration list needs judgement about which old URLs still deserve a destination and "
       + "which are simply gone.",
-      "Entries take effect on the next deploy, staging first. They are written to the edge's key-value store "
-      + "when the deploy syncs routing, and that store is eventually consistent, so a spot-check run "
-      + "immediately afterwards can briefly still see the previous map. Re-check before concluding an entry "
-      + "did not land.",
+      "Entries take effect on the next deploy, staging first. Each is a file inside that release, so it goes live "
+      + "exactly when the release does: staging with the staged release, production when it 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.",
+      "A source cannot name a file the site generates: '/index.html' or any page's own 'index.html', '/404.html', "
+      + "'/sitemap.xml', '/robots.txt', '/favicon.ico', or a path under the sitemap or robots names. The platform "
+      + "already redirects every '…/index.html' address to its directory, so no entry is needed for one. A source "
+      + "that could not be stored as a file (a dot-prefixed segment, a reserved device name, an escaped percent "
+      + "sign) is refused too. 'validate' names the entry and the reason.",
     ]),
     example: Object.freeze({
       siteId: "<site-uuid>",

package/src/verbs/deploy.js

@@ -27,24 +27,18 @@ import { ApiError } from "../transport.js";
 import { readManifest, writeManifest } from "../workspace.js";
 
 /**
- * What a deploy does not finish (TR00702).
+ * When a redirect goes live (TR00702, TR00968).
  *
- * A deploy writes the site's redirect and gone entries into the edge's
- * key-value store as part of syncing routing. That store is eventually
- * consistent, so a spot-check run the second a deploy reports success can
- * briefly read the previous map, and taking that for "the redirect did not
- * land" is the wrong conclusion to reach in front of a customer waiting to cut
- * DNS over.
- *
- * No number is quoted, because there is none to quote: the coordinator holds
- * nothing back for a standard site's redirects. Its propagation grace governs
- * only the *deletion* of a superseded Docs pointer namespace; a standard site's
- * rows are written and removed immediately.
+ * 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.
  */
-const REDIRECT_PROPAGATION_NOTE =
-  "Redirect and gone entries are written to the edge's key-value store when this deploy syncs routing. That "
-  + "store is eventually consistent, so a spot-check run immediately afterwards can briefly still see the "
-  + "previous map; re-check before concluding an entry is missing.";
+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.";
 
 /**
  * `deploy --staging` / `deploy --production` — readiness, deploy, poll to
@@ -158,7 +152,7 @@ async function inspectStagingPreview(client, siteId, onProgress, now) {
     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.",
+        "Warning: staging redirects are not all verified. Check the reported mismatches against the staged release; run 'taproot-site redirects check' again once the deployment has completed.",
       );
     }
   } catch {
@@ -288,7 +282,7 @@ export async function deploy(invocation) {
         now,
       });
       await recordDeployment(config, manifest, "production", completed);
-      if (!presentationOnly) onProgress(REDIRECT_PROPAGATION_NOTE);
+      if (!presentationOnly) onProgress(REDIRECT_ACTIVATION_NOTE);
       return successResult(VERB_DEPLOY, siteId, {
         target,
         environment: DEPLOYMENT_ENVIRONMENT_PRODUCTION,
@@ -324,16 +318,22 @@ export async function deploy(invocation) {
     const stagedPageIds = presentationOnly ? [] : selection.stagedPageIds ?? defaults.stagedPageIds;
     const selectedSettingsTypes = selection.selectedSettingsTypes ?? defaults.selectedSettingsTypes;
     const includeNavigation = presentationOnly ? false : selection.includeNavigation ?? defaults.includeNavigation;
-    if (stagedPageIds.length === 0 && selectedSettingsTypes.length === 0 && !includeNavigation) {
-      throw new SiteAuthoringError(
+    const nothingSelected = stagedPageIds.length === 0 && selectedSettingsTypes.length === 0 && !includeNavigation;
+    // A managed Docs site stages settings only, so an empty selection is final.
+    // Any other site may still have a publishable change no selection names: an
+    // edited redirect map. Readiness below says whether it does.
+    const emptySelectionError = () =>
+      new SiteAuthoringError(
         "deploy.empty_selection",
         presentationOnly
           ? "A staging deployment on a managed Docs site needs at least one settings change; it stages settings "
             + "only. Change a theme, brand, header, or footer setting first."
-          : "A staging deployment needs at least one approved page, settings group, or navigation change. "
-            + "Run 'taproot-site approve' or change staged settings/navigation first.",
+          : "A staging deployment needs at least one approved page, settings group, or navigation change, or an "
+            + "edited redirect map. Run 'taproot-site approve' or change staged settings/navigation first.",
         { field: "Candidate" },
       );
+    if (nothingSelected && presentationOnly) {
+      throw emptySelectionError();
     }
 
     const candidate = {
@@ -359,6 +359,9 @@ export async function deploy(invocation) {
         { field: readiness.blockers[0].imageId || "blockers", status: readiness.blockers[0].state },
       );
     }
+    if (nothingSelected && !readiness.hasCandidateChanges) {
+      throw emptySelectionError();
+    }
     if (!readiness.hasCandidateChanges) {
       onProgress("Taproot reports this candidate contains no changes; deploying it anyway would be a no-op.");
     }
@@ -398,7 +401,7 @@ export async function deploy(invocation) {
       });
     }
     const stagingPreview = await inspectStagingPreview(client, siteId, onProgress, now);
-    onProgress(REDIRECT_PROPAGATION_NOTE);
+    onProgress(REDIRECT_ACTIVATION_NOTE);
     return successResult(VERB_DEPLOY, siteId, {
       target,
       environment: DEPLOYMENT_ENVIRONMENT_STAGING,

package/src/verbs/redirects-check.js

@@ -9,7 +9,7 @@ export async function redirectsCheck(invocation) {
     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.",
+        "Warning: staging redirects are not verified. Check the reported mismatches against the staged release and retry once its deployment has completed.",
       );
     }
     const handoff = await mintStagingPreviewHandoff(client, siteId, { now });