@taprootio/site-authoring 0.15.0 → 0.16.0

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",

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

@@ -22,7 +22,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";
 
@@ -162,31 +162,6 @@ function reportReadiness(readiness) {
   };
 }
 
-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.";
 
@@ -428,7 +403,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 +416,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,6 +14,7 @@ import {
   VERB_LOGOUT,
   VERB_MEDIA_UPLOAD,
   VERB_NAV_PUSH,
+  VERB_PAGES_META_SET,
   VERB_PAGES_PUSH,
   VERB_PLACES_SEARCH,
   VERB_PLACES_SELECT,
@@ -31,6 +34,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,6 +46,7 @@ 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 { apply, plan } from "./plan.js";
@@ -103,6 +108,7 @@ import { whoami } from "./whoami.js";
  *   placeSelection, // places select: [googlePlaceId, sessionToken]
  *   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,6 +141,9 @@ 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,