@taprootio/site-authoring 0.14.0 → 0.15.0

package/README.md

@@ -119,8 +119,16 @@ dark logo on the rendered dark header at desktop and compact/mobile widths;
 transparent canvas pixels do not count as contrast. Supply separate
 scheme-specific assets when one visible mark cannot satisfy both surfaces.
 
+`taproot-site validate` checks the pulled workspace `taproot-site.json` names,
+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.
+
 `taproot-site validate <fixture-directory>` checks a complete offline fixture
-with no credential, no network, and no write: a directory laid out like a
+the same way: a directory laid out like a
 pulled workspace — `pages/`, `nav.json`, `redirects.json`, and the four
 `settings/` documents —
 whose `manifest.fixture.json` binds deterministic page, resource, image, and
@@ -143,9 +151,10 @@ taproot-site validate "$(npm root --global)/@taprootio/site-authoring/examples/r
 The fixture is a fictional wellness studio — `example.test` hostnames, a
 reserved `555-01xx` telephone number, an invented street and town — with two
 free-form pages and one each of the article, recipe, album and place-review
-templates, a three-item navigation tree, and all four settings documents. Nothing in it describes a real business. Copy the directory
-somewhere writable before you edit it; `validate` never writes to the fixture
-it reads.
+templates, a three-item navigation tree, all four settings documents, and a
+`.taproot-site-media.json` that maps its one media path to a fixture image id.
+Nothing in it describes a real business. Copy the directory somewhere writable
+before you edit it; `validate` never writes to the fixture it reads.
 
 ## Authorize
 
@@ -285,14 +294,15 @@ each step names the reference it relies on.
 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.
+   and favicon; `help fonts` lists the font families, by category, that the
+   font fields can name.
 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, preview, then push.** `validate` runs offline;
+5. **Validate, preview, then push.** `validate` checks the whole workspace offline;
    `theme push --dry-run` reads the site and lists the JSON paths at which
    each settings file differs from it, and whether the baseline `pull`
    recorded is still current; `theme push` saves both themes, the appearance
@@ -351,12 +361,40 @@ it is created: a source for another template is refused with
 template's fields and one worked example.
 
 `pages push [page-path...]` validates and sends the selected pages, or every
-workspace page when none is named; the homepage is addressed as `/`. It fails
+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
+problem in `error.problems`. `pages push --dry-run` runs the same checks
+against the live site, lists which pages would be created, updated, or left
+unchanged, and sends nothing. It fails
 closed with `pages.push_conflict` when a page's stored-state revision has
 moved since this workspace last reconciled with it, naming both revisions;
 `pull` first, or push after a refused pull has shown you the site's version.
-`media upload [path...]` uploads raster files and records component-ready
-delivery fields; MP4, MOV, and WebM files are uploaded as videos. Taproot does not
+
+`places search <name and city>` asks Google Places for the place a review
+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:`.
+
+`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
+links, the theme, navigation — and orders what is left
+to send: media upload, pages push, footer push (theme push refuses unsaved
+footer content), theme push, nav push, each marked ready, blocked, or nothing
+to do. It writes nothing and reports a `planHash`. `apply --plan <planHash>`
+plans again, refuses with `apply.plan_stale` if the workspace or the site
+moved, and otherwise runs the steps through the ordinary push verbs. While
+they run, a workspace file read differently from the plan (or not read by it)
+stops the step before it writes, naming the file, and so does a page revision
+or the site's navigation that moved. Steps are
+not atomic together: a failure reports in `error.completedWrites` which steps
+completed, which failed, and which did not run, and the next `plan` shows
+finished steps as nothing to do. Redirects, forms, approval, and deployment
+stay separate commands.
+`media upload [path...]` uploads raster files and records each one in
+`.taproot-site-media.json`; Markdown then names an image by its path (such as
+`media/photo.webp`) everywhere an image goes, from body images to component and
+section image fields. MP4, MOV, and WebM files are uploaded as videos. Taproot does not
 encode: the command reads each file with mediabunny, rewrites an H.264 and AAC
 file that is not an MP4 with its index first as one (copying the tracks, never
 re-encoding), declares its codecs, and prints the server's one-line refusal as
@@ -372,7 +410,9 @@ 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.
+`explicitMappingTokens` at the root; a pin inside a context needs no marker)
+because a pinned token shadows its role. Contrast and status-color warnings
+name the nearest passing value the CLI found and checked.
 `theme push` — and `theme push --dry-run`, which writes nothing — also runs
 Espalier's fit report over the root and every context in both schemes and
 prints each lint as a warning, such as a filled action that renders the
@@ -505,6 +545,18 @@ 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`.
 
+### Link rel in 0.15.0
+
+A link publishes followed unless its author chooses otherwise. A link mark's
+`rel` takes space-separated link types (`nofollow`, `sponsored`, `ugc`, `me`,
+and the other standard types except `opener`), on any link; `target: "_blank"`
+opens a new tab with `noopener noreferrer` added. In Markdown, write
+`[Shop](https://shop.example){rel="sponsored nofollow" target="_blank"}`
+(either attribute alone works). Other tokens and
+targets are refused (`content.link_rel`, `content.link_target`). The editor's
+old default, `noopener noreferrer nofollow`, reads as no choice. See
+`taproot-site help page free-form`.
+
 ### Staging verification and deployment evidence
 
 `deploy --staging` selects the same changed pages, settings groups and navigation

package/examples/riverbend-wellness/.taproot-site-media.json

@@ -0,0 +1,23 @@
+{
+  "mediaManifestVersion": 2,
+  "siteId": "a0000000-0000-4000-8000-000000000001",
+  "media": {
+    "media/riverbend-studio.webp": {
+      "imageId": "a0000000-0000-4000-8000-0000000000a2",
+      "src": "https://static.example.test/site/img/riverbend-studio-1280.webp",
+      "urls": [
+        {
+          "minWidth": 640,
+          "url": "https://static.example.test/site/img/riverbend-studio-640.webp"
+        },
+        {
+          "minWidth": 1280,
+          "url": "https://static.example.test/site/img/riverbend-studio-1280.webp"
+        }
+      ],
+      "width": 1600,
+      "height": 1067,
+      "alt": "An example photograph placeholder for the fixture studio"
+    }
+  }
+}

package/examples/riverbend-wellness/pages/index.md

@@ -19,23 +19,7 @@ description: An example home page for the offline authoring fixture.
     "url": "https://schedule.example.test/riverbend"
   },
   "alignment": "start",
-  "media": {
-    "imageId": "a0000000-0000-4000-8000-0000000000a2",
-    "src": "https://static.example.test/site/img/riverbend-studio-1280.webp",
-    "urls": [
-      {
-        "minWidth": 640,
-        "url": "https://static.example.test/site/img/riverbend-studio-640.webp"
-      },
-      {
-        "minWidth": 1280,
-        "url": "https://static.example.test/site/img/riverbend-studio-1280.webp"
-      }
-    ],
-    "width": 1600,
-    "height": 1067,
-    "alt": "An example photograph placeholder for the fixture studio"
-  },
+  "media": "media/riverbend-studio.webp",
   "mediaArrangement": "split",
   "mediaPosition": "after",
   "mediaWidth": "equal"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.14.0",
+  "version": "0.15.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",
@@ -28,7 +28,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@taprootio/espalier": "5.0.0",
+    "@taprootio/espalier": "6.2.0",
     "mediabunny": "1.61.1"
   },
   "scripts": {

package/src/api.js

@@ -178,7 +178,8 @@ const AUTHORING_PREVIEW_FIELD_ERRORS = Object.freeze({
   ],
   [AUTHORING_PREVIEW_FIELDS.staging]: [
     "preview.staging_unavailable",
-    "The site does not have an available staging hostname for authoring previews.",
+    "The site's staging address is not ready for previews. If the site has never deployed to staging, run "
+      + "'deploy --staging' once; otherwise check its staging host with 'taproot-site status'.",
   ],
   [AUTHORING_PREVIEW_FIELDS.expiry]: ["preview.expired", "The authoring preview has expired."],
   [AUTHORING_PREVIEW_FIELDS.readiness]: ["preview.not_ready", "The authoring preview is not ready for a handoff."],
@@ -233,6 +234,11 @@ function requireIdentifier(value, code, field) {
   return value;
 }
 
+/** A Google place id as Taproot stores it: the server's characters and its 256-character column. */
+export function isGooglePlaceId(value) {
+  return typeof value === "string" && value.length <= 256 && /^[A-Za-z0-9_-]+$/u.test(value);
+}
+
 function requireCanonicalUuid(value, code, field) {
   if (!isCanonicalUuid(value)) {
     throw new SiteAuthoringError(code, `Taproot returned an invalid ${field}.`, { field });
@@ -874,6 +880,57 @@ export async function listVideos(client, siteId, requestOptions = {}) {
   return { videos, truncated: true };
 }
 
+/**
+ * Google Places autocomplete for a place review (TR01003). A key searches for
+ * the site it was issued for; every search and the select that follows share
+ * `sessionToken`, which is what groups them into one billed session.
+ */
+export async function searchPlaces(client, siteId, { text: searchText, sessionToken }) {
+  const search = query([["query", searchText], ["siteId", siteId], ["sessionToken", sessionToken]]);
+  const response = requireObject(
+    await client.request(`v1/places/search${search}`),
+    "api.place_contract",
+    "place search",
+  );
+  return (Array.isArray(response.predictions) ? response.predictions : []).map((value) => {
+    const prediction = requireObject(value, "api.place_contract", "place prediction");
+    return {
+      googlePlaceId: requireGooglePlaceId(prediction.googlePlaceId),
+      name: text(prediction.name),
+      formattedAddress: text(prediction.formattedAddress),
+    };
+  });
+}
+
+function requireGooglePlaceId(value) {
+  if (!isGooglePlaceId(value)) {
+    throw new SiteAuthoringError("api.place_contract", "Taproot returned an invalid googlePlaceId.", { field: "googlePlaceId" });
+  }
+  return value;
+}
+
+/** Records a prediction as a Taproot place, ending the search's billed session, and returns its id. */
+export async function selectPlace(client, siteId, { googlePlaceId, sessionToken }) {
+  const place = requireObject(
+    await client.request("v1/places/select", {
+      method: "POST",
+      body: { siteId, googlePlaceId, sessionToken },
+    }),
+    "api.place_contract",
+    "selected place",
+  );
+  return {
+    // Any UUID version: the server mints place ids.
+    placeId: requireIdentifier(place.id, "api.place_contract", "id"),
+    name: text(place.name),
+    category: text(place.category),
+    address: text(place.address),
+    city: text(place.city),
+    region: text(place.region),
+    country: text(place.country),
+  };
+}
+
 /**
  * Processing is observed through `ListSiteImages`; `GetImageById` is
  * session-only under TR00602's read list, so a key-authorized client watches
@@ -1008,6 +1065,7 @@ export async function getPublishingReadiness(client, siteId, selection = {}) {
           ["stagedPageIds", selection.stagedPageIds],
           ["selectedSettingsTypes", selection.selectedSettingsTypes],
           ["includeNavigation", selection.includeNavigation],
+          ["useExactPageSelection", selection.useExactPageSelection],
         ])
       }`,
     )),

package/src/cli.js

@@ -10,10 +10,12 @@ import {
   DEPLOY_TARGET_STAGING,
   LIMITS,
   LOGIN_KEY_NAME_MAXIMUM,
+  PLAN_HASH,
   PUBLISH_KEY_ENVIRONMENT_VARIABLE,
   RESULT_SCHEMA_VERSION,
   SURFACE_DOCS_PRESENTATION,
   SURFACE_STANDARD,
+  VERB_APPLY,
   VERB_APPROVE,
   VERB_DELIVERY_CHECK,
   VERB_DEPLOY,
@@ -29,6 +31,9 @@ import {
   VERB_MEDIA_UPLOAD,
   VERB_NAV_PUSH,
   VERB_PAGES_PUSH,
+  VERB_PLACES_SEARCH,
+  VERB_PLACES_SELECT,
+  VERB_PLAN,
   VERB_PREVIEW_PAGE,
   VERB_PREVIEW_REVOKE,
   VERB_PULL,
@@ -68,6 +73,7 @@ import {
   REFERENCE_TOPICS,
   REFERENCE_VERSION,
 } from "./reference-help.js";
+import { FONT_CATEGORIES, getFontCatalogReference } from "./font-catalog.js";
 import { assertCliCurrent } from "./session.js";
 import { VERB_HANDLERS } from "./verbs/index.js";
 
@@ -95,15 +101,20 @@ const VERBS = Object.freeze([
   {
     name: VERB_VALIDATE,
     tokens: ["validate"],
-    summary: "Validate an offline fixture, or initialize one from a pulled workspace with --init.",
+    summary: "Check a whole workspace or offline fixture at once, or initialize a fixture with --init.",
     positionals: "fixturePath",
     offline: true,
     note:
-      "Reads manifest.fixture.json plus the fixture's page, navigation, theme, appearance, header, brand, and footer files. "
-      + "This proves local structure and semantics only. It does not prove authorization, live site ownership, concurrency, "
-      + "persisted round trips, or rendering; run a real pull and authorized preview before deployment. "
-      + `See '${CLI_BINARY_NAME} help fixture' for the manifest contract and for the path of the complete example `
-      + "fixture this package ships, which needs no credential and no pulled site. "
+      "With no directory, checks the pulled workspace taproot-site.json names; with one, checks that directory, which "
+      + "is either an offline fixture (manifest.fixture.json) or a pulled workspace. Every page source, the theme, "
+      + "appearance, header, brand, footer, navigation, redirects, and forms are checked with the validators the "
+      + "pushes use, and every problem is reported at once in error.problems (each with its file, code, and field) "
+      + "rather than one per run. A pulled workspace is checked against the pages, images, and baselines its "
+      + "manifests recorded at the pull. This proves local structure and semantics only. It does not prove "
+      + "authorization, live site ownership, concurrency, persisted round trips, or rendering: 'plan' checks a "
+      + "workspace against the live site, and 'pages push --dry-run' does that for pages alone. "
+      + `See '${CLI_BINARY_NAME} help fixture' for the fixture manifest contract and for the path of the complete `
+      + "example fixture this package ships, which needs no credential and no pulled site. "
       + "With --init, the directory is a new destination; the current pulled workspace or --config supplies the source.",
   },
   {
@@ -224,6 +235,7 @@ const VERBS = Object.freeze([
     surface: SURFACE_STANDARD,
     capabilities: [CAPABILITY_CONTENT],
     tokens: ["pages", "push"],
+    dryRun: true,
     summary: "Create and update pages from the local workspace.",
     positionals: "pagePaths",
     note:
@@ -237,8 +249,71 @@ const VERBS = Object.freeze([
       + "documents of pages it is not sending: an unrelated page left on an obsolete contract is reported by the "
       + "whole-workspace push, not used to block this one. The result states the selection and how many sources were "
       + "discovered and validated. "
+      + "Every selected page is checked before anything is sent, and a refusal lists every problem found in "
+      + "error.problems with its file, code, and field. --dry-run does all of that against the live site, reports "
+      + "which pages would be created, updated, or left unchanged, and sends nothing; it exits 1 when there are "
+      + "problems. "
       + "See 'taproot-site help page free-form' for the stable manifest and error contract.",
   },
+  {
+    name: VERB_PLACES_SEARCH,
+    surface: SURFACE_STANDARD,
+    // A key finds the places for the place reviews it writes, so page editing
+    // is what it needs; each search is a billed Google Places request.
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["places", "search"],
+    positionals: "placeQuery",
+    summary: "Search Google Places for the place a review names; reports predictions and a session token.",
+    note: "Give the place's name and city, such as 'places search Blue Bottle Coffee Oakland'. Each prediction "
+      + "carries a googlePlaceId; pass the one that matches, with the reported sessionToken, to 'places select' to "
+      + "get the Taproot placeId a place review's front matter needs. Searches and the select that follows them are "
+      + "one billed session, so search with a precise query rather than many broad ones.",
+  },
+  {
+    name: VERB_PLACES_SELECT,
+    surface: SURFACE_STANDARD,
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["places", "select"],
+    positionals: "placeSelection",
+    summary: "Record a places search prediction as a Taproot place and report its placeId.",
+    note: "Takes the googlePlaceId from 'places search', then that search's sessionToken. The place is recorded "
+      + "once for every site, so selecting it again returns the same placeId. Use it as placeId in a place review, "
+      + "or as place in an article or album.",
+  },
+  {
+    name: VERB_PLAN,
+    surface: SURFACE_STANDARD,
+    // Pages, media and navigation reads are Content; the presentation read and
+    // the footer draft are Design. The same set apply writes with.
+    capabilities: [CAPABILITY_CONTENT, CAPABILITY_DESIGN],
+    tokens: ["plan"],
+    summary: "Check the whole workspace against the live site and order what is left to send. Writes nothing.",
+    note: "Runs every check the pushes run — each page against the site's pages, revisions and videos; media that "
+      + "pages reference and media upload has not sent; the theme, appearance and footer colors against the site's "
+      + "presentation revision; the footer against its draft; navigation against the live page list — and lists "
+      + "every problem with its area, file, code and field. It then orders the steps that remain: media upload, "
+      + "pages push, footer push (theme push refuses unsaved footer content), theme push, nav push, each marked "
+      + "ready, blocked, or nothing to do with the reason for its place. The result's planHash covers what each "
+      + "step would send and the live state it would meet; pass it to 'apply'. Redirects and forms are not "
+      + "covered: push them on their own. Approval and deployment stay separate.",
+  },
+  {
+    name: VERB_APPLY,
+    surface: SURFACE_STANDARD,
+    capabilities: [CAPABILITY_CONTENT, CAPABILITY_DESIGN],
+    tokens: ["apply"],
+    planHash: true,
+    summary: "Run the steps a plan listed, in order, through the ordinary push verbs.",
+    note: "Plans again first and refuses with apply.plan_stale when the workspace or the site moved since the plan "
+      + "you read, and with the plan's problems when it has any; nothing is written either way. While the steps "
+      + "run, any workspace file read differently from the plan, or not read by the plan at all, stops the step "
+      + "before it writes (apply.plan_stale, naming the file); so does a page revision or the site's navigation "
+      + "that moved, and the theme and footer saves are refused by the site when it moved. Steps are not "
+      + "atomic together: when one fails, the error's completedWrites lists the steps that completed, the one that "
+      + "failed, and those that did not run. Run 'plan' again — finished steps read as nothing to do, and a step "
+      + "whose answer was lost is reconciled by its own verb, never repeated blindly. Pages land as drafts; "
+      + "'approve' and 'deploy' remain separate.",
+  },
   {
     name: VERB_NAV_PUSH,
     surface: SURFACE_STANDARD,
@@ -344,8 +419,9 @@ const VERBS = Object.freeze([
       + "as a warning naming 'fit lint <id>' and does not stop the push, so read them in a --dry-run first. "
       + "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.",
+      + "in explicitMappingTokens at the root (a context's pins need no marker); every other token compiles from roles "
+      + "at render time, so never copy default mappings into a theme: a pinned token shadows its role. Contrast and "
+      + "status-color warnings name the nearest passing value the CLI found and checked.",
   },
   {
     name: VERB_FOOTER_PUSH,
@@ -591,7 +667,7 @@ ${COMMON_OPTIONS}
 function verbHelp(verb) {
   const targetUsage = verb.target ? " (--staging | --production)" : "";
   const positionalUsage = verb.positionals === "fixturePath"
-    ? " <fixture-directory>"
+    ? " [<directory>]"
     : verb.positionals === "pageSelector"
     ? " <page-path-or-id>"
     : verb.positionals === "previewIds"
@@ -602,6 +678,10 @@ function verbHelp(verb) {
     ? " <site-name-or-id>"
     : verb.positionals === "formKeys"
     ? " [form-key...]"
+    : verb.positionals === "placeQuery"
+    ? " <query...>"
+    : verb.positionals === "placeSelection"
+    ? " <google-place-id> <session-token>"
     : verb.positionals
     ? ` [${verb.positionals === "paths" ? "path" : "page-path"}...]`
     : "";
@@ -621,6 +701,9 @@ function verbHelp(verb) {
   const dryRunOption = verb.dryRun
     ? "\n  --dry-run        Read the site and report what a push would change, without writing."
     : "";
+  const planOption = verb.planHash
+    ? "\n  --plan <hash>    The planHash 'plan' reported; required."
+    : "";
   const nameOption = verb.keyName
     ? `\n  --name <text>    Name recorded on the issued key (default "${DEFAULT_LOGIN_KEY_NAME}",\n`
       + `                   1-${LOGIN_KEY_NAME_MAXIMUM} characters). The approval screen shows it.`
@@ -644,8 +727,9 @@ function verbHelp(verb) {
       + "Taproot accepts only the latest; with nothing recorded it runs."
     : "";
   const boundary = verb.name === VERB_VALIDATE
-    ? "Validation uses no credential, configuration, network or write. With --init it reads the pulled workspace "
-      + `or selected configuration and writes a new fixture directory, still without credentials or network.${upgradeGate}`
+    ? "Validation uses no credential, network or write; it reads the configuration only to find the workspace when "
+      + "no directory is given. With --init it reads the pulled workspace or selected configuration and writes a new "
+      + `fixture directory, still without credentials or network.${upgradeGate}`
     : selfContained
     ? "This offline verb uses no credential and reads no configuration, and performs no network request and no "
       + `write.${upgradeGate}`
@@ -661,7 +745,8 @@ function verbHelp(verb) {
   const options = verb.name === VERB_VALIDATE
     ? `Options:
   --init           Export a pulled workspace into the new fixture directory.
-  --config <path>  Before the verb; source configuration for --init only.
+  --config <path>  Before the verb; the configuration naming the workspace (no
+                   directory) or the --init source.
   --quiet          Suppress human progress. The JSON result is unchanged.
   --help           Show this help.
   --version        Show the package version.`
@@ -688,7 +773,7 @@ function verbHelp(verb) {
 ${verb.summary}
 ${boundary}
 
-${options}${targetOption}${deliveryTargetOption}${jsonOption}${dryRunOption}${nameOption}${note}
+${options}${targetOption}${deliveryTargetOption}${jsonOption}${dryRunOption}${planOption}${nameOption}${note}
 `;
 }
 
@@ -761,6 +846,9 @@ function parseReferenceArguments(arguments_) {
   ) {
     throw usageError("help.usage", `The '${topic}' topic does not accept a name.`);
   }
+  if (topic === "fonts" && extra.length > 0) {
+    throw usageError("help.usage", "The 'fonts' topic accepts at most one category.");
+  }
   if ((topic === "page" || topic === "component" || topic === "design") && (subject === undefined || extra.length > 0)) {
     throw usageError("help.usage", `The '${topic}' topic requires exactly one name.`);
   }
@@ -833,6 +921,17 @@ function referenceResult(parsed) {
         referenceKind: parsed.topic,
         reference: getWorkflowReference(parsed.topic),
       };
+    case "fonts": {
+      const fonts = getFontCatalogReference(parsed.subject);
+      if (!fonts) {
+        throw usageError(
+          "help.font_category_unknown",
+          `Unknown font category. Expected one of: ${FONT_CATEGORIES.join(", ")}.`,
+          { alternatives: FONT_CATEGORIES },
+        );
+      }
+      return { ...result, topic: "fonts", fonts };
+    }
     case "theme":
       return { ...result, topic: "presentation", referenceKind: "theme", reference: getThemeReference() };
     case "appearance":
@@ -896,6 +995,16 @@ function parseWaitOption(arguments_, index) {
   return seconds;
 }
 
+function parsePlanOption(arguments_, index) {
+  const candidate = arguments_[index + 1];
+  if (typeof candidate !== "string" || !PLAN_HASH.test(candidate)) {
+    throw usageError("apply.plan_required", "--plan requires the planHash 'plan' reported (sha256:<64 hex>).", {
+      field: "planHash",
+    });
+  }
+  return candidate;
+}
+
 function parseNameOption(arguments_, index) {
   const candidate = arguments_[index + 1];
   if (
@@ -948,10 +1057,11 @@ function parseArguments(arguments_) {
   // origin the sign-in belongs to — so they accept it. whoami is offline and
   // reads both the store and the configuration, so it accepts it too: the test
   // is "reads nothing local", not "makes no request".
-  if (
-    verb.offline && !verb.readsLocalState && configPath !== undefined
-    && !(verb.name === VERB_VALIDATE && rest.includes("--init"))
-  ) {
+  // validate reads the configuration in two cases: --init, and no directory,
+  // which checks the workspace the configuration names.
+  const validateReadsConfig = verb.name === VERB_VALIDATE
+    && (rest.includes("--init") || rest.every((argument) => argument.startsWith("-")));
+  if (verb.offline && !verb.readsLocalState && configPath !== undefined && !validateReadsConfig) {
     throw usageError("cli.config_option", "--config applies only to verbs that read the site configuration.", {
       field: "configPath",
     });
@@ -969,6 +1079,7 @@ function parseArguments(arguments_) {
   let dryRun = false;
   let json = false;
   let keyName;
+  let planHash;
   const positionals = [];
   for (let index = 0; index < rest.length; index += 1) {
     const argument = rest[index];
@@ -1035,6 +1146,12 @@ function parseArguments(arguments_) {
       json = true;
       continue;
     }
+    if (verb.planHash && argument === "--plan") {
+      if (planHash !== undefined) throw usageError("cli.duplicate_option", "--plan may be supplied only once.");
+      planHash = parsePlanOption(rest, index);
+      index += 1;
+      continue;
+    }
     if (verb.keyName && argument === "--name") {
       if (keyName !== undefined) throw usageError("cli.duplicate_option", "--name may be supplied only once.");
       keyName = parseNameOption(rest, index);
@@ -1066,13 +1183,10 @@ function parseArguments(arguments_) {
       `${verb.tokens.join(" ")} requires exactly one of --staging or --production.`,
     );
   }
-  if (
-    verb.positionals === "fixturePath"
-    && positionals.length !== 1
-  ) {
+  if (verb.positionals === "fixturePath" && (positionals.length > 1 || (init && positionals.length !== 1))) {
     throw usageError(
       "validate.fixture_path_invalid",
-      "validate requires exactly one fixture directory.",
+      init ? "validate --init requires exactly one new fixture directory." : "validate accepts at most one directory.",
       { field: "fixturePath" },
     );
   }
@@ -1120,6 +1234,11 @@ function parseArguments(arguments_) {
       { field: "environmentSelector" },
     );
   }
+  if (verb.planHash && planHash === undefined) {
+    throw usageError("apply.plan_required", "apply requires --plan with the planHash that 'plan' reported.", {
+      field: "planHash",
+    });
+  }
   if (quiet && verb.name === VERB_LOGIN) {
     // The approval URL and user code reach the operator only as progress
     // lines, and the JSON result is serialized only after polling ends — so a
@@ -1161,6 +1280,7 @@ function parseArguments(arguments_) {
     init,
     dryRun,
     keyName,
+    ...(planHash === undefined ? {} : { planHash }),
     positionals: verb.positionals
       ? {
         key: verb.positionals,
@@ -1244,6 +1364,11 @@ export async function runCli({
       quiet: parsed.quiet,
       dryRun: parsed.dryRun,
       keyName: parsed.keyName,
+      ...(parsed.planHash === undefined ? {} : { planHash: parsed.planHash }),
+      // Only when given, like the other optional fields, so each verb keeps its default (TR00925).
+      ...(parsed.deliveryUrl === undefined ? {} : { deliveryUrl: parsed.deliveryUrl }),
+      ...(parsed.propagationWaitSeconds === undefined ? {} : { propagationWaitSeconds: parsed.propagationWaitSeconds }),
+      ...(parsed.browser === undefined ? {} : { browser: parsed.browser }),
       capabilities: parsed.capabilities,
       surface: parsed.surface,
       surfaceCapabilities: parsed.surfaceCapabilities,

package/src/constants.js

@@ -103,6 +103,12 @@ export const VERB_STAGING_REVIEW = "staging review";
 export const VERB_SITES = "sites";
 export const VERB_USE = "use";
 export const VERB_WHOAMI = "whoami";
+export const VERB_PLAN = "plan";
+export const VERB_APPLY = "apply";
+export const VERB_PLACES_SEARCH = "places search";
+export const VERB_PLACES_SELECT = "places select";
+/** The identity `plan` reports and `apply --plan` requires. */
+export const PLAN_HASH = /^sha256:[0-9a-f]{64}$/u;
 export const VERB_ENV = "env";
 
 // Which authoring verbs a site accepts (TR00790), as `use` records it in the