@taprootio/site-authoring 0.24.0 → 0.27.0

package/src/verbs/link-build.js

@@ -0,0 +1,195 @@
+import { listAuthorableSites, withRefusalGuidance } from "../api.js";
+import { CLI_BINARY_NAME, VERB_LINK_BUILD, VERB_LOGIN } from "../constants.js";
+import { sanitizeDiagnostic, SiteAuthoringError } from "../errors.js";
+import { listMarketingRecords } from "../marketing-api.js";
+import {
+  isMarketingKey,
+  LINK_SOURCES,
+  MARKETING_KINDS,
+  MARKETING_STATES,
+  MARKETING_STATE_ARCHIVED,
+  MARKETING_KEY_RULE,
+  notLiveNote,
+} from "../marketing-contract.js";
+import { readWorkspaceMarketing, recordedMarketing } from "../marketing-workspace.js";
+import {
+  openAccountSession,
+  openAnonymousSession,
+  openSession,
+  requireRecordedSurface,
+  successResult,
+} from "../session.js";
+import { readManifest } from "../workspace.js";
+import { ENGAGEMENT_HOST_PATTERN, normalizeSitePath, trackedAddress } from "../utm-link.js";
+
+function invalidOption(code, message, field) {
+  return new SiteAuthoringError(code, message, { field, exitCode: 2 });
+}
+
+/** The site's public host: the one given, or the signed-in account's record of the configured site. */
+async function resolveHost(invocation, config) {
+  if (invocation.linkDomain !== undefined) {
+    const host = invocation.linkDomain.trim().toLowerCase();
+    if (!ENGAGEMENT_HOST_PATTERN.test(host)) {
+      throw invalidOption("link.domain_invalid", "--domain is the site's public host name, such as example.com, without a scheme or path.", "domain");
+    }
+    return host;
+  }
+  let sites;
+  try {
+    const account = await openAccountSession(invocation);
+    sites = await withRefusalGuidance(account.onProgress, "site list", async () => await listAuthorableSites(account.client));
+  } catch (error) {
+    if (error instanceof SiteAuthoringError && error.code === "auth.key_missing") {
+      throw new SiteAuthoringError(
+        "link.domain_unknown",
+        `A link needs the site's public host, which comes from the signed-in site. Run '${CLI_BINARY_NAME} ${VERB_LOGIN}', `
+          + "or pass --domain <host>: a site credential cannot read hosting configuration.",
+        { field: "domain" },
+      );
+    }
+    throw error;
+  }
+  const host = sites.find((site) => site.siteId === config.siteId)?.primaryDomain ?? "";
+  if (host === "") {
+    throw new SiteAuthoringError(
+      "link.no_public_address",
+      "This site does not have a public address yet, so there is nothing to build a link to. "
+        + "Set it in Settings, Licence & domain, or pass --domain <host>.",
+      { field: "domain" },
+    );
+  }
+  return host.toLowerCase();
+}
+
+/**
+ * The campaign or placement a link names. The state comes from the baseline the last pull or push recorded in the
+ * manifest when the workspace holds this kind's file and a known, unarchived state was recorded for the key; in every
+ * other case the live site is asked. (A file's own `state` is only what the author left there, so it is never used.)
+ * A key the site does not hold is not counted, so it is refused rather than printed; an archived key is no longer
+ * admitted, so it is refused the same way.
+ */
+async function findRecord(kind, key, files, invocation, config) {
+  const { noun, file } = MARKETING_KINDS[kind];
+  const fromFile = files.get(kind);
+  if (fromFile !== undefined) {
+    const record = fromFile.find((candidate) => candidate.key === key);
+    if (record === undefined) {
+      throw new SiteAuthoringError(
+        `link.${noun}_unknown`,
+        `${file} has no ${noun} '${key}'. Run 'marketing pull' if it was made since, or add it to the file and `
+          + "run 'marketing push': a key the site does not hold is not counted.",
+        { field: noun },
+      );
+    }
+    // The state a pull or push recorded for this key is the one to report. A key with no baseline entry (made or
+    // restored in the app and then added to the file), an archived entry, or an entry with no known state is not
+    // known to be live, so the site is asked, and it refuses a key it does not hold.
+    const manifest = await readManifest(config.workspaceDir, config.siteId, { required: false });
+    const recorded = manifest === undefined ? undefined : recordedMarketing(manifest, kind).get(key);
+    if (
+      recorded !== undefined && !recorded.archived && MARKETING_STATES.includes(recorded.state)
+      && recorded.state !== MARKETING_STATE_ARCHIVED
+    ) {
+      return { name: record.name, state: recorded.state, fromFile: file };
+    }
+  }
+  const session = await openSession(invocation);
+  const listing = await withRefusalGuidance(
+    session.onProgress,
+    "link build",
+    async () => await listMarketingRecords(session.client, session.siteId, kind),
+  );
+  const record = listing.records.find((candidate) => candidate.key === key);
+  if (record === undefined || record.state === MARKETING_STATE_ARCHIVED) {
+    throw new SiteAuthoringError(
+      `link.${noun}_unknown`,
+      `The site has no ${record === undefined ? "" : "unarchived "}${noun} '${key}'. A key the site does not hold is `
+        + "not counted. Create it with 'marketing push' (or restore it by naming it in the file).",
+      { field: noun },
+    );
+  }
+  return { name: record.name, state: record.state };
+}
+
+/**
+ * `link build` — print one tracked address and save nothing.
+ *
+ * It runs the Marketing link builder's own rules (compiled into `utm-link.js`) and its source vocabulary, so an
+ * address built here counts exactly as one built in the app. A campaign or placement that is not live yet is
+ * allowed, with the builder's note that page views count under the source only until it is.
+ */
+export async function linkBuild(invocation) {
+  const { linkPath, linkSource, linkCampaign, linkPlacement } = invocation;
+  if (linkPath === undefined) {
+    throw invalidOption("link.path_missing", "link build needs --path, the page on this site; use / for the home page.", "path");
+  }
+  if (linkSource === undefined) {
+    throw invalidOption("link.source_missing", `link build needs --source, one of: ${LINK_SOURCES.map((source) => source.key).join(", ")}.`, "source");
+  }
+  const source = LINK_SOURCES.find((candidate) => candidate.key === linkSource);
+  if (source === undefined) {
+    throw new SiteAuthoringError(
+      "link.source_unknown",
+      linkSource === "reader"
+        ? "The reader source is set by a published page's own share action and cannot be built here."
+        : `'${linkSource}' is not a source. Use one of: ${LINK_SOURCES.map((candidate) => candidate.key).join(", ")}.`,
+      { field: "source", exitCode: 2, alternatives: LINK_SOURCES.map((candidate) => candidate.key) },
+    );
+  }
+  for (const [field, value] of [["campaign", linkCampaign], ["placement", linkPlacement]]) {
+    if (value !== undefined && !isMarketingKey(value)) {
+      throw invalidOption("link.key_invalid", `--${field} is a key of ${MARKETING_KEY_RULE}.`, field);
+    }
+  }
+
+  const { config, onProgress } = await openAnonymousSession({ ...invocation, client: null });
+  if (config?.siteId === undefined) {
+    throw new SiteAuthoringError(
+      "config.site_missing",
+      `No site is selected. Run '${CLI_BINARY_NAME} use <site>' to choose one, or set siteId in taproot-site.json.`,
+    );
+  }
+  // Offline, like every other verb: a site that cannot take it is told so before any request.
+  requireRecordedSurface(invocation, config);
+  const host = await resolveHost(invocation, config);
+  const normalized = normalizeSitePath(linkPath, host);
+  if (!normalized.ok) throw invalidOption("link.path_invalid", normalized.error, "path");
+
+  // Only the files of the kinds named are read, so a half-edited file never stops a link that does not use it.
+  const files = await readWorkspaceMarketing(
+    config.workspaceDir,
+    [["campaigns", linkCampaign], ["placements", linkPlacement]].filter(([, key]) => key !== undefined).map(([kind]) => kind),
+  );
+  const notes = [];
+  const named = {};
+  for (const [kind, key] of [["campaigns", linkCampaign], ["placements", linkPlacement]]) {
+    if (key === undefined) continue;
+    const record = await findRecord(kind, key, files, invocation, config);
+    named[kind] = key;
+    const note = notLiveNote(sanitizeDiagnostic(record.name, key), record.state);
+    // A file's state is the one written at the last pull or push, so say so rather than present it as current.
+    if (note !== "") notes.push(record.fromFile === undefined ? note : `${note} (As of the last marketing pull or push; ${record.fromFile}.)`);
+  }
+
+  const address = trackedAddress(host, normalized.path, {
+    source: source.key,
+    medium: source.medium,
+    campaign: named.campaigns,
+    placement: named.placements,
+  });
+  onProgress(address);
+  for (const note of notes) onProgress(note);
+  return successResult(VERB_LINK_BUILD, config.siteId, {
+    link: {
+      address,
+      host,
+      path: normalized.path,
+      source: source.key,
+      medium: source.medium,
+      ...(named.campaigns === undefined ? {} : { campaign: named.campaigns }),
+      ...(named.placements === undefined ? {} : { placement: named.placements }),
+    },
+    ...(notes.length === 0 ? {} : { notes }),
+  });
+}

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/pull.js

@@ -36,6 +36,7 @@ import {
 } from "../settings-catalog.js";
 import { ApiError } from "../transport.js";
 import { placesFormIds, readFormIndex, withFormKeys } from "../form-references.js";
+import { MARKETING_MANIFEST_KEY } from "../marketing-workspace.js";
 import {
   generatedIdentity,
   legalIdentity,
@@ -1395,10 +1396,13 @@ export async function pull(invocation) {
 
     // `forms pull` owns the forms baseline, and a plain pull does not read forms.
     // Carrying it forward keeps the next `forms push` fenced instead of refusing
-    // it as never pulled. An unreadable old manifest has nothing to carry.
-    const formsBaseline = (await readManifest(config.workspaceDir, siteId, { required: false }).catch(() =>
+    // it as never pulled. The marketing baseline is carried for the same reason
+    // (TR01301). An unreadable old manifest has nothing to carry.
+    const previousManifest = await readManifest(config.workspaceDir, siteId, { required: false }).catch(() =>
       undefined
-    ))?.forms;
+    );
+    const formsBaseline = previousManifest?.forms;
+    const marketingBaseline = previousManifest?.[MARKETING_MANIFEST_KEY];
     const manifest = {
       manifestVersion: MANIFEST_VERSION,
       siteId,
@@ -1420,6 +1424,7 @@ export async function pull(invocation) {
       ),
       ...(presentationRevision === undefined ? {} : { presentation: presentationManifestEntry(presentationRevision) }),
       ...(formsBaseline === undefined ? {} : { forms: formsBaseline }),
+      ...(marketingBaseline === undefined ? {} : { [MARKETING_MANIFEST_KEY]: marketingBaseline }),
       pages: manifestPages,
       ...(retiredGeneratedSources.length === 0 ? {} : { retiredGeneratedSources }),
     };

package/src/verbs/whoami.js

@@ -12,7 +12,7 @@ import {
 } from "../constants.js";
 import { isBehindLatest } from "../cli-release.js";
 import { credentialApiOrigin, findCredential } from "../credentials.js";
-import { SITE_AUTHORING_CAPABILITIES } from "../capabilities.js";
+import { CAPABILITY_CONTENT, SITE_AUTHORING_CAPABILITIES } from "../capabilities.js";
 import { openAnonymousSession, successResult } from "../session.js";
 import { environmentNameFor } from "../settings.js";
 import { describeSurface } from "../surface.js";
@@ -64,6 +64,33 @@ function cliReleaseLine(lastExchange) {
     : `Latest CLI release ${when}: ${lastExchange.latestCliVersion}. This CLI is ${CLI_VERSION}.`;
 }
 
+/**
+ * Whether the credential can manage the site's campaigns and placements (TR01301), from what is known locally.
+ *
+ * The Content capability carries both permissions those verbs need, so the answer is whether the last exchange
+ * held it. Like the rest of this verb it is a recording: `granted` is "what that exchange held", and `exchange`
+ * says no exchange has happened yet, when the next command that needs it will mint one.
+ */
+function marketingAccess(lastExchange, environmentOverride) {
+  if (environmentOverride) return { capability: CAPABILITY_CONTENT, access: "unknown" };
+  if (lastExchange === undefined) return { capability: CAPABILITY_CONTENT, access: "on_exchange" };
+  return {
+    capability: CAPABILITY_CONTENT,
+    access: lastExchange.capabilities.includes(CAPABILITY_CONTENT) ? "granted" : "not_in_last_exchange",
+  };
+}
+
+function marketingLine({ capability, access }) {
+  const verbs = "'marketing pull', 'marketing push' and 'link build'";
+  return access === "granted"
+    ? `Campaigns and placements (${verbs}): allowed; the last exchange held ${capability}.`
+    : access === "not_in_last_exchange"
+    ? `Campaigns and placements (${verbs}): the last exchange did not hold ${capability}, which the next command that needs it requests; a sign-in's ceiling includes it.`
+    : access === "on_exchange"
+    ? `Campaigns and placements (${verbs}): carried by ${capability}, which the next command that needs it requests.`
+    : `Campaigns and placements (${verbs}): needs ${capability}; ${PUBLISH_KEY_ENVIRONMENT_VARIABLE} supplies the credential, so this command cannot tell.`;
+}
+
 /**
  * `taproot-site whoami` — which Taproot, which account, which site, until when.
  *
@@ -155,6 +182,9 @@ export async function whoami(invocation) {
     onProgress(cliReleaseLine(lastExchange));
   }
 
+  const marketing = marketingAccess(lastExchange, environmentOverride);
+  onProgress(marketingLine(marketing));
+
   return successResult(VERB_WHOAMI, config?.siteId, {
     apiOrigin,
     // Named as well as spelled out, so "am I on local right now" is answerable
@@ -176,6 +206,7 @@ export async function whoami(invocation) {
     // Named for what each is. `capabilities` alone would conflate the ceiling
     // with the grant, which are different numbers and differently trustworthy.
     capabilityCeiling: SITE_AUTHORING_CAPABILITIES,
+    marketing,
     ...(environmentOverride || lastExchange === undefined ? {} : {
       lastExchange: {
         siteId: lastExchange.siteId,