@taprootio/site-authoring 0.15.0 → 0.18.0

package/src/content/link-warnings.js

@@ -0,0 +1,109 @@
+import { sanitizeDiagnostic } from "../errors.js";
+import { boundedByBytes } from "../session.js";
+import { contentDocuments } from "../typed-pages.js";
+import { displayPagePath } from "../workspace.js";
+
+/**
+ * Links the editor made on its own before TR01191: text such as "ASP.NET"
+ * whose address is just "http://ASP.NET". The address names the text and
+ * nothing else (no path, query or fragment), so the author almost certainly
+ * never chose it. Reported as warnings so an author can remove them.
+ */
+export const LINK_AUTOLINKED = "content.link_autolinked";
+
+// Progress names this many; the JSON list is bounded by bytes instead.
+const MAXIMUM_PROGRESS_LINES = 20;
+
+export function autolinkedLinks(document) {
+  const found = [];
+  (function walk(node, depth) {
+    if (depth > 64 || node === null || typeof node !== "object" || !Array.isArray(node.content)) return;
+    // A link split across runs (part of it bold, say) is one link, so adjacent
+    // text sharing one href is read as one label.
+    let run;
+    const close = () => {
+      if (run !== undefined && looksAutolinked(run.text, run.href)) found.push(run);
+      run = undefined;
+    };
+    for (const child of node.content) {
+      const href = child?.type === "text" && typeof child.text === "string" && Array.isArray(child.marks)
+        ? child.marks.find((mark) => mark?.type === "link")?.attrs?.href
+        : undefined;
+      if (typeof href !== "string") {
+        close();
+        walk(child, depth + 1);
+      } else if (run !== undefined && run.href === href) {
+        run.text += child.text;
+      } else {
+        close();
+        run = { text: child.text, href };
+      }
+    }
+    close();
+  })(document, 0);
+  return found;
+}
+
+function looksAutolinked(text, href) {
+  const label = text.trim();
+  if (label === "" || /^[a-z][a-z0-9+.-]*:/iu.test(label)) return false;
+  let url;
+  try {
+    url = new URL(href);
+  } catch {
+    return false;
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return false;
+  if (url.pathname !== "/" || url.search !== "" || url.hash !== "" || url.username !== "" || url.port !== "") {
+    return false;
+  }
+  const written = href.replace(/^https?:\/\//iu, "").replace(/\/$/u, "");
+  return written.toLowerCase() === label.toLowerCase();
+}
+
+/**
+ * Links that look made by the editor's old autolinking ("ASP.NET" linked to
+ * http://ASP.NET), named so an author can remove them; never a refusal.
+ */
+export function autolinkWarnings(planned, onProgress) {
+  const items = [];
+  for (const page of planned ?? []) {
+    for (const link of pageDocuments(page.document).flatMap((document) => autolinkedLinks(document))) {
+      const item = {
+        code: LINK_AUTOLINKED,
+        file: page.file,
+        path: displayPagePath(page.pagePath),
+        text: [...sanitizeDiagnostic(link.text, "")].slice(0, 200).join(""),
+        href: [...sanitizeDiagnostic(link.href, "")].slice(0, 300).join(""),
+      };
+      if (items.length < MAXIMUM_PROGRESS_LINES) {
+        onProgress(
+          `Warning: '${item.text}' in ${item.file} links to ${item.href}, which looks made by autolinking; `
+            + "remove the link if nobody chose it.",
+        );
+      }
+      items.push(item);
+    }
+  }
+  if (items.length > MAXIMUM_PROGRESS_LINES) {
+    onProgress(`Warning: ${items.length - MAXIMUM_PROGRESS_LINES} more autolink-shaped link(s); see linkWarnings.`);
+  }
+  const reported = boundedByBytes(items, 8 * 1024);
+  return items.length === 0
+    ? {}
+    : { linkWarnings: { total: items.length, items: reported.items, ...(reported.truncated ? { truncated: true } : {}) } };
+}
+
+/**
+ * Every ProseMirror document a page carries: a free-form body, or a typed
+ * page's body, introduction and recipe steps. A page that failed validation
+ * may have none.
+ */
+function pageDocuments(document) {
+  if (document === null || typeof document !== "object") return [];
+  try {
+    return contentDocuments(document).map((entry) => entry.doc);
+  } catch {
+    return [];
+  }
+}

package/src/fixture-init.js

@@ -15,6 +15,8 @@ import {
   MANIFEST_FILE_NAME,
   MANIFEST_VERSION,
   PAGE_WORKSPACE_MODE_EDITABLE,
+  normalizePagePath,
+  PAGE_WORKSPACE_MODE_METADATA_ONLY,
   readManifest,
   readMediaManifest,
   readWorkspaceJson,
@@ -143,10 +145,14 @@ export async function initializeFixture(invocation, validate) {
       status: entry.status,
       templateType: entry.templateType,
       hasDraft: entry.hasDraft,
-      isGenerated: false,
+      isGenerated: entry.isGenerated === true,
       file,
       sourceFormat: "prosemirror",
       workspaceMode: "editable",
+      // What a generated page is, which its identity check needs offline.
+      ...(entry.generated !== null && typeof entry.generated === "object" && !Array.isArray(entry.generated)
+        ? { generated: entry.generated }
+        : {}),
     }));
     add(file, sanitize(page.document));
   }
@@ -194,6 +200,44 @@ export async function initializeFixture(invocation, validate) {
       ),
     );
   }
+  // Navigation and footer links may point at pages the fixture has no source
+  // for, such as generated section pages; they travel as metadata-only entries
+  // so the fixture validates as the site does (TR01198).
+  const editablePageCount = pages.length;
+  const linkedResourceIds = new Set();
+  (function collect(value) {
+    if (Array.isArray(value)) value.forEach(collect);
+    else if (value && typeof value === "object") {
+      for (const [key, child] of Object.entries(value)) {
+        if ((key === "resourceId" || key === "pageResourceId") && typeof child === "string") {
+          linkedResourceIds.add(child);
+        } else collect(child);
+      }
+    }
+  })([...documents.values()]);
+  for (const entry of source.pages) {
+    if (entry.workspaceMode !== PAGE_WORKSPACE_MODE_METADATA_ONLY) continue;
+    if (!isCanonicalUuid(entry.pageId) || !isCanonicalUuid(entry.resourceId)) continue;
+    if (!linkedResourceIds.has(identity(entry.resourceId))) continue;
+    const linkedPath = normalizePagePath(entry.path);
+    if (linkedPath === undefined || linkedPath === "") {
+      refuse(
+        `A page that is linked to has no usable path of its own (${JSON.stringify(entry.path ?? null)}); pull again.`,
+        "pages",
+      );
+    }
+    pages.push(sanitize({
+      pageId: entry.pageId,
+      resourceId: entry.resourceId,
+      path: linkedPath,
+      title: typeof entry.title === "string" ? entry.title : "",
+      status: entry.status,
+      templateType: entry.templateType,
+      hasDraft: entry.hasDraft === true,
+      isGenerated: entry.isGenerated === true,
+      workspaceMode: PAGE_WORKSPACE_MODE_METADATA_ONLY,
+    }));
+  }
   const redirects = documents.get("redirects.json");
   // A fixture hash is a local placeholder, not authority to mutate the original site.
   const revision = createHash("sha256").update(JSON.stringify(redirects.entries)).digest("hex");
@@ -242,10 +286,18 @@ export async function initializeFixture(invocation, validate) {
   try {
     for (const [file, value] of documents) await writeWorkspaceJson(destination, file, value);
     const result = await validate({ ...invocation, init: false, cwd, fixturePath: destination });
-    invocation.onProgress?.(`Initialized a sanitized fixture with ${pages.length} editable page(s).`);
+    invocation.onProgress?.(
+      `Initialized a sanitized fixture with ${editablePageCount} editable page(s)`
+        + `${pages.length > editablePageCount ? ` and ${pages.length - editablePageCount} linked page(s)` : ""}.`,
+    );
     return {
       ...result,
-      initialized: { directory: destination, pages: pages.length, skippedPages: source.pages.length - pages.length },
+      initialized: {
+        directory: destination,
+        pages: editablePageCount,
+        linkedPages: pages.length - editablePageCount,
+        skippedPages: source.pages.length - pages.length,
+      },
     };
   } catch (error) {
     await rm(destination, { recursive: true, force: true });

package/src/page-metadata.js

@@ -0,0 +1,92 @@
+import { SiteAuthoringError } from "./errors.js";
+import { boundedByBytes } from "./session.js";
+import { displayPagePath } from "./workspace.js";
+
+/**
+ * A page description is what search results and link previews show. Past about
+ * 160 characters search engines cut it off, so it is warned about; past 1000 it
+ * is refused, here and by the API (TR01194).
+ */
+export const DESCRIPTION_WARN_LENGTH = 160;
+export const DESCRIPTION_MAXIMUM_LENGTH = 1000;
+export const PAGE_DESCRIPTION_LONG = "pages.description_long";
+
+const length = (value) => [...value].length;
+
+/** Refuses a description the API would refuse. */
+export function requireDescriptionLength(description, field = "description") {
+  if (typeof description === "string" && length(description) > DESCRIPTION_MAXIMUM_LENGTH) {
+    throw new SiteAuthoringError(
+      "pages.description_too_long",
+      `The description is ${length(description)} characters; it may be at most ${DESCRIPTION_MAXIMUM_LENGTH} `
+        + `(search results show about ${DESCRIPTION_WARN_LENGTH}).`,
+      { field },
+    );
+  }
+}
+
+/** Warnings for descriptions search results will cut off, named per page. */
+export function descriptionWarnings(pages, onProgress) {
+  const items = [];
+  for (const page of pages ?? []) {
+    const description = page.declaredDescription ?? page.description;
+    if (typeof description !== "string" || length(description) <= DESCRIPTION_WARN_LENGTH) continue;
+    const item = {
+      code: PAGE_DESCRIPTION_LONG,
+      file: page.file,
+      path: displayPagePath(page.pagePath ?? page.path),
+      length: length(description),
+    };
+    onProgress(
+      `Warning: ${item.file}'s description is ${item.length} characters; search results show about `
+        + `${DESCRIPTION_WARN_LENGTH}.`,
+    );
+    items.push(item);
+  }
+  const reported = boundedByBytes(items, 8 * 1024);
+  return items.length === 0
+    ? {}
+    : {
+      descriptionWarnings: {
+        total: items.length,
+        items: reported.items,
+        ...(reported.truncated ? { truncated: true } : {}),
+      },
+    };
+}
+
+export const PAGE_AUTHOR_UNVERIFIED = "pages.author_unverified";
+
+/**
+ * Warnings for authors an offline run could not confirm (TR01196). The only
+ * evidence offline is `authors.json`, which is as old as the last `pull` or
+ * `authors list`, so a name missing from it may simply be newer; it is flagged
+ * rather than refused, and an online run settles it against the site.
+ */
+export function authorWarnings(pages, onProgress) {
+  const items = [];
+  for (const page of pages ?? []) {
+    if (page.authorUnverified !== true) continue;
+    const item = {
+      code: PAGE_AUTHOR_UNVERIFIED,
+      file: page.file,
+      path: displayPagePath(page.pagePath ?? page.path),
+      author: page.author,
+    };
+    onProgress(
+      `Warning: ${item.file} names author '${item.author}', who is not in authors.json; it may have been added `
+        + "since. 'taproot-site authors list' refreshes it, and 'pages push' checks the name against the site.",
+    );
+    items.push(item);
+  }
+  const reported = boundedByBytes(items, 8 * 1024);
+  return items.length === 0
+    ? {}
+    : {
+      authorWarnings: {
+        total: items.length,
+        items: reported.items,
+        ...(reported.truncated ? { truncated: true } : {}),
+      },
+    };
+}

package/src/reference-help.js

@@ -64,7 +64,12 @@ import {
   REDIRECTS_FILE_NAME,
 } from "./redirects-contract.js";
 import { SETTINGS_GROUPS } from "./settings-catalog.js";
-import { formatTypedPageReference, getTypedPageReference, TYPED_PAGE_TYPES } from "./typed-page-reference.js";
+import {
+  formatTypedPageReference,
+  getTypedPageReference,
+  MARKDOWN_PAGE_TYPES,
+  TYPED_PAGE_TYPES,
+} from "./typed-page-reference.js";
 import { PAGE_TEMPLATES } from "./typed-pages.js";
 import {
   INTERNAL_PAGE_BASELINE_DIRECTORY,
@@ -72,6 +77,7 @@ import {
   NAVIGATION_FILE_NAME,
   PAGE_SOURCE_EXTENSIONS,
   PAGE_WORKSPACE_MODE_EDITABLE,
+  PAGE_WORKSPACE_MODE_METADATA_ONLY,
   PAGES_DIRECTORY,
   pageSourceFormat,
   SETTINGS_DIRECTORY,
@@ -80,7 +86,7 @@ import {
 
 export { getAppearanceReference, getFooterReference, getThemeReference };
 
-export const REFERENCE_VERSION = 34;
+export const REFERENCE_VERSION = 36;
 
 // The date-limit examples `help forms` prints; tests run them through the form validator.
 export const FORM_DATE_WINDOW_FIELD = Object.freeze({
@@ -672,10 +678,16 @@ const WORKFLOW_REFERENCES = Object.freeze({
       "Run 'redirects check' after staging, or read deploy --staging's automatic check. The Node CLI consumes "
       + "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.",
+      "The result carries routeCheck (resolved or unresolved) and redirects: { revision, revisionUnchanged, "
+      + "verified, total, checked, matched, failed, items: [{ path, status, location, expectedStatus, matches, "
+      + "error? }], itemsTruncated? }, at the top level of both redirects check and deploy --staging. An entry "
+      + "whose request failed carries error: \"request_failed\". A check that cannot finish at all reports "
+      + "verified: false, an empty items list and redirects.error { code, message }.",
       "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 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.",
+      + "large JSON lists are truncated explicitly with failed entries first (redirects.itemsTruncated). Progress "
+      + "output reports every entry on stderr; --quiet hides it.",
       "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 "
       + "five minutes and remains subject to current site/host/credential permission.",
@@ -937,7 +949,9 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + `sourceFormat, and workspaceMode ${PAGE_WORKSPACE_MODE_EDITABLE}. Album images and the cover image must be `
       + "listed in fixture.imageIds. "
       + "status, hasDraft, isGenerated, and description are recorded by pull and not read: the page key set "
-      + "stays open so a fixture from a newer pull is not refused. The homepage's path is the empty string.",
+      + "stays open so a fixture from a newer pull is not refused. The homepage's path is the empty string. "
+      + `An entry with workspaceMode ${PAGE_WORKSPACE_MODE_METADATA_ONLY} names a page the fixture has no source for, `
+      + "such as a generated section page navigation links to: pageId, resourceId and path, and no file.",
       `file lives under '${PAGES_DIRECTORY}/' and ends in ${PAGE_SOURCE_EXTENSIONS.join(" or ")}; sourceFormat must be `
       + `the format that extension implies (${
         PAGE_SOURCE_EXTENSIONS.map((extension) => `${extension} is '${pageSourceFormat(`page${extension}`)}'`).join(
@@ -971,8 +985,9 @@ const WORKFLOW_REFERENCES = Object.freeze({
       "validate reads the fixture and writes nothing to it. Copy the directory somewhere writable before editing it.",
       "validate --init <new-directory> exports the current pulled workspace as a validated version-7 fixture with "
       + "appearance and footer metadata. Run from the workspace or its configured project; --config may select the source.",
-      "Initialization keeps editable pages of every template as workspace documents and reports excluded metadata-only pages. "
-      + "References to excluded pages must be resolved before the fixture can validate. It never copies credentials, "
+      "Initialization keeps editable pages of every template as workspace documents. A metadata-only page that "
+      + "navigation, the footer or a page links to is kept as a metadata-only entry (initialized.linkedPages); other "
+      + "metadata-only pages are left out (initialized.skippedPages). It never copies credentials, "
       + "internal reconciliation state, or deployment receipts. UUIDs and HTTP(S) origins are replaced with deterministic "
       + "fixture identities and example.test origins; URL credentials, queries and fragments are removed. Authored prose is retained.",
       "The destination must be outside the source workspace and must not exist; its parent must already exist without symlinks. Exports are bounded to 64 MiB. "
@@ -1518,6 +1533,31 @@ const FREE_FORM_REFERENCE = Object.freeze({
         + "refuses before changing anything under pages/ and preserves the site's version as internal state. A "
         + "locally edited .pm.json is kept rather than overwritten, and only collides when the site changed too.",
       conflictError: "pages.pull_conflict",
+      metadata:
+        "A .pm.json page's title, path and description live in the manifest, not the file. Change the title or "
+        + "description with pages meta set <path> --title/--description; a Markdown page keeps them in its front "
+        + "matter. pull keeps such an edit until pages push sends it, and a site edit to the same page is a "
+        + "pages.pull_conflict. A description over 160 characters is warned about (search results cut it off); "
+        + "over 1000 is refused.",
+      authorship:
+        "Pages are authorless by default: a page created without an author publishes with no byline, and pages push "
+        + "lists the pages it created that way in pages.authorless. Name an author with author: in the front matter "
+        + "(every template) or, for a .pm.json page, pages meta set <path> --author. An author is a site author "
+        + "without a Taproot account, named by handle (jane-doe), or a site member who can create pages, named by "
+        + "email address. authors list shows who can be named and rewrites authors.json; authors add <handle> "
+        + "--name <name> [--email <address>] creates a site author, whose address stays private. A site author's "
+        + "name appears on the byline and in structured data, with no profile link or follow button. authors add "
+        + "again with the same handle and name succeeds (existing: true); another name for a taken handle is "
+        + "authors.handle_taken. Only the CLI assigns authors, and only to a page that has none. authors.json is as old "
+        + "as the last pull or authors list, so offline commands (validate, pages meta set) only warn "
+        + "(pages.author_unverified) about a name it lacks; pages push and plan read the site's current list once on a "
+        + "miss and refuse only a name the site lacks. The CLI only fills a page that has no author: a different one "
+        + "already on the page is pages.author_conflict, which names the way out (pages meta set <path> --author "
+        + "<the site's author> for a .pm.json page, the author: line for Markdown, or pages meta set <path> --author "
+        + "\"\" to drop an author that was never sent), naming the author a page already has changes nothing, and a "
+        + "name that is unknown or belongs to a member who cannot create pages is pages.author_unknown either way. "
+        + "Text that is neither a handle nor an address is pages.author_invalid.",
+      authorshipErrors: Object.freeze(["pages.author_invalid", "pages.author_unknown", "pages.author_conflict"]),
       conflictDetail:
         "A reported conflict names the JSON paths at which the site's document differs from the copy this workspace "
         + "last reconciled with, in error.differences, which carries three states. Absent: the two documents were "
@@ -1569,13 +1609,23 @@ const FREE_FORM_REFERENCE = Object.freeze({
             inheritedForTracked: true,
             defaultForNew: "",
           }),
+          Object.freeze({
+            name: "author",
+            type: "string",
+            requiredForNew: false,
+            inheritedForTracked: true,
+            defaultForNew: "",
+            description:
+              "A site author's handle (jane-doe) or a member's email address. Omit it for an authorless page; it "
+              + "only fills a page that has none, and never replaces one.",
+          }),
           Object.freeze({
             name: "template",
             type: "string",
             requiredForNew: false,
             inheritedForTracked: false,
             defaultForNew: "free-form",
-            description: `Other templates: ${TYPED_PAGE_TYPES.join(", ")}; see '${CLI_BINARY_NAME} help pages'.`,
+            description: `Other templates: ${MARKDOWN_PAGE_TYPES.join(", ")}; see '${CLI_BINARY_NAME} help pages'.`,
           }),
         ]),
       }),
@@ -1866,7 +1916,7 @@ export function formatReferenceResult(result) {
         page.workspace.formats.map((format) => `  ${format.extension.padEnd(9)} ${format.purpose}`).join("\n")
       }\n\nOne source per page:\n  rule                  ${sourceRule.rule}\n  manifest fields       ${
         sourceRule.manifestFields.join(", ")
-      }\n  pull                  ${sourceRule.pull}\n  internal state        ${sourceRule.internalState}\n  format change         ${sourceRule.formatChange} (${sourceRule.formatChangeError})\n  renamed source        ${sourceRule.renamedSource} (${sourceRule.renamedSourceError})\n  conflicts             ${sourceRule.conflict} (${sourceRule.conflictError})\n  conflict detail       ${sourceRule.conflictDetail}\n  push conflicts        ${sourceRule.pushConflict} (${sourceRule.pushConflictError})\n  revision              ${sourceRule.revisionSource}\n  recovery              ${sourceRule.conflictRecovery}\n  push selection        ${sourceRule.pushSelection}\n\nSystem pages: ${page.workspace.systemPages}\n\nMarkdown front matter:\n${
+      }\n  pull                  ${sourceRule.pull}\n  internal state        ${sourceRule.internalState}\n  format change         ${sourceRule.formatChange} (${sourceRule.formatChangeError})\n  renamed source        ${sourceRule.renamedSource} (${sourceRule.renamedSourceError})\n  conflicts             ${sourceRule.conflict} (${sourceRule.conflictError})\n  conflict detail       ${sourceRule.conflictDetail}\n  push conflicts        ${sourceRule.pushConflict} (${sourceRule.pushConflictError})\n  revision              ${sourceRule.revisionSource}\n  recovery              ${sourceRule.conflictRecovery}\n  push selection        ${sourceRule.pushSelection}\n  authors               ${sourceRule.authorship} (${sourceRule.authorshipErrors.join(", ")})\n\nSystem pages: ${page.workspace.systemPages}\n\nMarkdown front matter:\n${
         markdownFormat.metadata.map(formatMetadata).join("\n")
       }\n\nDocument root: { "type": "doc", "content": [...] }\nSupported nodes: ${
         page.document.nodes.join(", ")

package/src/staging-check.js

@@ -152,3 +152,65 @@ export async function checkStagingRedirects(client, siteId, onProgress, now) {
     },
   };
 }
+
+/**
+ * The staging redirect check and a fresh preview handoff, as redirects check and
+ * deploy --staging report them. A check that cannot finish keeps the same shape,
+ * with the reason.
+ */
+export async function inspectStagingPreview(client, siteId, onProgress, now) {
+  let routeCheck;
+  let redirects;
+  let stagingUrl;
+  try {
+    ({ routeCheck, redirects, stagingUrl } = await checkStagingRedirects(client, siteId, onProgress, now));
+    if (!redirects.verified) {
+      onProgress(
+        "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 (error) {
+    onProgress(
+      "Warning: the authenticated staging redirect check could not finish. Run 'taproot-site redirects check' again.",
+    );
+    routeCheck = "unresolved";
+    redirects = {
+      total: 0,
+      checked: 0,
+      matched: 0,
+      failed: 0,
+      verified: false,
+      items: [],
+      error: redirectCheckError(error),
+    };
+  }
+  try {
+    // Mint after checks so the final single-use URL has never been consumed.
+    const stagingPreview = await mintStagingPreviewHandoff(client, siteId, { now });
+    return { routeCheck, redirects, stagingPreview };
+  } catch {
+    onProgress("Warning: a staging handoff could not be minted.");
+    return {
+      routeCheck,
+      redirects,
+      stagingPreview: {
+        url: "",
+        ...(stagingUrl ? { stagingUrl } : {}),
+        warning: "Staging handoff unavailable; run redirects check to retry.",
+      },
+    };
+  }
+}
+
+/**
+ * Why the automatic redirect check could not finish. Only this CLI's own
+ * errors carry their code and message; anything else (a timeout, a network
+ * failure) is named, never echoed, since its text is not ours to publish.
+ */
+function redirectCheckError(error) {
+  if (error instanceof SiteAuthoringError) {
+    return { code: error.code, message: sanitizeDiagnostic(error.message, "The redirect check could not finish.") };
+  }
+  const name = typeof error?.name === "string" && /^[A-Za-z]{1,40}$/u.test(error.name) ? error.name : "Error";
+  return { code: "redirects.check_failed", message: `The redirect check could not finish (${name}).` };
+}

package/src/transport.js

@@ -1,10 +1,12 @@
 import {
+  BANDWIDTH_ALLOWANCE_REFUSAL_REASON,
   CAPABILITY_REFUSAL_FIELD,
   CAPABILITY_REFUSAL_REASON,
   CLI_NAME,
   CLI_UPGRADE_REFUSAL_FIELD,
   CLI_VERSION,
   CREDENTIAL_REFUSAL_FIELD,
+  DEPLOYMENT_ALLOWANCE_REFUSAL_REASON,
   GRPC_RESOURCE_EXHAUSTED,
   GRPC_UNAUTHENTICATED,
   HTTP_TOO_MANY_REQUESTS,
@@ -21,6 +23,7 @@ import {
   REFUSAL_THROTTLED,
   REFUSAL_UNCLASSIFIED,
   ROLLOUT_REFUSAL_FIELD,
+  SITE_DEPLOYMENT_REFUSAL_DOMAIN,
 } from "./constants.js";
 import { Readable } from "node:stream";
 
@@ -409,15 +412,10 @@ function capabilityNames(value) {
  * keys on it rather than on `@type`, which a future packing could reshape.
  */
 export function capabilityRefusal(value) {
-  const queue = [{ value, depth: 0 }];
-  let work = 0;
-  while (queue.length > 0 && work < 1_000) {
-    const current = queue.shift();
-    work += 1;
-    if (!current || current.depth > 8 || current.value === null || typeof current.value !== "object") continue;
-    const metadata = current.value.metadata;
+  return findErrorInfo(value, (detail) => {
+    const metadata = detail.metadata;
     if (
-      current.value.reason === CAPABILITY_REFUSAL_REASON
+      detail.reason === CAPABILITY_REFUSAL_REASON
       && metadata !== null
       && typeof metadata === "object"
       && !Array.isArray(metadata)
@@ -434,6 +432,61 @@ export function capabilityRefusal(value) {
         });
       }
     }
+    return undefined;
+  });
+}
+
+/**
+ * The pages-generated allowance or bandwidth-pause refusal the deploy API attaches
+ * as a `google.rpc.ErrorInfo` detail (TR00445, TR01201), or undefined. Keyed on the
+ * namespaced domain and reason, never the message sentence. `resetsAt` is the
+ * server's `resets_at` re-serialized as an ISO-8601 UTC instant, or undefined
+ * when it is absent (a licence that grants no deployments has no period) or
+ * does not parse. `requestedPages` and `remainingPages` are present on the
+ * allowance refusal only.
+ */
+export function planLimitRefusal(value) {
+  return findErrorInfo(value, (detail) => {
+    if (
+      detail.domain !== SITE_DEPLOYMENT_REFUSAL_DOMAIN
+      || (detail.reason !== DEPLOYMENT_ALLOWANCE_REFUSAL_REASON && detail.reason !== BANDWIDTH_ALLOWANCE_REFUSAL_REASON)
+    ) {
+      return undefined;
+    }
+    const metadata = detail.metadata !== null && typeof detail.metadata === "object" ? detail.metadata : {};
+    const resetsAt = typeof metadata.resets_at === "string" ? new Date(metadata.resets_at) : undefined;
+    return Object.freeze({
+      reason: detail.reason,
+      resetsAt: resetsAt !== undefined && !Number.isNaN(resetsAt.getTime()) ? resetsAt.toISOString() : undefined,
+      // The pages the refused request needed and the period had left (TR01201).
+      requestedPages: pageCount(metadata.requested_pages),
+      remainingPages: pageCount(metadata.remaining_pages),
+    });
+  });
+}
+
+/** A page count the server reported as a decimal string, or undefined. */
+function pageCount(value) {
+  const count = typeof value === "string" && /^[0-9]{1,9}$/u.test(value) ? Number(value) : undefined;
+  return Number.isSafeInteger(count) ? count : undefined;
+}
+
+/**
+ * The first object in `value`, breadth first, for which `match` returns a
+ * result. Transcoded `details[]` entries are `Any`-packed and nested, so one
+ * pinned path through them would silently empty every extractor on a contract
+ * change; the walk is bounded in depth and in work so a hostile body cannot
+ * stall it.
+ */
+function findErrorInfo(value, match) {
+  const queue = [{ value, depth: 0 }];
+  let work = 0;
+  while (queue.length > 0 && work < 1_000) {
+    const current = queue.shift();
+    work += 1;
+    if (!current || current.depth > 8 || current.value === null || typeof current.value !== "object") continue;
+    const found = match(current.value);
+    if (found !== undefined) return found;
     for (const child of Object.values(current.value)) {
       if (child !== null && typeof child === "object") queue.push({ value: child, depth: current.depth + 1 });
     }
@@ -459,6 +512,7 @@ export class ApiError extends SiteAuthoringError {
     const grpcCode = Number.isSafeInteger(body?.code) ? body.code : undefined;
     const fields = fieldViolations(body);
     const capability = capabilityRefusal(body);
+    const planLimit = planLimitRefusal(body);
     // Only the known upgrade refusal may supply a human message. Other server
     // errors can contain internal diagnostics and retain their generic output.
     const upgradeMessage = fields.includes(CLI_UPGRADE_REFUSAL_FIELD)
@@ -472,6 +526,10 @@ export class ApiError extends SiteAuthoringError {
       "api.request_rejected",
       upgradeMessage || (fields.length > 0
         ? `Taproot rejected the request field '${fields[0]}'.`
+        : planLimit !== undefined
+        ? planLimit.reason === BANDWIDTH_ALLOWANCE_REFUSAL_REASON
+          ? "Taproot paused deployments: the site used more than its monthly bandwidth for two months in a row."
+          : "Taproot refused the request: it generates more pages than the site's allowance for this billing period has left."
         : capability !== undefined
         ? `Taproot refused the request: this credential does not carry a capability granting '${
           capability.permission
@@ -491,6 +549,7 @@ export class ApiError extends SiteAuthoringError {
     this.fields = fields;
     this.violationDescriptions = fieldDescriptions(body);
     this.capability = capability;
+    this.planLimit = planLimit;
     // The `retry-after` trailer (TR00839's deployment throttle, or any other
     // ResourceExhausted refusal that sets it) transcodes to an ordinary
     // response header. Undefined when absent or unparseable — callers must
@@ -545,10 +604,12 @@ export class ApiError extends SiteAuthoringError {
    *   left it unclassified: no `refusal` in the JSON result, and nothing said
    *   on the human channel. The field arrives only from the in-transaction
    *   re-validation, which does attach `ExternalApiKey`.
-   * - `plan_limit` (field `UpgradePrompt`) — a commercial ceiling, surfaced at
+   * - `plan_limit` (field `UpgradePrompt`, or `ErrorInfo` reason
+   *   `DEPLOYMENT_PERIOD_ALLOWANCE_EXCEEDED` / `BANDWIDTH_ALLOWANCE_EXCEEDED`
+   *   with the server's `resets_at`) — a commercial ceiling, surfaced at
    *   deploy time because no pre-flight read of the published-page quota
-   *   exists on the contract. **Upgrade** (or publish fewer pages); the CLI
-   *   never invents the numeric limit.
+   *   exists on the contract. **Upgrade** (or publish fewer pages, or wait for
+   *   the named reset); the CLI never invents the numeric limit.
    * - `throttled` (gRPC `ResourceExhausted` / HTTP 429) — the per-key
    *   throttle. **Back off** and retry with delay.
    * - `capability_missing` (`ErrorInfo` reason `SITE_AUTHORING_CAPABILITY_MISSING`)
@@ -568,7 +629,7 @@ export class ApiError extends SiteAuthoringError {
     if (this.hasField(CLI_UPGRADE_REFUSAL_FIELD)) return REFUSAL_CLI_OUTDATED;
     if (this.hasField(ROLLOUT_REFUSAL_FIELD)) return REFUSAL_PLATFORM_PAUSED;
     if (this.hasField(CREDENTIAL_REFUSAL_FIELD)) return REFUSAL_CREDENTIAL_REJECTED;
-    if (this.hasField(PLAN_LIMIT_REFUSAL_FIELD)) return REFUSAL_PLAN_LIMIT;
+    if (this.hasField(PLAN_LIMIT_REFUSAL_FIELD) || this.planLimit !== undefined) return REFUSAL_PLAN_LIMIT;
     // The named detail ranks with the fields and above the status mappings, for
     // the same reason: it is the specific statement about this refusal.
     if (this.capability !== undefined) return REFUSAL_CAPABILITY_MISSING;