@taprootio/site-authoring 0.23.1 → 0.26.0

package/src/verbs/login.js

@@ -22,6 +22,7 @@ import {
   VERB_LOGIN,
   VERB_LOGOUT,
   VERB_SITES,
+  SURFACE_STANDARD,
 } from "../constants.js";
 import { assertCredentialCapacity, credentialApiOrigin, saveCredential } from "../credentials.js";
 import { asSiteAuthoringError, hasControlCharacter, SiteAuthoringError } from "../errors.js";
@@ -156,7 +157,7 @@ function describeMinutes(milliseconds) {
  * revoked — named by its exact id and display prefix when the server supplied
  * them, and by its display name otherwise.
  */
-function terminalFailure(answer, keyName) {
+function terminalFailure(answer, keyName, loginCommand) {
   const status = answer.status;
   switch (status) {
     case CLI_AUTHORIZATION_CLAIM_STATUS_DENIED:
@@ -168,7 +169,7 @@ function terminalFailure(answer, keyName) {
     case CLI_AUTHORIZATION_CLAIM_STATUS_EXPIRED:
       return new SiteAuthoringError(
         "login.expired",
-        `The authorization expired before it was approved. Run '${CLI_BINARY_NAME} ${VERB_LOGIN}' again.`,
+        `The authorization expired before it was approved. Run '${loginCommand}' again.`,
         { status },
       );
     case CLI_AUTHORIZATION_CLAIM_STATUS_CONSUMED:
@@ -179,7 +180,7 @@ function terminalFailure(answer, keyName) {
             ? `Revoke the credential with id ${answer.keyId}`
             + (answer.keyPrefix === undefined ? "" : ` (display prefix ${answer.keyPrefix})`)
             : `Revoke the credential named '${keyName}'`)
-          + ` under Account -> Settings -> API keys, then run '${CLI_BINARY_NAME} ${VERB_LOGIN}' again.`,
+          + ` under Account -> Settings -> API keys, then run '${loginCommand}' again.`,
         { status },
       );
     default:
@@ -191,11 +192,11 @@ function terminalFailure(answer, keyName) {
   }
 }
 
-function translateClaimApiError(error) {
+function translateClaimApiError(error, loginCommand) {
   if (!(error instanceof ApiError) || error.httpStatus !== 404) return error;
   return new SiteAuthoringError(
     "login.unknown",
-    `Taproot does not recognize this authorization. Run '${CLI_BINARY_NAME} ${VERB_LOGIN}' to start a new one.`,
+    `Taproot does not recognize this authorization. Run '${loginCommand}' to start a new one.`,
     { status: error.status },
   );
 }
@@ -222,13 +223,13 @@ function translateStartApiError(error) {
  * display prefix, never by value — and direct the owner to revoke it, because
  * silence here is a live credential the owner does not know exists.
  */
-function unstoredCredentialFailure(error, claimed) {
+function unstoredCredentialFailure(error, claimed, loginCommand) {
   const cause = asSiteAuthoringError(error);
   return new SiteAuthoringError(
     "login.credential_unstored",
     `A credential WAS issued (id ${claimed.keyId}, display prefix ${claimed.keyPrefix}) but could not `
       + `be stored: ${cause.message} Revoke it under Account -> Settings -> API keys, then run `
-      + `'${CLI_BINARY_NAME} ${VERB_LOGIN}' again.`,
+      + `'${loginCommand}' again.`,
     { ...(cause.status === undefined ? {} : { status: cause.status }) },
   );
 }
@@ -311,7 +312,12 @@ async function handOffToBrowser({ verificationUrl, userCode, onProgress, awaitEn
 
 export async function login(invocation) {
   const keyName = normalizeKeyName(invocation.keyName);
-  const { apiBaseUrl, client, now, onProgress } = await openAnonymousSession(invocation);
+  const { config, apiBaseUrl, client, now, onProgress } = await openAnonymousSession(invocation);
+  const legalDraftSiteId = invocation.legalDrafts ? config?.siteId : undefined;
+  if (invocation.legalDrafts && (!legalDraftSiteId || (config.authoringSurface !== undefined && config.authoringSurface !== SURFACE_STANDARD))) {
+    throw new SiteAuthoringError("auth.legal_site_required", "Select a standard site with taproot-site use before requesting legal draft access.");
+  }
+  const loginCommand = `${CLI_BINARY_NAME} ${VERB_LOGIN}${legalDraftSiteId === undefined ? "" : " --legal-drafts"}`;
   const environment = invocation.environment ?? process.env;
   const apiOrigin = credentialApiOrigin(apiBaseUrl);
 
@@ -323,11 +329,11 @@ export async function login(invocation) {
   // now rather than at the write, which is the same failure arriving after the
   // damage. A residual write failure can still happen (the disk can fill during
   // the poll), which is what `unstoredCredentialFailure` below is for.
-  await assertCredentialCapacity(environment, apiOrigin);
+  await assertCredentialCapacity(environment, apiOrigin, { siteId: legalDraftSiteId });
 
   let authorization;
   try {
-    authorization = await startCliAuthorization(client, { keyName });
+    authorization = await startCliAuthorization(client, { keyName, legalDraftSiteId });
   } catch (error) {
     // Announced only when the refusal survives translation: sign-in is the
     // earlier of the two calls that carry this CLI's version, so it is where
@@ -390,7 +396,7 @@ export async function login(invocation) {
       // total wall time.
       read: async () => {
         try {
-          return await claimCliAuthorization(client, authorization.deviceCode);
+          return await claimCliAuthorization(client, authorization.deviceCode, {}, { legalDraftSiteId, now });
         } catch (error) {
           // A throttle is the endpoint doing its job, not a verdict on this
           // authorization. Back off within the same deadline instead of
@@ -441,7 +447,7 @@ export async function login(invocation) {
             if (error.ambiguousMutation === true) claimResponseLost = true;
             throw error;
           }
-          throw translateClaimApiError(error);
+          throw translateClaimApiError(error, loginCommand);
         }
       },
       evaluate: (value) => {
@@ -464,7 +470,7 @@ export async function login(invocation) {
           // each line pushes the code the operator is still reading off screen.
           return { done: false };
         }
-        throw terminalFailure(value, keyName);
+        throw terminalFailure(value, keyName, loginCommand);
       },
       // A deadline reached after a lost answer cannot honestly say nothing was
       // issued: one of those lost checks may have consumed the approval and
@@ -477,12 +483,12 @@ export async function login(invocation) {
             "The polling deadline passed, and at least one check's answer was lost in transit — a credential "
               + `MAY have been issued without this command receiving it. Nothing was stored locally; check `
               + `Account -> Settings -> API keys for a credential named '${keyName}' and revoke it before running `
-              + `'${CLI_BINARY_NAME} ${VERB_LOGIN}' again.`,
+              + `'${loginCommand}' again.`,
           )
           : new SiteAuthoringError(
             "login.timeout",
             "The approval was not completed before this command's polling deadline. Nothing was stored; "
-              + `run '${CLI_BINARY_NAME} ${VERB_LOGIN}' again.`,
+              + `run '${loginCommand}' again.`,
           ),
     });
   } catch (error) {
@@ -498,9 +504,12 @@ export async function login(invocation) {
         "site.cancelled",
         "The login was cancelled after a claim's answer was lost — a credential MAY have been issued without "
           + `this command receiving it. Check Account -> Settings -> API keys for a credential named '${keyName}' `
-          + `and revoke it before running '${CLI_BINARY_NAME} ${VERB_LOGIN}' again.`,
+          + `and revoke it before running '${loginCommand}' again.`,
       );
     }
+    if (error instanceof SiteAuthoringError && error.code === "site.cancelled" && legalDraftSiteId !== undefined) {
+      throw new SiteAuthoringError("site.cancelled", `${error.message} Run '${loginCommand}' again.`);
+    }
     throw error;
   }
 
@@ -510,6 +519,7 @@ export async function login(invocation) {
       environment,
       {
         apiOrigin,
+        ...(legalDraftSiteId === undefined ? {} : { purpose: claimed.purpose, siteId: claimed.siteId, capabilities: claimed.capabilities, legalDraftPlatformSite: claimed.legalDraftPlatformSite }),
         accountId: claimed.accountId,
         key: claimed.key,
         keyId: claimed.keyId,
@@ -519,7 +529,13 @@ export async function login(invocation) {
       { now },
     );
   } catch (error) {
-    throw unstoredCredentialFailure(error, claimed);
+    throw unstoredCredentialFailure(error, claimed, loginCommand);
+  }
+  if (legalDraftSiteId !== undefined) {
+    onProgress(`Stored legal draft access for site ${legalDraftSiteId} in ${credentialPath}. The credential itself is never displayed.`);
+    onProgress(`Use '${CLI_BINARY_NAME} --legal-drafts pages push' to save drafts; approve and publish them in Taproot.`);
+    onProgress(`Discard this local grant with '${CLI_BINARY_NAME} --legal-drafts ${VERB_LOGOUT}'; revoke it in Account -> Settings -> API keys.`);
+    return successResult(VERB_LOGIN, legalDraftSiteId, { accountId: claimed.accountId, keyId: claimed.keyId, keyPrefix: claimed.keyPrefix, keyExpiresAt: claimed.keyExpiresAt, userCode: authorization.userCode, verificationUrl, credentialPath, legalDrafts: true });
   }
   onProgress(`Stored the sign-in in ${credentialPath}. The credential itself is never displayed.`);
   onProgress(`Run '${CLI_BINARY_NAME} ${VERB_SITES}' to see the sites you can author.`);

package/src/verbs/logout.js

@@ -1,6 +1,7 @@
 import { CLI_BINARY_NAME, VERB_LOGOUT } from "../constants.js";
 import { credentialApiOrigin, removeCredential } from "../credentials.js";
 import { openAnonymousSession, successResult } from "../session.js";
+import { SiteAuthoringError } from "../errors.js";
 
 /**
  * `taproot-site logout` — local discard, and nothing more.
@@ -19,11 +20,20 @@ import { openAnonymousSession, successResult } from "../session.js";
  * discards is addressed by API origin.
  */
 export async function logout(invocation) {
-  const { apiBaseUrl, onProgress } = await openAnonymousSession(invocation);
+  const { config, apiBaseUrl, onProgress } = await openAnonymousSession(invocation);
+  if (invocation.legalDrafts && !config?.siteId) {
+    throw new SiteAuthoringError("config.site_missing", "Select a site before discarding its legal draft grant.");
+  }
   const { path: credentialPath, removed } = await removeCredential(
     invocation.environment ?? process.env,
     credentialApiOrigin(apiBaseUrl),
+    { siteId: invocation.legalDrafts ? config.siteId : undefined },
   );
+  if (invocation.legalDrafts) {
+    onProgress(removed ? `Discarded the legal draft grant for site ${config.siteId} from ${credentialPath}.` : `No legal draft grant for site ${config.siteId} was found in ${credentialPath}.`);
+    if (removed) onProgress("This is a local discard; revoke the credential in Account -> Settings -> API keys.");
+    return successResult(VERB_LOGOUT, config.siteId, { removed, credentialPath, legalDrafts: true });
+  }
   onProgress(
     removed
       ? `Discarded the stored Taproot sign-in from ${credentialPath}.`
@@ -35,5 +45,9 @@ export async function logout(invocation) {
         + `Account -> Settings -> API keys; '${CLI_BINARY_NAME} ${VERB_LOGOUT}' cannot revoke it.`,
     );
   }
+  onProgress(
+    "Separate site legal draft grants, if any, remain stored. Select each site and run "
+      + `'${CLI_BINARY_NAME} --legal-drafts ${VERB_LOGOUT}' to discard its grant, or revoke the keys in Account -> Settings -> API keys.`,
+  );
   return successResult(VERB_LOGOUT, undefined, { removed, credentialPath });
 }

package/src/verbs/marketing-pull.js

@@ -0,0 +1,80 @@
+import { withRefusalGuidance } from "../api.js";
+import { VERB_MARKETING_PULL } from "../constants.js";
+import { listMarketingRecords } from "../marketing-api.js";
+import {
+  MARKETING_KIND_NAMES,
+  MARKETING_KINDS,
+  projectMarketingDocument,
+} from "../marketing-contract.js";
+import { baselineEntry, withRecordedMarketing } from "../marketing-workspace.js";
+import { boundedList, openSession, successResult } from "../session.js";
+import { readManifest, writeManifest, writeWorkspaceJson } from "../workspace.js";
+
+const MAXIMUM_REPORTED = 200;
+
+/** The archived keys, bounded like the live ones so a site with thousands of them still fits the result. */
+function archivedSummary(keys) {
+  const reported = boundedList(keys, MAXIMUM_REPORTED);
+  return {
+    archived: reported.items,
+    archivedTotal: keys.length,
+    ...(reported.truncated ? { archivedTruncated: true } : {}),
+  };
+}
+
+/**
+ * `marketing pull` — write the site's live campaigns and placements and record what was read.
+ *
+ * It replaces each file with the site's state, so a local edit that was never pushed is replaced; that is what
+ * pull means everywhere else in this CLI. Archived records are listed and not written: a record the site has
+ * archived keeps its key for ever, and a file that names the key asks for it to be restored. The baseline it
+ * records is what `marketing push` fences against.
+ */
+export async function marketingPull(invocation) {
+  const { client, config, siteId, onProgress } = await openSession(invocation);
+  // The manifest is the pulled workspace this baseline belongs to, the same precondition every push has.
+  let manifest = await readManifest(config.workspaceDir, siteId);
+
+  // Both kinds are read before either file is written, so a refusal on the second never leaves a first file
+  // without its baseline.
+  const listings = new Map();
+  for (const kind of MARKETING_KIND_NAMES) {
+    listings.set(
+      kind,
+      await withRefusalGuidance(
+        onProgress,
+        "marketing pull",
+        async () => await listMarketingRecords(client, siteId, kind),
+      ),
+    );
+  }
+
+  const summary = {};
+  for (const [kind, listing] of listings) {
+    const { file, noun } = MARKETING_KINDS[kind];
+    const live = listing.records.filter((record) => !record.archived);
+    const archived = listing.records.filter((record) => record.archived).map((record) => record.key).sort();
+    await writeWorkspaceJson(config.workspaceDir, file, projectMarketingDocument(kind, live));
+    manifest = withRecordedMarketing(
+      manifest,
+      kind,
+      listing.records.map((record) => [record.key, baselineEntry(kind, record)]),
+    );
+    const reported = boundedList(
+      live.map((record) => ({ key: record.key, state: record.state })).sort((left, right) => left.key < right.key ? -1 : 1),
+      MAXIMUM_REPORTED,
+    );
+    summary[kind] = {
+      file,
+      total: live.length,
+      items: reported.items,
+      ...(reported.truncated ? { itemsTruncated: true } : {}),
+      ...(archived.length > 0 ? archivedSummary(archived) : {}),
+      canManage: listing.canManage,
+      ...(listing.maxActive === undefined ? {} : { maxActive: listing.maxActive }),
+    };
+    onProgress(`Wrote ${file} with ${live.length} ${noun}${live.length === 1 ? "" : "s"}.`);
+  }
+  await writeManifest(config.workspaceDir, manifest);
+  return successResult(VERB_MARKETING_PULL, siteId, { marketing: summary });
+}

package/src/verbs/marketing-push.js

@@ -0,0 +1,250 @@
+import { randomUUID } from "node:crypto";
+
+import { withRefusalGuidance } from "../api.js";
+import { VERB_MARKETING_PULL, VERB_MARKETING_PUSH } from "../constants.js";
+import { SiteAuthoringError } from "../errors.js";
+import {
+  createMarketingRecord,
+  listMarketingRecords,
+  setMarketingRecordArchived,
+  updateMarketingRecord,
+  withSiteWording,
+} from "../marketing-api.js";
+import { MARKETING_KINDS, projectMarketingDocument } from "../marketing-contract.js";
+import {
+  baselineEntry,
+  readWorkspaceMarketing,
+  recordedMarketing,
+  sameLabels,
+  withRecordedMarketing,
+} from "../marketing-workspace.js";
+import { openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
+import { readManifest, writeManifest, writeWorkspaceJson } from "../workspace.js";
+
+const MAXIMUM_REPORTED = 50;
+
+function pullRequired(kind, key, reason) {
+  const { file } = MARKETING_KINDS[kind];
+  return new SiteAuthoringError(
+    "marketing.pull_required",
+    `${file}: ${reason} Run '${VERB_MARKETING_PULL}', reconcile '${key}', and retry. Nothing was written.`,
+    { field: `${file}:${key}` },
+  );
+}
+
+/**
+ * Whether a recorded baseline already says what the site's record says, including its state: a release that
+ * finished since the last write moves a key from publishing to live, and the file is rewritten with that, so the
+ * baseline `link build` reads must follow it.
+ */
+function currentBaseline(recorded, remote, kind) {
+  return recorded !== undefined && recorded.id === remote.id && recorded.archived === remote.archived
+    && recorded.state === remote.state && sameLabels(kind, recorded, remote);
+}
+
+function changedOnTheSite(kind, key) {
+  const { file, noun } = MARKETING_KINDS[kind];
+  return new SiteAuthoringError(
+    "marketing.concurrent_modification",
+    `${file}: the ${noun} '${key}' changed on the site after this workspace read it. Run '${VERB_MARKETING_PULL}', `
+      + "reconcile the file, and retry. Nothing was written.",
+    { field: `${file}:${key}` },
+  );
+}
+
+/**
+ * Decides what one kind needs, from the file, the site's records and the baseline the last pull recorded.
+ * Throws before anything is written.
+ *
+ * A key is public URL text and never changes or returns to use, so a changed key in the file is a new record
+ * (a create) and the old one is only archived when the push says so. A record the file leaves out is archived
+ * only under --archive, and only when this workspace pulled it: a record the workspace never saw is reported,
+ * never touched.
+ */
+function planKind(kind, fileRecords, remoteRecords, baseline, archive) {
+  const remoteByKey = new Map(remoteRecords.map((record) => [record.key, record]));
+  const actions = [];
+  const named = new Set();
+  for (const desired of fileRecords) {
+    named.add(desired.key);
+    const remote = remoteByKey.get(desired.key);
+    const recorded = baseline.get(desired.key);
+    if (remote === undefined) {
+      if (recorded !== undefined) {
+        throw pullRequired(kind, desired.key, "This workspace recorded it, but the site no longer has it.");
+      }
+      actions.push({ type: "create", key: desired.key, desired });
+      continue;
+    }
+    // A write whose answer was lost leaves the site holding what the file asks for while the baseline is stale
+    // (or missing, for a create). Nothing needs writing then, so the site's record is adopted as the baseline
+    // rather than sending the author to a pull that would discard the file's other edits.
+    if (!remote.archived && sameLabels(kind, desired, remote)) {
+      actions.push({ type: "unchanged", key: desired.key, desired, remote, adopt: true });
+      continue;
+    }
+    if (recorded === undefined) {
+      throw pullRequired(kind, desired.key, "The site already has one with this key that this workspace never pulled.");
+    }
+    // An archived record whose labels already equal the file's had its update land before a restore whose answer
+    // was lost; the restore is all that is left, so the drift from the baseline is this push's own.
+    const ownUpdate = remote.archived && sameLabels(kind, desired, remote);
+    if (recorded.id !== remote.id || recorded.archived !== remote.archived || (!ownUpdate && !sameLabels(kind, recorded, remote))) {
+      throw changedOnTheSite(kind, desired.key);
+    }
+    const labelsChanged = !sameLabels(kind, desired, remote);
+    if (remote.archived) {
+      actions.push({ type: "restore", key: desired.key, desired, remote, labelsChanged });
+    } else {
+      actions.push({ type: labelsChanged ? "update" : "unchanged", key: desired.key, desired, remote });
+    }
+  }
+
+  const unlisted = [];
+  const unpulled = [];
+  for (const remote of remoteRecords) {
+    if (named.has(remote.key) || remote.archived) continue;
+    const recorded = baseline.get(remote.key);
+    if (recorded === undefined) {
+      unpulled.push(remote.key);
+      continue;
+    }
+    if (!archive) {
+      unlisted.push(remote.key);
+      continue;
+    }
+    if (recorded.id !== remote.id || recorded.archived !== remote.archived || !sameLabels(kind, recorded, remote)) {
+      throw changedOnTheSite(kind, remote.key);
+    }
+    actions.push({ type: "archive", key: remote.key, remote });
+  }
+  return { actions, unlisted: unlisted.sort(), unpulled: unpulled.sort() };
+}
+
+/**
+ * `marketing push` — make the site's campaigns and placements match the workspace's files.
+ *
+ * Every file is validated and every record compared with the site before the first write, so a conflict on the
+ * third record refuses the whole push rather than landing two. Archives run first, so a push that swaps a key
+ * for a new one stays inside the site's quota. Each write advances the baseline straight away, so a failure
+ * partway leaves a workspace the next push can resume from. Creating or restoring a key queues the silent
+ * release that starts counting it; this verb waits for nothing.
+ *
+ * There is no plan/apply step. Like the forms push it models, it reads the site, refuses a stale baseline, and
+ * writes; there is no remote state to freeze that the baseline does not already fence.
+ */
+export async function marketingPush(invocation) {
+  const session = await openSession(invocation);
+  const { client, config, siteId, onProgress } = session;
+  warnIfExternalWritesPaused(session, VERB_MARKETING_PUSH);
+  const archive = invocation.archive === true;
+
+  const files = await readWorkspaceMarketing(config.workspaceDir);
+  if (files.size === 0) {
+    throw new SiteAuthoringError(
+      "marketing.file_missing",
+      "The workspace has no marketing/campaigns.json or marketing/placements.json. "
+        + `Run '${VERB_MARKETING_PULL}' to write them.`,
+      { field: "marketing" },
+    );
+  }
+  onProgress(`Validated ${[...files.keys()].map((kind) => MARKETING_KINDS[kind].file).join(" and ")}.`);
+  let manifest = await readManifest(config.workspaceDir, siteId);
+
+  const plans = new Map();
+  for (const [kind, records] of files) {
+    const listing = await withRefusalGuidance(
+      onProgress,
+      "marketing push",
+      async () => await listMarketingRecords(client, siteId, kind),
+    );
+    plans.set(kind, { ...planKind(kind, records, listing.records, recordedMarketing(manifest, kind), archive), remote: listing.records });
+  }
+
+  const results = {};
+  let changedCount = 0;
+  const completedWrites = [];
+  for (const [kind, plan] of plans) {
+    const { noun } = MARKETING_KINDS[kind];
+    const baseline = recordedMarketing(manifest, kind);
+    // What the site holds for each key after the writes, so the file and the baseline are written from it.
+    const view = new Map(plan.remote.map((record) => [record.key, record]));
+    const applied = { created: [], updated: [], restored: [], archived: [], unchanged: [] };
+
+    const write = async (action, verb, work) => {
+      let label;
+      try {
+        label = await withRefusalGuidance(onProgress, "marketing push", work);
+      } catch (caught) {
+        const error = withSiteWording(caught, kind, action.key);
+        if (error instanceof SiteAuthoringError && completedWrites.length > 0) {
+          throw error.withCompletedWrites(completedWrites);
+        }
+        throw error;
+      }
+      completedWrites.push(`${kind}:${action.key}:${verb}`);
+      view.set(action.key, label);
+      baseline.set(action.key, baselineEntry(kind, label));
+      manifest = withRecordedMarketing(manifest, kind, baseline);
+      await writeManifest(config.workspaceDir, manifest);
+      onProgress(`${action.key}: ${verb} the ${noun}.`);
+    };
+
+    for (const action of plan.actions.filter((candidate) => candidate.adopt && !currentBaseline(baseline.get(candidate.key), candidate.remote, kind))) {
+      baseline.set(action.key, baselineEntry(kind, action.remote));
+      manifest = withRecordedMarketing(manifest, kind, baseline);
+      await writeManifest(config.workspaceDir, manifest);
+    }
+
+    // Archives first, so swapping a key for a new one stays inside the quota; creates last.
+    for (const action of plan.actions.filter((candidate) => candidate.type === "archive")) {
+      await write(action, "archived", () => setMarketingRecordArchived(client, siteId, kind, action.remote.id, true));
+      applied.archived.push(action.key);
+    }
+    for (const action of plan.actions.filter((candidate) => candidate.type === "update" || candidate.labelsChanged)) {
+      await write(action, "updated", () => updateMarketingRecord(client, siteId, kind, action.remote.id, action.desired));
+      // A restore that also changes labels is reported as a restore.
+      if (action.type === "update") applied.updated.push(action.key);
+    }
+    for (const action of plan.actions.filter((candidate) => candidate.type === "restore")) {
+      await write(action, "restored", () => setMarketingRecordArchived(client, siteId, kind, action.remote.id, false));
+      applied.restored.push(action.key);
+    }
+    for (const action of plan.actions.filter((candidate) => candidate.type === "create")) {
+      await write(action, "created", () => createMarketingRecord(client, siteId, kind, randomUUID(), action.desired));
+      applied.created.push(action.key);
+    }
+    applied.unchanged = plan.actions.filter((action) => action.type === "unchanged").map((action) => action.key);
+
+    // The file is rewritten from what the site now holds, in canonical form, so the workspace and the site
+    // agree byte for byte and the read-only state and counted_from are current.
+    const kept = plan.actions.filter((action) => action.type !== "archive").map((action) => view.get(action.key));
+    await writeWorkspaceJson(config.workspaceDir, MARKETING_KINDS[kind].file, projectMarketingDocument(kind, kept));
+    // Every list is bounded so a site with thousands of records still fits the result; `counts` says how many.
+    const lists = { ...applied, unlisted: plan.unlisted, unpulled: plan.unpulled };
+    const capped = Object.entries(lists).filter(([, keys]) => keys.length > MAXIMUM_REPORTED).map(([name]) => name);
+    results[kind] = {
+      ...Object.fromEntries(Object.entries(lists).map(([name, keys]) => [name, keys.slice(0, MAXIMUM_REPORTED)])),
+      counts: Object.fromEntries(Object.entries(lists).map(([name, keys]) => [name, keys.length])),
+      ...(capped.length > 0 ? { truncated: capped } : {}),
+    };
+    changedCount += applied.created.length + applied.updated.length + applied.restored.length + applied.archived.length;
+  }
+
+  const changed = Object.entries(results).flatMap(([kind, value]) =>
+    ["created", "updated", "restored", "archived"].flatMap((name) => value[name].map((key) => `${kind}:${key}`))
+  );
+  for (const [kind, value] of Object.entries(results)) {
+    if (value.counts.unlisted > 0) {
+      onProgress(
+        `${MARKETING_KINDS[kind].file}: left ${value.unlisted.slice(0, 20).join(", ")}`
+          + `${value.counts.unlisted > 20 ? ` and ${value.counts.unlisted - 20} more` : ""} on the site because the file `
+          + "omits it. Push with --archive to archive a record the file leaves out.",
+      );
+    }
+  }
+  return successResult(VERB_MARKETING_PUSH, siteId, {
+    marketing: results,
+    written: { items: changed, count: changedCount, ...(changed.length < changedCount ? { itemsTruncated: true } : {}) },
+  });
+}

package/src/verbs/pages-delete.js

@@ -14,7 +14,7 @@ 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 { isAuthorableTemplateType, isGeneratedTemplateType, isLegalTemplateType } from "../typed-pages.js";
 import {
   deleteWorkspaceFile,
   displayPagePath,
@@ -194,10 +194,10 @@ function requireDeletable(manifest, entry, pagePath) {
       shown,
     );
   }
-  if (!isAuthorableTemplateType(entry.templateType)) {
+  if (isLegalTemplateType(entry.templateType) || !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}' is a ${entry.templateType ?? "system-managed"} page, which this CLI cannot delete; delete it in the app.`,
       shown,
     );
   }
@@ -241,6 +241,9 @@ export async function pagesDelete(invocation) {
         shown,
       );
     }
+    if (live !== undefined && isLegalTemplateType(live.templateType)) {
+      throw refusal("pages.delete_not_authorable", `'${shown}' is a legal page; delete it in the app.`, shown);
+    }
     const alreadyGone = live === undefined || isGonePage(live);
     if (!alreadyGone) {
       // The fence `pages push` uses, against the revision this workspace last reconciled with.