@taprootio/site-authoring 0.15.0 → 0.18.0

package/src/authors-contract.js

@@ -0,0 +1,170 @@
+import { SiteAuthoringError } from "./errors.js";
+
+/**
+ * Who a page can be credited to (TR01196).
+ *
+ * A page's author is one of two kinds of person, named by one string:
+ *
+ * - a site member who can create pages, by email address; or
+ * - a site author without a Taproot account, by handle. Handles are a
+ *   lowercase slug the site fixes when the author is created, so a page keeps
+ *   pointing at the same person if their display name changes.
+ *
+ * The two spellings cannot collide: a handle never contains '@'. The site
+ * folds case on both (an address is stored lowercase, a handle is lowercase),
+ * so this module does too, and compares only folded values.
+ */
+
+export const AUTHORS_FILE_NAME = "authors.json";
+
+export const AUTHOR_HANDLE_MAXIMUM_LENGTH = 64;
+export const AUTHOR_DISPLAY_NAME_MAXIMUM_LENGTH = 256;
+export const AUTHOR_EMAIL_MAXIMUM_LENGTH = 320;
+
+const HANDLE = /^[a-z0-9]+(-[a-z0-9]+)*$/u;
+// Deliberately loose: the site canonicalizes and decides. This only tells an
+// address from a handle and refuses text that cannot be one.
+const EMAIL = /^[^\s@<>()]+@[^\s@<>()]+\.[^\s@<>()]+$/u;
+
+export const AUTHOR_KIND_HANDLE = "handle";
+export const AUTHOR_KIND_EMAIL = "email";
+
+/** The folded handle, or undefined when the text is not a handle. */
+export function normalizeAuthorHandle(value) {
+  if (typeof value !== "string") return undefined;
+  const handle = value.trim().toLowerCase();
+  return handle.length > 0 && handle.length <= AUTHOR_HANDLE_MAXIMUM_LENGTH && HANDLE.test(handle)
+    ? handle
+    : undefined;
+}
+
+/** The folded address, or undefined when the text is not an email address. */
+export function normalizeAuthorEmail(value) {
+  if (typeof value !== "string") return undefined;
+  const email = value.trim().toLowerCase();
+  return email.length <= AUTHOR_EMAIL_MAXIMUM_LENGTH && EMAIL.test(email) ? email : undefined;
+}
+
+/**
+ * What an `author` reference names: `{ kind, value }` with the folded value, or
+ * undefined for text that is neither a handle nor an email address.
+ */
+export function parseAuthorReference(value) {
+  if (typeof value !== "string") return undefined;
+  if (value.includes("@")) {
+    const email = normalizeAuthorEmail(value);
+    return email === undefined ? undefined : { kind: AUTHOR_KIND_EMAIL, value: email };
+  }
+  const handle = normalizeAuthorHandle(value);
+  return handle === undefined ? undefined : { kind: AUTHOR_KIND_HANDLE, value: handle };
+}
+
+/** The folded reference, or a refusal that names where it was written. */
+export function requireAuthorReference(value, field, code = "pages.author_invalid") {
+  const reference = parseAuthorReference(value);
+  if (reference === undefined) {
+    throw new SiteAuthoringError(
+      code,
+      `'${typeof value === "string" ? value.slice(0, 80) : ""}' is not an author reference. Name a site author by `
+        + "handle (lowercase letters, digits and hyphens, such as jane-doe) or a site member by email address.",
+      { field },
+    );
+  }
+  return reference.value;
+}
+
+function boundedText(value, maximum) {
+  return typeof value === "string" && value.length <= maximum ? value : undefined;
+}
+
+/**
+ * Reads the site's author listing, refusing a response that does not have the
+ * shape this CLI relies on. A member's address is only present for a caller
+ * allowed to see it; the CLI's credential is, so an absent one is dropped.
+ */
+export function normalizeAuthorListing(value) {
+  const listing = value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+  const authors = [];
+  for (const raw of Array.isArray(listing.authors) ? listing.authors : []) {
+    const handle = normalizeAuthorHandle(raw?.handle);
+    if (handle === undefined) continue;
+    authors.push({
+      handle,
+      displayName: boundedText(raw.displayName, AUTHOR_DISPLAY_NAME_MAXIMUM_LENGTH) ?? "",
+      hasEmail: raw.hasEmail === true || (typeof raw.email === "string" && raw.email !== ""),
+    });
+  }
+  const members = [];
+  for (const raw of Array.isArray(listing.members) ? listing.members : []) {
+    const email = normalizeAuthorEmail(raw?.email);
+    if (email === undefined) continue;
+    members.push({
+      email,
+      displayName: boundedText(raw.displayName, AUTHOR_DISPLAY_NAME_MAXIMUM_LENGTH) ?? "",
+    });
+  }
+  return { authors, members };
+}
+
+/**
+ * The workspace file `pull` and `authors list` write. Site authors carry no
+ * address: it is private to the site and nothing local needs it. Members carry
+ * theirs, because that is how a page names them.
+ */
+export function projectAuthorsForWorkspace(siteId, listing) {
+  return {
+    siteId,
+    authors: listing.authors.map(({ handle, displayName }) => ({ handle, displayName })),
+    members: listing.members.map(({ email, displayName }) => ({ email, displayName })),
+  };
+}
+
+/**
+ * Reads `authors.json` back. Anything unreadable or bound to another site is
+ * treated as absent: it can only ever make a reference unprovable offline,
+ * never turn a valid one into a refusal.
+ */
+export function readAuthorsDocument(value, siteId) {
+  if (value === null || typeof value !== "object" || Array.isArray(value) || value.siteId !== siteId) {
+    return undefined;
+  }
+  const handles = new Set();
+  for (const author of Array.isArray(value.authors) ? value.authors : []) {
+    const handle = normalizeAuthorHandle(author?.handle);
+    if (handle !== undefined) handles.add(handle);
+  }
+  const emails = new Set();
+  for (const member of Array.isArray(value.members) ? value.members : []) {
+    const email = normalizeAuthorEmail(member?.email);
+    if (email !== undefined) emails.add(email);
+  }
+  return { handles, emails };
+}
+
+/**
+ * Whether a folded reference names someone the recorded listing knows, or
+ * `undefined` when there is no listing to ask.
+ */
+export function authorKnown(authors, reference) {
+  if (authors === undefined) return undefined;
+  const parsed = parseAuthorReference(reference);
+  if (parsed === undefined) return false;
+  return parsed.kind === AUTHOR_KIND_EMAIL ? authors.emails.has(parsed.value) : authors.handles.has(parsed.value);
+}
+
+/**
+ * The refusal text for a source that names a different author than the site
+ * holds. The way out depends on where the author is written: a `.pm.json`
+ * page keeps it in the workspace manifest, edited with `pages meta set`; a
+ * Markdown page keeps it in its front matter (TR01196).
+ */
+export function authorConflictMessage({ shown, file, held, wanted, markdown }) {
+  const lead = `Page '${shown}' already has the author '${held}'`
+    + (wanted === undefined ? "" : `, and '${file}' names '${wanted}'`)
+    + ". An author is never replaced from the CLI";
+  return markdown
+    ? `${lead}: set 'author: ${held}' in the front matter, or remove the line, to match the site. To credit someone `
+      + "else, change it in the app."
+    : `${lead}: run 'taproot-site pages meta set ${shown} --author ${held}' to match the site. To credit someone `
+      + "else, change it in the app.";
+}

package/src/cli.js

@@ -17,6 +17,8 @@ import {
   SURFACE_STANDARD,
   VERB_APPLY,
   VERB_APPROVE,
+  VERB_AUTHORS_ADD,
+  VERB_AUTHORS_LIST,
   VERB_DELIVERY_CHECK,
   VERB_DEPLOY,
   VERB_STAGING_REVIEW,
@@ -30,7 +32,11 @@ import {
   VERB_LOGOUT,
   VERB_MEDIA_UPLOAD,
   VERB_NAV_PUSH,
+  VERB_PAGES_META_SET,
   VERB_PAGES_PUSH,
+  VERB_PLACES_CATEGORY_CLEAR,
+  VERB_PLACES_CATEGORY_LIST,
+  VERB_PLACES_CATEGORY_SET,
   VERB_PLACES_SEARCH,
   VERB_PLACES_SELECT,
   VERB_PLAN,
@@ -109,8 +115,10 @@ const VERBS = Object.freeze([
       + "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 "
+      + "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 `
@@ -228,7 +236,64 @@ 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,
@@ -240,6 +305,10 @@ const VERBS = Object.freeze([
     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 "
@@ -253,6 +322,10 @@ const VERBS = Object.freeze([
       + "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.",
   },
   {
@@ -280,6 +353,39 @@ const VERBS = Object.freeze([
       + "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_PLACES_CATEGORY_SET,
+    surface: SURFACE_STANDARD,
+    // Changes what the site's place reviews publish, so it needs page editing.
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["places", "category", "set"],
+    positionals: "placeCategory",
+    summary: "Set this site's category for a place, from the closed category list.",
+    note: "Takes the placeId from 'places select' (or a page's front matter), then one category from "
+      + "'places category list', which prints the closed list; a name outside it is refused, and capitalization is "
+      + "ignored. Use it when Google's own category for a place is not the one this site wants, such as a park filed "
+      + "under Other. The category is this site's alone and applies to every review of that place here: the place "
+      + "itself and other sites do not change. Place-review bylines and the /places/<category> pages use it from the "
+      + "next deployment, which a changed category alone is enough to start. Undo it with 'places category clear'.",
+  },
+  {
+    name: VERB_PLACES_CATEGORY_CLEAR,
+    surface: SURFACE_STANDARD,
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["places", "category", "clear"],
+    positionals: "placeId",
+    summary: "Remove this site's category for a place, so the place's own category applies again.",
+    note: "Takes the placeId. Clearing a place this site never set succeeds and changes nothing. Pages use the "
+      + "place's own category from the next deployment.",
+  },
+  {
+    name: VERB_PLACES_CATEGORY_LIST,
+    surface: SURFACE_STANDARD,
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["places", "category", "list"],
+    summary: "List the place categories 'places category set' accepts.",
+    note: "The list is closed: a category outside it is refused.",
+  },
   {
     name: VERB_PLAN,
     surface: SURFACE_STANDARD,
@@ -330,9 +436,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,
@@ -457,7 +563,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,
@@ -479,7 +588,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,
@@ -639,7 +749,7 @@ upgrade. Once a run has recorded a newer release, help, validate, and whoami
 refuse the same way offline. --version and --help always answer.
 
 Verbs:
-${VERBS.map((verb) => `  ${verb.tokens.join(" ").padEnd(14)} ${verb.summary}`).join("\n")}
+${VERBS.map((verb) => `  ${verb.tokens.join(" ").padEnd(20)} ${verb.summary}`).join("\n")}
 
 Configuration:
   Site verbs read taproot-site.json, found by walking up from the current
@@ -682,6 +792,14 @@ function verbHelp(verb) {
     ? " <query...>"
     : verb.positionals === "placeSelection"
     ? " <google-place-id> <session-token>"
+    : verb.positionals === "placeCategory"
+    ? " <place-id> <category>"
+    : verb.positionals === "placeId"
+    ? " <place-id>"
+    : 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"}...]`
     : "";
@@ -695,6 +813,15 @@ 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)."
     : "";
@@ -733,6 +860,9 @@ function verbHelp(verb) {
     : 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}`
@@ -773,7 +903,7 @@ function verbHelp(verb) {
 ${verb.summary}
 ${boundary}
 
-${options}${targetOption}${deliveryTargetOption}${jsonOption}${dryRunOption}${planOption}${nameOption}${note}
+${options}${targetOption}${deliveryTargetOption}${metaOptions}${authorOptions}${jsonOption}${dryRunOption}${planOption}${nameOption}${note}
 `;
 }
 
@@ -1005,6 +1135,45 @@ function parsePlanOption(arguments_, index) {
   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 (
@@ -1080,6 +1249,11 @@ function parseArguments(arguments_) {
   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];
@@ -1152,6 +1326,39 @@ function parseArguments(arguments_) {
       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);
@@ -1234,6 +1441,28 @@ 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",
@@ -1281,12 +1510,18 @@ function parseArguments(arguments_) {
     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,
   };
@@ -1369,6 +1604,11 @@ export async function runCli({
       ...(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";
@@ -107,6 +110,9 @@ export const VERB_PLAN = "plan";
 export const VERB_APPLY = "apply";
 export const VERB_PLACES_SEARCH = "places search";
 export const VERB_PLACES_SELECT = "places select";
+export const VERB_PLACES_CATEGORY_SET = "places category set";
+export const VERB_PLACES_CATEGORY_CLEAR = "places category clear";
+export const VERB_PLACES_CATEGORY_LIST = "places category list";
 /** The identity `plan` reports and `apply --plan` requires. */
 export const PLAN_HASH = /^sha256:[0-9a-f]{64}$/u;
 export const VERB_ENV = "env";
@@ -201,6 +207,19 @@ export const CAPABILITY_REFUSAL_REASON = "SITE_AUTHORING_CAPABILITY_MISSING";
  */
 export const CAPABILITY_REFUSAL_FIELD = "GrantedCapabilities";
 
+/**
+ * The `google.rpc.ErrorInfo` reasons a deploy carries when the site has hit a
+ * commercial ceiling that no retry can clear (TR00445): the deployments-per-
+ * billing-period allowance, or the bandwidth pause. Wire identities matched
+ * exactly, within {@link SITE_DEPLOYMENT_REFUSAL_DOMAIN}. The refusal is
+ * classified `plan_limit`, the same class as the page-count `UpgradePrompt`
+ * field, because the right next move is the same: upgrade, or wait for the
+ * reset the server names in `resets_at`.
+ */
+export const DEPLOYMENT_ALLOWANCE_REFUSAL_REASON = "DEPLOYMENT_PERIOD_ALLOWANCE_EXCEEDED";
+export const BANDWIDTH_ALLOWANCE_REFUSAL_REASON = "BANDWIDTH_ALLOWANCE_EXCEEDED";
+export const SITE_DEPLOYMENT_REFUSAL_DOMAIN = "sites.taproot.io";
+
 // gRPC `ResourceExhausted`. Transcoded responses carry the numeric code in the
 // body; the HTTP mapping is 429.
 export const GRPC_RESOURCE_EXHAUSTED = 8;