@taprootio/site-authoring 0.15.0 → 0.18.0

package/src/typed-page-reference.js

@@ -4,6 +4,7 @@ import {
   PLACE_REVIEW_RATINGS,
   TEMPLATE_ALBUM,
   TEMPLATE_ARTICLE,
+  TEMPLATE_GENERATED,
   TEMPLATE_PLACE_REVIEW,
   TEMPLATE_RECIPE,
 } from "./typed-pages.js";
@@ -35,6 +36,14 @@ const FIELD_HELP = Object.freeze({
     required: true,
     description: "Selects the template. A page's template never changes after it is created.",
   },
+  author: {
+    type: "string",
+    required: false,
+    description:
+      "Credits the page to a site author by handle (jane-doe) or to a site member who can create pages by email "
+      + "address. Pages are authorless unless you name one, and an author already on the page is never replaced. "
+      + "'authors list' shows who can be named; 'authors add' creates a site author without an account.",
+  },
   displayDate: {
     type: "YYYY-MM-DD",
     required: false,
@@ -67,7 +76,9 @@ const FIELD_HELP = Object.freeze({
     required: true,
     description:
       "The Taproot place being reviewed. The site fills in its name, address and coordinates from this record. Find "
-      + "it with 'places search <name and city>' and 'places select <googlePlaceId> <sessionToken>'.",
+      + "it with 'places search <name and city>' and 'places select <googlePlaceId> <sessionToken>'. The site publishes the "
+      + "place's category in the byline and files the review under /places/<category>; change it for this site with "
+      + "'places category set <placeId> <category>'.",
   },
   place: {
     type: "UUID",
@@ -270,48 +281,106 @@ const TYPE_DETAILS = Object.freeze({
       "body: ProseMirror document (required, not empty)",
     ],
   },
+  [TEMPLATE_GENERATED]: {
+    displayName: "Generated page",
+    summary:
+      "A listing Taproot generates from the site's content: a tag, the tags index, a published year or month, a place "
+      + "archive, or a folder. You cannot create one; you customize its title, breadcrumb, description and introduction.",
+    documentExample: documentExample(
+      TEMPLATE_GENERATED,
+      {},
+      {
+        kind: "GENERATED_PAGE_KIND_TAG",
+        tagId: "0198a3f2-7c4e-4a10-9b2d-3f6e5d4c3b2a",
+        year: 0,
+        month: 0,
+        countryCode: "",
+        regionCode: "",
+        citySlug: "",
+        categorySlug: "",
+        customTitle: "Trail notes",
+        breadcrumbTitle: "",
+        customDescription: "Field notes from the trails I walk most often.",
+        introductionBody: PARAGRAPH("Everything I have written about walking."),
+      },
+    ),
+    dataFields: [
+      "kind and the identity fields (tagId, year, month, countryCode, regionCode, citySlug, categorySlug): what the "
+      + "page is, written by pull. Leave them as pulled; a push that changes them is refused (pages.generated_identity)",
+      "customTitle: string; empty uses the generated title (the page's reader-facing title)",
+      "breadcrumbTitle: string; empty uses the generated label (used on pages beneath this one)",
+      "customDescription: string, at most 1000 characters, about 160 shown in search results; empty uses the "
+      + "introduction's first paragraph, else the generated description",
+      "introductionBody: ProseMirror document (optional), shown above the generated listing",
+    ],
+    note:
+      "The manifest's title and description for a generated page are what the site reports, recorded for reference; "
+      + "edit customTitle and customDescription here (or with 'pages meta set'), not the manifest. "
+      + "pages push updates the page and refuses to create one (pages.generated_create), move it (pages.generated_move) "
+      + "or change its identity (pages.generated_identity). The site derives the page's title and description from "
+      + "customTitle, customDescription and introductionBody, so what a push sends for them is ignored. A source the site "
+      + "no longer has a page for is reported and skipped by a whole-workspace push.",
+  },
 });
 
 export const TYPED_PAGE_TYPES = Object.freeze(Object.keys(TYPE_DETAILS));
+/** The templates a Markdown source can declare: every typed page but the update-only generated one. */
+export const MARKDOWN_PAGE_TYPES = Object.freeze(TYPED_PAGE_TYPES.filter((type) => type !== TEMPLATE_GENERATED));
 
 function typedReference(type) {
   const details = TYPE_DETAILS[type];
+  const generated = type === TEMPLATE_GENERATED;
   return Object.freeze({
     type,
     displayName: details.displayName,
     summary: details.summary,
     workspace: Object.freeze({
       directory: `${PAGES_DIRECTORY}/`,
-      sourceRule:
-        `One source file per page, exactly as for a free-form page: see '${CLI_BINARY_NAME} help page free-form'. `
-        + "The template is declared in the source (front matter 'template', or the .pm.json 'template' field) and is "
-        + "immutable after creation: pages push refuses a source whose template differs from the live page's "
-        + "(pages.template_immutable).",
-      pull:
-        "pull writes each page of this template as a .pm.json document, byte-stable across pulls. A page you authored as "
-        + "Markdown keeps its Markdown source, and a change made on the site since the last pull is reported as a conflict.",
+      sourceRule: generated
+        ? `One source file per page, exactly as for a free-form page: see '${CLI_BINARY_NAME} help page free-form'. `
+          + "A generated page exists only because the site's content produces it, so its source exists only after "
+          + "'pull' and is never created by hand."
+        : `One source file per page, exactly as for a free-form page: see '${CLI_BINARY_NAME} help page free-form'. `
+          + "The template is declared in the source (front matter 'template', or the .pm.json 'template' field) and is "
+          + "immutable after creation: pages push refuses a source whose template differs from the live page's "
+          + "(pages.template_immutable).",
+      pull: generated
+        ? "pull writes each generated page as a .pm.json document, byte-stable across pulls, and keeps your edits to it "
+          + "when the site's copy has not changed. A change made on the site since the last pull is reported as a conflict."
+        : "pull writes each page of this template as a .pm.json document, byte-stable across pulls. A page you authored as "
+          + "Markdown keeps its Markdown source, and a change made on the site since the last pull is reported as a conflict.",
       formats: Object.freeze([
-        Object.freeze({
+        ...(generated ? [] : [Object.freeze({
           extension: ".md",
           purpose: "Author the page as Markdown with front matter.",
           metadata: Object.freeze(
             frontMatterKeysFor(type).map((name) => Object.freeze({ name, ...FIELD_HELP[name] })),
           ),
-        }),
+        })]),
         Object.freeze({
           extension: ".pm.json",
-          purpose:
-            "The pulled form: { template, displayDate?, coverImageId?, data }. Title, path and description come from the manifest.",
+          purpose: generated
+            ? "The pulled form, and the only one: { template, data }. Path comes from the manifest; title and description "
+              + "are the custom ones in data."
+            : "The pulled form: { template, displayDate?, coverImageId?, data }. Title, path and description come from the manifest.",
           dataFields: Object.freeze(details.dataFields),
         }),
       ]),
     }),
-    markdown: Object.freeze({ body: details.body, example: details.markdownExample }),
+    ...(generated ? {} : { markdown: Object.freeze({ body: details.body, example: details.markdownExample }) }),
     document: Object.freeze({ example: details.documentExample, ...(details.note ? { note: details.note } : {}) }),
     workflow: Object.freeze([
-      Object.freeze({ command: `${CLI_BINARY_NAME} media upload`, result: "Upload cover and album images first." }),
+      ...(generated
+        ? [Object.freeze({
+          command: `${CLI_BINARY_NAME} pull, then pages meta set <path> --title/--description`,
+          result: "Pull the page, then set its custom title or description (or edit the .pm.json).",
+        })]
+        : [Object.freeze({ command: `${CLI_BINARY_NAME} media upload`, result: "Upload cover and album images first." })]),
       Object.freeze({ command: `${CLI_BINARY_NAME} validate`, result: "Check the workspace before sending anything." }),
-      Object.freeze({ command: `${CLI_BINARY_NAME} pages push`, result: "Create or update an unapproved draft." }),
+      Object.freeze({
+        command: `${CLI_BINARY_NAME} pages push`,
+        result: generated ? "Update the generated page's unapproved draft." : "Create or update an unapproved draft.",
+      }),
       Object.freeze({
         command: `${CLI_BINARY_NAME} approve, deploy --staging, deploy --production`,
         result: "Stage, review and promote, as for any page.",
@@ -335,9 +404,10 @@ function formatField(field) {
 export function formatTypedPageReference(page) {
   const markdown = page.workspace.formats.find((format) => format.extension === ".md");
   const json = page.workspace.formats.find((format) => format.extension === ".pm.json");
-  return `${page.displayName} (${page.type})\n${page.summary}\n\nWorkspace (${page.workspace.directory}):\n  source rule           ${page.workspace.sourceRule}\n  pull                  ${page.workspace.pull}\n\nMarkdown front matter:\n${
-    markdown.metadata.map(formatField).join("\n")
-  }\n\nMarkdown body: ${page.markdown.body}\n\nMarkdown example:\n${page.markdown.example}\n.pm.json (${json.purpose})\n  data:\n${
+  const markdownSection = markdown === undefined
+    ? ""
+    : `Markdown front matter:\n${markdown.metadata.map(formatField).join("\n")}\n\nMarkdown body: ${page.markdown.body}\n\nMarkdown example:\n${page.markdown.example}\n`;
+  return `${page.displayName} (${page.type})\n${page.summary}\n\nWorkspace (${page.workspace.directory}):\n  source rule           ${page.workspace.sourceRule}\n  pull                  ${page.workspace.pull}\n\n${markdownSection}.pm.json (${json.purpose})\n  data:\n${
     json.dataFields.map((field) => `    ${field}`).join("\n")
   }\n${page.document.note === undefined ? "" : `  ${page.document.note}\n`}\n.pm.json example:\n${
     JSON.stringify(page.document.example, null, 2)

package/src/typed-pages.js

@@ -1,6 +1,7 @@
 import { FREE_FORM_TEMPLATE_VERSION, TEMPLATE_TYPE_FREE_FORM } from "./api.js";
 import { isVideoEmbedId } from "./content/video-embed-url.js";
 import { SiteAuthoringError } from "./errors.js";
+import { requireDescriptionLength } from "./page-metadata.js";
 
 /**
  * The authored page templates (TR00893).
@@ -29,6 +30,12 @@ export const TEMPLATE_ARTICLE = "article";
 export const TEMPLATE_RECIPE = "recipe";
 export const TEMPLATE_ALBUM = "album";
 export const TEMPLATE_PLACE_REVIEW = "place-review";
+/**
+ * A page Taproot generates (a tag, a month, a folder). It is update-only: the
+ * owner's title, breadcrumb, description and introduction are authored, and
+ * pages push refuses to create one or to change what it is (TR01195).
+ */
+export const TEMPLATE_GENERATED = "generated";
 
 /** Wire identity and the `PageTemplate` member that carries each template's data. */
 export const PAGE_TEMPLATES = Object.freeze({
@@ -37,12 +44,13 @@ export const PAGE_TEMPLATES = Object.freeze({
   [TEMPLATE_RECIPE]: Object.freeze({ wireType: "TEMPLATE_TYPE_RECIPE", dataKey: "recipeData" }),
   [TEMPLATE_ALBUM]: Object.freeze({ wireType: "TEMPLATE_TYPE_ALBUM", dataKey: "albumData" }),
   [TEMPLATE_PLACE_REVIEW]: Object.freeze({ wireType: "TEMPLATE_TYPE_PLACE_REVIEW", dataKey: "placeReviewData" }),
+  [TEMPLATE_GENERATED]: Object.freeze({ wireType: "TEMPLATE_TYPE_GENERATED", dataKey: "generatedPageData" }),
 });
 
 export const PAGE_TEMPLATE_NAMES = Object.freeze(Object.keys(PAGE_TEMPLATES));
 
 /** Front-matter fields every template accepts. */
-export const SHARED_FRONT_MATTER_KEYS = Object.freeze(["title", "path", "description", "template"]);
+export const SHARED_FRONT_MATTER_KEYS = Object.freeze(["title", "path", "description", "template", "author"]);
 
 /**
  * The page-level fields the other templates add. A free-form page's source is
@@ -67,6 +75,8 @@ const TEMPLATE_FRONT_MATTER_KEYS = Object.freeze({
   ]),
   [TEMPLATE_ALBUM]: Object.freeze([...TYPED_PAGE_FRONT_MATTER_KEYS, "seamless", "borderWidth", "place"]),
   [TEMPLATE_PLACE_REVIEW]: Object.freeze([...TYPED_PAGE_FRONT_MATTER_KEYS, "placeId", "rating"]),
+  // Generated pages have no Markdown form.
+  [TEMPLATE_GENERATED]: Object.freeze([]),
 });
 
 export const FRONT_MATTER_KEYS = Object.freeze(
@@ -96,6 +106,52 @@ const DISPLAY_DATE = /^\d{4}-\d{2}-\d{2}$/u;
 const ALBUM_IMAGES_HEADING = "images";
 const RECIPE_HEADINGS = Object.freeze(["ingredients", "instructions"]);
 
+/** The generated page kinds the site reports, as the API names them (never the unknown kind). */
+export const GENERATED_PAGE_KINDS = Object.freeze([
+  "GENERATED_PAGE_KIND_TAG",
+  "GENERATED_PAGE_KIND_TAGS_INDEX",
+  "GENERATED_PAGE_KIND_PUBLISHED_INDEX",
+  "GENERATED_PAGE_KIND_PUBLISHED_YEAR",
+  "GENERATED_PAGE_KIND_PUBLISHED_MONTH",
+  "GENERATED_PAGE_KIND_PLACES_INDEX",
+  "GENERATED_PAGE_KIND_PLACES_COUNTRY",
+  "GENERATED_PAGE_KIND_PLACES_STATE",
+  "GENERATED_PAGE_KIND_PLACES_CITY",
+  "GENERATED_PAGE_KIND_PLACES_CATEGORY",
+  "GENERATED_PAGE_KIND_FOLDER_INDEX",
+]);
+/** What a generated page is: system-managed, so a push must send it back unchanged. */
+export const GENERATED_IDENTITY_KEYS = Object.freeze([
+  "kind",
+  "tagId",
+  "year",
+  "month",
+  "countryCode",
+  "regionCode",
+  "citySlug",
+  "categorySlug",
+]);
+const GENERATED_KEYS = [
+  ...GENERATED_IDENTITY_KEYS,
+  "customTitle",
+  "breadcrumbTitle",
+  "customDescription",
+  "introductionBody",
+];
+const GENERATED_TEXT_KEYS = [
+  "tagId",
+  "countryCode",
+  "regionCode",
+  "citySlug",
+  "categorySlug",
+  "customTitle",
+  "breadcrumbTitle",
+  "customDescription",
+];
+const GENERATED_MAXIMUM_YEAR = 9999;
+const GENERATED_MAXIMUM_MONTH = 12;
+const EMPTY_DOCUMENT = Object.freeze({ type: "doc", content: Object.freeze([]) });
+
 function fail(code, message, field) {
   return new SiteAuthoringError(code, message, { field });
 }
@@ -116,6 +172,32 @@ export function isAuthorableTemplateType(wireType) {
   return templateNameForWireType(wireType) !== undefined;
 }
 
+/** Whether a wire `templateType` is a generated page. */
+export function isGeneratedTemplateType(wireType) {
+  return wireType === PAGE_TEMPLATES[TEMPLATE_GENERATED].wireType;
+}
+
+/** The system-managed fields of a generated page's `data`, which the manifest records and a push must not change. */
+export function generatedIdentity(data) {
+  return Object.fromEntries(GENERATED_IDENTITY_KEYS.map((key) => [key, data[key]]));
+}
+
+/** The names of the identity fields that differ, for a message. */
+export function changedGeneratedIdentity(recorded, data) {
+  return GENERATED_IDENTITY_KEYS.filter((key) => recorded[key] !== data[key]);
+}
+
+/** The title a generated page is sent with: the owner's, else the one the site last reported. */
+export function generatedPageTitle(data, reportedTitle) {
+  // Trimmed as Taproot trims it, or a padded title would never match the key a pull recorded.
+  return data.customTitle.trim() || reportedTitle;
+}
+
+/** The description a generated page is sent with: the owner's, else the one the site last reported. */
+export function generatedPageDescription(data, reportedDescription) {
+  return data.customDescription.trim() === "" ? reportedDescription : data.customDescription.trim();
+}
+
 /** The template a canonical workspace document represents. */
 export function documentTemplate(document_) {
   return isPlainObject(document_) && typeof document_.template === "string" && document_.type === undefined
@@ -262,6 +344,22 @@ function canonicalIngredient(value) {
 const DATA_BUILDERS = Object.freeze({
   [TEMPLATE_ARTICLE]: (raw) => definedEntries([["body", raw.body], ["place", raw.place]]),
   [TEMPLATE_PLACE_REVIEW]: (raw) => ({ placeId: raw.placeId, rating: raw.rating, body: raw.body }),
+  // Defaults are written out, so a page with no custom title reads the same on every pull.
+  [TEMPLATE_GENERATED]: (raw) =>
+    definedEntries([
+      ["kind", raw.kind],
+      ["tagId", raw.tagId ?? ""],
+      ["year", raw.year ?? 0],
+      ["month", raw.month ?? 0],
+      ["countryCode", raw.countryCode ?? ""],
+      ["regionCode", raw.regionCode ?? ""],
+      ["citySlug", raw.citySlug ?? ""],
+      ["categorySlug", raw.categorySlug ?? ""],
+      ["customTitle", raw.customTitle ?? ""],
+      ["breadcrumbTitle", raw.breadcrumbTitle ?? ""],
+      ["customDescription", raw.customDescription ?? ""],
+      ["introductionBody", raw.introductionBody],
+    ]),
   [TEMPLATE_ALBUM]: (raw) =>
     definedEntries([
       ["introductionBody", raw.introductionBody],
@@ -339,6 +437,30 @@ function canonicalSourceData(template, data, file) {
       body: requireDocument(data.body, file, `${path}.body`, { nonEmpty: true }),
     });
   }
+  if (template === TEMPLATE_GENERATED) {
+    requireKeys(data, GENERATED_KEYS, file, path);
+    if (!GENERATED_PAGE_KINDS.includes(data.kind)) {
+      throw fail(
+        "pages.document_shape",
+        `'${file}' ${path}.kind must be one of ${GENERATED_PAGE_KINDS.join(", ")}.`,
+        file,
+      );
+    }
+    for (const key of GENERATED_TEXT_KEYS) {
+      if (data[key] !== undefined) requireString(data[key], file, `${path}.${key}`);
+    }
+    if (data.tagId !== undefined && data.tagId !== "") requireIdentifier(data.tagId, file, `${path}.tagId`);
+    if (data.year !== undefined) requireCount(data.year, file, `${path}.year`, GENERATED_MAXIMUM_YEAR);
+    if (data.month !== undefined) requireCount(data.month, file, `${path}.month`, GENERATED_MAXIMUM_MONTH);
+    // The API trims a description, so the length that counts is the trimmed one.
+    const customDescription = data.customDescription?.trim();
+    requireDescriptionLength(customDescription, `${file}:${path}.customDescription`);
+    return DATA_BUILDERS[template]({
+      ...data,
+      customDescription,
+      introductionBody: OPTIONAL_INTRODUCTION(data.introductionBody, file, `${path}.introductionBody`),
+    });
+  }
   if (template === TEMPLATE_ALBUM) {
     requireKeys(data, ALBUM_KEYS, file, path);
     const images = requireArray(data.images, file, `${path}.images`);
@@ -442,6 +564,14 @@ export function typedDocumentFromJson(parsed, file) {
       file,
     );
   }
+  if (template === TEMPLATE_GENERATED && (parsed.displayDate !== undefined || parsed.coverImageId !== undefined)) {
+    throw fail(
+      "pages.document_shape",
+      `'${file}' is a generated page, which has no displayDate or coverImageId of its own: its document is `
+        + "{ template, data }.",
+      file,
+    );
+  }
   const displayDate = parsed.displayDate === undefined ? undefined : requireDisplayDate(parsed.displayDate, file);
   let coverImageId;
   if (parsed.coverImageId !== undefined) {
@@ -482,6 +612,17 @@ const PAGE_PROJECTIONS = Object.freeze({
     if (body === undefined || rating === undefined || typeof raw.placeId !== "string") return undefined;
     return DATA_BUILDERS[TEMPLATE_PLACE_REVIEW]({ placeId: raw.placeId, rating, body });
   },
+  // A kind this package does not know cannot be pushed back safely, so it is not readable here.
+  [TEMPLATE_GENERATED]: (raw) =>
+    GENERATED_PAGE_KINDS.includes(raw.kind)
+      ? DATA_BUILDERS[TEMPLATE_GENERATED]({
+        kind: raw.kind,
+        ...Object.fromEntries(GENERATED_TEXT_KEYS.map((key) => [key, typeof raw[key] === "string" ? raw[key] : ""])),
+        year: Number.isSafeInteger(raw.year) ? raw.year : 0,
+        month: Number.isSafeInteger(raw.month) ? raw.month : 0,
+        introductionBody: presentIntroduction(raw.introductionBody),
+      })
+      : undefined,
   [TEMPLATE_ALBUM]: (raw) =>
     DATA_BUILDERS[TEMPLATE_ALBUM]({
       introductionBody: presentIntroduction(raw.introductionBody),
@@ -524,9 +665,15 @@ export function workspaceDocumentFromPage(page, listedTemplateType) {
   if (name === TEMPLATE_FREE_FORM) return isPlainObject(raw.body) ? raw.body : undefined;
   const data = PAGE_PROJECTIONS[name](raw);
   if (data === undefined) return undefined;
+  // A generated page's date and cover are not part of its source: a push leaves them as the site holds them.
+  const generated = name === TEMPLATE_GENERATED;
   return typedDocument(name, {
-    displayDate: typeof page.displayDate === "string" && page.displayDate !== "" ? page.displayDate : undefined,
-    coverImageId: typeof page.coverImageId === "string" && page.coverImageId !== "" ? page.coverImageId : undefined,
+    displayDate: !generated && typeof page.displayDate === "string" && page.displayDate !== ""
+      ? page.displayDate
+      : undefined,
+    coverImageId: !generated && typeof page.coverImageId === "string" && page.coverImageId !== ""
+      ? page.coverImageId
+      : undefined,
     data,
   });
 }
@@ -558,7 +705,7 @@ export function contentDocuments(document_) {
 /** Whether a push sends `displayDate` for pages of this wire template type (every template but free-form). */
 export function sentDisplayDate(wireType) {
   const name = templateNameForWireType(wireType);
-  return name !== undefined && name !== TEMPLATE_FREE_FORM;
+  return name !== undefined && name !== TEMPLATE_FREE_FORM && name !== TEMPLATE_GENERATED;
 }
 
 // The nodes the API accepts in an album or recipe introduction and in a recipe
@@ -742,6 +889,9 @@ export function wireTemplate(document_) {
     ? { body: document_ }
     : template === TEMPLATE_PLACE_REVIEW
     ? { ...document_.data, rating: PLACE_REVIEW_RATINGS[document_.data.rating] }
+    // The API reads a missing introduction as no document at all, so the empty one is sent.
+    : template === TEMPLATE_GENERATED
+    ? { ...document_.data, introductionBody: document_.data.introductionBody ?? EMPTY_DOCUMENT }
     : document_.data.place === undefined
     ? document_.data
     : { ...document_.data, place: { placeId: document_.data.place } };
@@ -960,6 +1110,16 @@ function parseFlag(fields, key, file) {
   return value === "true";
 }
 
+/** Generated pages are edited in their .pm.json source only. */
+export function generatedMarkdownFault(file) {
+  return fail(
+    "pages.generated_markdown",
+    `'${file}' declares the generated template, which has no Markdown form: a generated page is pulled as a `
+      + ".pm.json document and edited there.",
+    file,
+  );
+}
+
 /**
  * Front-matter fields the declared template does not accept.
  *
@@ -988,6 +1148,7 @@ export function templateFrontMatterFault(template, fieldNames, file) {
  * module stays pure.
  */
 export async function typedDocumentFromMarkdown({ template, fields, markdown, file, convert, resolveImage }) {
+  if (template === TEMPLATE_GENERATED) throw generatedMarkdownFault(file);
   const displayDate = fields.has("displayDate") ? requireDisplayDate(fields.get("displayDate"), file) : undefined;
   let coverImageId;
   if (fields.has("coverImage")) {

package/src/verbs/approve.js

@@ -1,8 +1,14 @@
-import { listSitePages, PAGE_STATUS_DELETED, publishDrafts, withRefusalGuidance } from "../api.js";
+import {
+  listSitePages,
+  PAGE_STATUS_APPROVED,
+  PAGE_STATUS_DELETED,
+  publishDrafts,
+  withRefusalGuidance,
+} from "../api.js";
 import { VERB_APPROVE } from "../constants.js";
 import { SiteAuthoringError } from "../errors.js";
-import { boundedList, openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
-import { normalizePagePath, readManifest, writeManifest } from "../workspace.js";
+import { boundedByBytes, boundedList, openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
+import { displayPagePath, normalizePagePath, readManifest, writeManifest } from "../workspace.js";
 
 /**
  * `approve` — publish the site's drafts.
@@ -19,6 +25,8 @@ import { normalizePagePath, readManifest, writeManifest } from "../workspace.js"
  */
 
 const MAXIMUM_REPORTED = 200;
+// Room for the unknown-path list inside the 64 KiB result, beside the envelope.
+const ALTERNATIVES_BYTES = 16 * 1024;
 // `PublishDrafts` resolves the credential from the first page id in the batch,
 // so batches stay one-site and bounded rather than unbounded and clever.
 const MAXIMUM_BATCH = 100;
@@ -71,31 +79,71 @@ export async function approve(invocation) {
         { field: "pages" },
       );
     }
+    const pathOf = (summary) => normalizePagePath(summary.path) ?? summary.path;
     const candidates = pages.filter((summary) =>
       summary.status !== PAGE_STATUS_DELETED
       && summary.hasDraft
       && manifestByPageId.has(summary.pageId)
-      && (requestedPaths === undefined || requestedPaths.has(normalizePagePath(summary.path) ?? summary.path)));
+      && (requestedPaths === undefined || requestedPaths.has(pathOf(summary))));
 
+    // A requested page with nothing to approve is reported, not refused, so
+    // one already-approved path does not stop the rest of the batch. A path
+    // that names no page this workspace tracks is still refused by name.
+    const skipped = [];
     if (requestedPaths !== undefined) {
-      const matched = new Set(candidates.map((summary) => normalizePagePath(summary.path) ?? summary.path));
-      const missing = [...requestedPaths].filter((value) => !matched.has(value)).sort();
-      if (missing.length > 0) {
-        // The homepage normalizes to the empty path, which the result
-        // emitters drop as falsy; name it by its documented '/' spelling so
-        // the stable error contract keeps a field for every unknown path.
+      const matched = new Set(candidates.map(pathOf));
+      const unknown = [];
+      for (const requested of [...requestedPaths].filter((value) => !matched.has(value)).sort()) {
+        const summary = pages.find((page) => page.status !== PAGE_STATUS_DELETED && pathOf(page) === requested);
+        if (summary === undefined || !manifestByPageId.has(summary.pageId)) {
+          unknown.push(displayPagePath(requested));
+          continue;
+        }
+        skipped.push({
+          pageId: summary.pageId,
+          path: displayPagePath(requested),
+          status: summary.status,
+          reason: summary.status === PAGE_STATUS_APPROVED ? "already_approved" : "no_pending_draft",
+        });
+      }
+      if (unknown.length > 0) {
+        // Every path is named on progress, since the message and the
+        // alternatives list are both bounded.
+        for (const value of unknown) onProgress(`No page this workspace tracks is at '${value}'.`);
+        const shown = unknown.slice(0, 5).map((value) => `'${value}'`).join(", ");
+        const listed = boundedByBytes(unknown.slice(0, 100), ALTERNATIVES_BYTES).items;
         throw new SiteAuthoringError(
           "approve.page_not_found",
-          `No approvable draft was found for page path '${missing[0] || "/"}'.`,
-          { field: missing[0] || "/" },
+          `${unknown.length} requested path(s) name no page this workspace tracks. The first ${listed.length} are `
+            + "in alternatives and every one is on progress output. Nothing was approved. Run 'taproot-site pull' if "
+            + `a page was created elsewhere. ${shown}${unknown.length > 5 ? ", …" : ""}`,
+          { field: unknown[0], alternatives: listed },
         );
       }
+      for (const item of skipped) {
+        onProgress(`${item.path} has no pending draft (${item.reason.replaceAll("_", " ")}); skipping it.`);
+      }
     }
+    const reportedSkipped = boundedList(skipped, MAXIMUM_REPORTED);
+    const skippedResult = skipped.length > 0
+      ? {
+        skipped: {
+          total: skipped.length,
+          items: reportedSkipped.items,
+          ...(reportedSkipped.truncated ? { itemsTruncated: true } : {}),
+        },
+      }
+      : {};
 
     if (candidates.length === 0) {
-      onProgress("No page in this workspace is carrying a draft; there is nothing to approve.");
+      onProgress(
+        skipped.length > 0
+          ? "Nothing to approve: the requested page(s) have no pending draft."
+          : "No page in this workspace is carrying a draft; there is nothing to approve.",
+      );
       return successResult(VERB_APPROVE, siteId, {
         approved: { total: 0, items: [] },
+        ...skippedResult,
         stagedNotDeployed: true,
         nextStep: "deploy --staging",
       });
@@ -110,7 +158,7 @@ export async function approve(invocation) {
         const summaries = await publishDrafts(client, batch.map((summary) => summary.pageId));
         manifestDirty = true;
         for (const summary of summaries) {
-          approved.push({ pageId: summary.pageId, path: summary.path, status: summary.status });
+          approved.push({ pageId: summary.pageId, path: displayPagePath(summary.path), status: summary.status });
           const entry = manifestByPageId.get(summary.pageId);
           if (entry !== undefined) {
             entry.status = summary.status;
@@ -131,6 +179,7 @@ export async function approve(invocation) {
         items: reported.items,
         ...(reported.truncated ? { itemsTruncated: true } : {}),
       },
+      ...skippedResult,
       // Said explicitly so a caller cannot read "approve" as "live".
       stagedNotDeployed: true,
       nextStep: "deploy --staging",