@taprootio/site-authoring 0.12.0 → 0.12.1

package/README.md

@@ -501,7 +501,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.1",
   "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/cli.js

@@ -251,7 +251,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 +276,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'.",
   },
   {

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,
@@ -398,7 +392,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 });