@taprootio/site-authoring 0.14.1 → 0.16.0

package/src/cli.js

@@ -10,11 +10,15 @@ 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_AUTHORS_ADD,
+  VERB_AUTHORS_LIST,
   VERB_DELIVERY_CHECK,
   VERB_DEPLOY,
   VERB_STAGING_REVIEW,
@@ -28,7 +32,11 @@ import {
   VERB_LOGOUT,
   VERB_MEDIA_UPLOAD,
   VERB_NAV_PUSH,
+  VERB_PAGES_META_SET,
   VERB_PAGES_PUSH,
+  VERB_PLACES_SEARCH,
+  VERB_PLACES_SELECT,
+  VERB_PLAN,
   VERB_PREVIEW_PAGE,
   VERB_PREVIEW_REVOKE,
   VERB_PULL,
@@ -68,6 +76,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 +104,22 @@ 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 offline against the pages (generated ones included, "
+      + "so navigation to a section or tag page resolves), images, and baselines its manifests recorded at the pull. "
+      + "A link whose address is only http(s):// plus its own text (left by older editor autolinking) is reported in "
+      + "linkWarnings without refusing; pages push reports the same for the pages it sends. 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.",
   },
   {
@@ -217,17 +233,79 @@ const VERBS = Object.freeze([
       + "site's version under '.taproot-site-state/', and leaves you to either push the local source or delete it "
       + "and pull again. A locally edited '.pm.json' is kept rather than overwritten for the same reason. "
       + "First revisions adopted without a completed body comparison are counted in pages.revisionsRecordedWithoutBodyComparison "
-      + "and announced on the human channel. New downloads and compared bodies are excluded.",
+      + "and announced on the human channel. New downloads and compared bodies are excluded. "
+      + "A page Taproot generates (a tag, an archive, a place, a folder) is pulled as an update-only '.pm.json' "
+      + "(template 'generated'): you edit its custom title, breadcrumb title, custom description and introduction, "
+      + "and the manifest keeps the title and description the site reports.",
+  },
+  {
+    name: VERB_PAGES_META_SET,
+    tokens: ["pages", "meta", "set"],
+    offline: true,
+    // Offline, but it reads taproot-site.json and edits the workspace manifest.
+    readsLocalState: true,
+    writesWorkspace: true,
+    metaOptions: true,
+    positionals: "metaPagePath",
+    summary: "Set a tracked page's title, description or author in the workspace; 'pages push' sends it.",
+    note: "Names one page by its path ('/' for the homepage) and sets --title, --description, --author, or any of "
+      + "them, in the workspace's record of that page. A .pm.json page keeps its title, description and author "
+      + "there, so this is the supported way to change them; a Markdown page keeps them in its front matter, which "
+      + "is edited instead. --author names a site author by handle or a member by email address (see 'authors "
+      + "list'); it only fills a page that has no author, and a page that already has a different one is refused "
+      + "(pages.author_conflict). A name missing from authors.json is only warned about (authors.json can be older "
+      + "than the site's list); 'pages push' checks it against the site. --author \"\" drops an author that has not "
+      + "been sent; it never removes the site's. "
+      + "A generated page keeps its own in its source (data.customTitle and data.customDescription), which this "
+      + "edits; an empty --title or --description there clears the custom value so the page uses its generated one. "
+      + "A description longer than 160 characters is warned about (search results cut it off) and one longer than "
+      + "1000 is refused. Nothing is sent: run 'pages push', then 'approve'.",
+  },
+  {
+    name: VERB_AUTHORS_LIST,
+    surface: SURFACE_STANDARD,
+    // Naming an author is part of writing a page, and the site gates both the
+    // list and the creation on the permission that creates pages (TR01196).
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["authors", "list"],
+    summary: "List the site authors and the members a page can be credited to; refreshes authors.json.",
+    note: "A page's author is a site author without a Taproot account (named by handle, such as jane-doe) or a site "
+      + "member who can create pages (named by email address). Pages are authorless unless a source names one, and "
+      + "an author already on a page is never replaced. The result lists authors { handle, displayName, hasEmail } "
+      + "and members { email, displayName }, and rewrites authors.json, which the offline checks ('validate', "
+      + "'pages meta set') read to warn about a name it lacks. authors.json holds members' email addresses: keep it "
+      + "out of a public repository. "
+      + "A site author's own address is private and is never listed or written.",
+  },
+  {
+    name: VERB_AUTHORS_ADD,
+    surface: SURFACE_STANDARD,
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["authors", "add"],
+    positionals: "authorHandle",
+    authorOptions: true,
+    summary: "Create a site author, someone a page can be credited to who has no Taproot account.",
+    note: "Give the handle (lowercase letters, digits and single hyphens, at most 64 characters; it never changes) "
+      + "and --name, the name readers see on the byline. --email is optional: it is kept private, never published, "
+      + "and lets the person be linked to a Taproot account later. Then credit pages to the author with "
+      + "'author: <handle>' in a page's front matter or 'pages meta set <path> --author <handle>'. A handle the site "
+      + "already has under another name is refused (authors.handle_taken); under the same name it succeeds with "
+      + "existing: true. authors.json is updated with the new author.",
   },
   {
     name: VERB_PAGES_PUSH,
     surface: SURFACE_STANDARD,
     capabilities: [CAPABILITY_CONTENT],
     tokens: ["pages", "push"],
+    dryRun: true,
     summary: "Create and update pages from the local workspace.",
     positionals: "pagePaths",
     note:
       "Positional page paths narrow the push to those pages; with none, every workspace page is validated and sent. "
+      + "A link in a page being sent whose address is only http(s):// plus its own text is reported in linkWarnings "
+      + "(content.link_autolinked) without refusing. "
+      + "A page is created without an author unless its source names one ('author:' in the front matter, or 'pages "
+      + "meta set --author'); the pages created that way are listed in pages.authorless with how to credit them. "
       + "The homepage is recorded with an empty path, so address it as '/'. "
       + "A selected path resolves to its one authoritative source from metadata alone, and that page is then validated "
       + "exactly as a whole push would validate it — site binding, manifest integrity, live create-or-update "
@@ -237,8 +315,75 @@ 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. "
+      + "A generated page's source is update-only: a push refuses to create one (pages.generated_create), move it "
+      + "(pages.generated_move), or change what it is (pages.generated_identity). A generated page you did not edit "
+      + "never blocks a whole-workspace push, and one the site no longer has is reported as pages.staleGeneratedSources "
+      + "and skipped (naming its path refuses with pages.generated_create). "
       + "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,
@@ -255,9 +400,9 @@ const VERBS = Object.freeze([
     capabilities: [CAPABILITY_CONTENT, CAPABILITY_DEPLOYMENTS],
     tokens: ["redirects", "check"],
     summary: "Check the current redirect map through the authenticated staging edge.",
-    note: "Reports path, HTTP status and Location without following redirects. A redirect is live only with the release "
-      + "that carries it, so this reads the staged release. "
-      + "The result includes a fresh single-use staging handoff; keep it private.",
+    note: "Reports each entry's path, HTTP status and Location in redirects.items, and redirects.verified, without "
+      + "following redirects. A redirect is live only with the release that carries it, so this reads the staged release. "
+      + "The result includes a fresh single-use staging handoff in stagingPreview.url; keep it private.",
   },
   {
     name: VERB_REDIRECTS_PULL,
@@ -344,8 +489,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,
@@ -381,7 +527,10 @@ const VERBS = Object.freeze([
     positionals: "pagePaths",
     note: "Positional arguments narrow the selection to those page paths;"
       + " with none, every draft the workspace manifest tracks is staged."
-      + " The homepage is recorded with an empty path, so address it as '/'.",
+      + " The homepage is recorded with an empty path, so address it as '/'."
+      + " A named page with no pending draft (already approved, or published with no new draft) is listed in"
+      + " skipped { total, items: [{ pageId, path, status, reason }] } and the rest are approved; a path that names"
+      + " no page this workspace tracks refuses the whole call.",
   },
   {
     name: VERB_DEPLOY,
@@ -403,7 +552,8 @@ const VERBS = Object.freeze([
     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.",
+      + "stagingPreview.recovery the next step; 'staging review' mints another. On a Standard site the result also "
+      + "carries the automatic redirect check: routeCheck and redirects (see 'help redirects').",
   },
   {
     name: VERB_PREVIEW_PAGE,
@@ -591,7 +741,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 +752,14 @@ 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 === "metaPagePath"
+    ? " <page-path> [--title <text>] [--description <text>] [--author <handle-or-email>]"
+    : verb.positionals === "authorHandle"
+    ? " <handle> --name <display-name> [--email <address>]"
     : verb.positionals
     ? ` [${verb.positionals === "paths" ? "path" : "page-path"}...]`
     : "";
@@ -615,12 +773,24 @@ function verbHelp(verb) {
   --production     Promote the completed staging deployment to production.
   --allow-failed-preview  Explicitly override the matching candidate's failed preview.`
     : "";
+  const metaOptions = verb.metaOptions
+    ? `\n  --title <text>       The page's title.
+  --description <text> The page's description for search results and link previews; '' clears it.
+  --author <ref>       Credit a page that has no author: a site author's handle or a member's email address.`
+    : "";
+  const authorOptions = verb.authorOptions
+    ? `\n  --name <text>        The name readers see on the byline (required).
+  --email <address>    A private address, kept to link the person to an account later (optional).`
+    : "";
   const jsonOption = verb.json
     ? "\n  --json           Emit the stable JSON contract (operational output is always JSON)."
     : "";
   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,11 +814,15 @@ 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}`
+    : verb.writesWorkspace
+    ? "This verb edits only the local workspace: it reads the configuration, uses no credential, and makes no "
+      + "network request."
     : verb.offline
     ? "This verb answers entirely from local state — the stored sign-in and the configuration — and makes no "
       + `network request and no write.${upgradeGate}`
@@ -661,7 +835,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 +863,7 @@ function verbHelp(verb) {
 ${verb.summary}
 ${boundary}
 
-${options}${targetOption}${deliveryTargetOption}${jsonOption}${dryRunOption}${nameOption}${note}
+${options}${targetOption}${deliveryTargetOption}${metaOptions}${authorOptions}${jsonOption}${dryRunOption}${planOption}${nameOption}${note}
 `;
 }
 
@@ -761,6 +936,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 +1011,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 +1085,55 @@ 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;
+}
+
+/**
+ * The text after --title or --description. Either may be empty, which clears a
+ * generated page's custom value; a page with its own title refuses an empty one.
+ */
+function parseMetaOption(arguments_, index, option) {
+  const candidate = arguments_[index + 1];
+  if (
+    typeof candidate !== "string"
+    || Buffer.byteLength(candidate, "utf8") > 8 * 1024
+    || hasAsciiControl(candidate)
+  ) {
+    throw usageError(
+      "cli.meta_option",
+      option === "--title"
+        ? "--title requires one printable title (an empty one clears a generated page's custom title)."
+        : "--description requires one printable description (an empty one clears it).",
+      { field: option.slice(2) },
+    );
+  }
+  return candidate;
+}
+
+/** The text after --author, --name (authors add) or --email: one printable value, bounded. */
+function parseAuthorOption(arguments_, index, option, { allowEmpty = false } = {}) {
+  const candidate = arguments_[index + 1];
+  if (
+    typeof candidate !== "string"
+    || (candidate.length === 0 && !allowEmpty)
+    || Buffer.byteLength(candidate, "utf8") > 2 * 1024
+    || hasAsciiControl(candidate)
+    || candidate.startsWith("--")
+  ) {
+    throw usageError("cli.author_option", `${option} requires exactly one printable value.`, {
+      field: option.slice(2),
+    });
+  }
+  return candidate;
+}
+
 function parseNameOption(arguments_, index) {
   const candidate = arguments_[index + 1];
   if (
@@ -948,10 +1186,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 +1208,12 @@ function parseArguments(arguments_) {
   let dryRun = false;
   let json = false;
   let keyName;
+  let planHash;
+  let metaTitle;
+  let metaDescription;
+  let metaAuthor;
+  let authorName;
+  let authorEmail;
   const positionals = [];
   for (let index = 0; index < rest.length; index += 1) {
     const argument = rest[index];
@@ -1035,6 +1280,45 @@ 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.metaOptions && (argument === "--title" || argument === "--description")) {
+      const value = parseMetaOption(rest, index, argument);
+      if (argument === "--title") {
+        if (metaTitle !== undefined) throw usageError("cli.duplicate_option", "--title may be supplied only once.");
+        metaTitle = value;
+      } else {
+        if (metaDescription !== undefined) {
+          throw usageError("cli.duplicate_option", "--description may be supplied only once.");
+        }
+        metaDescription = value;
+      }
+      index += 1;
+      continue;
+    }
+    if (verb.metaOptions && argument === "--author") {
+      if (metaAuthor !== undefined) throw usageError("cli.duplicate_option", "--author may be supplied only once.");
+      // An empty value clears a pending author that was never sent.
+      metaAuthor = parseAuthorOption(rest, index, argument, { allowEmpty: true });
+      index += 1;
+      continue;
+    }
+    if (verb.authorOptions && (argument === "--name" || argument === "--email")) {
+      const value = parseAuthorOption(rest, index, argument);
+      if (argument === "--name") {
+        if (authorName !== undefined) throw usageError("cli.duplicate_option", "--name may be supplied only once.");
+        authorName = value;
+      } else {
+        if (authorEmail !== undefined) throw usageError("cli.duplicate_option", "--email may be supplied only once.");
+        authorEmail = value;
+      }
+      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 +1350,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 +1401,33 @@ function parseArguments(arguments_) {
       { field: "environmentSelector" },
     );
   }
+  if (verb.positionals === "metaPagePath" && positionals.length !== 1) {
+    throw usageError("pages.meta_path_invalid", "pages meta set names exactly one page path ('/' for the homepage).", {
+      field: "pagePath",
+    });
+  }
+  if (verb.metaOptions && metaTitle === undefined && metaDescription === undefined && metaAuthor === undefined) {
+    throw usageError(
+      "pages.meta_nothing_to_set",
+      "pages meta set needs --title, --description, --author, or any of them.",
+      { field: "title" },
+    );
+  }
+  if (verb.positionals === "authorHandle" && positionals.length !== 1) {
+    throw usageError("authors.handle_missing", "authors add needs exactly one handle, such as jane-doe.", {
+      field: "handle",
+    });
+  }
+  if (verb.authorOptions && authorName === undefined) {
+    throw usageError("authors.name_missing", "authors add needs --name, the name readers see on the byline.", {
+      field: "name",
+    });
+  }
+  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,12 +1469,19 @@ function parseArguments(arguments_) {
     init,
     dryRun,
     keyName,
+    ...(planHash === undefined ? {} : { planHash }),
+    ...(metaTitle === undefined ? {} : { metaTitle }),
+    ...(metaDescription === undefined ? {} : { metaDescription }),
+    ...(metaAuthor === undefined ? {} : { metaAuthor }),
+    ...(authorName === undefined ? {} : { authorName }),
+    ...(authorEmail === undefined ? {} : { authorEmail }),
     positionals: verb.positionals
       ? {
         key: verb.positionals,
         values: positionals,
-        scalar: verb.positionals === "pageSelector" || verb.positionals === "fixturePath"
-          || verb.positionals === "siteSelector" || verb.positionals === "environmentSelector",
+        scalar: verb.positionals === "pageSelector" || verb.positionals === "fixturePath" || verb.positionals === "metaPagePath"
+          || verb.positionals === "siteSelector" || verb.positionals === "environmentSelector"
+          || verb.positionals === "authorHandle",
       }
       : undefined,
   };
@@ -1244,6 +1559,16 @@ 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 }),
+      ...(parsed.metaTitle === undefined ? {} : { metaTitle: parsed.metaTitle }),
+      ...(parsed.metaDescription === undefined ? {} : { metaDescription: parsed.metaDescription }),
+      ...(parsed.metaAuthor === undefined ? {} : { metaAuthor: parsed.metaAuthor }),
+      ...(parsed.authorName === undefined ? {} : { authorName: parsed.authorName }),
+      ...(parsed.authorEmail === undefined ? {} : { authorEmail: parsed.authorEmail }),
       capabilities: parsed.capabilities,
       surface: parsed.surface,
       surfaceCapabilities: parsed.surfaceCapabilities,

package/src/constants.js

@@ -83,6 +83,9 @@ export const VERB_VALIDATE = "validate";
 export const VERB_LOGIN = "login";
 export const VERB_LOGOUT = "logout";
 export const VERB_PAGES_PUSH = "pages push";
+export const VERB_PAGES_META_SET = "pages meta set";
+export const VERB_AUTHORS_LIST = "authors list";
+export const VERB_AUTHORS_ADD = "authors add";
 export const VERB_NAV_PUSH = "nav push";
 export const VERB_REDIRECTS_CHECK = "redirects check";
 export const VERB_REDIRECTS_PULL = "redirects pull";
@@ -103,6 +106,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