@taprootio/site-authoring 0.1.0

package/src/verbs/media-upload.js

@@ -0,0 +1,319 @@
+import {
+  confirmImageUpload,
+  IMAGE_OWNERSHIP_SCOPE_SITE,
+  IMAGE_PROCESSING_STATE_COMPLETE,
+  IMAGE_PROCESSING_STATE_FAILED,
+  listSiteImages,
+  normalizeImage,
+  poll,
+  requestImageUpload,
+  withRefusalGuidance,
+} from "../api.js";
+import { LIMITS, VERB_MEDIA_UPLOAD } from "../constants.js";
+import { SiteAuthoringError } from "../errors.js";
+import { contentHash, inspectImageBytes } from "../image-metadata.js";
+import { boundedList, openSession, successResult } from "../session.js";
+import {
+  ensureWorkspaceRoot,
+  inspectWorkspaceEntry,
+  MEDIA_DIRECTORY,
+  MEDIA_MANIFEST_FILE_NAME,
+  MEDIA_MANIFEST_VERSION,
+  readMediaManifest,
+  readWorkspaceFile,
+  SAFE_MEDIA_SEGMENT,
+  walkWorkspaceFiles,
+  WORKSPACE_LIMITS,
+  writeMediaManifest,
+} from "../workspace.js";
+
+/**
+ * `media upload` — hash, request, PUT, confirm, then wait for processing.
+ *
+ * The client computes the SHA-256 and the pixel dimensions before it asks for
+ * anything, because `RequestImageUpload` needs all three: the hash drives the
+ * dedup short-circuit, and the dimensions are recorded with the image. When the
+ * response reports `isDuplicate`, the presigned PUT and the confirm are both
+ * skipped and the returned image is used as-is — re-uploading identical bytes
+ * would spend the site's storage budget to produce the row it already has.
+ *
+ * Otherwise the signed capability goes to `SiteApiClient.upload`, which echoes
+ * `requiredHeaders` verbatim: those values are covered by the signature, so a
+ * regenerated `Content-Type` turns into an opaque object-store 403.
+ *
+ * Processing is observed through `ListSiteImages`; `GetImageById` is
+ * session-only under TR00602's read list.
+ *
+ * What gets uploaded comes from the positional arguments — files, directories,
+ * or both — and from the workspace's `media/` directory when none are given.
+ *
+ * The workspace media manifest this writes is what `pages push` resolves image
+ * references against, and it is deliberately a separate file from the pull
+ * manifest: uploading media into a workspace that was never pulled is
+ * legitimate, and minting a pull manifest here would let `pages push` mistake
+ * it for evidence of a pull that never happened.
+ */
+
+const MAXIMUM_REPORTED = 200;
+const MAXIMUM_FILES = 500;
+const MEDIA_EXTENSIONS = [".png", ".jpg", ".jpeg", ".gif", ".webp"];
+const MEDIA_WALK_OPTIONS = Object.freeze({
+  segmentPattern: SAFE_MEDIA_SEGMENT,
+  segmentDescription: "letters, digits, '.', '_', '-', and '@'",
+});
+
+function requireUploadCapability(response, fileName) {
+  if (
+    typeof response.presignedUrl !== "string"
+    || response.presignedUrl === ""
+    || typeof response.uploadId !== "string"
+    || response.uploadId === ""
+  ) {
+    throw new SiteAuthoringError(
+      "media.upload_capability_invalid",
+      `Taproot did not return a usable upload capability for '${fileName}'.`,
+      { field: fileName },
+    );
+  }
+  return { url: response.presignedUrl, requiredHeaders: response.requiredHeaders };
+}
+
+function fileNameOf(relativePath) {
+  return relativePath.slice(relativePath.lastIndexOf("/") + 1);
+}
+
+/**
+ * Normalizes one positional into the workspace-relative form the workspace
+ * helpers accept: `./media/hero.png` and `media/` and `media` all name the same
+ * thing to a person typing them, and none of the three should be a different
+ * outcome.
+ */
+function normalizePositional(value) {
+  return typeof value === "string" ? value.replace(/^\.\//u, "").replace(/\/+$/u, "") : "";
+}
+
+/**
+ * Expands the positional arguments into the concrete files to upload. A
+ * directory is walked for media the way a bare invocation walks `media/`; a
+ * regular file is taken as named, and its container is validated from its bytes
+ * rather than its extension. Anything else — a missing path, a symlink, a
+ * device — is refused by name rather than surfacing later as an unrelated
+ * "not a regular file" from the read.
+ */
+async function resolveUploadTargets(workspaceDir, positionals) {
+  const files = [];
+  const seen = new Set();
+  for (const positional of positionals) {
+    const candidate = normalizePositional(positional);
+    if (candidate === "") {
+      throw new SiteAuthoringError(
+        "media.path_invalid",
+        `'${positional}' does not name a file or directory relative to the workspace root.`,
+        { field: positional },
+      );
+    }
+    const kind = await inspectWorkspaceEntry(workspaceDir, candidate);
+    if (kind === "missing" || kind === "other") {
+      throw new SiteAuthoringError(
+        "media.path_invalid",
+        `'${candidate}' is neither a media file nor a directory relative to the workspace root.`,
+        { field: candidate },
+      );
+    }
+    const expanded = kind === "directory"
+      ? await walkWorkspaceFiles(workspaceDir, candidate, MEDIA_EXTENSIONS, MEDIA_WALK_OPTIONS)
+      : [candidate];
+    for (const file of expanded) {
+      // Overlapping positionals — a directory and a file inside it — upload
+      // each file once.
+      if (seen.has(file)) continue;
+      seen.add(file);
+      files.push(file);
+    }
+  }
+  return files;
+}
+
+async function waitForProcessing(client, siteId, imageIds, { onProgress, now }) {
+  const pending = new Set(imageIds);
+  if (pending.size === 0) return new Map();
+  const observed = new Map();
+  return await poll({
+    client,
+    now,
+    onProgress,
+    timeoutMilliseconds: LIMITS.uploadMilliseconds,
+    // The poller's `{ deadline, now }` travels into every page of the listing,
+    // so the bound holds *within* one read of a large library and not only
+    // between reads.
+    read: async (requestOptions) => (await listSiteImages(client, siteId, requestOptions)).images,
+    evaluate: (images) => {
+      for (const image of images) {
+        if (!pending.has(image.imageId)) continue;
+        observed.set(image.imageId, image);
+      }
+      const waiting = [...pending].filter((imageId) => {
+        const state = observed.get(imageId)?.processingState;
+        return state !== IMAGE_PROCESSING_STATE_COMPLETE && state !== IMAGE_PROCESSING_STATE_FAILED;
+      });
+      if (waiting.length === 0) return { done: true, value: observed };
+      return { done: false, progress: `Waiting for ${waiting.length} image(s) to finish processing.` };
+    },
+    timeoutCode: "media.processing_timeout",
+  });
+}
+
+export async function mediaUpload(invocation) {
+  const { client, config, siteId, now, onProgress } = await openSession(invocation);
+  await ensureWorkspaceRoot(config);
+
+  // Positional arguments name the files or directories to upload — `cli.js`
+  // hands them over as `paths`, and a programmatic caller can supply the same
+  // key directly. With none, the workspace's own `media/` directory is walked.
+  // Read before anything is selected or sent: a media manifest from another
+  // site holds image ids this site cannot deliver, and appending to it would
+  // mix two sites' media in one file.
+  const mediaManifest = await readMediaManifest(config.workspaceDir, siteId);
+
+  const selected = Array.isArray(invocation.paths) ? invocation.paths.filter((value) => value !== "") : [];
+  const files = selected.length > 0
+    ? await resolveUploadTargets(config.workspaceDir, selected)
+    : await walkWorkspaceFiles(config.workspaceDir, MEDIA_DIRECTORY, MEDIA_EXTENSIONS, MEDIA_WALK_OPTIONS);
+  if (files.length === 0) {
+    throw new SiteAuthoringError(
+      "media.none_found",
+      selected.length > 0
+        ? `No PNG, JPEG, GIF, or WebP files were found under ${selected.map((value) => `'${value}'`).join(", ")}.`
+        : `No PNG, JPEG, GIF, or WebP files were found under '${MEDIA_DIRECTORY}/' in the workspace.`,
+      { 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 },
+    );
+  }
+
+  const uploaded = [];
+
+  return await withRefusalGuidance(onProgress, "upload", async () => {
+    try {
+      for (const file of files) {
+        const fileName = fileNameOf(file);
+        const bytes = await readWorkspaceFile(config.workspaceDir, file, WORKSPACE_LIMITS.mediaBytes);
+        const { contentType, width, height } = inspectImageBytes(bytes, file);
+        const hash = contentHash(bytes);
+        onProgress(`Requesting an upload for '${file}' (${contentType}, ${width}x${height}).`);
+        const response = await requestImageUpload(client, {
+          fileName,
+          contentType,
+          fileSize: bytes.byteLength,
+          contentHash: hash,
+          width,
+          height,
+          ownershipScope: IMAGE_OWNERSHIP_SCOPE_SITE,
+          siteId,
+        });
+
+        let image;
+        let deduplicated = false;
+        if (response.isDuplicate === true) {
+          // The dedup hit *is* the existing image. There is nothing to PUT and
+          // nothing to confirm.
+          deduplicated = true;
+          image = normalizeImage(response.image);
+          onProgress(`'${file}' matched an existing image by content hash; skipping the upload.`);
+        } else {
+          await client.upload(requireUploadCapability(response, file), bytes);
+          const confirmation = await confirmImageUpload(client, response.uploadId);
+          image = normalizeImage(confirmation.image);
+          onProgress(`Uploaded and confirmed '${file}'.`);
+        }
+
+        mediaManifest.media[file] = {
+          imageId: image.imageId,
+          contentHash: hash,
+          contentType,
+          width: width || image.width,
+          height: height || image.height,
+          byteLength: bytes.byteLength,
+          // 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 : "",
+          src: image.url,
+          urls: image.responsiveUrls,
+          deduplicated,
+        };
+        uploaded.push({ file, imageId: image.imageId, deduplicated, contentType, width, height });
+      }
+    } finally {
+      // Written before processing is awaited: an image that fails to process
+      // still exists, and losing its id would orphan it. The site is recorded
+      // with it, because an image id means nothing without one.
+      mediaManifest.mediaManifestVersion = MEDIA_MANIFEST_VERSION;
+      mediaManifest.siteId = siteId;
+      if (uploaded.length > 0) await writeMediaManifest(config.workspaceDir, mediaManifest);
+    }
+
+    onProgress("Waiting for image processing to finish.");
+    const observed = await waitForProcessing(client, siteId, uploaded.map((entry) => entry.imageId), {
+      onProgress,
+      now,
+    });
+    const failed = uploaded
+      .map((entry) => ({ ...entry, processingState: observed.get(entry.imageId)?.processingState }))
+      .filter((entry) => entry.processingState === IMAGE_PROCESSING_STATE_FAILED);
+    if (failed.length > 0) {
+      throw new SiteAuthoringError(
+        "media.processing_failed",
+        `Taproot failed to process ${failed.length} uploaded image(s), starting with '${failed[0].file}'. `
+          + `They are recorded in ${MEDIA_MANIFEST_FILE_NAME} but cannot be published.`,
+        { field: failed[0].file, status: IMAGE_PROCESSING_STATE_FAILED },
+      );
+    }
+
+    // Processing is the point at which the delivery contract is complete.
+    // Persist and report the exact object shape component media fields accept,
+    // so an author never has to invent empty `src`/`urls` placeholders.
+    for (const entry of uploaded) {
+      const image = observed.get(entry.imageId);
+      const manifestEntry = mediaManifest.media[entry.file];
+      if (image === undefined || manifestEntry === undefined) continue;
+      manifestEntry.src = image.url;
+      manifestEntry.urls = image.responsiveUrls;
+    }
+    await writeMediaManifest(config.workspaceDir, mediaManifest);
+
+    const reported = boundedList(
+      uploaded.map((entry) => ({
+        file: entry.file,
+        imageId: entry.imageId,
+        deduplicated: entry.deduplicated,
+        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,
+    );
+    return successResult(VERB_MEDIA_UPLOAD, siteId, {
+      mediaManifestFile: MEDIA_MANIFEST_FILE_NAME,
+      media: {
+        total: uploaded.length,
+        deduplicated: uploaded.filter((entry) => entry.deduplicated).length,
+        items: reported.items,
+        ...(reported.truncated ? { itemsTruncated: true } : {}),
+      },
+    });
+  });
+}

package/src/verbs/nav-push.js

@@ -0,0 +1,333 @@
+import {
+  getNavigation,
+  listSitePages,
+  NAV_ITEM_KIND_EXTERNAL_URL,
+  NAV_ITEM_KIND_PAGE,
+  NAV_ITEM_KINDS,
+  NAVIGATION_MAXIMUM_DEPTH,
+  saveNavigation,
+  withRefusalGuidance,
+} from "../api.js";
+import { VERB_NAV_PUSH } from "../constants.js";
+import { SiteAuthoringError } from "../errors.js";
+import { boundedList, openSession, successResult } from "../session.js";
+import {
+  NAVIGATION_FILE_NAME,
+  readWorkspaceJson,
+  workspaceFileExists,
+  WORKSPACE_LIMITS,
+} from "../workspace.js";
+
+/**
+ * `nav push` — replace the whole navigation tree.
+ *
+ * `SaveSiteNavigation` is a whole-tree PUT with no concurrency token, so it is
+ * last-write-wins against a browser session editing the same tree. Two things
+ * follow, and the body does both:
+ *
+ * 1. The tree is re-read immediately before the write, so the window in which
+ *    someone else's edit can be lost is as small as the contract allows, and
+ *    what the replace is about to remove is *named* rather than discovered
+ *    afterwards.
+ * 2. Local validation is exhaustive and refuses by item path. The server stores
+ *    what it is given; a `PAGE` item carrying `pageId` instead of `resourceId`,
+ *    or a fourth level of nesting, is accepted and then renders wrong. And the
+ *    one shape it does check — `id` and `resourceId` are parsed as GUIDs — it
+ *    refuses with a bare `InvalidArgument` naming no field at all, so a single
+ *    `id: "home"` in a hundred-item tree would come back as an unclassified 400
+ *    with nothing to grep for. A `resourceId` that is a valid UUID pointing at
+ *    no page is the same story with a bare `ResourceId`, so PAGE targets are
+ *    checked against the live page list too. Naming `navItems[1].children[0]`
+ *    is the difference between a fixable error and a hunt.
+ */
+
+const MAXIMUM_REPORTED = 100;
+const MAXIMUM_ITEMS = 1_000;
+const MAXIMUM_TITLE_LENGTH = 200;
+const MAXIMUM_URL_LENGTH = 2_048;
+const ITEM_KEYS = new Set(["id", "kind", "title", "resourceId", "externalUrl", "children"]);
+
+// `SaveSiteNavigation` maps both `id` and `resourceId` through
+// `RequestValidation.RequireGuid`. A value that is not a GUID comes back as a
+// bare `InvalidArgument` carrying no field violation at all — an unclassified
+// 400 with nothing to say which of a hundred items was wrong. This verb's whole
+// contract is that a malformed tree is named locally, by item path, so the
+// shape is checked here rather than discovered there.
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+
+function navError(code, message, itemPath) {
+  return new SiteAuthoringError(code, `${itemPath}: ${message}`, { field: itemPath });
+}
+
+function isBoundedText(value, maximum) {
+  return typeof value === "string" && value.length > 0 && value.length <= maximum;
+}
+
+function isUuid(value) {
+  return typeof value === "string" && UUID.test(value);
+}
+
+function isEmpty(value) {
+  return value === undefined || value === null || value === "";
+}
+
+function validateItem(item, itemPath, depth, seenIds, counters) {
+  if (item === null || typeof item !== "object" || Array.isArray(item)) {
+    throw navError("nav.item_invalid", "a navigation item must be an object.", itemPath);
+  }
+  if (depth > NAVIGATION_MAXIMUM_DEPTH) {
+    throw navError(
+      "nav.depth_exceeded",
+      `navigation nests deeper than ${NAVIGATION_MAXIMUM_DEPTH} levels.`,
+      itemPath,
+    );
+  }
+  counters.items += 1;
+  if (counters.items > MAXIMUM_ITEMS) {
+    throw navError("nav.too_many_items", `the navigation tree holds more than ${MAXIMUM_ITEMS} items.`, itemPath);
+  }
+
+  const unknown = Object.keys(item).filter((key) => !ITEM_KEYS.has(key)).sort();
+  if (unknown.length > 0) {
+    // `pageId` is the specific mistake this catches: the navigation contract
+    // targets a page by its *site resource* id, and a `pageId` key is stored
+    // and then silently ignored.
+    throw navError(
+      "nav.unknown_field",
+      unknown.includes("pageId")
+        ? "a PAGE item targets 'resourceId', never 'pageId'."
+        : `unsupported navigation field '${unknown[0]}'.`,
+      itemPath,
+    );
+  }
+  if (!isUuid(item.id)) {
+    throw navError(
+      "nav.id_invalid",
+      "every navigation item needs a stable 'id' that is a canonical lowercase UUID; Taproot parses it as one.",
+      itemPath,
+    );
+  }
+  if (seenIds.has(item.id)) {
+    throw navError("nav.id_duplicate", `navigation id '${item.id}' appears more than once in the tree.`, itemPath);
+  }
+  seenIds.add(item.id);
+  if (typeof item.kind !== "string" || !NAV_ITEM_KINDS.includes(item.kind)) {
+    throw navError(
+      "nav.kind_invalid",
+      `'kind' must be one of ${NAV_ITEM_KINDS.join(", ")}.`,
+      itemPath,
+    );
+  }
+  if (!isBoundedText(item.title, MAXIMUM_TITLE_LENGTH)) {
+    throw navError("nav.title_invalid", "every navigation item needs a non-empty 'title'.", itemPath);
+  }
+
+  if (item.kind === NAV_ITEM_KIND_PAGE) {
+    if (!isUuid(item.resourceId)) {
+      throw navError(
+        "nav.resource_missing",
+        "a PAGE item needs the target page's 'resourceId' — the canonical lowercase UUID 'pull' records in the "
+          + "manifest, not the page path or pageId.",
+        itemPath,
+      );
+    }
+    if (!isEmpty(item.externalUrl)) {
+      throw navError("nav.external_url_unexpected", "a PAGE item must not carry 'externalUrl'.", itemPath);
+    }
+    // Kept with its item path so the liveness check below can still name the
+    // item; by then the tree has been rebuilt and the paths are gone.
+    counters.pageReferences.push({ itemPath, resourceId: item.resourceId });
+  } else if (item.kind === NAV_ITEM_KIND_EXTERNAL_URL) {
+    if (!isBoundedText(item.externalUrl, MAXIMUM_URL_LENGTH)) {
+      throw navError("nav.external_url_missing", "an EXTERNAL_URL item needs a non-empty 'externalUrl'.", itemPath);
+    }
+    let url;
+    try {
+      url = new URL(item.externalUrl);
+    } catch {
+      url = undefined;
+    }
+    if (url === undefined || (url.protocol !== "https:" && url.protocol !== "http:")) {
+      throw navError("nav.external_url_invalid", "'externalUrl' must be an absolute http or https URL.", itemPath);
+    }
+    if (!isEmpty(item.resourceId)) {
+      throw navError("nav.resource_unexpected", "an EXTERNAL_URL item must not carry 'resourceId'.", itemPath);
+    }
+  } else if (!isEmpty(item.resourceId) || !isEmpty(item.externalUrl)) {
+    throw navError(
+      "nav.target_unexpected",
+      "a GROUP_HEADER item is a label and must carry neither 'resourceId' nor 'externalUrl'.",
+      itemPath,
+    );
+  }
+
+  const children = item.children ?? [];
+  if (!Array.isArray(children)) {
+    throw navError("nav.children_invalid", "'children' must be a list when it is present.", itemPath);
+  }
+  const validated = children.map((child, index) =>
+    validateItem(child, `${itemPath}.children[${index}]`, depth + 1, seenIds, counters));
+  // Rebuilt field by field so nothing outside the contract can ride along, and
+  // so an absent optional crosses the wire as the zero value proto3 expects.
+  return {
+    id: item.id,
+    kind: item.kind,
+    title: item.title,
+    resourceId: item.kind === NAV_ITEM_KIND_PAGE ? item.resourceId : "",
+    externalUrl: item.kind === NAV_ITEM_KIND_EXTERNAL_URL ? item.externalUrl : "",
+    children: validated,
+  };
+}
+
+function collectIds(items, into = new Set()) {
+  for (const item of items) {
+    if (item === null || typeof item !== "object") continue;
+    if (typeof item.id === "string") into.add(item.id);
+    if (Array.isArray(item.children)) collectIds(item.children, into);
+  }
+  return into;
+}
+
+function requireKnownPageTargets(pageReferences, knownResourceIds, knownPageIds) {
+  for (const reference of pageReferences) {
+    if (knownResourceIds.has(reference.resourceId)) continue;
+    throw navError(
+      "nav.resource_unknown",
+      knownPageIds.has(reference.resourceId)
+        ? `'${reference.resourceId}' is a pageId, not a site resourceId. Navigation targets resource_id — use the `
+          + "'resourceId' that 'pull' records beside 'pageId' on the same manifest entry."
+        : `'${reference.resourceId}' does not name a page on this site. Use the 'resourceId' that 'pull' records `
+          + "in the manifest, and re-run 'pull' if the page was created elsewhere.",
+      reference.itemPath,
+    );
+  }
+}
+
+/**
+ * Refuses a PAGE item whose `resourceId` is well-formed but points at nothing.
+ *
+ * The shape check upstream only proves the value is a UUID. A UUID that names
+ * no page on this site is accepted by every local rule and then refused by the
+ * server with a bare `ResourceId` — no index, no item path, nothing to locate
+ * across a tree that may hold a thousand items. Since the ids come from the
+ * manifest, where `pageId` and `resourceId` sit next to each other on the same
+ * entry, the overwhelmingly likely mistake is reaching for the wrong one; when
+ * the value turns out to be a live `pageId`, the message says so instead of
+ * repeating "not found".
+ *
+ * A page list this CLI could not fully enumerate produces no refusal at all: an
+ * incomplete set would reject valid trees, and a false refusal here is worse
+ * than the server's vague one.
+ */
+async function requireLivePageTargets(client, siteId, pageReferences, onProgress) {
+  if (pageReferences.length === 0) return;
+  onProgress(`Checking ${pageReferences.length} PAGE target(s) against the site's pages.`);
+  const { pages, truncated } = await listSitePages(client, siteId, { onProgress });
+  if (truncated) {
+    onProgress("The page list was bounded before the site was fully enumerated; PAGE targets are not checked.");
+    return;
+  }
+  const liveResourceIds = new Set(pages.map((summary) => summary.resourceId).filter(Boolean));
+  const livePageIds = new Set(pages.map((summary) => summary.pageId));
+  requireKnownPageTargets(pageReferences, liveResourceIds, livePageIds);
+}
+
+/** The complete local validation phase shared by live push and offline fixtures. */
+export function validateNavigationWorkspaceDocument(parsed, siteId, knownPages) {
+  // The pulled shape, and only the pulled shape. A bare array carries no site,
+  // and this verb replaces a whole navigation tree in one unversioned write.
+  if (parsed === null || Array.isArray(parsed) || typeof parsed !== "object") {
+    throw new SiteAuthoringError(
+      "nav.file_invalid",
+      `${NAVIGATION_FILE_NAME} must be the object 'pull' writes — { "siteId": ..., "navItems": [...] } — `
+        + "not a bare list.",
+      { field: NAVIGATION_FILE_NAME },
+    );
+  }
+  if (parsed.siteId !== siteId) {
+    throw new SiteAuthoringError(
+      "nav.file_site_mismatch",
+      `${NAVIGATION_FILE_NAME} records ${
+        typeof parsed.siteId === "string" && parsed.siteId !== "" ? `site ${parsed.siteId.slice(0, 64)}` : "no site"
+      }, but this configuration targets site ${siteId}. Run 'taproot-site pull' into a workspace of its own `
+        + "for this site.",
+      { field: NAVIGATION_FILE_NAME },
+    );
+  }
+  const declared = parsed.navItems;
+  if (!Array.isArray(declared)) {
+    throw new SiteAuthoringError(
+      "nav.file_invalid",
+      `${NAVIGATION_FILE_NAME} must hold a 'navItems' list.`,
+      { field: "navItems" },
+    );
+  }
+
+  const counters = { items: 0, pageReferences: [] };
+  const seenIds = new Set();
+  const navItems = declared.map((item, index) =>
+    validateItem(item, `navItems[${index}]`, 1, seenIds, counters)
+  );
+  if (knownPages !== undefined) {
+    requireKnownPageTargets(counters.pageReferences, knownPages.resourceIds, knownPages.pageIds);
+  }
+  return { navItems, items: counters.items, pageReferences: counters.pageReferences };
+}
+
+export async function navPush(invocation) {
+  const { client, config, siteId, onProgress } = await openSession(invocation);
+  if (!await workspaceFileExists(config.workspaceDir, NAVIGATION_FILE_NAME)) {
+    throw new SiteAuthoringError(
+      "nav.file_missing",
+      `No ${NAVIGATION_FILE_NAME} was found in the workspace. Run 'taproot-site pull' first.`,
+      { field: NAVIGATION_FILE_NAME },
+    );
+  }
+  const parsed = await readWorkspaceJson(config.workspaceDir, NAVIGATION_FILE_NAME, WORKSPACE_LIMITS.navigationBytes);
+  const validated = validateNavigationWorkspaceDocument(parsed, siteId);
+  const { navItems, pageReferences } = validated;
+  onProgress(`Validated ${validated.items} navigation items to depth ${NAVIGATION_MAXIMUM_DEPTH}.`);
+
+  return await withRefusalGuidance(onProgress, "navigation push", async () => {
+    await requireLivePageTargets(client, siteId, pageReferences, onProgress);
+
+    // Re-read immediately before the replace. There is no concurrency token to
+    // check, so this is the narrowest window the contract permits — and the
+    // only way to say what the replace removes. It happens *after* the target
+    // check so the window between reading the tree and replacing it stays as
+    // small as the contract allows.
+    onProgress("Re-reading the live navigation tree immediately before replacing it.");
+    const liveItems = await getNavigation(client, siteId);
+    const liveIds = collectIds(liveItems);
+    const pushedIds = collectIds(navItems);
+    const removed = [...liveIds].filter((id) => !pushedIds.has(id)).sort();
+    const added = [...pushedIds].filter((id) => !liveIds.has(id)).sort();
+    if (removed.length > 0) {
+      onProgress(
+        `This whole-tree replace removes ${removed.length} navigation item(s) that are live now: ${
+          removed.slice(0, 10).join(", ")
+        }${removed.length > 10 ? ", ..." : ""}.`,
+      );
+    }
+
+    const saved = await saveNavigation(client, siteId, navItems);
+    onProgress(`Replaced the navigation tree with ${validated.items} items.`);
+
+    const removedReport = boundedList(removed, MAXIMUM_REPORTED);
+    const addedReport = boundedList(added, MAXIMUM_REPORTED);
+    return successResult(VERB_NAV_PUSH, siteId, {
+      navigation: {
+        file: NAVIGATION_FILE_NAME,
+        items: validated.items,
+        rootItems: navItems.length,
+        savedRootItems: saved.length,
+        added: addedReport.items,
+        removed: removedReport.items,
+        ...(addedReport.truncated || removedReport.truncated ? { diffTruncated: true } : {}),
+      },
+      // Said plainly, because it is the risk this verb carries: there is no
+      // concurrency token on the navigation contract.
+      lastWriteWins: true,
+    });
+  });
+}