@taprootio/site-authoring 0.22.3 → 0.23.0

package/src/verbs/nav-push.js

@@ -16,10 +16,17 @@ import {
 } from "../contact-url.js";
 import { SiteAuthoringError } from "../errors.js";
 import { stableJson } from "../footer-draft-hash.js";
+import {
+  advanceNavigationManifest,
+  navigationMovedRefusal,
+  requireNavigationBaseline,
+} from "../navigation-workspace.js";
 import { planStale } from "../problems.js";
 import { boundedList, openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
+import { ApiError } from "../transport.js";
 import {
   NAVIGATION_FILE_NAME,
+  readManifest,
   readWorkspaceJson,
   workspaceFileExists,
   WORKSPACE_LIMITS,
@@ -29,14 +36,14 @@ import {
 /**
  * `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:
+ * `SaveSiteNavigation` is a whole-tree PUT fenced by a revision (TR01231): the
+ * pull records the revision the tree was read at, and the save presents it. A
+ * tree edited in the app since is refused with `nav.concurrent_modification`
+ * and nothing is written. Two more 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.
+ * 1. The tree is re-read immediately before the write, so a moved tree is
+ *    refused before anything is sent, 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
@@ -178,9 +185,10 @@ function validateItem(item, itemPath, depth, seenIds, counters) {
   return {
     id: item.id,
     kind: item.kind,
-    title: item.title,
+    // Trimmed as the site stores them, so a padded value still equals the stored tree when a lost push is settled.
+    title: item.title.trim(),
     resourceId: item.kind === NAV_ITEM_KIND_PAGE ? item.resourceId : "",
-    externalUrl: item.kind === NAV_ITEM_KIND_EXTERNAL_URL ? item.externalUrl : "",
+    externalUrl: item.kind === NAV_ITEM_KIND_EXTERNAL_URL ? item.externalUrl.trim() : "",
     children: validated,
   };
 }
@@ -271,7 +279,7 @@ async function requireLivePageTargets(client, siteId, pageReferences, onProgress
 /** 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.
+  // and this verb replaces a whole navigation tree in one write, fenced by the pulled revision.
   if (parsed === null || Array.isArray(parsed) || typeof parsed !== "object") {
     throw new SiteAuthoringError(
       "nav.file_invalid",
@@ -328,22 +336,31 @@ export async function navPush(invocation) {
   const validated = validateNavigationWorkspaceDocument(parsed, siteId);
   const { navItems, pageReferences } = validated;
   onProgress(`Validated ${validated.items} navigation items to depth ${NAVIGATION_MAXIMUM_DEPTH}.`);
+  // The manifest's baseline, never a value from the file: nav.json is hand-edited, and its revision would be a
+  // claim rather than a record of a read. Refused before any request when the workspace has none.
+  const expectedRevision = requireNavigationBaseline(await readManifest(config.workspaceDir, siteId));
 
   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.
+    // Re-read immediately before the replace: a tree that moved since the pull is refused here, before anything
+    // is sent, and it is 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 possible; the site's own fence
+    // closes what is left.
     onProgress("Re-reading the live navigation tree immediately before replacing it.");
-    const liveItems = await getNavigation(client, siteId);
+    const live = await getNavigation(client, siteId);
+    const liveItems = live.navItems;
     // 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);
     }
+    // A moved tree that already equals the file is a push whose answer was lost after it committed (the
+    // transport never replays a write): the retry settles the workspace rather than refusing a tree that is
+    // exactly what the file says.
+    const alreadyApplied = live.revision !== expectedRevision
+      && stableJson(projectNavigationForWorkspace(liveItems)) === stableJson(projectNavigationForWorkspace(navItems));
+    if (live.revision !== expectedRevision && !alreadyApplied) throw navigationMovedRefusal();
     const liveIds = collectIds(liveItems);
     const pushedIds = collectIds(navItems);
     const removed = [...liveIds].filter((id) => !pushedIds.has(id)).sort();
@@ -356,11 +373,25 @@ export async function navPush(invocation) {
       );
     }
 
-    const saved = await saveNavigation(client, siteId, navItems);
-    onProgress(`Replaced the navigation tree with ${validated.items} items.`);
+    let saved;
+    if (alreadyApplied) {
+      onProgress("The site already holds this navigation tree (an earlier push whose answer was lost); nothing is sent.");
+      saved = { navItems: liveItems, revision: live.revision };
+    } else {
+      try {
+        saved = await saveNavigation(client, siteId, navItems, expectedRevision);
+      } catch (error) {
+        // The tree moved between the read above and this write.
+        if (error instanceof ApiError && error.hasField("ExpectedRevision")) throw navigationMovedRefusal();
+        throw error;
+      }
+      onProgress(`Replaced the navigation tree with ${validated.items} items.`);
+    }
     try {
       // The file now holds what the site stored, in the form pull writes, so the next pull is byte-identical.
-      const stored = saved.length > 0 || navItems.length === 0 ? saved : navItems;
+      // Always the answer's tree, even an empty one: the recorded revision describes that response, and another
+      // editor may have changed the tree between this save and the site's read of it.
+      const stored = saved.navItems;
       // siteId and navItems first, in pull's order; any other key the author kept follows.
       const { siteId: _siteId, navItems: _navItems, ...extras } = parsed;
       await writeWorkspaceJson(config.workspaceDir, NAVIGATION_FILE_NAME, {
@@ -368,6 +399,9 @@ export async function navPush(invocation) {
         navItems: projectNavigationForWorkspace(stored),
         ...extras,
       });
+      // After the document, as redirects push orders them: if this write fails, the old baseline refuses the
+      // next push rather than letting it overwrite the tree just saved.
+      await advanceNavigationManifest(config.workspaceDir, siteId, { navItems: stored, revision: saved.revision });
     } catch (error) {
       // The site already holds the new tree; only the local file is stale, so say the tree was replaced.
       if (error instanceof SiteAuthoringError) throw error.withCompletedWrites(["navigationTree"]);
@@ -381,14 +415,13 @@ export async function navPush(invocation) {
         file: NAVIGATION_FILE_NAME,
         items: validated.items,
         rootItems: navItems.length,
-        savedRootItems: saved.length,
+        savedRootItems: saved.navItems.length,
         added: addedReport.items,
         removed: removedReport.items,
         ...(addedReport.truncated || removedReport.truncated ? { diffTruncated: true } : {}),
+        revision: saved.revision,
+        ...(alreadyApplied ? { alreadyApplied: true } : {}),
       },
-      // Said plainly, because it is the risk this verb carries: there is no
-      // concurrency token on the navigation contract.
-      lastWriteWins: true,
     });
   });
 }

package/src/verbs/pages-delete.js

@@ -0,0 +1,380 @@
+import {
+  deletePage,
+  getNavigation,
+  getSiteRedirectMap,
+  isGonePage,
+  listSitePages,
+  NAV_ITEM_KIND_PAGE,
+  PAGE_STATUS_PUBLISHED,
+  withRefusalGuidance,
+} from "../api.js";
+import { VERB_PAGES_DELETE } from "../constants.js";
+import { SiteAuthoringError } from "../errors.js";
+import { FOOTER_SETTINGS_FILE } from "../footer-workspace.js";
+import { afterSubmitPage, FORM_FILE_EXTENSION, FORMS_DIRECTORY, normalizePagePath as normalizeFormPagePath } from "../forms-contract.js";
+import { normalizeRedirectPath } from "../site-checks.js";
+import { boundedList, openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
+import { isAuthorableTemplateType, isGeneratedTemplateType } from "../typed-pages.js";
+import {
+  deleteWorkspaceFile,
+  displayPagePath,
+  isDiscoverablePageSource,
+  internalPageBaselineFile,
+  internalPageObservedRevisionFile,
+  normalizePagePath,
+  pageSourceFormat,
+  pageSourceRegistry,
+  readManifest,
+  readObservedPageRecord,
+  readWorkspaceJson,
+  requireManifestSourceRegistry,
+  SYSTEM_PAGE_NOT_FOUND_PATH,
+  walkWorkspaceFiles,
+  WORKSPACE_LIMITS,
+  workspaceFileExists,
+  writeManifest,
+} from "../workspace.js";
+import { outcomeUnknown, requireReconciledRevision } from "./pages-push.js";
+
+/**
+ * `pages delete` — remove one page this workspace tracks (TR01226).
+ *
+ * Deleting goes through the page delete the app uses, so the rules are the
+ * site's: a page that was never published is removed outright and its path is
+ * free again. A page the live site serves is not taken off it by the delete: the
+ * site stages the removal and the page stays live until a deployment promotes it
+ * (TR01278), so the CLI reports `removalStaged` and the staging loop finishes
+ * the job.
+ *
+ * The same fence as `pages push` runs first: a page edited on the site since
+ * this workspace last reconciled with it is refused with `pages.push_conflict`.
+ * Then the references a delete would leave dangling are checked: a navigation
+ * item, a footer link or a form's after-submit page refuses the delete (the
+ * site would drop the navigation item silently, which would also move the
+ * revision `nav push` is fenced by), while a redirect that lands on the path
+ * is only reported, because a redirect to a missing page is a broken link
+ * rather than a broken site.
+ *
+ * `--dry-run` runs every check and sends nothing. A page the site already
+ * deleted, or already staged for removal, is the retry of an interrupted run:
+ * only the workspace is cleaned.
+ */
+
+const MAXIMUM_REPORTED = 50;
+
+function refusal(code, message, field, alternatives) {
+  return new SiteAuthoringError(code, message, { field, ...(alternatives === undefined ? {} : { alternatives }) });
+}
+
+/** Every `pageResourceId` in a footer settings document that names the page. */
+function footerLinksTo(value, resourceId, found = []) {
+  if (Array.isArray(value)) {
+    for (const item of value) footerLinksTo(item, resourceId, found);
+  } else if (value !== null && typeof value === "object") {
+    if (value.pageResourceId === resourceId) found.push(value.label ?? value.id ?? "a footer link");
+    for (const item of Object.values(value)) footerLinksTo(item, resourceId, found);
+  }
+  return found;
+}
+
+function navigationItemsTo(items, resourceId, trail = "navItems", found = []) {
+  items.forEach((item, index) => {
+    const at = `${trail}[${index}]`;
+    if (item?.kind === NAV_ITEM_KIND_PAGE && item.resourceId === resourceId) {
+      found.push({ at, title: typeof item.title === "string" ? item.title : "" });
+    }
+    if (Array.isArray(item?.children)) navigationItemsTo(item.children, resourceId, `${at}.children`, found);
+  });
+  return found;
+}
+
+/**
+ * Reads workspace files that may name the page, failing closed: a file that cannot be read could be the one that
+ * does, so its error refuses the delete rather than letting it pass unchecked.
+ */
+async function readReferenceSource(read, what, shown) {
+  try {
+    return await read();
+  } catch (error) {
+    if (!(error instanceof SiteAuthoringError)) throw error;
+    throw refusal(
+      "pages.delete_references_unreadable",
+      `Could not read ${what} to check whether it uses '${shown}': ${error.message} Nothing was deleted. Fix or `
+        + "remove it, then try again.",
+      error.field ?? shown,
+    );
+  }
+}
+
+/** The workspace's form files whose after-submit page is this path or resource. */
+async function formsSendingTo(workspaceDir, pagePath, resourceId) {
+  const shown = displayPagePath(pagePath);
+  const files = await readReferenceSource(
+    async () => await walkWorkspaceFiles(workspaceDir, FORMS_DIRECTORY, [FORM_FILE_EXTENSION]),
+    `the ${FORMS_DIRECTORY}/ folder`,
+    shown,
+  );
+  const found = [];
+  for (const file of files) {
+    const document_ = await readReferenceSource(
+      async () => await readWorkspaceJson(workspaceDir, file, WORKSPACE_LIMITS.documentBytes),
+      file,
+      shown,
+    );
+    const after = afterSubmitPage(document_?.definition);
+    if (after === undefined) continue;
+    // A form names its page by path, or by resource id when the page was not in the path index at pull.
+    const byPath = typeof after.page_path === "string"
+      && normalizeFormPagePath(after.page_path) === normalizeFormPagePath(`/${pagePath}`);
+    if (byPath || after.page_resource_id === resourceId) found.push(file);
+  }
+  return found;
+}
+
+async function footerLinks(workspaceDir, resourceId, shown) {
+  if (!await workspaceFileExists(workspaceDir, FOOTER_SETTINGS_FILE)) return [];
+  return footerLinksTo(
+    await readReferenceSource(
+      async () => await readWorkspaceJson(workspaceDir, FOOTER_SETTINGS_FILE, WORKSPACE_LIMITS.documentBytes),
+      FOOTER_SETTINGS_FILE,
+      shown,
+    ),
+    resourceId,
+  );
+}
+
+function redirectsLandingOn(entries, pagePath) {
+  const target = normalizeRedirectPath(`/${pagePath}`);
+  return entries
+    .filter((entry) => typeof entry.target === "string" && normalizeRedirectPath(entry.target) === target)
+    .map((entry) => entry.path);
+}
+
+/** The live site serves this page, so the site stages its removal instead of deleting it. */
+function servedLive(summary) {
+  return summary !== undefined && (summary.status === PAGE_STATUS_PUBLISHED || summary.datePublished !== "");
+}
+
+function trackedEntry(manifest, pagePath) {
+  return manifest.pages.find((entry) => entry !== null && normalizePagePath(entry.path) === pagePath);
+}
+
+function requireDeletable(manifest, entry, pagePath) {
+  const shown = displayPagePath(pagePath);
+  if (entry === undefined) {
+    throw refusal(
+      "pages.delete_page_unknown",
+      `No page this workspace tracks is at '${shown}'. Run 'taproot-site pull' if it was created elsewhere.`,
+      shown,
+    );
+  }
+  // The entry names a file this verb unlinks and a page it deletes, so a hand-edited manifest is refused first.
+  requireManifestSourceRegistry(pageSourceRegistry(manifest));
+  if (typeof entry.pageId !== "string" || entry.pageId === "") {
+    throw refusal(
+      "pages.delete_manifest_invalid",
+      `The manifest entry for '${shown}' records no page id. Run 'taproot-site pull' to rebuild it.`,
+      shown,
+    );
+  }
+  if (entry.file !== undefined && (typeof entry.file !== "string" || !isDiscoverablePageSource(entry.file) || pageSourceFormat(entry.file) === undefined)) {
+    throw refusal(
+      "pages.delete_manifest_invalid",
+      `The manifest entry for '${shown}' names a file that is not a page source. Run 'taproot-site pull' to rebuild it.`,
+      shown,
+    );
+  }
+  if (pagePath === "" || pagePath.toLowerCase() === SYSTEM_PAGE_NOT_FOUND_PATH) {
+    throw refusal("pages.delete_system", `'${shown}' is a system page; the site cannot be without it.`, shown);
+  }
+  if (isGeneratedTemplateType(entry.templateType) || entry.isGenerated === true) {
+    throw refusal(
+      "pages.delete_generated",
+      `'${shown}' is a page Taproot generates from the site's content; remove the content that produces it.`,
+      shown,
+    );
+  }
+  if (!isAuthorableTemplateType(entry.templateType)) {
+    throw refusal(
+      "pages.delete_not_authorable",
+      `'${shown}' is a ${entry.templateType ?? "system-managed"} page, which this CLI does not author; delete it in the app.`,
+      shown,
+    );
+  }
+}
+
+export async function pagesDelete(invocation) {
+  const session = await openSession(invocation);
+  const { client, config, siteId, onProgress } = session;
+  const dryRun = invocation.dryRun === true;
+  if (!dryRun) warnIfExternalWritesPaused(session, VERB_PAGES_DELETE);
+  const pagePath = normalizePagePath(invocation.deletePagePath);
+  if (pagePath === undefined) {
+    throw new SiteAuthoringError("pages.delete_path_invalid", "The page path is not usable.", {
+      field: "pagePath",
+      exitCode: 2,
+    });
+  }
+  const shown = displayPagePath(pagePath);
+  const manifest = await readManifest(config.workspaceDir, siteId);
+  const entry = trackedEntry(manifest, pagePath);
+  requireDeletable(manifest, entry, pagePath);
+  // A link or directory where a workspace file should be would fail the cleanup after the site delete, and
+  // every retry would meet it again, so it is refused before anything is sent.
+  const cleanupFiles = [
+    ...(typeof entry.file === "string" ? [entry.file] : []),
+    ...[internalPageBaselineFile(entry.pageId), internalPageObservedRevisionFile(entry.pageId)].filter(
+      (internal) => internal !== undefined,
+    ),
+  ];
+  for (const file of cleanupFiles) await workspaceFileExists(config.workspaceDir, file);
+
+  return await withRefusalGuidance(onProgress, "page delete", async () => {
+    onProgress(`Reading the site's pages to check '${shown}'.`);
+    const { pages, truncated } = await listSitePages(client, siteId, { onProgress });
+    const live = pages.find((summary) => summary.pageId === entry.pageId);
+    if (truncated && live === undefined) {
+      throw refusal(
+        "pages.delete_list_incomplete",
+        `The site has more pages than this CLI could list, so it cannot tell whether '${shown}' still exists. `
+          + "Nothing was deleted.",
+        shown,
+      );
+    }
+    const alreadyGone = live === undefined || isGonePage(live);
+    if (!alreadyGone) {
+      // The fence `pages push` uses, against the revision this workspace last reconciled with.
+      requireReconciledRevision({
+        file: entry.file ?? shown,
+        pagePath,
+        target: live,
+        entry,
+        observedRevision: (await readObservedPageRecord(config.workspaceDir, live.pageId))?.revision,
+        deleting: true,
+      });
+    }
+
+    const references = { navigation: [], footer: [], forms: [] };
+    let redirects = [];
+    if (!alreadyGone) {
+      onProgress("Checking what refers to the page.");
+      references.navigation = navigationItemsTo((await getNavigation(client, siteId)).navItems, live.resourceId);
+      references.footer = await footerLinks(config.workspaceDir, live.resourceId, shown);
+      references.forms = await formsSendingTo(config.workspaceDir, pagePath, live.resourceId);
+      if (references.navigation.length + references.footer.length + references.forms.length > 0) {
+        throw refusal(
+          "pages.delete_referenced",
+          `'${shown}' is still used by ${
+            [
+              references.navigation.length > 0 && `${references.navigation.length} navigation item(s)`,
+              references.footer.length > 0 && `${references.footer.length} footer link(s)`,
+              references.forms.length > 0 && `${references.forms.length} form(s)`,
+            ].filter(Boolean).join(", ")
+          }. Remove those first (edit nav.json and run 'nav push'; edit the footer and run 'footer push'; point `
+            + "the form's after_submit elsewhere and run 'forms push'), then delete the page. Nothing was deleted.",
+          shown,
+          [
+            ...references.navigation.map(({ at, title }) => `${at}${title === "" ? "" : ` (${title})`}`),
+            ...references.footer.map((label) => `footer: ${label}`),
+            ...references.forms,
+          ],
+        );
+      }
+      redirects = redirectsLandingOn((await getSiteRedirectMap(client, siteId)).entries, pagePath);
+    }
+
+    const report = {
+      page: {
+        path: shown,
+        ...(entry.file === undefined ? {} : { file: entry.file }),
+        pageId: entry.pageId,
+        title: entry.title,
+      },
+      // A page the live site serves stays live until a deployment removes it; the dry run predicts that from
+      // the status, and a real delete reads it from the site's answer.
+      // A page published and being edited looks the same as a restored draft that is not live, so only a
+      // PUBLISHED status predicts the staged removal; the ambiguous case names no effect until the site answers.
+      ...(alreadyGone
+        ? { effect: live?.removalStaged === true ? "alreadyRemovalStaged" : "alreadyDeleted" }
+        : live.status === PAGE_STATUS_PUBLISHED
+        ? { effect: "removalStaged" }
+        : servedLive(live)
+        ? {}
+        : { effect: "removed" }),
+      ...(live?.removalStaged === true ? { removalStaged: true } : {}),
+      ...(redirects.length === 0
+        ? {}
+        : {
+          redirectsToPage: boundedList(redirects, MAXIMUM_REPORTED).items,
+          redirectsToPageCount: redirects.length,
+        }),
+    };
+    if (redirects.length > 0) {
+      onProgress(
+        `${redirects.length} redirect(s) land on '${shown}' and will point at a missing page. `
+          + "Edit them with 'redirects pull' and 'redirects push', or leave them.",
+      );
+    }
+    if (dryRun) {
+      onProgress(
+        alreadyGone
+          ? `Dry run: '${shown}' is already ${
+            live?.removalStaged === true ? "staged for removal" : "gone from the site"
+          }; a delete would only clean the workspace.`
+          : live.status === PAGE_STATUS_PUBLISHED
+          ? `Dry run: '${shown}' is live, so deleting it stages its removal and it stays live until you deploy. `
+            + "Nothing was sent."
+          : servedLive(live)
+          ? `Dry run: '${shown}' has been published. If the site serves it, the delete stages its removal and it `
+            + "stays live until you deploy; otherwise it is deleted at once. Nothing was sent."
+          : `Dry run: '${shown}' would be deleted. Nothing was sent.`,
+      );
+      return successResult(VERB_PAGES_DELETE, siteId, { dryRun: true, ...report });
+    }
+
+    let removalStaged = false;
+    if (!alreadyGone) {
+      onProgress(`Deleting '${shown}'.`);
+      try {
+        removalStaged = (await deletePage(client, entry.pageId)).removalStaged;
+      } catch (error) {
+        // A reply that never arrived may still have deleted the page; the retry meets it already gone.
+        // A reply that arrived but cannot be read (api.page_contract) follows a delete the site may have run.
+        if (error instanceof SiteAuthoringError && (outcomeUnknown(error) || error.code === "api.page_contract")) {
+          throw error.withCompletedWrites([`page ${shown}: unknown`]);
+        }
+        throw error;
+      }
+    }
+
+    // The source goes with the page: left behind, a whole-workspace push would create it again.
+    try {
+      for (const file of cleanupFiles) await deleteWorkspaceFile(config.workspaceDir, file);
+      manifest.pages = manifest.pages.filter((candidate) => candidate !== entry);
+      await writeManifest(config.workspaceDir, manifest);
+    } catch (error) {
+      if (error instanceof SiteAuthoringError) {
+        throw error.withCompletedWrites([`page ${shown}: ${removalStaged ? "removal staged" : "deleted"}`]);
+      }
+      throw error;
+    }
+    onProgress(
+      removalStaged
+        ? `Removal staged for '${shown}': it stays live until you deploy. It is removed from the workspace.`
+        : `Deleted '${shown}' and removed it from the workspace.`,
+    );
+    return successResult(VERB_PAGES_DELETE, siteId, {
+      ...report,
+      // The effect the site reported, which a dry run could only predict.
+      ...(alreadyGone ? {} : { effect: removalStaged ? "removalStaged" : "removed" }),
+      // True only when the page is gone from the site now; a staged removal is still live, so read `effect`.
+      deleted: !alreadyGone && !removalStaged,
+      ...(removalStaged ? { removalStaged: true } : {}),
+      // Site writes only: a retry that finds the page already gone sends nothing.
+      ...(alreadyGone ? {} : { written: { items: [`page ${shown}`], count: 1 } }),
+      // A staged removal reaches the live site only through a deployment; a page deleted at once may have
+      // been in the staging candidate, which a new staging deploy refreshes.
+      nextStep: "deploy --staging",
+    });
+  });
+}

package/src/verbs/pages-push.js

@@ -1,10 +1,10 @@
 import {
   createPage,
   importVideoEmbedPoster,
+  isGonePage,
   listSitePages,
   listVideos,
   IMAGE_PROCESSING_STATE_COMPLETE,
-  PAGE_STATUS_DELETED,
   listSiteAuthors,
   posterFromImage,
   translateAuthorRefusal,
@@ -146,7 +146,7 @@ const OUTCOME_UNKNOWN_CODES = new Set([
   "api.page_contract",
 ]);
 
-function outcomeUnknown(error) {
+export function outcomeUnknown(error) {
   // A cancelled retry of a write, and a server error on a write the transport
   // does not replay, leave the same question open.
   return OUTCOME_UNKNOWN_CODES.has(error.code) || error.ambiguousMutation === true || error.httpStatus >= 500;
@@ -613,7 +613,7 @@ export async function readWorkspacePageSource({ workspaceDir, file, manifestEntr
  * Both leave this exactly where TR00622 left it, which is where the caller
  * already is.
  */
-function requireReconciledRevision({ file, pagePath, target, entry, observedRevision }) {
+export function requireReconciledRevision({ file, pagePath, target, entry, observedRevision, deleting = false }) {
   // What the operator was shown by a refused pull outranks what the manifest
   // last reconciled with. Without that, this guard would also refuse the pull
   // conflict's own documented recovery, and the only way out of a conflict
@@ -622,12 +622,16 @@ function requireReconciledRevision({ file, pagePath, target, entry, observedRevi
   const live = target.bodyRevision;
   if (recorded === undefined || live === undefined || recorded === live) return;
   const selector = pagePath || "/";
+  // `pages delete` shares the fence (TR01226): the same code, with the way out that fits a delete.
+  const outcome = deleting
+    ? `No page was deleted. Run 'taproot-site pull' to see what differs and to adopt the site's version, then `
+      + "decide again."
+    : `No page was pushed. Run 'taproot-site pull' to see what differs and to adopt the site's version, or delete `
+      + `'${file}' and pull again to take the site's document as this page's source.`;
   throw new SiteAuthoringError(
     "pages.push_conflict",
     `Page '${selector}' changed on the site since this workspace last reconciled with it: it now reports revision `
-      + `${live}, and '${file}' was written against ${recorded}. No page was pushed. Run `
-      + `'taproot-site pull' to see what differs and to adopt the site's version, or delete '${file}' and pull `
-      + "again to take the site's document as this page's source.",
+      + `${live}, and '${file}' was written against ${recorded}. ${outcome}`,
     { field: file, alternatives: [recorded, live] },
   );
 }
@@ -1110,7 +1114,7 @@ export async function planPages({
   if (problems.length > 0) {
     return { targeted, sources: [], selected: [], planned: [], unresolved: [], staleGenerated, problems };
   }
-  const live = livePages.filter((summary) => summary.status !== PAGE_STATUS_DELETED);
+  const live = livePages.filter((summary) => !isGonePage(summary));
   const liveById = new Map(live.map((summary) => [summary.pageId, summary]));
   const liveByPath = new Map(live.map((summary) => [normalizePagePath(summary.path) ?? summary.path, summary]));
   const manifestByFile = new Map(