@taprootio/site-authoring 0.8.4 → 0.8.6

package/README.md

@@ -29,6 +29,17 @@ npm install --global @taprootio/site-authoring
 taproot-site --help
 ```
 
+Or run the current release without installing it:
+
+```bash
+npx --yes @taprootio/site-authoring@latest --version
+```
+
+Always name `@latest` with `npx`: an unversioned `npx @taprootio/site-authoring`
+reuses whatever copy npx cached, which is how a design pass ran an old release.
+`--version` prints what is running; `status` reports the latest known release
+as `cliRelease`, and every online verb refuses an outdated CLI (below).
+
 Node 22 or later. The package has one runtime dependency,
 `@taprootio/espalier`, pinned to an exact version: the CLI validates themes
 against one Espalier theme contract, and a floating range would let an install
@@ -257,6 +268,39 @@ distribution, and every other host is refused before a bearer can be built.
 Sign-ins are stored per origin, so switching away and back finds the one that
 was already there.
 
+## Design walkthrough
+
+`taproot-site help walkthrough` is the self-contained version of this pass;
+each step names the reference it relies on.
+
+1. **Select a supported site.** `login`, then `sites` and
+   `use <site-name-or-id>`. A standard site takes every verb; a managed Docs
+   site takes presentation only (`pull`, `theme push`, `footer push`,
+   `media upload`, `deploy`, `status`) because its pages, navigation and
+   redirects come from the Docs artifact; a prebuilt Docs site takes no verb.
+2. **Pull and keep the baseline.** `pull` writes both schemes' complete
+   effective themes, the appearance files and the footer. Edit that pull;
+   never build a theme from memory or an example.
+3. **Edit both schemes and the appearance.** `help theme` lists every field,
+   the role slots, how anchor references resolve and what wins when a pin and
+   a role disagree; `help appearance` covers the default scheme, header, logos
+   and favicon.
+4. **Prepare media locally.** Raster files only (PNG, JPEG, GIF, WebP),
+   relative to the workspace root; make the transparent logo, its `@2x` copy,
+   a dark-scheme logo when needed and a square favicon with your own tools,
+   upload them with `media upload`, then assign `lightLogoId`, `darkLogoId`
+   and `brand.faviconId` from the returned ids. There is no recolor, crop or
+   SVG upload command.
+5. **Validate, then push.** `validate` runs offline; `theme push` writes the
+   footer colours, the appearance scalars and then both themes in that order,
+   not atomically, and a failure names `completedWrites` — pull, reconcile,
+   push again.
+6. **Review on staging in both schemes.** `deploy --staging` returns a
+   single-use handoff in `stagingPreview.url`, on a managed Docs site too;
+   open it once and use the site's theme toggle. No page draft is needed;
+   `preview page` renders one draft and is a different tool.
+7. **Promote only after review.** `deploy --production`.
+
 ## The authoring loop
 
 ```bash
@@ -292,7 +336,12 @@ moved since this workspace last reconciled with it, naming both revisions;
 `media upload [path...]` uploads raster files and records component-ready
 delivery fields. `nav push`, `theme push`, and `footer push` replace the whole
 navigation tree, the complete light/dark theme pair with its appearance
-settings, and the closed footer document. `redirects pull` writes the site's
+settings, and the closed footer document. `pull` writes each scheme's
+complete effective theme — the stored theme resolved over the same defaults
+every consumer renders — so a fresh workspace validates as pulled, and it
+keeps only authored `semanticMappings` pins (listed in
+`explicitMappingTokens`) because a pinned token shadows its role.
+`redirects pull` writes the site's
 redirect map to `redirects.json` with a baseline, and `redirects push`
 validates the file offline and replaces the whole map; `help redirects`
 states the entry shape (`path`, `kind` redirect or gone, `target`, `status`
@@ -304,7 +353,10 @@ result. **Each handoff is single-use.** Opening the URL consumes it; a reused,
 shared, or bookmarked preview URL answers `Not found`, which is the handoff
 being spent rather than the preview being broken. Run `preview page` again
 for another. The handoff also expires two minutes after it is minted;
-`preview revoke <page-id> <snapshot-id>` releases a preview early.
+`preview revoke <page-id> <snapshot-id>` releases a preview early. It
+addresses the snapshot, so it still works after `approve` has consumed the
+draft; revoking an already revoked snapshot succeeds again, and an unknown or
+cleaned-up snapshot answers `preview.not_found`.
 
 `approve [page-path...]` publishes drafts into the approved candidate pool.
 It stages; nothing reaches an audience until `deploy --staging` publishes the
@@ -406,7 +458,12 @@ with the exact fact field path. A label is optional and stays outside the value'
 ### Staging verification and deployment evidence
 
 `deploy --staging` selects the same changed pages, settings groups and navigation
-as the Deployments page. `status` checks that exact current candidate, so a
+as the Deployments page, and returns a single-use staging review handoff in
+`stagingPreview.url` — on a managed Docs site too, where it stages settings
+only: open the URL once, then use the site's theme toggle to review both
+schemes before promoting. When no handoff can be minted, `stagingPreview.reason`
+and `stagingPreview.recovery` say why and what to do next; `staging review`
+mints another on any surface. `status` checks that exact current candidate, so a
 completed CLI stage counts as successful until that candidate changes.
 
 A retained failed preview of selected page content refuses deployment as
@@ -441,6 +498,31 @@ are calculated only between recorded transitions. `truncated` marks missing
 older history; `known: false` marks legacy rows. CLI polling never invents phase
 timestamps. Progress reports the same recorded timestamps and durations.
 
+### Verify what visitors receive
+
+A completed deployment job is not a verified delivery. `delivery check
+(--staging | --production --url https://<published-domain>/)` reads the target
+the way a visitor does and reports each dimension separately: the latest
+completed deployment for the target, HTTP delivery of the authored routes and
+the favicon, images, module preloads and site bundle they declare (status and
+content type, no redirects followed), internal link targets, accidental
+local-only references, and the declared runtime — the major pointer's stream,
+entry and capability modules, and whether the pointer lags the fallback copy
+the site shipped with. The browser dimension (a fresh and a returning load
+compared against the pointer's entry, every document request in the browser,
+popups included, held to the site origin before it is sent, and cache reuse
+on the returning load observed rather than assumed)
+runs only when Playwright resolves from the CLI's own install (install
+`@taprootio/site-authoring` and `playwright` together globally and run the
+installed `taproot-site` command; a copy run through `npx` cannot see a
+global Playwright) and is reported as `unchecked` with that recovery
+otherwise. `--wait <seconds>` re-checks
+failures once for edge propagation; `--no-browser` skips the browser; `--url`
+is a production option, since staging always checks the acknowledged host
+with an authorized preview session. Only same-origin assets and the declared
+runtime are fetched, and the check is read-only and bounded; `help delivery`
+states the limits and verdicts.
+
 ### Export a pulled workspace as an offline fixture
 
 From a pulled workspace (or its configured project), run:

package/examples/riverbend-wellness/settings/taproot-styles.json

@@ -256,100 +256,7 @@
         "success": 150,
         "warning": 90
       },
-      "semanticMappings": {
-        "actionBackground": {
-          "lightness": "raised3",
-          "source": "primary"
-        },
-        "actionText": {
-          "lightness": "ink",
-          "source": "primary"
-        },
-        "background": {
-          "lightness": "surface",
-          "source": "primary"
-        },
-        "border": {
-          "lightness": "border",
-          "source": "primary"
-        },
-        "dangerText": {
-          "lightness": "text",
-          "source": "danger"
-        },
-        "headings": {
-          "lightness": "muted",
-          "source": "primary"
-        },
-        "headingsHover": {
-          "lightness": "text",
-          "source": "primary"
-        },
-        "inputCaret": {
-          "lightness": "ink",
-          "source": "triadic-right"
-        },
-        "inputSelection": {
-          "lightness": "text",
-          "source": "complementary"
-        },
-        "inputSelectionBg": {
-          "lightness": "raised2",
-          "source": "triadic-left"
-        },
-        "layer1": {
-          "lightness": "raised1",
-          "source": "primary"
-        },
-        "layer2": {
-          "lightness": "raised2",
-          "source": "primary"
-        },
-        "layer3": {
-          "lightness": "raised3",
-          "source": "primary"
-        },
-        "layer4": {
-          "lightness": "raised4",
-          "source": "primary"
-        },
-        "link": {
-          "lightness": "accent",
-          "source": "complementary"
-        },
-        "linkHover": {
-          "lightness": "text",
-          "source": "complementary"
-        },
-        "linkHoverBg": {
-          "lightness": "raised2",
-          "source": "triadic-left"
-        },
-        "shadow": {
-          "lightness": "shadow",
-          "source": "primary"
-        },
-        "text": {
-          "lightness": "text",
-          "source": "primary"
-        },
-        "typeCaption": {
-          "lightness": "text",
-          "source": "primary"
-        },
-        "typeLabel": {
-          "lightness": "text",
-          "source": "primary"
-        },
-        "typeLead": {
-          "lightness": "text",
-          "source": "primary"
-        },
-        "typeOverline": {
-          "lightness": "text",
-          "source": "primary"
-        }
-      },
+      "semanticMappings": {},
       "spaceRatio": 1.618,
       "stylesheets": [],
       "tones": {},
@@ -613,100 +520,7 @@
         "success": 150,
         "warning": 90
       },
-      "semanticMappings": {
-        "actionBackground": {
-          "lightness": "raised3",
-          "source": "primary"
-        },
-        "actionText": {
-          "lightness": "ink",
-          "source": "primary"
-        },
-        "background": {
-          "lightness": "surface",
-          "source": "primary"
-        },
-        "border": {
-          "lightness": "border",
-          "source": "primary"
-        },
-        "dangerText": {
-          "lightness": "text",
-          "source": "danger"
-        },
-        "headings": {
-          "lightness": "muted",
-          "source": "primary"
-        },
-        "headingsHover": {
-          "lightness": "text",
-          "source": "primary"
-        },
-        "inputCaret": {
-          "lightness": "ink",
-          "source": "triadic-right"
-        },
-        "inputSelection": {
-          "lightness": "text",
-          "source": "complementary"
-        },
-        "inputSelectionBg": {
-          "lightness": "raised2",
-          "source": "triadic-left"
-        },
-        "layer1": {
-          "lightness": "raised1",
-          "source": "primary"
-        },
-        "layer2": {
-          "lightness": "raised2",
-          "source": "primary"
-        },
-        "layer3": {
-          "lightness": "raised3",
-          "source": "primary"
-        },
-        "layer4": {
-          "lightness": "raised4",
-          "source": "primary"
-        },
-        "link": {
-          "lightness": "accent",
-          "source": "complementary"
-        },
-        "linkHover": {
-          "lightness": "text",
-          "source": "complementary"
-        },
-        "linkHoverBg": {
-          "lightness": "raised2",
-          "source": "triadic-left"
-        },
-        "shadow": {
-          "lightness": "shadow",
-          "source": "primary"
-        },
-        "text": {
-          "lightness": "text",
-          "source": "primary"
-        },
-        "typeCaption": {
-          "lightness": "text",
-          "source": "primary"
-        },
-        "typeLabel": {
-          "lightness": "text",
-          "source": "primary"
-        },
-        "typeLead": {
-          "lightness": "text",
-          "source": "primary"
-        },
-        "typeOverline": {
-          "lightness": "text",
-          "source": "primary"
-        }
-      },
+      "semanticMappings": {},
       "spaceRatio": 1.618,
       "stylesheets": [],
       "tones": {},

package/package.json

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

@@ -7,6 +7,8 @@ import {
   CLI_VERSION,
   EXTERNAL_WRITES_SETTING_KEY,
   EXTERNAL_WRITES_SETTING_LOCATION,
+  GRPC_NOT_FOUND,
+  HTTP_NOT_FOUND,
   LIMITS,
   REFUSAL_CAPABILITY_MISSING,
   REFUSAL_CLI_OUTDATED,
@@ -101,6 +103,15 @@ export const DEPLOYMENT_STATUSES = Object.freeze([
   DEPLOYMENT_STATUS_FAILED,
 ]);
 
+// DeploySite's admission outcome (TR00839): whether this request created the
+// deployment or coalesced into an already-anchored one.
+export const DEPLOYMENT_REQUEST_OUTCOME_ACCEPTED = "DEPLOYMENT_REQUEST_OUTCOME_ACCEPTED";
+export const DEPLOYMENT_REQUEST_OUTCOME_COALESCED = "DEPLOYMENT_REQUEST_OUTCOME_COALESCED";
+export const DEPLOYMENT_REQUEST_OUTCOMES = Object.freeze([
+  DEPLOYMENT_REQUEST_OUTCOME_ACCEPTED,
+  DEPLOYMENT_REQUEST_OUTCOME_COALESCED,
+]);
+
 export const IMAGE_PROCESSING_STATE_UNKNOWN = "IMAGE_PROCESSING_STATE_UNKNOWN";
 export const IMAGE_PROCESSING_STATE_COMPLETE = "IMAGE_PROCESSING_STATE_COMPLETE";
 export const IMAGE_PROCESSING_STATE_FAILED = "IMAGE_PROCESSING_STATE_FAILED";
@@ -158,6 +169,7 @@ const AUTHORING_PREVIEW_FIELDS = Object.freeze({
   siteCapacity: "AuthoringPreviewCapacity",
   authorityCapacity: "AuthoringPreviewAuthorityCapacity",
   manifest: "AuthoringPreviewManifest",
+  snapshot: "AuthoringPreview",
 });
 const AUTHORING_PREVIEW_FIELD_ERRORS = Object.freeze({
   [AUTHORING_PREVIEW_FIELDS.draft]: [
@@ -348,7 +360,11 @@ const REFUSAL_GUIDANCE = Object.freeze({
   [REFUSAL_CREDENTIAL_REJECTED]:
     "The site authoring credential was rejected: it is invalid, revoked, or bound to a different site. "
     + "Stop and re-issue it; retrying cannot succeed.",
-  [REFUSAL_THROTTLED]: "This credential exceeded its request budget. Back off and retry with delay.",
+  // Covers both the per-key request-budget throttle and the durable
+  // per-site/per-account deployment request limit (TR00839): both surface as
+  // gRPC ResourceExhausted / HTTP 429, and the remedy is identical either way.
+  [REFUSAL_THROTTLED]:
+    "Too many deployment requests for this site or account. Back off and retry after the delay the server reported.",
 });
 
 /**
@@ -433,6 +449,12 @@ export function announceRefusal(error, onProgress, action = "request") {
   }
   const guidance = REFUSAL_GUIDANCE[kind];
   if (guidance) onProgress(guidance);
+  // The retry-after trailer (TR00839) is the exact delay the server measured;
+  // surface it when the transport captured it rather than leaving the agent
+  // to guess a backoff.
+  if (kind === REFUSAL_THROTTLED && typeof error.retryAfterSeconds === "number") {
+    onProgress(`  Retry after: ${error.retryAfterSeconds}s.`);
+  }
 }
 
 /**
@@ -1014,6 +1036,9 @@ export function normalizeDeployment(value) {
     errorMessage: text(deployment.errorMessage),
     pageCount: safeCount(deployment.pageCount),
     phaseTimings: normalizePhaseTimings(deployment.phaseHistory),
+    // Identical requests coalesced into this deployment inside its settling
+    // window (TR00839). Zero for a deployment that never anchored one.
+    coalescedRequestCount: safeCount(deployment.coalescedRequestCount),
   };
 }
 
@@ -1071,7 +1096,19 @@ export async function deploySite(client, siteId, body) {
     }
     throw error;
   }
-  return normalizeDeployment(response.deployment);
+  const deployment = normalizeDeployment(response.deployment);
+  // `DEPLOYMENT_REQUEST_OUTCOME_ACCEPTED` is the zero-adjacent default: an
+  // older server that omits the field, or the immutable Standard/Docs
+  // branches that never run through the admission seam, both read as this
+  // request creating its own deployment (TR00839).
+  const outcome = enumValue(
+    response.outcome,
+    DEPLOYMENT_REQUEST_OUTCOMES,
+    DEPLOYMENT_REQUEST_OUTCOME_ACCEPTED,
+    "api.deployment_contract",
+    "deployment request outcome",
+  );
+  return { ...deployment, outcome };
 }
 
 /**
@@ -1924,6 +1961,38 @@ export async function claimCliAuthorization(client, deviceCode, requestOptions =
 }
 
 /** Maps only preview-domain validation fields; authentication/refusal identity stays an ApiError. */
+/**
+ * Revocation addresses one snapshot, so its refusals are snapshot outcomes.
+ * A NotFound (the page or the snapshot is not available to this caller on
+ * this site) and the server's in-transaction `AuthoringPreview` unavailability
+ * both become `preview.not_found`; the wording never distinguishes another
+ * caller's snapshot from a missing one, mirroring the server. A snapshot that
+ * is already revoked is not an error at all: the server answers REVOKED and
+ * the verb reports that idempotent success. Every other refusal keeps the
+ * shared preview translation (TR00773).
+ */
+export function translateAuthoringPreviewRevokeApiError(error) {
+  if (!(error instanceof ApiError) || error.refusalKind() !== REFUSAL_UNCLASSIFIED) return error;
+  if (
+    error.httpStatus === HTTP_NOT_FOUND || error.grpcCode === GRPC_NOT_FOUND
+    || error.hasField(AUTHORING_PREVIEW_FIELDS.snapshot)
+  ) {
+    return new SiteAuthoringError(
+      "preview.not_found",
+      "No authoring preview with that snapshot ID is available for that page on this site. It may have expired "
+        + "and been cleaned up, or the IDs may belong to another page or site; a snapshot that was already revoked "
+        + "reports a successful revocation instead.",
+      // A NotFound can name the page as readily as the snapshot, so only the
+      // in-transaction snapshot refusal pins the field a caller should fix.
+      {
+        ...(error.hasField(AUTHORING_PREVIEW_FIELDS.snapshot) ? { field: "snapshotId" } : {}),
+        status: error.status,
+      },
+    );
+  }
+  return translateAuthoringPreviewApiError(error);
+}
+
 export function translateAuthoringPreviewApiError(error) {
   if (!(error instanceof ApiError) || error.refusalKind() !== REFUSAL_UNCLASSIFIED) return error;
   for (const [field, [code, message]] of Object.entries(AUTHORING_PREVIEW_FIELD_ERRORS)) {