@taprootio/site-authoring 0.8.4 → 0.8.5

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.5",
   "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,
@@ -158,6 +160,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]: [
@@ -1924,6 +1927,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)) {

package/src/cli.js

@@ -15,7 +15,9 @@ import {
   SURFACE_DOCS_PRESENTATION,
   SURFACE_STANDARD,
   VERB_APPROVE,
+  VERB_DELIVERY_CHECK,
   VERB_DEPLOY,
+  VERB_STAGING_REVIEW,
   VERB_ENV,
   VERB_FOOTER_PUSH,
   VERB_HELP,
@@ -290,7 +292,11 @@ const VERBS = Object.freeze([
     tokens: ["theme", "push"],
     summary: "Validate and push the workspace's complete theme and appearance settings.",
     note: "Run pull first. Theme JSON stays decoded in the workspace; this command validates the complete light/dark"
-      + " pair and encodes it only at the API boundary. Image settings reference site-owned image IDs from media upload.",
+      + " pair and encodes it only at the API boundary. Image settings reference site-owned image IDs from media upload. "
+      + "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. semanticMappings holds only authored pins, listed "
+      + "in explicitMappingTokens; every other token compiles from roles at render time, so never copy default "
+      + "mappings into a theme: a pinned token shadows its role.",
   },
   {
     name: VERB_FOOTER_PUSH,
@@ -345,6 +351,10 @@ const VERBS = Object.freeze([
     tokens: ["deploy"],
     summary: "Deploy to staging, or promote staging to production.",
     target: true,
+    note: "deploy --staging returns a single-use review handoff in stagingPreview.url, on a managed Docs site too, "
+      + "where it stages settings only: open the URL once, then switch the site's theme toggle to review both "
+      + "schemes before deploy --production. If no handoff could be minted, stagingPreview.reason names why and "
+      + "stagingPreview.recovery the next step; 'staging review' mints another.",
   },
   {
     name: VERB_PREVIEW_PAGE,
@@ -357,7 +367,8 @@ const VERBS = Object.freeze([
     note: "Select the persisted draft by page path (as recorded by pull) or canonical lowercase UUID. "
       + "The homepage is recorded with an empty path, so address it as '/'. "
       + "Preview before approving: approve consumes the draft, so a page that has been approved has no draft "
-      + "left to render and answers preview.no_draft. Review it on staging after a deploy instead. "
+      + "left to render and answers preview.no_draft. Review it on staging after a deploy instead. A preview "
+      + "captured before approval stays revocable afterwards: preview revoke addresses the snapshot itself. "
       + "The handoff URL in the result is single-use and expires two minutes after it is minted: opening it "
       + "consumes it, and a reused, shared, or bookmarked preview URL answers Not found. Run preview page again "
       + "for another. "
@@ -374,6 +385,39 @@ const VERBS = Object.freeze([
     json: true,
     note: "Supply the canonical lowercase page UUID followed by the snapshot UUID returned by preview page.",
   },
+  {
+    name: VERB_DELIVERY_CHECK,
+    surface: SURFACE_DOCS_PRESENTATION,
+    // Deployments reads the deployment log and mints the staging handoff the
+    // check consumes; the public target itself needs no credential.
+    capabilities: [CAPABILITY_DEPLOYMENTS],
+    tokens: ["delivery", "check"],
+    summary: "Verify what a visitor receives after a deployment completed: routes, assets, runtime, browser.",
+    target: true,
+    deliveryOptions: true,
+    note: "A completed deployment job is not a verified delivery. This read-only check 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 (from the workspace manifest, bounded), the favicon, images, module "
+      + "preloads and site bundle they reference, internal link targets, accidental local-only references, and the "
+      + "declared runtime (major pointer, fallback copy, entry module and capability modules), plus a browser "
+      + "dimension that runs only when Playwright is installed and is reported as unchecked otherwise. --staging "
+      + "resolves the acknowledged staging host and authorizes one preview session for the run (--url is refused "
+      + "there); --production needs --url https://<published-domain>/ because a site-authoring key cannot read "
+      + "hosting configuration. Only assets on the site's own origin and the runtime the page declares are "
+      + "fetched. --wait "
+      + "<seconds> (at most 120) observes everything once more after that pause for edge propagation. --no-browser skips "
+      + "the browser dimension. Nothing is purged, republished or rolled back.",
+  },
+  {
+    name: VERB_STAGING_REVIEW,
+    surface: SURFACE_DOCS_PRESENTATION,
+    capabilities: [CAPABILITY_DEPLOYMENTS],
+    tokens: ["staging", "review"],
+    summary: "Mint a fresh single-use review handoff for the site's staging host.",
+    note: "The handoff URL is reported only in the final JSON as stagingPreview.url, is single-use, and expires two "
+      + "minutes after it is minted; keep it private. Open it once, then use the site's theme toggle to review both "
+      + "schemes. This is the recovery when deploy --staging could not mint a handoff, on a managed Docs site too.",
+  },
   {
     name: VERB_STATUS,
     surface: SURFACE_DOCS_PRESENTATION,
@@ -454,6 +498,12 @@ whoami, and env need no configuration and no site. The offline help family is
 human-readable by default; add --json for stable reference data. Exit codes: 0
 success, 1 failure, 2 usage fault.
 
+Install globally (npm install --global @taprootio/site-authoring) or run the
+current release without installing: npx --yes @taprootio/site-authoring@latest
+<verb>. An unversioned npx keeps whatever copy it cached, so always name
+@latest; check what is running with --version, and compare it with the
+release status reports as cliRelease.
+
 Troubleshooting: a command that fails with field=CliUpgradeRequired (or
 refusal=cli_outdated) means this CLI is behind the latest published release,
 which is the only release Taproot accepts. Nothing is wrong with the
@@ -499,10 +549,17 @@ function verbHelp(verb) {
     ? " <page-id> <snapshot-id>"
     : verb.positionals === "environmentSelector"
     ? " [production | local | <url>]"
+    : verb.positionals === "siteSelector"
+    ? " <site-name-or-id>"
     : verb.positionals
     ? ` [${verb.positionals === "paths" ? "path" : "page-path"}...]`
     : "";
-  const targetOption = verb.target
+  const deliveryOptions = verb.deliveryOptions
+    ? `\n  --url <origin>   The https origin to check; required for --production, refused for --staging.
+  --wait <seconds> Re-check failures once after this pause (0-120) for edge propagation.
+  --no-browser     Skip the browser dimension even when Playwright is installed.`
+    : "";
+  const targetOption = verb.target && !verb.deliveryOptions
     ? `\n  --staging        Deploy the staged site to staging.
   --production     Promote the completed staging deployment to production.
   --allow-failed-preview  Explicitly override the matching candidate's failed preview.`
@@ -571,12 +628,16 @@ function verbHelp(verb) {
   --help           Show this help.
   --version        Show the package version.`
     : COMMON_OPTIONS;
+  const deliveryTargetOption = verb.deliveryOptions
+    ? `\n  --staging        Check the staging target.
+  --production     Check the production target.${deliveryOptions}`
+    : "";
   return `Usage: ${prefix} ${verb.tokens.join(" ")}${positionalUsage}${targetUsage} [options]
 
 ${verb.summary}
 ${boundary}
 
-${options}${targetOption}${rawHtmlOption}${jsonOption}${nameOption}${note}
+${options}${targetOption}${deliveryTargetOption}${rawHtmlOption}${jsonOption}${nameOption}${note}
 `;
 }
 
@@ -640,6 +701,8 @@ function parseReferenceArguments(arguments_) {
       || topic === "footer"
       || topic === "fixture"
       || topic === "redirects"
+      || topic === "walkthrough"
+      || topic === "delivery"
     )
     && (subject !== undefined || extra.length > 0)
   ) {
@@ -707,6 +770,8 @@ function referenceResult(parsed) {
     case "media":
     case "preview":
     case "fixture":
+    case "walkthrough":
+    case "delivery":
       return {
         ...result,
         topic: "workflow",
@@ -746,6 +811,36 @@ function parseConfigOption(arguments_, index) {
  * (trimmed, 1-100 characters) belongs to the verb, which a programmatic caller
  * reaches without passing through this parser at all.
  */
+function parseUrlOption(arguments_, index) {
+  const candidate = arguments_[index + 1];
+  let url;
+  try {
+    url = typeof candidate === "string" ? new URL(candidate) : undefined;
+  } catch {
+    url = undefined;
+  }
+  if (
+    !url || url.protocol !== "https:" || url.username || url.password || url.search || url.hash
+    || (url.pathname !== "/" && url.pathname !== "") || hasAsciiControl(candidate)
+  ) {
+    throw usageError("cli.url_option", "--url requires one https origin such as https://example.com/.", {
+      field: "url",
+    });
+  }
+  return `${url.origin}/`;
+}
+
+function parseWaitOption(arguments_, index) {
+  const candidate = arguments_[index + 1];
+  const seconds = typeof candidate === "string" && /^\d{1,3}$/u.test(candidate) ? Number(candidate) : undefined;
+  if (seconds === undefined || seconds > 120) {
+    throw usageError("cli.wait_option", "--wait requires a whole number of seconds from 0 to 120.", {
+      field: "propagationWaitSeconds",
+    });
+  }
+  return seconds;
+}
+
 function parseNameOption(arguments_, index) {
   const candidate = arguments_[index + 1];
   if (
@@ -812,6 +907,9 @@ function parseArguments(arguments_) {
   let init = false;
   let quiet = false;
   let deployTarget;
+  let deliveryUrl;
+  let propagationWaitSeconds;
+  let browser;
   let allowFailedPreview = false;
   let allowRawHtml = false;
   let json = false;
@@ -848,6 +946,23 @@ function parseArguments(arguments_) {
       deployTarget = candidate;
       continue;
     }
+    if (verb.deliveryOptions && argument === "--url") {
+      if (deliveryUrl !== undefined) throw usageError("cli.duplicate_option", "--url may be supplied only once.");
+      deliveryUrl = parseUrlOption(rest, index);
+      index += 1;
+      continue;
+    }
+    if (verb.deliveryOptions && argument === "--wait") {
+      if (propagationWaitSeconds !== undefined) throw usageError("cli.duplicate_option", "--wait may be supplied only once.");
+      propagationWaitSeconds = parseWaitOption(rest, index);
+      index += 1;
+      continue;
+    }
+    if (verb.deliveryOptions && argument === "--no-browser") {
+      if (browser === false) throw usageError("cli.duplicate_option", "--no-browser may be supplied only once.");
+      browser = false;
+      continue;
+    }
     if (verb.target && argument === "--allow-failed-preview") {
       if (allowFailedPreview) {
         throw usageError("cli.duplicate_option", "--allow-failed-preview may be supplied only once.");
@@ -893,7 +1008,10 @@ function parseArguments(arguments_) {
     throw usageError("cli.unexpected_argument", "The command contains an unexpected argument.");
   }
   if (verb.target && deployTarget === undefined) {
-    throw usageError("cli.deploy_target", "deploy requires exactly one of --staging or --production.");
+    throw usageError(
+      "cli.deploy_target",
+      `${verb.tokens.join(" ")} requires exactly one of --staging or --production.`,
+    );
   }
   if (
     verb.positionals === "fixturePath"
@@ -984,6 +1102,9 @@ function parseArguments(arguments_) {
     quiet,
     deployTarget,
     allowFailedPreview,
+    ...(deliveryUrl === undefined ? {} : { deliveryUrl }),
+    ...(propagationWaitSeconds === undefined ? {} : { propagationWaitSeconds }),
+    ...(browser === undefined ? {} : { browser }),
     init,
     allowRawHtml,
     keyName,

package/src/constants.js

@@ -1,5 +1,5 @@
 export const CLI_NAME = "@taprootio/site-authoring";
-export const CLI_VERSION = "0.8.4";
+export const CLI_VERSION = "0.8.5";
 export const CLI_BINARY_NAME = "taproot-site";
 export const RESULT_SCHEMA_VERSION = 1;
 export const CONFIG_FILE_NAME = "taproot-site.json";
@@ -93,6 +93,8 @@ export const VERB_DEPLOY = "deploy";
 export const VERB_PREVIEW_PAGE = "preview page";
 export const VERB_PREVIEW_REVOKE = "preview revoke";
 export const VERB_STATUS = "status";
+export const VERB_DELIVERY_CHECK = "delivery check";
+export const VERB_STAGING_REVIEW = "staging review";
 export const VERB_SITES = "sites";
 export const VERB_USE = "use";
 export const VERB_WHOAMI = "whoami";
@@ -199,6 +201,11 @@ export const HTTP_TOO_MANY_REQUESTS = 429;
 export const GRPC_UNAUTHENTICATED = 16;
 export const HTTP_UNAUTHORIZED = 401;
 
+// gRPC `NotFound`, and its HTTP mapping. Preview revocation classifies on it:
+// the page or snapshot is not available to this caller on this site.
+export const GRPC_NOT_FOUND = 5;
+export const HTTP_NOT_FOUND = 404;
+
 export const LIMITS = Object.freeze({
   configBytes: 16 * 1024,
   configPathBytes: 4 * 1024,