@taprootio/site-authoring 0.2.0 → 0.4.0

package/src/verbs/pull.js

@@ -2,6 +2,7 @@ import {
   getNavigation,
   getPage,
   getSettingsGroup,
+  getSiteRedirectMap,
   listSitePages,
   PAGE_STATUS_DELETED,
   PAGE_STATUS_DRAFT,
@@ -9,9 +10,12 @@ import {
   TEMPLATE_TYPE_FREE_FORM,
   withRefusalGuidance,
 } from "../api.js";
-import { REFUSAL_UNCLASSIFIED, VERB_PULL } from "../constants.js";
-import { SiteAuthoringError } from "../errors.js";
+import { REFUSAL_CAPABILITY_MISSING, REFUSAL_UNCLASSIFIED, VERB_PULL } from "../constants.js";
+import { sanitizeDiagnostic, SiteAuthoringError } from "../errors.js";
 import { appearanceManifestEntry, footerManifestEntry } from "../footer-workspace.js";
+import { describeJsonDifferences, reportableDifferencePaths } from "../json-path-diff.js";
+import { projectRedirectMapForWorkspace, REDIRECTS_FILE_NAME } from "../redirects-contract.js";
+import { redirectsManifestEntry } from "../redirects-workspace.js";
 import { boundedList, openSession, successResult } from "../session.js";
 import {
   projectSettingsGroup,
@@ -29,10 +33,12 @@ import {
   inspectArtifactSiteBinding,
   inspectManifestSiteBinding,
   internalPageBaselineFile,
+  internalPageObservedRevisionFile,
   MANIFEST_FILE_NAME,
   MANIFEST_VERSION,
   MEDIA_MANIFEST_FILE_NAME,
   NAVIGATION_FILE_NAME,
+  normalizePageBodyRevision,
   normalizePagePath,
   PAGE_READ_ONLY_REASON_SYSTEM_404,
   PAGE_SOURCE_EXTENSIONS,
@@ -43,6 +49,7 @@ import {
   pageSourceFormat,
   pageSourceRegistry,
   PAGES_DIRECTORY,
+  readObservedPageRecord,
   readWorkspaceFile,
   readWorkspaceJson,
   SETTINGS_DIRECTORY,
@@ -94,8 +101,10 @@ import {
 
 const MAXIMUM_REPORTED = 200;
 // A settings group the credential's envelope does not reach is a narrower
-// snapshot, not a failed pull. Anything the transport classified as a refusal
-// is a different matter and always propagates.
+// snapshot, not a failed pull. The server names that shortfall as a
+// capability denial (TR00691), and an older server answers a bare 403; both
+// mean the same thing here. Any other classified refusal — a rejected
+// credential, the rollout switch, a plan ceiling — always propagates.
 const UNAVAILABLE_SETTINGS_STATUSES = new Set([403, 404]);
 const APPEARANCE_SETTINGS_TYPES = Object.freeze([
   SETTINGS_TYPE_TAPROOT_STYLES,
@@ -126,9 +135,39 @@ function pullConflict(conflicts) {
       + `was changed, and the site's version is preserved at '${first.baselineFile}'. Either run `
       + `'taproot-site pages push ${selector}' to make the site match '${first.file}', or delete '${first.file}' `
       + `and pull again to adopt the site's version as this page's source.`
-      + (remaining > 0 ? ` ${remaining} other tracked page(s) are in the same state.` : ""),
+      + (remaining > 0 ? ` ${remaining} other tracked page(s) are in the same state.` : "")
+      // Last, so the diagnostic bounds itself: the message is cut at
+      // LIMITS.diagnosticScalars, and twenty long paths must never cut off the
+      // recovery the refusal exists to state.
+      + ` ${describeDifferenceSummary(first.differences)}`,
     { field: first.file, alternatives: conflicts.map((entry) => entry.file) },
-  );
+    // Deliberately not `?? []`: an empty list is the claim "compared, and the
+    // body is identical", which is what an agent reads as "look at the title,
+    // path, or description instead". A comparison that could not be made at all
+    // must leave the field absent rather than make that claim.
+  ).withDifferences(reportableDifferencePaths(first.differences));
+}
+
+/**
+ * One sentence naming what actually moved, for the conflict that reports it.
+ *
+ * "This page changed on the site" is true and useless: on the SHY production
+ * home page the whole change was an image's `src` and `urls`, re-projected on
+ * every read, and nothing in the refusal said so. The paths do not decide
+ * anything — the revision already did — but they are what tells an operator
+ * whether the site gained real content or merely a new signed URL.
+ */
+function describeDifferenceSummary(differences) {
+  if (differences === undefined) {
+    return "This workspace kept no copy of the site's previous version, so there is nothing to compare it against.";
+  }
+  if (differences.paths.length === 0) {
+    return differences.truncated
+      ? "The two documents were too large to compare completely; no difference was found in the part compared."
+      : "The site's document is identical to the copy this workspace last reconciled with, so the change is in the "
+        + "page's title, path, or description rather than its body.";
+  }
+  return `Differs at: ${differences.paths.join(", ")}${differences.truncated ? ", and more" : ""}.`;
 }
 
 /**
@@ -152,6 +191,63 @@ function holdsRemoteDocument(sourceBytes, remoteHash) {
   }
 }
 
+/** A page document, or `undefined` when the bytes are not one. */
+function parsePageDocument(bytes) {
+  try {
+    const parsed = JSON.parse(bytes.toString("utf8"));
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The document this workspace last reconciled with, if it still holds one.
+ *
+ * Two places can hold it. Internal state holds it for a page whose own source
+ * could not be rewritten from the site's document — every Markdown-tracked
+ * page, and any ProseMirror source carrying unpushed edits. For a ProseMirror
+ * source pull last refreshed, the source file *is* what pull wrote, so it is
+ * the previous version; but only while it has not been edited since, because
+ * an edited file is a mixture of local and remote work and diffing it would
+ * attribute the author's own changes to the site.
+ *
+ * Every failure is "nothing to compare against", the way
+ * `readObservedPageRevision` treats damaged internal state. This read exists to
+ * make a message more legible and decides nothing; pull writes the preserved
+ * body pretty-printed and under no per-file cap of its own, so a body large
+ * enough to trip `documentBytes` on the way back in is reachable — and a throw
+ * there would replace the `pages.pull_conflict` the caller is raising (skipping
+ * the observed-revision write that keeps the recovery push reachable), or fail
+ * an ordinary non-conflicting refresh outright. The conflict is still raised,
+ * and reports that this workspace kept no copy of the previous version.
+ */
+async function readPreviousRemoteDocument({ workspaceDir, baselineFile, sourceBytes, markdown, localChanged }) {
+  try {
+    if (await workspaceFileExists(workspaceDir, baselineFile)) {
+      const bytes = await readWorkspaceFile(workspaceDir, baselineFile, WORKSPACE_LIMITS.documentBytes);
+      const preserved = parsePageDocument(bytes);
+      if (preserved !== undefined) return preserved;
+    }
+  } catch {
+    return undefined;
+  }
+  if (markdown || localChanged) return undefined;
+  return parsePageDocument(sourceBytes);
+}
+
+/** The JSON paths at which the site's document moved, when that is knowable. */
+async function describeRemoteMovement({ workspaceDir, baselineFile, sourceBytes, markdown, localChanged, body }) {
+  const previous = await readPreviousRemoteDocument({
+    workspaceDir,
+    baselineFile,
+    sourceBytes,
+    markdown,
+    localChanged,
+  });
+  return previous === undefined ? undefined : describeJsonDifferences(previous, body);
+}
+
 function bodyStatusFor(summary) {
   if (summary.hasDraft) return PAGE_STATUS_DRAFT;
   if (summary.status !== PAGE_STATUS_UNKNOWN) return summary.status;
@@ -294,6 +390,9 @@ async function resolveTrackedSources(workspaceDir, pages, registry, onProgress)
  * and honoring it is what repairs an existing workspace in one pull instead of
  * by hand. Every other verb keeps refusing an old manifest outright — the site
  * binding is checked before this runs, so a foreign manifest never reaches it.
+ *
+ * What it does *not* honor is a comparison recorded under the superseded
+ * scheme; see `withoutSupersededRemoteHashes`.
  */
 async function readSourceRegistry(workspaceDir, siteId) {
   if (!await workspaceFileExists(workspaceDir, MANIFEST_FILE_NAME)) return new Map();
@@ -306,7 +405,64 @@ async function readSourceRegistry(workspaceDir, siteId) {
   if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed) || parsed.siteId !== siteId) {
     return new Map();
   }
-  return pageSourceRegistry(parsed);
+  const registry = pageSourceRegistry(parsed);
+  return parsed.manifestVersion === MANIFEST_VERSION ? registry : withoutSupersededRemoteHashes(registry);
+}
+
+/**
+ * Forgets `baseline.remoteHash` on every entry of a registry read out of a
+ * manifest that is not this version's.
+ *
+ * The hash answers "did the site's projected body change", which is the
+ * question version 6 stopped asking: the projection moves on its own, and the
+ * SHY home page's clean deploy is what proved it. On the first pull after the
+ * upgrade there is no recorded revision yet, so the comparison would fall back
+ * to that hash — and for a Markdown page, which is always kept and therefore
+ * always conflicts on a remote change, a projection that had moved in the
+ * meantime would refuse the pull *and* write no manifest. The documented
+ * recovery, `pages push`, reads the manifest strictly and refuses a superseded
+ * `manifestVersion` telling the operator to pull again, so the two verbs would
+ * send each other in a circle with no way out but deleting the source.
+ *
+ * Dropping the hash makes the migration pull establish the revision baseline
+ * instead, which is what every later pull compares. `sourceHash` is kept: it
+ * answers a question that has not changed — whether the author has edited a
+ * pulled ProseMirror source since — and losing it would let this same pull
+ * refresh the file over unpushed work.
+ *
+ * This discards state; it does not migrate any. An older manifest is still
+ * fully replaced by the pull that reads it.
+ */
+function withoutSupersededRemoteHashes(registry) {
+  for (const record of registry.values()) {
+    const baseline = record.baseline;
+    if (baseline?.remoteHash === undefined) continue;
+    const kept = {
+      ...(baseline.sourceHash === undefined ? {} : { sourceHash: baseline.sourceHash }),
+      ...(baseline.revision === undefined ? {} : { revision: baseline.revision }),
+    };
+    record.baseline = Object.keys(kept).length === 0 ? undefined : kept;
+  }
+  return registry;
+}
+
+/**
+ * The page read is the same response that supplies the body and the
+ * revision, so its title and path are the ones that revision describes. The
+ * listing's are one round trip older: a rename that landed in between would
+ * otherwise be recorded beside the newer revision, and the next push would
+ * send the old title or path against a revision that matches — reverting the
+ * rename with no conflict to report (TR00643).
+ */
+function titleFromRead(page, summary) {
+  // Stripped the way the listing's title is (`roundTrippedText` in api.js):
+  // control and bidi characters are terminal and diff safety, not fidelity.
+  return typeof page.title === "string" ? sanitizeDiagnostic(page.title, "") : summary.title;
+}
+
+function pathFromRead(page, summary) {
+  const normalized = typeof page.path === "string" ? normalizePagePath(page.path) : undefined;
+  return normalized === undefined ? summary.path : normalized;
 }
 
 function freeFormBody(page) {
@@ -386,8 +542,8 @@ async function requireWorkspaceBelongsToSite(workspaceDir, siteId) {
       PAGES_DIRECTORY,
     );
   }
-  // These two do carry a site, so they can clear themselves.
-  for (const artifact of [NAVIGATION_FILE_NAME, MEDIA_MANIFEST_FILE_NAME]) {
+  // These three do carry a site, so they can clear themselves.
+  for (const artifact of [NAVIGATION_FILE_NAME, MEDIA_MANIFEST_FILE_NAME, REDIRECTS_FILE_NAME]) {
     const artifactBinding = await inspectArtifactSiteBinding(workspaceDir, artifact);
     if (artifactBinding.state === "absent") continue;
     if (artifactBinding.state === "bound" && artifactBinding.siteId === siteId) continue;
@@ -418,6 +574,31 @@ export async function pull(invocation) {
     const tracked = await resolveTrackedSources(config.workspaceDir, freeForm, registry, onProgress);
     const pageFiles = assignPageFiles(freeForm, tracked);
 
+    // The redirect map, with the revision a later push is fenced by (TR00702).
+    // Read here, before the first workspace write, for the same reason the
+    // settings groups below are: a failure must strand nothing. A Taproot that
+    // predates the map answers the route with 404; that pull then records no
+    // redirect baseline, and `redirects push` asks for a pull against a site
+    // that has one rather than guessing.
+    onProgress("Reading the redirect map.");
+    let redirectMap;
+    try {
+      redirectMap = await getSiteRedirectMap(client, siteId);
+    } catch (error) {
+      if (
+        error instanceof ApiError
+        && error.refusalKind() === REFUSAL_UNCLASSIFIED
+        && error.httpStatus === 404
+      ) {
+        onProgress(
+          `This Taproot does not serve a redirect map yet; ${REDIRECTS_FILE_NAME} is not written and the manifest `
+            + "records no redirect baseline.",
+        );
+      } else {
+        throw error;
+      }
+    }
+
     // Project every settings response before the first workspace write. Theme
     // decoding is a wire-contract check and can fail on malformed stored data;
     // discovering that after page bodies were written would strand an
@@ -435,7 +616,8 @@ export async function pull(invocation) {
       } catch (error) {
         if (
           error instanceof ApiError
-          && error.refusalKind() === REFUSAL_UNCLASSIFIED
+          && (error.refusalKind() === REFUSAL_UNCLASSIFIED
+            || error.refusalKind() === REFUSAL_CAPABILITY_MISSING)
           && UNAVAILABLE_SETTINGS_STATUSES.has(error.httpStatus)
         ) {
           onProgress(`Settings group ${group.settingsType} is not readable by this credential; skipping it.`);
@@ -482,7 +664,13 @@ export async function pull(invocation) {
         // page's one source. Dropping it from the registry would let the next
         // pull mint the competing document all over again.
         onProgress(`Page '${summary.path}' has no readable free-form body; keeping '${source.file}' as its source.`);
-        trackedPlans.set(summary.pageId, { description, file: source.file, sourceFormat: source.sourceFormat });
+        trackedPlans.set(summary.pageId, {
+          description,
+          title: titleFromRead(page, summary),
+          path: pathFromRead(page, summary),
+          file: source.file,
+          sourceFormat: source.sourceFormat,
+        });
         continue;
       }
       const baselineFile = internalPageBaselineFile(summary.pageId);
@@ -510,7 +698,29 @@ export async function pull(invocation) {
       const remoteHash = canonicalDocumentHash(body);
       const sourceBytes = await readWorkspaceFile(config.workspaceDir, source.file, WORKSPACE_LIMITS.documentBytes);
       const sourceHash = workspaceContentHash(sourceBytes);
-      const remoteChanged = source.baseline?.remoteHash !== undefined && source.baseline.remoteHash !== remoteHash;
+      const revision = normalizePageBodyRevision(page.bodyRevision);
+      // The revision is the site's own statement about its stored state, so it
+      // moves for a real edit to the body, title, path, or description and for
+      // nothing else. The body hash cannot make that distinction: every read
+      // re-projects image delivery and re-serializes component data, so a
+      // signer rotation or a changed image reads as an edit — which is exactly
+      // what refused the SHY home page's pull after a clean deploy. So the
+      // hash is consulted only where there is no revision to compare: a
+      // Taproot that predates the revision contract, where it is still strictly
+      // better than assuming nothing moved.
+      //
+      // A site that *now* reports a revision establishes the revision baseline
+      // instead of comparing a superseded hash, even when the manifest recorded
+      // one. That manifest is this version's — `withoutSupersededRemoteHashes`
+      // never touched it — but its hash was recorded against a Taproot that had
+      // no revision to give, so it is the same superseded projected-body hash,
+      // and honoring it would refuse forever every Markdown page whose image
+      // projection moved across the API deploy. This costs one pull's detection
+      // at the upgrade boundary, the same trade `withoutSupersededRemoteHashes`
+      // accepts.
+      const remoteChanged = revision !== undefined
+        ? source.baseline?.revision !== undefined && source.baseline.revision !== revision
+        : source.baseline?.remoteHash !== undefined && source.baseline.remoteHash !== remoteHash;
       // Markdown is one-way, so a Markdown source can never be rewritten from
       // the site's document and is always kept. A ProseMirror source can be
       // refreshed — but only over content the author has not edited since the
@@ -539,6 +749,8 @@ export async function pull(invocation) {
       const conflicted = markdown ? remoteChanged : localChanged && remoteChanged;
       trackedPlans.set(summary.pageId, {
         description,
+        title: titleFromRead(page, summary),
+        path: pathFromRead(page, summary),
         file: source.file,
         sourceFormat: source.sourceFormat,
         // `sourceHash` records the source as of the last time it *agreed* with
@@ -550,17 +762,80 @@ export async function pull(invocation) {
         // carries its previous hash forward until a push records a new one or
         // a remote change turns the divergence into a conflict.
         baseline: keepLocal
-          ? { remoteHash, sourceHash: localChanged ? source.baseline?.sourceHash : sourceHash }
-          : { remoteHash, sourceHash: workspaceContentHash(serialized) },
+          // The revision records what this workspace has reconciled with, and
+          // a conflicted page reconciles with nothing: this manifest is never
+          // written, because the refusal below is raised before it is. That is
+          // what keeps the same conflict coming back until somebody resolves
+          // it, rather than the site's new version being adopted by a pull
+          // that refused to adopt it.
+          ? {
+            remoteHash,
+            sourceHash: localChanged ? source.baseline?.sourceHash : sourceHash,
+            ...(revision === undefined ? {} : { revision }),
+          }
+          : {
+            remoteHash,
+            sourceHash: workspaceContentHash(serialized),
+            ...(revision === undefined ? {} : { revision }),
+          },
         ...(keepLocal ? { baselineBody: serialized, baselineFile } : { refresh: serialized, baselineFile }),
       });
-      if (conflicted) {
-        conflicts.push({
-          pagePath: normalizePagePath(summary.path) ?? summary.path,
-          file: source.file,
-          baselineFile,
-          localChanged,
-        });
+      if (remoteChanged) {
+        // A refusal for this same version already worked this out, against a
+        // baseline it then overwrote with the very version being compared.
+        // Recomputing now would compare that version with itself, find nothing,
+        // and report "the change is in the page's title, path, or description"
+        // for what was a body edit. So a record naming exactly this version is
+        // authoritative about what the operator was last shown — including its
+        // having been unable to tell — and a page that has moved *again* names
+        // a different one and is compared afresh, against the version that
+        // refusal preserved.
+        //
+        // "This version" is the revision where the site reports one, and the
+        // canonical body hash where it does not. Against a Taproot that
+        // predates the revision contract — which the published CLI meets
+        // whenever it runs ahead of the deployed API — the hash is the whole of
+        // what the fallback comparison above is made against, so it is equally
+        // the thing a record has to name.
+        const observed = await readObservedPageRecord(config.workspaceDir, summary.pageId);
+        const alreadyShown = observed !== undefined
+          && (revision === undefined
+            ? observed.revision === undefined && observed.remoteHash === remoteHash
+            : observed.revision === revision);
+        // Computed here, while both documents are in hand and before the
+        // preserved baseline below is overwritten with the new one — after
+        // that write the previous version is gone and nothing could say what
+        // moved.
+        const differences = alreadyShown
+          ? observed.differences
+          : await describeRemoteMovement({
+            workspaceDir: config.workspaceDir,
+            baselineFile,
+            sourceBytes,
+            markdown,
+            localChanged,
+            body,
+          });
+        // Sanitized as one message: the page path is server data and the paths
+        // are drawn from an untrusted document, and the same strings reach
+        // `error.differences` de-fanged. A progress line is the one place they
+        // would otherwise reach a terminal raw.
+        onProgress(
+          sanitizeDiagnostic(`Page '${summary.path}' moved on the site. ${describeDifferenceSummary(differences)}`),
+        );
+        if (conflicted) {
+          conflicts.push({
+            pageId: summary.pageId,
+            pagePath: normalizePagePath(summary.path) ?? summary.path,
+            file: source.file,
+            baselineFile,
+            localChanged,
+            differences,
+            observedRevision: revision,
+            observedRemoteHash: remoteHash,
+            observedRevisionFile: internalPageObservedRevisionFile(summary.pageId),
+          });
+        }
       } else if (keepLocal && localChanged) {
         // Two different situations, and saying "kept your edits" for both
         // would be a guess dressed as a fact: with a recorded hash the
@@ -584,7 +859,35 @@ export async function pull(invocation) {
       if (plan.baselineBody === undefined) continue;
       await writeWorkspaceFile(config.workspaceDir, plan.baselineFile, plan.baselineBody);
     }
-    if (conflicts.length > 0) throw pullConflict(conflicts);
+    if (conflicts.length > 0) {
+      // Recorded beside the preserved body, and only for a page this pull is
+      // about to refuse. It says "the operator has been shown this version",
+      // which is what keeps the refusal's own recovery — push the local source
+      // to make the site match it — reachable without weakening the push
+      // refusal for a page that moved while nobody was looking.
+      //
+      // The differences ride along because the write above has just replaced
+      // the only copy they could be computed from. Without them the second
+      // refusal for an unchanged version would carry no `differences` at all
+      // and claim the change was not in the body.
+      //
+      // Written for every conflict, not only for a site that reports a
+      // revision. A site that does not is compared by body hash, and skipping
+      // the record there left the second refusal recomputing against the copy
+      // the first one overwrote — finding no difference, and reporting a body
+      // edit as a metadata change every time.
+      for (const conflict of conflicts) {
+        if (conflict.observedRevisionFile === undefined) continue;
+        await writeWorkspaceJson(config.workspaceDir, conflict.observedRevisionFile, {
+          pageId: conflict.pageId,
+          ...(conflict.observedRevision === undefined
+            ? { remoteHash: conflict.observedRemoteHash }
+            : { revision: conflict.observedRevision }),
+          ...(conflict.differences === undefined ? {} : { differences: conflict.differences }),
+        });
+      }
+      throw pullConflict(conflicts);
+    }
 
     // Phase two: everything else, plus the tracked refreshes cleared above.
     const manifestPages = [];
@@ -602,9 +905,19 @@ export async function pull(invocation) {
         workspaceMode: PAGE_WORKSPACE_MODE_METADATA_ONLY,
       };
       if (summary.templateType === TEMPLATE_TYPE_FREE_FORM) {
+        // This pull is reconciling the page, so the manifest below carries the
+        // newer and stronger claim and the "what the operator was shown" record
+        // is spent. Leaving it would let a push override a remote change this
+        // workspace has since caught up with.
+        const observedRevisionFile = internalPageObservedRevisionFile(summary.pageId);
+        if (observedRevisionFile !== undefined) {
+          await deleteWorkspaceFile(config.workspaceDir, observedRevisionFile);
+        }
         const plan = trackedPlans.get(summary.pageId);
         if (plan !== undefined) {
           entry.description = plan.description;
+          if (plan.title !== undefined) entry.title = plan.title;
+          if (plan.path !== undefined) entry.path = plan.path;
           if (plan.file !== undefined) {
             entry.file = plan.file;
             entry.sourceFormat = plan.sourceFormat;
@@ -628,6 +941,8 @@ export async function pull(invocation) {
         const page = await getPage(client, summary.pageId, bodyStatusFor(summary));
         const body = freeFormBody(page);
         entry.description = typeof page.shortDescription === "string" ? page.shortDescription : "";
+        entry.title = titleFromRead(page, summary);
+        entry.path = pathFromRead(page, summary);
         if (body === undefined) {
           // The server accepts and stores a body it never validates, so an
           // unreadable one is a real state. It is reported rather than written
@@ -646,9 +961,11 @@ export async function pull(invocation) {
           } else {
             entry.workspaceMode = PAGE_WORKSPACE_MODE_EDITABLE;
             entry.sourceFormat = pageSourceFormat(entry.file);
+            const revision = normalizePageBodyRevision(page.bodyRevision);
             entry.baseline = {
               remoteHash: canonicalDocumentHash(body),
               sourceHash: workspaceContentHash(source),
+              ...(revision === undefined ? {} : { revision }),
             };
           }
           await writeWorkspaceFile(config.workspaceDir, entry.file, source);
@@ -664,6 +981,14 @@ export async function pull(invocation) {
     const navItems = await getNavigation(client, siteId);
     await writeWorkspaceJson(config.workspaceDir, NAVIGATION_FILE_NAME, { siteId, navItems });
 
+    if (redirectMap !== undefined) {
+      await writeWorkspaceJson(
+        config.workspaceDir,
+        REDIRECTS_FILE_NAME,
+        projectRedirectMapForWorkspace(siteId, redirectMap),
+      );
+    }
+
     for (const document of settingsDocuments) {
       await writeWorkspaceJson(config.workspaceDir, document.file, document.value);
     }
@@ -674,6 +999,7 @@ export async function pull(invocation) {
       pulledAt: new Date(now()).toISOString(),
       pagesTruncated: truncated,
       navigation: { file: NAVIGATION_FILE_NAME, items: navItems.length },
+      ...(redirectMap === undefined ? {} : { redirects: redirectsManifestEntry(redirectMap) }),
       settings: pulledSettings,
       settingsSkipped: skippedSettings,
       ...(pulledFooter === undefined ? {} : { footer: footerManifestEntry(pulledFooter) }),
@@ -717,6 +1043,15 @@ export async function pull(invocation) {
         ...(reported.truncated ? { itemsTruncated: true } : {}),
       },
       navigation: { file: NAVIGATION_FILE_NAME, items: navItems.length },
+      // Absent, not zeroed, when the site served no map: an agent reading
+      // `entries: 0` would take the site for one with no redirects.
+      ...(redirectMap === undefined ? {} : {
+        redirects: {
+          file: REDIRECTS_FILE_NAME,
+          revision: redirectMap.revision,
+          entries: redirectMap.entries.length,
+        },
+      }),
       settings: {
         pulled: pulledSettings.map((entry) => entry.settingsType),
         skipped: skippedSettings,

package/src/verbs/redirects-pull.js

@@ -0,0 +1,90 @@
+import { getSiteRedirectMap, withRefusalGuidance } from "../api.js";
+import { REFUSAL_UNCLASSIFIED, VERB_REDIRECTS_PULL } from "../constants.js";
+import { SiteAuthoringError } from "../errors.js";
+import {
+  projectRedirectMapForWorkspace,
+  REDIRECT_KIND_GONE,
+  REDIRECT_ORIGIN_AUTHORED,
+  REDIRECTS_FILE_NAME,
+} from "../redirects-contract.js";
+import { redirectsManifestEntry } from "../redirects-workspace.js";
+import { boundedList, openSession, successResult } from "../session.js";
+import { ApiError } from "../transport.js";
+import { readManifest, writeManifest, writeWorkspaceJson } from "../workspace.js";
+
+const MAXIMUM_REPORTED = 200;
+
+/**
+ * `redirects pull` — snapshot the site's whole redirect map.
+ *
+ * It writes `redirects.json` and records the map's revision in the pull
+ * manifest, because a whole-map push has to be fenced against the state it was
+ * built from: the map holds entries nobody typed — one per page or tag rename —
+ * and a stale replace would delete them.
+ *
+ * It is a verb of its own as well as part of `pull` so an agent can re-read
+ * just the map after a rename, or after a conflicting push, without re-pulling
+ * every page.
+ */
+export async function redirectsPull(invocation) {
+  const { client, config, siteId, onProgress } = await openSession(invocation);
+  // The manifest is required rather than optional: without one there is no
+  // pulled workspace for this file to belong to, and the same refusal `pages
+  // push` gives is the right one here.
+  const manifest = await readManifest(config.workspaceDir, siteId);
+
+  const map = await withRefusalGuidance(
+    onProgress,
+    "redirects pull",
+    async () => await readRedirectMapOrRefuse(client, siteId),
+  );
+
+  const document_ = projectRedirectMapForWorkspace(siteId, map);
+  await writeWorkspaceJson(config.workspaceDir, REDIRECTS_FILE_NAME, document_);
+  manifest.redirects = redirectsManifestEntry(map);
+  await writeManifest(config.workspaceDir, manifest);
+  onProgress(
+    `Wrote ${REDIRECTS_FILE_NAME} with ${map.entries.length} entr${map.entries.length === 1 ? "y" : "ies"} `
+      + "and recorded the map revision.",
+  );
+
+  const authored = map.entries.filter((entry) => entry.origin === REDIRECT_ORIGIN_AUTHORED).length;
+  const reported = boundedList(document_.entries, MAXIMUM_REPORTED);
+  return successResult(VERB_REDIRECTS_PULL, siteId, {
+    redirectsFile: REDIRECTS_FILE_NAME,
+    revision: map.revision,
+    redirects: {
+      total: map.entries.length,
+      // Split so an agent can tell what it declared from what a rename
+      // recorded, which is the difference between "mine to edit" and "the
+      // site's own history, delete it only on purpose".
+      authored,
+      pathHistory: map.entries.length - authored,
+      gone: map.entries.filter((entry) => entry.kind === REDIRECT_KIND_GONE).length,
+      items: reported.items,
+      ...(reported.truncated ? { itemsTruncated: true } : {}),
+    },
+  });
+}
+
+/**
+ * A Taproot that predates the redirect map answers the route with a bare 404.
+ * Named here rather than surfaced as an unclassified status, because the
+ * refusal `redirects push` gives for a missing baseline sends the operator to
+ * this verb (TR00702).
+ */
+async function readRedirectMapOrRefuse(client, siteId) {
+  try {
+    return await getSiteRedirectMap(client, siteId);
+  } catch (error) {
+    if (error instanceof ApiError && error.refusalKind() === REFUSAL_UNCLASSIFIED && error.httpStatus === 404) {
+      throw new SiteAuthoringError(
+        "redirects.not_served",
+        "This Taproot does not serve a redirect map yet. Wait for the deploy that adds it, then run "
+          + "'taproot-site redirects pull' again.",
+        { status: error.status },
+      );
+    }
+    throw error;
+  }
+}