@taprootio/site-authoring 0.15.0 → 0.18.0

package/README.md

@@ -124,8 +124,12 @@ with no credential, no network, and no write: every page source (metadata,
 Markdown conversion, media references, content vocabulary, section contexts),
 page paths and templates against the pages the pull recorded, navigation,
 redirects, forms, and the complete theme, appearance, header, brand, and
-footer. It reports every problem at once in `error.problems`, each with its
-file, code, and field, instead of one per run.
+footer. Navigation to a generated page (a section, tag or place page) resolves
+against the pages the pull recorded. It reports every problem at once in
+`error.problems`, each with its file, code, and field, instead of one per run.
+Warnings never refuse: `linkWarnings` names a link whose address is only
+`http(s)://` plus its own text (`content.link_autolinked`, left by older editor
+autolinking), and `pages push` reports the same for the pages it sends.
 
 `taproot-site validate <fixture-directory>` checks a complete offline fixture
 the same way: a directory laid out like a
@@ -360,6 +364,92 @@ it is created: a source for another template is refused with
 `pages.template_immutable`. `taproot-site help page <type>` gives each
 template's fields and one worked example.
 
+A `.pm.json` page's title, path, description and author live in the workspace
+manifest rather than the file. `pages meta set <path> --title <text>
+--description <text>` changes the title or description there (a Markdown page
+keeps them in its front matter; `--author` is described under *Page authors*); `pull` keeps that 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 a warning (`descriptionWarnings`), because
+search results cut it off; over 1000 is refused with
+`pages.description_too_long`, by the CLI and by Taproot.
+
+### Page authors
+
+Pages are authorless by default: a page you create with the CLI publishes with
+no byline unless you name an author, and `pages push` lists the pages it created
+that way in `pages.authorless`, with how to credit them. An author is one of two
+kinds of person, named by one string:
+
+- a **site author without a Taproot account** — one of an imported blog's
+  authors, say — named by handle (`jane-doe`: lowercase letters, digits and
+  single hyphens, at most 64 characters, fixed when the author is created). A
+  site author's name appears on the byline and in the page's structured data;
+  there is no profile link or follow button, because there is no account;
+- a **site member who can create pages**, named by email address.
+
+`authors list` prints both and rewrites `authors.json` (`pull` writes it too).
+`authors add jane-doe --name "Jane Doe" [--email jane@example.com]` creates a
+site author; `--email` is kept private (never published, never listed) so the
+person can be linked to a Taproot account later. Adding a handle the site
+already has under the same name succeeds and reports `existing: true`, so a
+script can repeat itself; a different name for a taken handle is refused
+(`authors.handle_taken`), naming the one the site has. `authors.json` holds the
+members' email addresses, so keep it out of a public repository.
+
+A page names its author with `author: jane-doe` in its front matter (any
+template), or, for a `.pm.json` page, `pages meta set <path> --author jane-doe`.
+Only the CLI assigns authors, and only to a page that has none; people editing
+in the app are never asked to name one. `authors.json` is as old as the last
+`pull` or `authors list`, so a name missing from it is not proof the person does
+not exist. `validate` and `pages meta set` run offline: they refuse text that
+is neither a handle nor an address (`pages.author_invalid`) and otherwise only
+warn (`pages.author_unverified`, in `authorWarnings`) about a name `authors.json`
+lacks. `pages push` and `plan` settle it online: on a miss they read the site's
+current list once (`pages push` rewrites `authors.json` with it) and refuse
+(`pages.author_unknown`) only a name the site really lacks. A member who cannot
+create pages is `pages.author_unknown` as well, with the same wording.
+
+The CLI only fills a page that has no author: a page that already has a
+different one is refused (`pages.author_conflict`), by the CLI from what the
+last pull recorded and by Taproot, and naming the author a page already has
+changes nothing. The refusal says how to settle it: for a `.pm.json` page,
+`pages meta set <path> --author <the site's author>` matches the site, and
+`pages meta set <path> --author ""` drops an author that was never sent (it
+never asks the site to remove one, and is refused once the site holds an
+author); for a Markdown page, fix the `author:` line. `pull` keeps a pending
+author the site now disagrees with and says so. The author is recorded on the
+page's manifest entry (`author`, and `baseline.author` for what the site
+held), so a re-push never resends it. The site names a page's author in
+listings only while that person can still be named: a former member's page, or
+a member who can no longer create pages, reports none, and a push that names
+someone else on it is refused as a conflict.
+
+Pages Taproot generates from the site's content — a tag, the tags index, a
+published year or month, a place archive, a folder — are update-only sources.
+`pull` writes each as `pages/<name>.pm.json` with `"template": "generated"`:
+`data` holds what the page is (`kind`, `tagId`, `year`, `month`, `countryCode`,
+`regionCode`, `citySlug`, `categorySlug`, which you leave as pulled) and the four
+things that are yours to author: `customTitle`, `breadcrumbTitle`,
+`customDescription` and `introductionBody`. An empty string means "use the
+generated default"; the description then falls back to the introduction's first
+paragraph, else the system default. The manifest keeps the title and description
+the site reports, for reference. `pages meta set <path> --title/--description`
+edits `customTitle` and `customDescription` in the source (an empty value
+clears it), and `pages push` sends the page back as an unapproved draft. The
+title and description the site stores are derived from `customTitle`,
+`customDescription` and `introductionBody`, so what a push sends for them is
+ignored. A push refuses to create a generated page (`pages.generated_create`),
+move one (`pages.generated_move`) or change its kind or identity
+(`pages.generated_identity`, also when the manifest has no record of what the
+file was pulled as: run `pull`); there is no Markdown form
+(`pages.generated_markdown`). A generated page you did not edit never blocks a
+push of the whole workspace, even when Taproot moved it since the pull (a tag was
+renamed). If the site no longer has the page (its tag, month or folder is gone),
+a whole-workspace push reports the file under `pages.staleGeneratedSources` and
+sends nothing for it, and `pull` says so; delete the file. Naming that path in
+`pages push <page-path>` is refused with `pages.generated_create`. A description over 160 characters is warned about,
+since search results cut it off, and one over 1000 is refused.
+
 `pages push [page-path...]` validates and sends the selected pages, or every
 workspace page when none is named; the homepage is addressed as `/`. Every
 selected page is checked before anything is sent, and a refusal lists every
@@ -374,7 +464,8 @@ moved since this workspace last reconciled with it, naming both revisions;
 names and reports predictions with a session token; `places select
 <googlePlaceId> <sessionToken>` records the match as a Taproot place and
 reports the `placeId` a place review's front matter needs. An article or an
-album can name its place the same way with `place:`.
+album can name its place the same way with `place:`. `places category set
+<placeId> <category>` changes the category this site shows for a place.
 
 `plan` checks the whole workspace against the live site — pages, the media
 they reference and the images the settings name, the footer and the pages it
@@ -477,8 +568,10 @@ paused; retry later), `credential_rejected` (stop and re-issue),
 not exchanged for a capability the request needs; the refusal carries
 `field: "GrantedCapabilities"`, and the CLI's human progress names the
 granted and required capabilities, so report the verb's declared set rather
-than re-issuing the key), `plan_limit` (the plan's published-page allowance,
-surfaced at deploy), and `throttled` (back off).
+than re-issuing the key), `plan_limit` (the plan's published-page allowance or
+its pages-generated allowance, or the bandwidth pause on deploys,
+surfaced at deploy; the allowance shows its reset time, while the bandwidth pause shows the earliest
+time it can lift, since it lifts only after a month ends under the allowance or on upgrade), and `throttled` (back off).
 
 When `GITHUB_OUTPUT` names the runner's existing output file, every
 operational verb appends the same JSON under `taproot_site_result` through a
@@ -545,6 +638,69 @@ Other C0/C1 controls, U+2028/U+2029, U+FEFF, and literal `<br>` tags are rejecte
 with the exact fact field path. A label is optional and stays outside the value's link. See
 `taproot-site help page free-form` and `taproot-site help component cta`.
 
+### Place categories in 0.18.0
+
+A place has one category for every site, taken from Google's types, and a place
+that Taproot could not classify is filed under `Other`. A site can file a place
+under a category of its own:
+
+```
+taproot-site places category list
+taproot-site places category set <placeId> park
+taproot-site places category clear <placeId>
+```
+
+`list` prints the closed list `set` accepts; a name outside it is refused, and
+capitalization is ignored. The category is the site's alone and applies to every
+review of that place on the site: the place itself and other sites do not
+change. Place-review bylines and the `/places/<category>` pages use it from the
+site's next deployment, including reviews nobody has edited. `clear` removes it.
+Both need the same page-editing permission as `places select`.
+
+### Pages generated in 0.18.0
+
+A site's licence allows a number of pages generated per billing period, and
+`deploy --staging` is charged by the pages it generates, not by the deployment.
+The deploy asks Taproot to plan the candidate first and reports the plan before
+it sends anything: `This will generate 74 pages · 940 of 1,000 left this period
+(resets 2026-11-01T00:00:00.000Z)`. The same figures are in `readiness.pageEstimate`
+(`plannedPageCount`, `pagesGeneratedLimit`, `pagesGeneratedRemaining`, `periodEnd`
+and `exceedsAllowance`; a limit and what remains are `null` on an unlimited
+licence). The number shown is the number charged. Promoting a staged release to
+production generates nothing and costs no pages.
+
+A candidate that does not fit stops with `deploy.page_allowance_exceeded`, naming
+the pages it needs, the pages left, and the reset. A deploy refused by the server
+for the same reason, or for the bandwidth pause, reports `plan_limit` with the
+time it can lift (and `requested_pages` and `remaining_pages` for the allowance):
+the allowance's reset, or for the bandwidth pause the earliest month end that can
+clear it (an upgrade clears it at once).
+
+### Deployment allowances in 0.18.0
+
+A deploy refused for the bandwidth pause reports `plan_limit` with the time it
+can lift: the earliest month end that can clear it (an upgrade clears it at
+once).
+
+### Authoring feedback in 0.16.0
+
+- `pages meta set <path> --title/--description/--author` edits a `.pm.json`
+  page's title, description or author; `pull` keeps the edit until `pages push`
+  sends it. Descriptions are warned about over 160 characters and refused over
+  1000, here and by Taproot.
+- Generated pages (tags, archives, places, folders) pull as update-only sources
+  whose custom title, breadcrumb, description and introduction you can edit.
+- Pages are authorless by default. `authors list`, `authors add` and
+  `authors.json` name a member who can create pages or a site author without a
+  Taproot account; `author:` front matter or `pages meta set --author` credits
+  one on a page that has none, and an author is never replaced from the CLI.
+- `redirects check` and `deploy --staging` report `routeCheck`, `redirects` and
+  `stagingPreview` at the top level; result paths spell the home page `/`;
+  `approve` skips a page with nothing to approve instead of failing the batch.
+- `validate` checks a real pulled workspace offline (`validate --init` keeps the
+  generated pages navigation links to), and `validate` and `pages push` warn on
+  links that look made by autolinking (`content.link_autolinked`).
+
 ### Link rel in 0.15.0
 
 A link publishes followed unless its author chooses otherwise. A link mark's
@@ -579,13 +735,15 @@ 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 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
+memory, and requests each map path without following redirects. Both
+`redirects check` and `deploy --staging` report `routeCheck` and `redirects` at
+the top level of their result: `redirects.items` lists each path, HTTP status
+and Location, and `redirects.verified` requires all entries to match and the
 map revision to remain unchanged. A mismatch is evidence to investigate, not a
 failed deployment. Checks describe the current map, not a historical release.
 Requests have a 90-second deadline with eight concurrent requests; large JSON
-lists have explicit truncation, prioritizing failures. Human output reports each
-entry. A gate/transport failure never counts as verified.
+lists have explicit truncation, prioritizing failures. Progress output reports
+each entry. A gate/transport failure never counts as verified.
 
 `stagingPreview.url` is a fresh single-use two-minute handoff minted **after**
 checks. Opening it consumes it and establishes a five-minute staging cookie.
@@ -640,8 +798,10 @@ The destination must be new, outside the source workspace, and its parent must e
 to select another source configuration. Initialization needs no credential or
 network. It exports editable pages of every template as workspace documents with navigation,
 redirects, settings, and version-7 appearance/footer metadata, validates the
-result, and leaves the source unchanged. Excluded metadata-only pages are
-counted; unresolved references to them fail validation.
+result, and leaves the source unchanged. A metadata-only page that navigation,
+the footer or a page links to, such as a generated section page, is kept as a
+metadata-only entry (`initialized.linkedPages`); other metadata-only pages are
+left out (`initialized.skippedPages`).
 
 Exported UUIDs and HTTP(S) origins are deterministic fixture values under
 `example.test`; URL credentials, query strings and fragments are removed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.15.0",
+  "version": "0.18.0",
   "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

@@ -1,5 +1,6 @@
 import { normalizeLatestCliVersion } from "./cli-release.js";
 import {
+  BANDWIDTH_ALLOWANCE_REFUSAL_REASON,
   CANONICAL_TIMESTAMP,
   CAPABILITY_REFUSAL_FIELD,
   CLI_UPGRADE_COMMAND,
@@ -23,6 +24,7 @@ import {
 // would turn a successful mint into an orphaned key.
 import { KEY_PREFIX } from "./credentials.js";
 import { isCanonicalUuid, normalizePreviewDiagnostic, sanitizeDiagnostic, SiteAuthoringError } from "./errors.js";
+import { normalizeAuthorListing, parseAuthorReference } from "./authors-contract.js";
 import { docsPublicationModeFromWire, siteKindFromWire, surfaceFromWire } from "./surface.js";
 import {
   DEFAULT_REDIRECT_STATUS,
@@ -436,6 +438,34 @@ export function announceRefusal(error, onProgress, action = "request") {
   }
   if (kind === REFUSAL_PLAN_LIMIT) {
     onProgress("");
+    if (error.planLimit !== undefined) {
+      // The allowance and bandwidth refusals ride an ErrorInfo detail, not the
+      // UpgradePrompt field, and name when they can next lift on their own.
+      const bandwidth = error.planLimit.reason === BANDWIDTH_ALLOWANCE_REFUSAL_REASON;
+      onProgress(`PLAN LIMIT (refusal=plan_limit, reason=${error.planLimit.reason})`);
+      onProgress(
+        bandwidth
+          ? `  Taproot paused this ${action}: the site's measured bandwidth was over its monthly allowance for two `
+            + "months in a row. The published site keeps serving; only new deployments wait."
+          : error.planLimit.requestedPages === undefined
+          ? `  Taproot refused this ${action}: it generates more pages than the site's allowance for this billing period has left.`
+          : `  Taproot refused this ${action}: it generates ${pagesLabel(error.planLimit.requestedPages)} and the site has ${
+            (error.planLimit.remainingPages ?? 0).toLocaleString("en-US")
+          } left for this billing period.`,
+      );
+      // The bandwidth pause is not an unconditional reset: it lifts only after
+      // a month ends under the allowance (or on upgrade), so the instant is
+      // the earliest that can happen.
+      onProgress(
+        error.planLimit.resetsAt === undefined
+          ? "  Upgrade the site's plan, then run the request again."
+          : bandwidth
+          ? `  Upgrade the site's plan, or deployments resume after a month ends under the allowance (no earlier than ${error.planLimit.resetsAt}).`
+          : `  Resets at: ${error.planLimit.resetsAt}. Upgrade the site's plan to continue sooner.`,
+      );
+      onProgress("");
+      return;
+    }
     onProgress("PLAN LIMIT (refusal=plan_limit, field=UpgradePrompt)");
     onProgress(
       `  Taproot refused this ${action} against a plan ceiling rather than a content problem.`,
@@ -499,6 +529,14 @@ export function normalizePageSummary(value) {
     // The page's calendar date, empty when it has none. It is not part of
     // `bodyRevision`, so a typed page's push guard compares it separately.
     displayDate: typeof summary.displayDate === "string" ? summary.displayDate : "",
+    // The name the page's author goes by in a write: a site author's handle or
+    // a member's email address, folded. Empty for a page with no author, for a
+    // former member's page, and against a Taproot that predates authors
+    // (TR01196). Never the author's display name, which is not a reference.
+    authorRef: typeof summary.authorRef === "string" ? parseAuthorReference(summary.authorRef)?.value ?? "" : "",
+    // Whether the page credits anyone at all, which an empty authorRef cannot
+    // say: it is also empty for an author this credential may not name.
+    hasAuthor: typeof summary.authorDisplayName === "string" && summary.authorDisplayName.trim() !== "",
   };
 }
 
@@ -545,6 +583,62 @@ export async function updatePage(client, pageId, body) {
   );
 }
 
+/**
+ * Gives the site's two author refusals the stable codes the CLI documents
+ * (TR01196). The site answers an unknown name and one that cannot be named with
+ * the same field and wording on purpose; this keeps them one code too.
+ */
+export function translateAuthorRefusal(error, file) {
+  if (!(error instanceof ApiError)) return error;
+  for (const [field, code, fallback] of [
+    ["AuthorUnknown", "pages.author_unknown", "No site author or member who can create pages has that name."],
+    ["AuthorConflict", "pages.author_conflict", "The page already has a different author, which is never replaced."],
+  ]) {
+    if (error.hasField(field)) {
+      const detail = sanitizeDiagnostic(error.descriptionFor(field) ?? fallback, fallback);
+      // The workspace only learns who the site credits from a pull, and a
+      // conflict means someone gave the page an author after the last one.
+      const hint = field === "AuthorConflict"
+        ? " Run 'taproot-site pull' to learn who the site credits, then match it with 'pages meta set <path> --author "
+          + "<author>' (a .pm.json page) or the author: front matter line (Markdown)."
+        : "";
+      return new SiteAuthoringError(code, `'${file}': ${detail}${hint}`, { field: file });
+    }
+  }
+  return error;
+}
+
+/**
+ * Reads who a page can be credited to: the site's authors without an account
+ * and the members who can create pages (TR01196).
+ */
+export async function listSiteAuthors(client, siteId) {
+  return normalizeAuthorListing(
+    requireObject(await client.request(sitePath(siteId, "authors")), "api.authors_contract", "site authors"),
+  );
+}
+
+/** Creates a site author. The site folds the handle and the address. */
+export async function createSiteAuthor(client, siteId, { handle, displayName, email }) {
+  const created = requireObject(
+    await client.request(sitePath(siteId, "authors"), {
+      method: "POST",
+      body: { handle, displayName, ...(email === undefined ? {} : { email }) },
+    }),
+    "api.authors_contract",
+    "site author",
+  );
+  const listing = normalizeAuthorListing({ authors: [created], members: [] });
+  if (listing.authors.length !== 1) {
+    throw new SiteAuthoringError(
+      "api.authors_contract",
+      "Taproot returned a site author this CLI could not read.",
+      { field: "handle" },
+    );
+  }
+  return listing.authors[0];
+}
+
 export async function publishDrafts(client, pageIds) {
   const response = requireObject(
     await client.request("v1/pages/publish_drafts", { method: "POST", body: { pageIds } }),
@@ -931,6 +1025,45 @@ export async function selectPlace(client, siteId, { googlePlaceId, sessionToken
   };
 }
 
+function normalizeSiteCategory(value) {
+  const state = requireObject(value, "api.place_contract", "site place category");
+  return {
+    placeId: requireIdentifier(state.placeId, "api.place_contract", "placeId"),
+    category: text(state.category),
+    placeCategory: text(state.placeCategory),
+    isOverride: state.isOverride === true,
+  };
+}
+
+/** Sets this site's own category for a place; the place itself and other sites are unchanged. */
+export async function setPlaceCategory(client, siteId, { placeId, category }) {
+  return normalizeSiteCategory(
+    await client.request(sitePath(siteId, `places/${encodeURIComponent(placeId)}/category`), {
+      method: "PUT",
+      body: { siteId, placeId, category },
+    }),
+  );
+}
+
+/** Removes this site's category for a place, so the place's own category applies again. */
+export async function clearPlaceCategory(client, siteId, { placeId }) {
+  return normalizeSiteCategory(
+    await client.request(sitePath(siteId, `places/${encodeURIComponent(placeId)}/category`), { method: "DELETE" }),
+  );
+}
+
+/** The closed list of place categories, in Taproot's order. */
+export async function listPlaceCategories(client) {
+  const response = requireObject(
+    await client.request(`v1/standard-types${query([["typeGroup", "place_category"], ["maxResults", 1000]])}`),
+    "api.place_contract",
+    "place categories",
+  );
+  return (Array.isArray(response.standardTypes) ? response.standardTypes : [])
+    .map((type) => text(requireObject(type, "api.place_contract", "place category").name))
+    .filter((name) => name !== "");
+}
+
 /**
  * Processing is observed through `ListSiteImages`; `GetImageById` is
  * session-only under TR00602's read list, so a key-authorized client watches
@@ -1057,18 +1190,20 @@ export async function getDeploySelection(client, siteId) {
 }
 
 export async function getPublishingReadiness(client, siteId, selection = {}) {
+  // A body, not a query: the exact selection can run past a URL's limit, and the
+  // estimate must plan the pages the deploy will stage (TR01201).
   const response = requireObject(
-    await client.request(sitePath(
-      siteId,
-      `publishing/readiness${
-        query([
-          ["stagedPageIds", selection.stagedPageIds],
-          ["selectedSettingsTypes", selection.selectedSettingsTypes],
-          ["includeNavigation", selection.includeNavigation],
-          ["useExactPageSelection", selection.useExactPageSelection],
-        ])
-      }`,
-    )),
+    await client.request(sitePath(siteId, "publishing/readiness"), {
+      method: "POST",
+      body: {
+        stagedPageIds: selection.stagedPageIds,
+        selectedSettingsTypes: selection.selectedSettingsTypes,
+        includeNavigation: selection.includeNavigation,
+        useExactPageSelection: selection.useExactPageSelection,
+        includePageEstimate: selection.includePageEstimate,
+        allowFailedPreview: selection.allowFailedPreview,
+      },
+    }),
     "api.readiness_contract",
     "publishing readiness",
   );
@@ -1089,10 +1224,50 @@ export async function getPublishingReadiness(client, siteId, selection = {}) {
     redirectsChanged: response.redirectsChanged === true,
     formsChanged: response.formsChanged === true,
     videosChanged: response.videosChanged === true,
+    // The pages staging this candidate would generate, which is the number charged (TR01201).
+    // Absent unless asked for and the candidate could be planned.
+    pageEstimate: pageEstimate(response),
     blockers,
   };
 }
 
+/**
+ * The server's plan for a candidate: the pages staging it generates, the
+ * allowance left this period and when it resets. The CLI never computes any of
+ * it; limit, remaining and period end are null for an unlimited licence.
+ */
+function pageEstimate(response) {
+  if (!Number.isSafeInteger(response.plannedPageCount) || response.plannedPageCount < 0) return null;
+  const periodEnd = typeof response.pagesGeneratedPeriodEnd === "string"
+    ? new Date(response.pagesGeneratedPeriodEnd)
+    : undefined;
+  return {
+    plannedPageCount: response.plannedPageCount,
+    pagesGeneratedLimit: Number.isSafeInteger(response.pagesGeneratedLimit) ? response.pagesGeneratedLimit : null,
+    pagesGeneratedRemaining: Number.isSafeInteger(response.pagesGeneratedRemaining)
+      ? response.pagesGeneratedRemaining
+      : null,
+    periodEnd: periodEnd !== undefined && !Number.isNaN(periodEnd.getTime()) ? periodEnd.toISOString() : null,
+    exceedsAllowance: response.plannedPagesExceedAllowance === true,
+  };
+}
+
+const pagesLabel = (count) => `${count.toLocaleString("en-US")} ${count === 1 ? "page" : "pages"}`;
+
+/**
+ * The one line that states a candidate's plan in pages (TR01201), shared by the
+ * progress output and the refusal so the two never word it differently.
+ */
+export function describePageEstimate(estimate) {
+  const generates = `This will generate ${pagesLabel(estimate.plannedPageCount)}`;
+  if (estimate.pagesGeneratedLimit === null || estimate.pagesGeneratedRemaining === null) return generates;
+  const left = `${estimate.pagesGeneratedRemaining.toLocaleString("en-US")} of ${
+    estimate.pagesGeneratedLimit.toLocaleString("en-US")
+  } left this period`;
+  const resets = estimate.periodEnd === null ? "" : ` (resets ${estimate.periodEnd})`;
+  return `${generates} · ${left}${resets}`;
+}
+
 export async function getStagingPreviewStatus(client, siteId) {
   const response = requireObject(
     await client.request(sitePath(siteId, "staging-preview/status")),
@@ -1288,6 +1463,14 @@ export async function deploySite(client, siteId, body) {
         { field: "AuthoringPreviewFailed", status: error.status },
       );
     }
+    if (error instanceof ApiError && error.hasField("ExpectedPageCount")) {
+      throw new SiteAuthoringError(
+        "deploy.page_estimate_changed",
+        `${error.descriptionFor("ExpectedPageCount") ?? "The pages this publish generates have grown since the estimate."} `
+          + "Nothing was staged; run the command again to confirm the new count.",
+        { field: "ExpectedPageCount", status: error.status },
+      );
+    }
     throw error;
   }
   const deployment = normalizeDeployment(response.deployment);