@taprootio/site-authoring 0.14.1 → 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,5 +1,8 @@
 import {
+  VERB_APPLY,
   VERB_APPROVE,
+  VERB_AUTHORS_ADD,
+  VERB_AUTHORS_LIST,
   VERB_DELIVERY_CHECK,
   VERB_DEPLOY,
   VERB_ENV,
@@ -11,7 +14,11 @@ import {
   VERB_LOGOUT,
   VERB_MEDIA_UPLOAD,
   VERB_NAV_PUSH,
+  VERB_PAGES_META_SET,
   VERB_PAGES_PUSH,
+  VERB_PLACES_SEARCH,
+  VERB_PLACES_SELECT,
+  VERB_PLAN,
   VERB_PREVIEW_PAGE,
   VERB_PREVIEW_REVOKE,
   VERB_PULL,
@@ -27,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";
@@ -38,7 +46,10 @@ 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";
 import { previewPage } from "./preview-page.js";
 import { previewRevoke } from "./preview-revoke.js";
 import { pull } from "./pull.js";
@@ -70,6 +81,7 @@ import { whoami } from "./whoami.js";
  *   deployTarget,  // "staging" | "production" for `deploy`, else undefined
  *   quiet,         // --quiet; suppresses progress, never the JSON result
  *   keyName,       // --name; `login` only, undefined everywhere else
+ *   planHash,      // --plan; `apply` only: the plan it may run
  *   onProgress,    // human progress sink (stderr, or a no-op when quiet)
  *   fetch,         // injectable fetch, for tests
  *   signal,        // optional AbortSignal
@@ -92,8 +104,11 @@ import { whoami } from "./whoami.js";
  *                  //   with none, the workspace's media/ directory is walked
  *   formKeys,      // forms validate / push: narrow to these form keys;
  *                  //   with none, every file under forms/
+ *   placeQuery,    // places search: the words of the query
+ *   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]
  * }
@@ -126,7 +141,14 @@ 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_APPLY]: apply,
   [VERB_REDIRECTS_CHECK]: redirectsCheck,
   [VERB_REDIRECTS_PULL]: redirectsPull,
   [VERB_REDIRECTS_PUSH]: redirectsPush,

package/src/verbs/media-upload.js

@@ -17,10 +17,11 @@ import {
 import { LIMITS, VERB_MEDIA_UPLOAD } from "../constants.js";
 import { SiteAuthoringError, sanitizeDiagnostic } from "../errors.js";
 import { contentHash, inspectImageBytes } from "../image-metadata.js";
+import { CHECK_AREA, collectProblems, problemsOf } from "../problems.js";
 import { ApiError } from "../transport.js";
 import { sniffVideoContentType, VIDEO_EXTENSIONS, videoTooLarge } from "../video-metadata.js";
-import { mp4Name, prepareVideoFile } from "../video-prepare.js";
-import { boundedList, openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
+import { mp4Name, prepareVideoFile, videoAcceptance } from "../video-prepare.js";
+import { boundedByBytes, openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
 import {
   ensureWorkspaceRoot,
   inspectWorkspaceEntry,
@@ -30,6 +31,7 @@ import {
   openWorkspaceFileStream,
   readMediaManifest,
   readWorkspaceFile,
+  recordedAlt,
   resolveWorkspacePath,
   SAFE_MEDIA_SEGMENT,
   walkWorkspaceFiles,
@@ -72,7 +74,8 @@ import {
  * it for evidence of a pull that never happened.
  */
 
-const MAXIMUM_REPORTED = 200;
+// Each list's share of the result's 64 KiB; the counts are always complete.
+const ITEMS_BYTES = 24 * 1024;
 const MAXIMUM_FILES = 500;
 const MEDIA_EXTENSIONS = [".png", ".jpg", ".jpeg", ".gif", ".webp", ...VIDEO_EXTENSIONS];
 const MEDIA_WALK_OPTIONS = Object.freeze({
@@ -80,6 +83,118 @@ const MEDIA_WALK_OPTIONS = Object.freeze({
   segmentDescription: "letters, digits, '.', '_', '-', and '@'",
 });
 
+/**
+ * The files under `media/` an upload would still send (TR00823): an image
+ * whose bytes the media manifest does not record, and a video with no
+ * confirmed upload. Each is classified and checked against the limits the
+ * upload applies, so a plan does not call ready a file the upload would
+ * refuse, and carries an identity of its content, so a plan made before the
+ * file was replaced does not describe it. A recorded upload is done only when
+ * the site still holds it: an image processed (one still processing, or gone,
+ * is sent again; the upload deduplicates and waits; one that failed is a
+ * problem), a video in its library. `site` answers both:
+ * `imageStates` maps the recorded image ids to what the site holds, and
+ * `videos` is the video library as `listVideos` reads it. Read only.
+ */
+export async function pendingMediaFiles(workspaceDir, mediaManifest, site) {
+  const files = await walkWorkspaceFiles(workspaceDir, MEDIA_DIRECTORY, MEDIA_EXTENSIONS, MEDIA_WALK_OPTIONS);
+  const pending = [];
+  const problems = [];
+  const listedVideoIds = new Set(site.videos.videos.map((candidate) => candidate.videoId));
+  for (const file of files) {
+    const video = mediaManifest.videos?.[file];
+    const image = mediaManifest.media?.[file];
+    const entry = await collectProblems(problems, { area: CHECK_AREA.media, file }, async () => {
+      if (typeof image?.imageId === "string") {
+        const bytes = await readWorkspaceFile(workspaceDir, file, WORKSPACE_LIMITS.mediaBytes);
+        if (image.contentHash === contentHash(bytes)) {
+          const held = site.imageStates.get(image.imageId);
+          if (held === IMAGE_PROCESSING_STATE_FAILED) {
+            throw new SiteAuthoringError(
+              "media.processing_failed",
+              `Taproot failed to process '${file}' (image ${image.imageId}), so it cannot be published. Replace the `
+                + "file with one that processes, or remove it and the references to it.",
+              { field: file, status: IMAGE_PROCESSING_STATE_FAILED },
+            );
+          }
+          if (held === IMAGE_PROCESSING_STATE_COMPLETE) return undefined;
+        }
+      }
+      const { source, identity, bytes } = await mediaFileIdentity(workspaceDir, file);
+      // One that still matches its confirmed video upload is done.
+      if (
+        typeof video?.videoId === "string"
+        && video.pendingConfirm !== true
+        && video.byteLength === source.byteLength
+        && video.modifiedMilliseconds === source.modifiedMilliseconds
+      ) {
+        if (listedVideoIds.has(video.videoId)) return undefined;
+        // The same refusal the upload gives: a listing cut short cannot say the video is gone.
+        if (site.videos.truncated) throw videoLibraryUnverifiable(file, video.videoId, site.videos.videos.length);
+      }
+      if (sniffVideoContentType(source.header) !== undefined) {
+        if (source.byteLength > WORKSPACE_LIMITS.videoBytes) throw videoTooLarge(file, WORKSPACE_LIMITS.videoBytes);
+        const acceptance = await videoAcceptance({
+          filePath: resolveWorkspacePath(workspaceDir, file),
+          byteLength: source.byteLength,
+        });
+        if (!acceptance.accepted) {
+          throw new SiteAuthoringError(
+            "media.video_unsupported",
+            acceptance.videoCodec === "" && acceptance.audioCodec === ""
+              ? `'${file}' could not be read as a video, so the upload would be refused.`
+              : `'${file}' is ${acceptance.videoCodec ? `${acceptance.videoCodec} video` : "no video"} with `
+                + `${acceptance.audioCodec ? `${acceptance.audioCodec} audio` : "no audio"}. `
+                + "Taproot accepts H.264 video with AAC audio or none: export it that way and upload it again.",
+            { field: file },
+          );
+        }
+        return { file, kind: "video", identity };
+      }
+      const { width, height } = inspectImageBytes(bytes, file);
+      return { file, kind: "image", identity, width, height };
+    });
+    if (entry !== undefined) pending.push(entry);
+  }
+  if (pending.length > MAXIMUM_FILES) {
+    problems.push(...problemsOf(tooManyFiles(pending.length), { area: CHECK_AREA.media }));
+  }
+  return { files: pending, problems };
+}
+
+/**
+ * What a media file is, for telling a plan's file from a replaced one: a
+ * video by its size and modification time, as the upload records it; anything
+ * else by its bytes, which are returned too.
+ */
+async function mediaFileIdentity(workspaceDir, file) {
+  const source = await openWorkspaceFileStream(workspaceDir, file, Number.MAX_SAFE_INTEGER);
+  await source.close();
+  if (sniffVideoContentType(source.header) !== undefined) {
+    return { source, identity: `${source.byteLength}:${source.modifiedMilliseconds}` };
+  }
+  const bytes = await readWorkspaceFile(workspaceDir, file, WORKSPACE_LIMITS.mediaBytes);
+  return { source, identity: contentHash(bytes), bytes };
+}
+
+function videoLibraryUnverifiable(file, videoId, listed) {
+  return new SiteAuthoringError(
+    "media.video_library_unverifiable",
+    `'${file}' was uploaded as video ${videoId}, which is not among the first ${listed} videos of this `
+      + "site's library, and the library is larger than one run can check. Remove the file's entry from "
+      + `${MEDIA_MANIFEST_FILE_NAME} to upload it again, or leave it.`,
+    { field: file },
+  );
+}
+
+function tooManyFiles(count) {
+  return new SiteAuthoringError(
+    "media.too_many_files",
+    `This run would upload ${count} files, more than the bounded maximum of ${MAXIMUM_FILES}.`,
+    { field: MEDIA_DIRECTORY },
+  );
+}
+
 function requireUploadCapability(response, fileName) {
   if (
     typeof response.presignedUrl !== "string"
@@ -339,13 +454,7 @@ async function uploadVideoFile({
         // A listing cut short cannot say the video is gone, and uploading again
         // would spend storage on a video that may well be there.
         if (truncated) {
-          throw new SiteAuthoringError(
-            "media.video_library_unverifiable",
-            `'${file}' was uploaded as video ${recorded.videoId}, which is not among the first ${byId.size} videos of this `
-              + "site's library, and the library is larger than one run can check. Remove the file's entry from "
-              + `${MEDIA_MANIFEST_FILE_NAME} to upload it again, or leave it.`,
-            { field: file },
-          );
+          throw videoLibraryUnverifiable(file, recorded.videoId, byId.size);
         }
       }
     }
@@ -441,13 +550,7 @@ export async function mediaUpload(invocation) {
       { field: selected.length > 0 ? normalizePositional(selected[0]) : MEDIA_DIRECTORY },
     );
   }
-  if (files.length > MAXIMUM_FILES) {
-    throw new SiteAuthoringError(
-      "media.too_many_files",
-      `This run would upload ${files.length} files, more than the bounded maximum of ${MAXIMUM_FILES}.`,
-      { field: MEDIA_DIRECTORY },
-    );
-  }
+  if (files.length > MAXIMUM_FILES) throw tooManyFiles(files.length);
 
   const uploaded = [];
   const uploadedVideos = [];
@@ -553,7 +656,7 @@ export async function mediaUpload(invocation) {
           // Preserve the author-owned alt text. Delivery fields start with
           // whatever confirm returned and are refreshed from the completed
           // library record below.
-          alt: typeof mediaManifest.media[file]?.alt === "string" ? mediaManifest.media[file].alt : "",
+          alt: recordedAlt(mediaManifest.media[file]),
           src: image.url,
           urls: image.responsiveUrls,
           deduplicated,
@@ -599,7 +702,9 @@ export async function mediaUpload(invocation) {
       manifestEntry.urls = image.responsiveUrls;
     }
     await writeMediaManifest(config.workspaceDir, mediaManifest);
-    const reported = boundedList(
+    // The delivery URLs stay in the media manifest: a signed URL list per
+    // file is what pushed a bulk upload past the result's 64 KiB (TR01001).
+    const reported = boundedByBytes(
       uploaded.map((entry) => ({
         file: entry.file,
         imageId: entry.imageId,
@@ -607,18 +712,10 @@ export async function mediaUpload(invocation) {
         width: entry.width,
         height: entry.height,
         processingState: observed.get(entry.imageId)?.processingState ?? IMAGE_PROCESSING_STATE_COMPLETE,
-        media: {
-          imageId: entry.imageId,
-          src: observed.get(entry.imageId)?.url ?? "",
-          urls: observed.get(entry.imageId)?.responsiveUrls ?? [],
-          width: entry.width,
-          height: entry.height,
-          alt: mediaManifest.media[entry.file]?.alt ?? "",
-        },
       })),
-      MAXIMUM_REPORTED,
+      ITEMS_BYTES,
     );
-    const reportedVideos = boundedList(
+    const reportedVideos = boundedByBytes(
       uploadedVideos.map((entry) => ({
         file: entry.file,
         videoId: entry.videoId,
@@ -635,7 +732,7 @@ export async function mediaUpload(invocation) {
         // block for `.pm.json` sources.
         component: videoComponent(entry.videoId),
       })),
-      MAXIMUM_REPORTED,
+      ITEMS_BYTES,
     );
     return successResult(VERB_MEDIA_UPLOAD, siteId, {
       mediaManifestFile: MEDIA_MANIFEST_FILE_NAME,

package/src/verbs/nav-push.js

@@ -15,6 +15,8 @@ import {
   isContactOrWebUrl,
 } from "../contact-url.js";
 import { SiteAuthoringError } from "../errors.js";
+import { stableJson } from "../footer-draft-hash.js";
+import { planStale } from "../problems.js";
 import { boundedList, openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
 import {
   NAVIGATION_FILE_NAME,
@@ -304,6 +306,11 @@ export async function navPush(invocation) {
     // small as the contract allows.
     onProgress("Re-reading the live navigation tree immediately before replacing it.");
     const liveItems = await getNavigation(client, siteId);
+    // Under apply, the tree replaced must be the one its plan read: a change
+    // made since was never reviewed, and this write would erase it.
+    if (invocation.plannedLiveNavigation !== undefined && stableJson(liveItems) !== invocation.plannedLiveNavigation) {
+      throw planStale("The site's navigation", NAVIGATION_FILE_NAME);
+    }
     const liveIds = collectIds(liveItems);
     const pushedIds = collectIds(navItems);
     const removed = [...liveIds].filter((id) => !pushedIds.has(id)).sort();