@taprootio/site-authoring 0.15.0 → 0.18.0

package/src/verbs/authors.js

@@ -0,0 +1,167 @@
+import { createSiteAuthor, listSiteAuthors, withRefusalGuidance } from "../api.js";
+import {
+  AUTHOR_DISPLAY_NAME_MAXIMUM_LENGTH,
+  AUTHOR_HANDLE_MAXIMUM_LENGTH,
+  AUTHORS_FILE_NAME,
+  normalizeAuthorEmail,
+  normalizeAuthorHandle,
+  projectAuthorsForWorkspace,
+} from "../authors-contract.js";
+import { VERB_AUTHORS_ADD, VERB_AUTHORS_LIST } from "../constants.js";
+import { sanitizeDiagnostic, SiteAuthoringError } from "../errors.js";
+import { boundedList, openSession, successResult } from "../session.js";
+import { ApiError } from "../transport.js";
+import { ensureWorkspaceRoot, writeWorkspaceJson } from "../workspace.js";
+
+const MAXIMUM_REPORTED = 200;
+
+/**
+ * `authors list` — who a page can be credited to (TR01196): the site's authors
+ * without a Taproot account and the members who can create pages. It also
+ * rewrites `authors.json`, the copy `validate` and `pages push` check an
+ * author reference against when they run offline.
+ */
+export async function authorsList(invocation) {
+  const { client, config, siteId, onProgress } = await openSession(invocation);
+  const listing = await withRefusalGuidance(onProgress, "authors list", () => listSiteAuthors(client, siteId));
+  await writeAuthorsFile(config, siteId, listing);
+
+  onProgress(
+    listing.authors.length === 0
+      ? "This site has no site authors without a Taproot account."
+      : `Site authors (handle: name):\n${
+        listing.authors.map((author) => `  ${author.handle}: ${author.displayName}`).join("\n")
+      }`,
+  );
+  onProgress(
+    listing.members.length === 0
+      ? "No member can be named as an author."
+      : `Members who can be named (email: name):\n${
+        listing.members.map((member) => `  ${member.email}: ${member.displayName}`).join("\n")
+      }`,
+  );
+  const authors = boundedList(listing.authors, MAXIMUM_REPORTED);
+  const members = boundedList(listing.members, MAXIMUM_REPORTED);
+  return successResult(VERB_AUTHORS_LIST, siteId, {
+    authorsFile: AUTHORS_FILE_NAME,
+    authors: {
+      total: listing.authors.length,
+      items: authors.items,
+      ...(authors.truncated ? { itemsTruncated: true } : {}),
+    },
+    members: {
+      total: listing.members.length,
+      items: members.items,
+      ...(members.truncated ? { itemsTruncated: true } : {}),
+    },
+  });
+}
+
+/**
+ * `authors add` — creates a site author, someone a page can be credited to who
+ * has no Taproot account, such as one of an imported blog's authors.
+ */
+export async function authorsAdd(invocation) {
+  const handle = normalizeAuthorHandle(invocation.authorHandle);
+  if (handle === undefined) {
+    throw new SiteAuthoringError(
+      "authors.handle_invalid",
+      `'${String(invocation.authorHandle ?? "").slice(0, 80)}' is not a handle. Use lowercase letters and digits `
+        + `with single hyphens between them, at most ${AUTHOR_HANDLE_MAXIMUM_LENGTH} characters, such as jane-doe.`,
+      { field: "handle", exitCode: 2 },
+    );
+  }
+  const displayName = typeof invocation.authorName === "string" ? invocation.authorName.trim() : "";
+  if (displayName === "" || [...displayName].length > AUTHOR_DISPLAY_NAME_MAXIMUM_LENGTH) {
+    throw new SiteAuthoringError(
+      "authors.name_invalid",
+      `--name must be the name readers see, 1 to ${AUTHOR_DISPLAY_NAME_MAXIMUM_LENGTH} characters.`,
+      { field: "name", exitCode: 2 },
+    );
+  }
+  let email;
+  if (invocation.authorEmail !== undefined) {
+    email = normalizeAuthorEmail(invocation.authorEmail);
+    if (email === undefined) {
+      throw new SiteAuthoringError("authors.email_invalid", "--email must be an email address.", {
+        field: "email",
+        exitCode: 2,
+      });
+    }
+  }
+
+  const { client, config, siteId, onProgress } = await openSession(invocation);
+  // A handle that is already taken by the same person is a repeat of this
+  // command, not a mistake: a script that adds its authors again succeeds.
+  let existing = false;
+  let known;
+  const created = await withRefusalGuidance(onProgress, "authors add", async () => {
+    try {
+      return await createSiteAuthor(client, siteId, { handle, displayName, email });
+    } catch (error) {
+      const refusal = translateAuthorsRefusal(error, handle);
+      if (refusal?.code !== "authors.handle_taken") throw refusal;
+      known = await listSiteAuthors(client, siteId);
+      const held = known.authors.find((author) => author.handle === handle);
+      if (held === undefined) throw refusal;
+      if (held.displayName !== displayName) {
+        throw new SiteAuthoringError(
+          "authors.handle_taken",
+          `A site author with the handle '${handle}' already exists, named '${held.displayName}', not `
+            + `'${displayName}'. Use another handle, or the existing author.`,
+          { field: "handle" },
+        );
+      }
+      existing = true;
+      return held;
+    }
+  });
+  onProgress(
+    existing
+      ? `Site author '${created.handle}' (${created.displayName}) already exists; nothing was created.`
+      : `Created site author '${created.handle}' (${created.displayName}).`,
+  );
+
+  // The listing is read back rather than patched, so authors.json is exactly
+  // what the site holds. Created is created: a failed refresh does not undo it.
+  let refreshed = false;
+  try {
+    await writeAuthorsFile(config, siteId, known ?? await listSiteAuthors(client, siteId));
+    refreshed = true;
+  } catch (error) {
+    if (!(error instanceof SiteAuthoringError)) throw error;
+    onProgress(`The author was created, but ${AUTHORS_FILE_NAME} could not be refreshed: run 'authors list'.`);
+  }
+  return successResult(VERB_AUTHORS_ADD, siteId, {
+    author: { handle: created.handle, displayName: created.displayName, hasEmail: created.hasEmail },
+    existing,
+    ...(refreshed ? { authorsFile: AUTHORS_FILE_NAME } : {}),
+    nextStep: `Credit pages with 'author: ${created.handle}' in a page's front matter or `
+      + `'pages meta set <path> --author ${created.handle}', then 'pages push'.`,
+  });
+}
+
+async function writeAuthorsFile(config, siteId, listing) {
+  await ensureWorkspaceRoot(config);
+  await writeWorkspaceJson(config.workspaceDir, AUTHORS_FILE_NAME, projectAuthorsForWorkspace(siteId, listing));
+}
+
+/** Gives the site's refusals of a new author the stable codes the CLI documents. */
+function translateAuthorsRefusal(error, handle) {
+  if (!(error instanceof ApiError)) return error;
+  for (const [field, code, fallback] of [
+    ["HandleTaken", "authors.handle_taken", `A site author with the handle '${handle}' already exists.`],
+    ["Handle", "authors.handle_invalid", `'${handle}' cannot be used as a handle.`],
+    ["DisplayName", "authors.name_invalid", "The name was refused."],
+    ["Email", "authors.email_invalid", "The email address was refused."],
+  ]) {
+    if (error.hasField(field)) {
+      return new SiteAuthoringError(
+        code,
+        sanitizeDiagnostic(error.descriptionFor(field) ?? fallback, fallback),
+        { field: field.toLowerCase() },
+      );
+    }
+  }
+  return error;
+}

package/src/verbs/deploy.js

@@ -4,6 +4,7 @@ import {
   DEPLOYMENT_REQUEST_OUTCOME_COALESCED,
   DEPLOYMENT_STATUS_COMPLETED,
   deploySite,
+  describePageEstimate,
   getDeploySelection,
   getPublishingReadiness,
   listDeployments,
@@ -22,7 +23,7 @@ import {
 } from "../constants.js";
 import { SiteAuthoringError } from "../errors.js";
 import { boundedList, openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
-import { checkStagingRedirects } from "../staging-check.js";
+import { inspectStagingPreview } from "../staging-check.js";
 import { ApiError } from "../transport.js";
 import { readManifest, writeManifest } from "../workspace.js";
 
@@ -67,9 +68,6 @@ const REDIRECT_ACTIVATION_NOTE =
  */
 
 const MAXIMUM_REPORTED_BLOCKERS = 50;
-// Staged page ids ride in the readiness query string, so a very large candidate
-// is checked at site level instead of pushing an unbounded URL at the API.
-const MAXIMUM_READINESS_PAGE_IDS = 100;
 
 function usageError(code, message, field) {
   return new SiteAuthoringError(code, message, { field, exitCode: 2 });
@@ -157,36 +155,13 @@ function reportReadiness(readiness) {
     redirectsChanged: readiness.redirectsChanged,
     formsChanged: readiness.formsChanged,
     videosChanged: readiness.videosChanged,
+    // The pages this deployment generates and the allowance left: what staging is charged (TR01201).
+    ...(readiness.pageEstimate === null ? {} : { pageEstimate: readiness.pageEstimate }),
     blockers: blockers.items,
     ...(blockers.truncated ? { blockersTruncated: true } : {}),
   };
 }
 
-async function inspectStagingPreview(client, siteId, onProgress, now) {
-  let checks;
-  try {
-    checks = await checkStagingRedirects(client, siteId, onProgress, now);
-    if (!checks.redirects.verified) {
-      onProgress(
-        "Warning: staging redirects are not all verified. Check the reported mismatches against the staged release; run 'taproot-site redirects check' again once the deployment has completed.",
-      );
-    }
-  } catch {
-    onProgress(
-      "Warning: the deployment completed, but authenticated staging redirect checks could not finish. Run 'taproot-site redirects check' again.",
-    );
-    checks = { routeCheck: "unresolved", redirects: { verified: false, covered: false } };
-  }
-  try {
-    // Mint after checks so the final single-use URL has never been consumed.
-    const handoff = await mintStagingPreviewHandoff(client, siteId, { now });
-    return { ...checks, ...handoff };
-  } catch {
-    onProgress("Warning: the deployment completed, but a staging handoff could not be minted.");
-    return { ...checks, url: "", warning: "Staging handoff unavailable; run redirects check to retry." };
-  }
-}
-
 const PRESENTATION_REVIEW_GUIDANCE = "Open the URL once in a browser, then switch the site's theme toggle between "
   + "light and dark to review both schemes; no page draft is needed to preview a presentation change.";
 
@@ -366,8 +341,10 @@ export async function deploy(invocation) {
     );
     const readiness = await getPublishingReadiness(client, siteId, {
       ...candidate,
-      stagedPageIds: stagedPageIds.length > MAXIMUM_READINESS_PAGE_IDS ? undefined : stagedPageIds,
       useExactPageSelection: stagedPageIds.length === 0,
+      includePageEstimate: true,
+      // The estimate must recognize the request it is about to be followed by.
+      ...(invocation.allowFailedPreview === true ? { allowFailedPreview: true } : {}),
     });
     if (readiness.blockers.length > 0) {
       throw new SiteAuthoringError(
@@ -393,11 +370,29 @@ export async function deploy(invocation) {
     if (!readiness.hasCandidateChanges) {
       onProgress("Taproot reports this candidate contains no changes; deploying it anyway would be a no-op.");
     }
+    // The plan is the charge: the same page count admission uses, shown before anything is sent.
+    if (readiness.pageEstimate !== null) {
+      onProgress(describePageEstimate(readiness.pageEstimate));
+      if (readiness.pageEstimate.exceedsAllowance) {
+        const estimate = readiness.pageEstimate;
+        throw new SiteAuthoringError(
+          "deploy.page_allowance_exceeded",
+          `This candidate generates ${estimate.plannedPageCount.toLocaleString("en-US")} ${
+            estimate.plannedPageCount === 1 ? "page" : "pages"
+          } but the site has ${(estimate.pagesGeneratedRemaining ?? 0).toLocaleString("en-US")} left for this billing `
+            + `period${estimate.periodEnd === null ? "" : ` (it resets ${estimate.periodEnd})`}. Stage a smaller change, `
+            + "or upgrade the site's plan for a larger allowance. Nothing was sent.",
+          { field: "plannedPageCount" },
+        );
+      }
+    }
 
     const created = await deploySite(client, siteId, {
       siteId,
       environment: DEPLOYMENT_ENVIRONMENT_STAGING,
       ...candidate,
+      // Confirms the number just shown: the server refuses if the plan has grown since.
+      ...(readiness.pageEstimate === null ? {} : { expectedPageCount: readiness.pageEstimate.plannedPageCount }),
       ...(invocation.allowFailedPreview === true ? { allowFailedPreview: true } : {}),
     });
     onProgress(`Staging deployment ${created.id} accepted; waiting for it to complete.`);
@@ -428,7 +423,7 @@ export async function deploy(invocation) {
         nextStep: stagingPreview.url === "" ? "staging review" : "deploy --production",
       });
     }
-    const stagingPreview = await inspectStagingPreview(client, siteId, onProgress, now);
+    const { routeCheck, redirects, stagingPreview } = await inspectStagingPreview(client, siteId, onProgress, now);
     onProgress(REDIRECT_ACTIVATION_NOTE);
     return successResult(VERB_DEPLOY, siteId, {
       target,
@@ -441,8 +436,10 @@ export async function deploy(invocation) {
       deployment: completed,
       outcome: created.outcome,
       readiness: reportReadiness(readiness),
+      routeCheck,
+      redirects,
       stagingPreview,
-      nextStep: stagingPreview.redirects?.verified === true ? "deploy --production" : "redirects check",
+      nextStep: redirects.verified === true ? "deploy --production" : "redirects check",
     });
   });
 }

package/src/verbs/index.js

@@ -1,6 +1,8 @@
 import {
   VERB_APPLY,
   VERB_APPROVE,
+  VERB_AUTHORS_ADD,
+  VERB_AUTHORS_LIST,
   VERB_DELIVERY_CHECK,
   VERB_DEPLOY,
   VERB_ENV,
@@ -12,7 +14,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,
@@ -31,6 +37,7 @@ import {
   VERB_WHOAMI,
 } from "../constants.js";
 import { approve } from "./approve.js";
+import { authorsAdd, authorsList } from "./authors.js";
 import { deliveryCheck } from "./delivery-check.js";
 import { deploy } from "./deploy.js";
 import { env } from "./env.js";
@@ -42,8 +49,9 @@ import { login } from "./login.js";
 import { logout } from "./logout.js";
 import { mediaUpload } from "./media-upload.js";
 import { navPush } from "./nav-push.js";
+import { pagesMetaSet } from "./pages-meta-set.js";
 import { pagesPush } from "./pages-push.js";
-import { placesSearch, placesSelect } from "./places.js";
+import { placesCategoryClear, placesCategoryList, placesCategorySet, placesSearch, placesSelect } from "./places.js";
 import { apply, plan } from "./plan.js";
 import { previewPage } from "./preview-page.js";
 import { previewRevoke } from "./preview-revoke.js";
@@ -101,8 +109,11 @@ import { whoami } from "./whoami.js";
  *                  //   with none, every file under forms/
  *   placeQuery,    // places search: the words of the query
  *   placeSelection, // places select: [googlePlaceId, sessionToken]
+ *   placeCategory, // places category set: [placeId, category]
+ *   placeId,       // places category clear: [placeId]
  *   pagePaths,     // approve: narrow to these page paths; with none, every
  *                  //   draft the workspace manifest tracks is staged
+ *   authorHandle,  // authors add: the handle of the site author to create
  *   pageId,        // preview page: the one persisted draft UUID to render
  *   previewIds,    // preview revoke: [page UUID, snapshot UUID]
  * }
@@ -135,10 +146,16 @@ export const VERB_HANDLERS = Object.freeze({
   [VERB_LOGOUT]: logout,
   [VERB_PULL]: pull,
   [VERB_PAGES_PUSH]: pagesPush,
+  [VERB_PAGES_META_SET]: pagesMetaSet,
+  [VERB_AUTHORS_LIST]: authorsList,
+  [VERB_AUTHORS_ADD]: authorsAdd,
   [VERB_NAV_PUSH]: navPush,
   [VERB_PLAN]: plan,
   [VERB_PLACES_SEARCH]: placesSearch,
   [VERB_PLACES_SELECT]: placesSelect,
+  [VERB_PLACES_CATEGORY_SET]: placesCategorySet,
+  [VERB_PLACES_CATEGORY_CLEAR]: placesCategoryClear,
+  [VERB_PLACES_CATEGORY_LIST]: placesCategoryList,
   [VERB_APPLY]: apply,
   [VERB_REDIRECTS_CHECK]: redirectsCheck,
   [VERB_REDIRECTS_PULL]: redirectsPull,

package/src/verbs/media-upload.js

@@ -354,7 +354,6 @@ const VIDEO_REFUSAL_FIELDS = Object.freeze([
   "Video",
   "UpgradePrompt",
   "VideoNotIncluded",
-  "VideoPendingDowngrade",
 ]);
 
 /**

package/src/verbs/pages-meta-set.js

@@ -0,0 +1,303 @@
+import {
+  AUTHORS_FILE_NAME,
+  authorConflictMessage,
+  authorKnown,
+  parseAuthorReference,
+  readAuthorsDocument,
+  requireAuthorReference,
+} from "../authors-contract.js";
+import { VERB_PAGES_META_SET } from "../constants.js";
+import { SiteAuthoringError } from "../errors.js";
+import { descriptionWarnings, PAGE_AUTHOR_UNVERIFIED, requireDescriptionLength } from "../page-metadata.js";
+import { openAnonymousSession, successResult } from "../session.js";
+import { isGeneratedTemplateType, TEMPLATE_GENERATED, typedDocumentFromJson } from "../typed-pages.js";
+import {
+  displayPagePath,
+  normalizePagePath,
+  PAGE_SOURCE_FORMAT_MARKDOWN,
+  PAGE_WORKSPACE_MODE_EDITABLE,
+  readManifest,
+  readWorkspaceFile,
+  readWorkspaceJson,
+  workspaceFileExists,
+  WORKSPACE_LIMITS,
+  writeManifest,
+  writeWorkspaceJson,
+} from "../workspace.js";
+
+/**
+ * `pages meta set` — the supported way to change a .pm.json page's title,
+ * description or author, which live in the workspace manifest rather than the
+ * file (TR01194, TR01196). It edits the workspace only; `pages push` sends the
+ * change, since the page's content key covers all three.
+ *
+ * The author is the one field that can only be filled, never changed: pages are
+ * authorless by default and an author already on the page is never replaced.
+ *
+ * A generated page keeps its own title and description in its source document
+ * (`data.customTitle`, `data.customDescription`), because the manifest holds the
+ * ones the site reports; an empty value there means "use the generated default"
+ * (TR01195).
+ */
+export async function pagesMetaSet(invocation) {
+  const { config, onProgress } = await openAnonymousSession({ ...invocation, client: null });
+  if (config === undefined) {
+    throw new SiteAuthoringError(
+      "config.not_found",
+      "No taproot-site.json was found. pages meta set edits the workspace it names.",
+    );
+  }
+  // The parser refuses this too; a handler called directly must not report
+  // "nothing changed" for a request that asked for nothing.
+  if (
+    invocation.metaTitle === undefined && invocation.metaDescription === undefined
+    && invocation.metaAuthor === undefined
+  ) {
+    throw new SiteAuthoringError(
+      "pages.meta_nothing_to_set",
+      "Name what to set: --title, --description, --author, or any of them.",
+      { exitCode: 2 },
+    );
+  }
+  // Surrounding whitespace is never meant; the site would keep it otherwise.
+  const title = invocation.metaTitle?.trim();
+  const description = invocation.metaDescription?.trim();
+  // An empty --author clears one that was never sent; any other value is a reference.
+  const clearAuthor = invocation.metaAuthor === "";
+  const author = invocation.metaAuthor === undefined || clearAuthor
+    ? undefined
+    : requireAuthorReference(invocation.metaAuthor, "author");
+  const requested = normalizePagePath(invocation.metaPagePath);
+  if (requested === undefined) {
+    throw new SiteAuthoringError("pages.meta_path_invalid", "The page path is not usable.", {
+      field: "pagePath",
+      exitCode: 2,
+    });
+  }
+  const manifest = await readManifest(config.workspaceDir, config.siteId);
+  const entry = manifest.pages.find((candidate) => normalizePagePath(candidate?.path) === requested);
+  const shown = displayPagePath(requested);
+  if (entry === undefined) {
+    throw new SiteAuthoringError(
+      "pages.meta_page_unknown",
+      `No page this workspace tracks is at '${shown}'. Run 'taproot-site pull' if it was created elsewhere.`,
+      { field: shown },
+    );
+  }
+  if (entry.workspaceMode !== PAGE_WORKSPACE_MODE_EDITABLE) {
+    throw new SiteAuthoringError(
+      "pages.meta_page_readonly",
+      `'${shown}' is not an editable page in this workspace, so its title, description and author cannot be set here.`,
+      { field: shown },
+    );
+  }
+  if (entry.sourceFormat === PAGE_SOURCE_FORMAT_MARKDOWN) {
+    throw new SiteAuthoringError(
+      "pages.meta_markdown",
+      `'${shown}' is authored in ${entry.file}, whose front matter holds its title, description and author; edit them there.`,
+      { field: shown },
+    );
+  }
+  // The manifest entry outlives a deleted source, and pull re-creates the file
+  // from the site, which would silently drop an edit made here.
+  if (typeof entry.file !== "string" || !await workspaceFileExists(config.workspaceDir, entry.file)) {
+    throw new SiteAuthoringError(
+      "pages.meta_source_missing",
+      `'${shown}' has no source file in this workspace. Run 'taproot-site pull' to restore it first.`,
+      { field: shown },
+    );
+  }
+  if (description !== undefined) requireDescriptionLength(description);
+  // A generated page's custom title and description are in its source, where
+  // pull already protects an edit like any other.
+  if (isGeneratedTemplateType(entry.templateType)) {
+    if (author !== undefined || clearAuthor) {
+      throw new SiteAuthoringError(
+        "pages.meta_author_generated",
+        `'${shown}' is a page Taproot generates, so it has no author to set.`,
+        { field: shown },
+      );
+    }
+    return await setGeneratedMetadata({ invocation, config, entry, shown, onProgress });
+  }
+  // pull tells a metadata edit from the site's values by the content key the
+  // last pull or push recorded. Without one the edit could not be protected,
+  // and the next pull would quietly overwrite it.
+  if (typeof entry.baseline?.sourceHash !== "string" || typeof entry.baseline?.contentKey !== "string") {
+    throw new SiteAuthoringError(
+      "pages.meta_unreconciled",
+      `'${shown}' has not been reconciled with the site yet, so an edit here could be lost to the next pull. Run `
+        + "'taproot-site pull' (or push the page) first.",
+      { field: shown },
+    );
+  }
+  if (title === "") {
+    throw new SiteAuthoringError(
+      "pages.meta_title_empty",
+      `'${shown}' needs a title. Only a generated page can clear its title, to use the default one.`,
+      { field: "title", exitCode: 2 },
+    );
+  }
+
+  let unverifiedAuthor = false;
+  if (clearAuthor) requireClearableAuthor({ entry, shown });
+  else if (author !== undefined) {
+    unverifiedAuthor = await requireAssignableAuthor({ config, entry, shown, author });
+    if (unverifiedAuthor) {
+      onProgress(
+        `Warning: '${author}' is not in ${AUTHORS_FILE_NAME}; it may have been added since. 'taproot-site authors list' `
+          + "refreshes it, and 'pages push' checks the name against the site before sending.",
+      );
+    }
+  }
+
+  const next = {
+    title: title ?? entry.title,
+    description: description ?? entry.description ?? "",
+    author: clearAuthor ? "" : author ?? entry.author ?? "",
+  };
+  const changed = next.title !== entry.title
+    || next.description !== (entry.description ?? "")
+    || next.author !== (entry.author ?? "");
+  if (changed) {
+    entry.title = next.title;
+    entry.description = next.description;
+    if (next.author === "") delete entry.author;
+    else entry.author = next.author;
+    await writeManifest(config.workspaceDir, manifest);
+    onProgress(`Set the ${describeFields(invocation)} of '${shown}'. Run 'taproot-site pages push' to send it.`);
+  } else {
+    onProgress(`'${shown}' already has that ${describeFields(invocation)}; nothing changed.`);
+  }
+  return successResult(VERB_PAGES_META_SET, config.siteId, {
+    page: {
+      path: shown,
+      file: entry.file,
+      title: next.title,
+      description: next.description,
+      ...(next.author === "" ? {} : { author: next.author }),
+    },
+    changed,
+    ...descriptionWarnings([{ file: entry.file, pagePath: entry.path, description: next.description }], onProgress),
+    ...(unverifiedAuthor
+      ? {
+        authorWarnings: {
+          total: 1,
+          items: [{ code: PAGE_AUTHOR_UNVERIFIED, file: entry.file, path: shown, author: next.author }],
+        },
+      }
+      : {}),
+    ...(changed ? { nextStep: "pages push" } : {}),
+  });
+}
+
+function describeFields(invocation) {
+  return [
+    invocation.metaTitle !== undefined && "title",
+    invocation.metaDescription !== undefined && "description",
+    invocation.metaAuthor !== undefined && "author",
+  ]
+    .filter(Boolean)
+    .join(" and ");
+}
+
+/**
+ * Refuses an author the site would not take: a different one than the site
+ * holds (never replaced). One that `authors.json` lacks is only warned about,
+ * because this verb is offline and the file is as old as the last `pull` or
+ * `authors list`: the person may have been added since, and `pages push` asks
+ * the site before it sends anything. Answers whether the name is unverified.
+ */
+async function requireAssignableAuthor({ config, entry, shown, author }) {
+  const held = parseAuthorReference(entry.baseline?.author)?.value ?? "";
+  if (held !== "" && held !== author) {
+    throw new SiteAuthoringError(
+      "pages.author_conflict",
+      authorConflictMessage({ shown, held, wanted: author, markdown: false, file: entry.file }),
+      { field: shown },
+    );
+  }
+  if (held === author) return false;
+  let recorded;
+  try {
+    if (await workspaceFileExists(config.workspaceDir, AUTHORS_FILE_NAME)) {
+      recorded = readAuthorsDocument(
+        await readWorkspaceJson(config.workspaceDir, AUTHORS_FILE_NAME, WORKSPACE_LIMITS.authorsBytes),
+        config.siteId,
+      );
+    }
+  } catch {
+    recorded = undefined;
+  }
+  return authorKnown(recorded, author) === false;
+}
+
+/**
+ * `--author ""` drops an author this workspace has not sent yet. It never asks
+ * the site to remove one: once the site holds an author (the last pull or push
+ * recorded it), only the app changes that, so the request is refused rather
+ * than quietly leaving the author in place.
+ */
+function requireClearableAuthor({ entry, shown }) {
+  const held = parseAuthorReference(entry.baseline?.author)?.value ?? "";
+  if (held !== "") {
+    throw new SiteAuthoringError(
+      "pages.author_conflict",
+      `Page '${shown}' already has the author '${held}', and an author is never removed from the CLI. `
+        + "To change or remove it, use the app.",
+      { field: shown },
+    );
+  }
+}
+
+/** Sets a generated page's custom title or description in its source document. */
+async function setGeneratedMetadata({ invocation, config, entry, shown, onProgress }) {
+  let parsed;
+  try {
+    const bytes = await readWorkspaceFile(config.workspaceDir, entry.file, WORKSPACE_LIMITS.documentBytes);
+    parsed = JSON.parse(bytes.toString("utf8"));
+  } catch (error) {
+    if (error instanceof SiteAuthoringError) throw error;
+    throw new SiteAuthoringError("pages.document_shape", `'${entry.file}' is not valid JSON.`, { field: entry.file });
+  }
+  const document_ = typedDocumentFromJson(parsed, entry.file);
+  if (document_.template !== TEMPLATE_GENERATED) {
+    throw new SiteAuthoringError(
+      "pages.meta_page_readonly",
+      `'${entry.file}' is not a generated-page source, so '${shown}' cannot be set from it.`,
+      { field: shown },
+    );
+  }
+  const data = {
+    ...document_.data,
+    ...(invocation.metaTitle === undefined ? {} : { customTitle: invocation.metaTitle.trim() }),
+    ...(invocation.metaDescription === undefined ? {} : { customDescription: invocation.metaDescription.trim() }),
+  };
+  const next = typedDocumentFromJson({ ...document_, data }, entry.file);
+  const changed = next.data.customTitle !== document_.data.customTitle
+    || next.data.customDescription !== document_.data.customDescription;
+  if (changed) {
+    await writeWorkspaceJson(config.workspaceDir, entry.file, next);
+    onProgress(
+      `Set the ${describeFields(invocation)} of '${shown}' in ${entry.file}. Run 'taproot-site pages push' to send it.`,
+    );
+  } else {
+    onProgress(`'${shown}' already has that ${describeFields(invocation)}; nothing changed.`);
+  }
+  return successResult(VERB_PAGES_META_SET, config.siteId, {
+    // The owner's own values; empty means the page uses its generated default.
+    page: {
+      path: shown,
+      file: entry.file,
+      title: next.data.customTitle,
+      description: next.data.customDescription,
+      generated: true,
+    },
+    changed,
+    ...descriptionWarnings(
+      [{ file: entry.file, pagePath: entry.path, description: next.data.customDescription }],
+      onProgress,
+    ),
+    ...(changed ? { nextStep: "pages push" } : {}),
+  });
+}