@taprootio/site-authoring 0.24.0 → 0.26.0

package/src/marketing-contract.js

@@ -0,0 +1,289 @@
+import campaignRules from "./analytics-campaign.json" with { type: "json" };
+import vocabulary from "./analytics-source-vocabulary.json" with { type: "json" };
+import linkLabelRules from "./analytics-link-label.json" with { type: "json" };
+import { SiteAuthoringError } from "./errors.js";
+
+/**
+ * The workspace contract for a site's campaigns and placements (TR01301).
+ *
+ * Each kind is one JSON file under `marketing/`: a closed object holding a list of records. A record
+ * is what an author decides (key, name, and for a campaign a note and two label dates) plus two
+ * read-only facts the site reports (`state`, `counted_from`), which a pull writes and a push ignores.
+ * The key grammar and the name and note limits come from the shared rule files that the API, the
+ * Worker and the app read too; their copies here are written by `scripts/sync-field-validation.mjs`.
+ * Records the site has archived are not written: archiving keeps history, so a key is never reused,
+ * and a file that names an archived key asks to restore it.
+ */
+
+export const MARKETING_DIRECTORY = "marketing";
+
+export const MARKETING_STATE_LIVE = "live";
+export const MARKETING_STATE_ARCHIVED = "archived";
+/** The words a creator reads for each state, in the app's order. */
+export const MARKETING_STATES = Object.freeze([
+  MARKETING_STATE_LIVE,
+  "publishing",
+  "goes_live_with_first_publish",
+  "not_in_current_release",
+  MARKETING_STATE_ARCHIVED,
+]);
+
+const MARKETING_STATE_WIRE = Object.freeze({
+  campaigns: Object.freeze({
+    SITE_CAMPAIGN_STATE_LIVE: MARKETING_STATE_LIVE,
+    SITE_CAMPAIGN_STATE_PUBLISHING: "publishing",
+    SITE_CAMPAIGN_STATE_GOES_LIVE_WITH_FIRST_PUBLISH: "goes_live_with_first_publish",
+    SITE_CAMPAIGN_STATE_NOT_IN_CURRENT_RELEASE: "not_in_current_release",
+    SITE_CAMPAIGN_STATE_ARCHIVED: MARKETING_STATE_ARCHIVED,
+  }),
+  placements: Object.freeze({
+    SITE_LINK_LABEL_STATE_LIVE: MARKETING_STATE_LIVE,
+    SITE_LINK_LABEL_STATE_PUBLISHING: "publishing",
+    SITE_LINK_LABEL_STATE_GOES_LIVE_WITH_FIRST_PUBLISH: "goes_live_with_first_publish",
+    SITE_LINK_LABEL_STATE_NOT_IN_CURRENT_RELEASE: "not_in_current_release",
+    SITE_LINK_LABEL_STATE_ARCHIVED: MARKETING_STATE_ARCHIVED,
+  }),
+});
+
+/**
+ * The two kinds. A placement is stored as a link label, so its routes and wire names say so; every word
+ * a person reads says placement.
+ */
+export const MARKETING_KINDS = Object.freeze({
+  campaigns: Object.freeze({
+    kind: "campaigns",
+    noun: "campaign",
+    file: `${MARKETING_DIRECTORY}/campaigns.json`,
+    listProperty: "campaigns",
+    route: "campaigns",
+    wireList: "campaigns",
+    wireId: "campaignId",
+    rules: campaignRules,
+    withLabels: true,
+  }),
+  placements: Object.freeze({
+    kind: "placements",
+    noun: "placement",
+    file: `${MARKETING_DIRECTORY}/placements.json`,
+    listProperty: "placements",
+    route: "link-labels",
+    wireList: "linkLabels",
+    wireId: "linkLabelId",
+    rules: linkLabelRules,
+    withLabels: false,
+  }),
+});
+
+export const MARKETING_KIND_NAMES = Object.freeze(Object.keys(MARKETING_KINDS));
+
+/**
+ * The sources a tracked link can name: the shared vocabulary without `reader`, which the published page's own
+ * share action sets. The medium is not chosen; the source decides it.
+ */
+export const LINK_SOURCES = Object.freeze(vocabulary.sources.filter((source) => source.key !== "reader"));
+
+/** The longest name either kind accepts; the shared rule files give each kind's own. */
+function nameMaximum(kind) {
+  return MARKETING_KINDS[kind].rules.nameMaxLength;
+}
+
+// A placement shares the campaign key grammar (shared/analytics-link-label.json delegates to it).
+const KEY_RULES = campaignRules;
+const KEY_PATTERN = new RegExp(KEY_RULES.keyPattern, "u");
+const LONG_DIGIT_RUN = new RegExp(`[0-9]{${KEY_RULES.maxDigitRun + 1},}`, "u");
+const NOTE_MAXIMUM = campaignRules.noteMaxLength;
+const FILE_BYTES = 512 * 1024;
+const DATE = /^(\d{4})-(\d{2})-(\d{2})$/u;
+
+export const MARKETING_LIMITS = Object.freeze({ fileBytes: FILE_BYTES });
+
+export const MARKETING_KEY_RULE = `${KEY_RULES.keyMinLength} to ${KEY_RULES.keyMaxLength} lowercase letters, `
+  + `numbers or hyphens, with no more than ${KEY_RULES.maxDigitRun} numbers in a row`;
+
+/** True for a public key: the one grammar campaigns and placements share. */
+export function isMarketingKey(value) {
+  return typeof value === "string" && KEY_PATTERN.test(value) && !LONG_DIGIT_RUN.test(value);
+}
+
+/** The most unarchived records a site can hold of this kind, from the shared rule file. */
+export function maximumActive(kind) {
+  return MARKETING_KINDS[kind].rules.maxActivePerSite;
+}
+
+function maximumTotal(kind) {
+  return MARKETING_KINDS[kind].rules.maxTotalPerSite;
+}
+
+function invalid(file, message, field) {
+  return new SiteAuthoringError("marketing.file_invalid", `${file}: ${message}`, { field: `${file}:${field}` });
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** A real calendar day written YYYY-MM-DD. */
+export function isCalendarDate(value) {
+  if (typeof value !== "string") return false;
+  const match = DATE.exec(value);
+  if (match === null) return false;
+  const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])];
+  // Year 0 is not a protobuf timestamp (0001 is the first), so the site could never hold it.
+  if (year < 1) return false;
+  // setUTCFullYear, not Date.UTC, which maps years 0 to 99 to 1900 to 1999 and would refuse a typo year the site keeps.
+  const parsed = new Date(0);
+  parsed.setUTCFullYear(year, month - 1, day);
+  return parsed.getUTCFullYear() === year && parsed.getUTCMonth() === month - 1 && parsed.getUTCDate() === day;
+}
+
+// The site trims with .NET's whitespace set, which differs from JavaScript's (U+FEFF is not trimmed there, U+0085 is),
+// so a name the site stored with an edge character must pass here exactly when the site would keep it.
+const DOTNET_WHITESPACE = "\\t-\\r \\u0085\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000";
+const DOTNET_EDGE_WHITESPACE = new RegExp(`^[${DOTNET_WHITESPACE}]|[${DOTNET_WHITESPACE}]$`, "u");
+
+/** NUL and lone surrogates cannot be stored by the site. */
+function hasUnstorableCharacters(text) {
+  return /\u0000|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(text);
+}
+
+function checkText(file, path, value, maximum, { allowEmpty = false } = {}) {
+  if (typeof value !== "string") throw invalid(file, "must be a string.", path);
+  if (DOTNET_EDGE_WHITESPACE.test(value)) throw invalid(file, "must have no space at either end.", path);
+  if (!allowEmpty && value.length === 0) throw invalid(file, "must not be empty.", path);
+  if (value.length > maximum) throw invalid(file, `must be at most ${maximum} characters.`, path);
+  // Only what the site cannot store is refused (NUL and lone surrogates): the site accepts any other text in a name
+  // or note, and a pull writes it back unchanged, so refusing more would fail an untouched pulled workspace.
+  if (hasUnstorableCharacters(value)) {
+    throw invalid(file, "must not contain NUL or an unpaired surrogate.", path);
+  }
+}
+
+const RECORD_KEYS = Object.freeze({
+  campaigns: ["key", "name", "note", "starts_on", "ends_on", "state", "counted_from"],
+  placements: ["key", "name", "state", "counted_from"],
+});
+const READ_ONLY_KEYS = new Set(["state", "counted_from"]);
+
+/**
+ * Validates one parsed marketing file and returns its records as the author decides them: key, name,
+ * and for a campaign note, starts_on and ends_on (absent when unset). The read-only state and counted_from
+ * are checked for shape and kept on the record, so `link build` can read the state a pull wrote; a push ignores them.
+ * `archived` as a state is refused: archiving is a push that omits the
+ * key under --archive, never a word in the file.
+ */
+export function validateMarketingDocument(kind, document_) {
+  const { file, listProperty } = MARKETING_KINDS[kind];
+  if (!isPlainObject(document_)) throw invalid(file, "must be a JSON object.", "$");
+  for (const property of Object.keys(document_)) {
+    if (property !== listProperty) {
+      throw invalid(file, `'${property}' is not a property of this file; it holds only '${listProperty}'.`, property);
+    }
+  }
+  const list = document_[listProperty];
+  if (!Array.isArray(list)) throw invalid(file, `'${listProperty}' must be an array.`, listProperty);
+  if (list.length > maximumTotal(kind)) {
+    throw invalid(file, `lists more than the ${maximumTotal(kind)} records a site can hold.`, listProperty);
+  }
+  const seen = new Set();
+  return list.map((record, index) => {
+    const at = `${listProperty}[${index}]`;
+    if (!isPlainObject(record)) throw invalid(file, "must be an object.", at);
+    for (const property of Object.keys(record)) {
+      if (!RECORD_KEYS[kind].includes(property)) {
+        throw invalid(file, `'${property}' is not a ${MARKETING_KINDS[kind].noun} property.`, `${at}.${property}`);
+      }
+    }
+    if (!isMarketingKey(record.key)) {
+      throw invalid(file, `key must be ${MARKETING_KEY_RULE}.`, `${at}.key`);
+    }
+    if (seen.has(record.key)) throw invalid(file, `names the key '${record.key}' more than once.`, `${at}.key`);
+    seen.add(record.key);
+    checkText(file, `${at}.name`, record.name, nameMaximum(kind));
+    const result = { key: record.key, name: record.name };
+    if (MARKETING_KINDS[kind].withLabels) {
+      if (record.note !== undefined) {
+        checkText(file, `${at}.note`, record.note, NOTE_MAXIMUM, { allowEmpty: true });
+        if (record.note !== "") result.note = record.note;
+      }
+      for (const field of ["starts_on", "ends_on"]) {
+        if (record[field] === undefined) continue;
+        if (!isCalendarDate(record[field])) throw invalid(file, "must be a day written YYYY-MM-DD.", `${at}.${field}`);
+        result[field] = record[field];
+      }
+      if (result.starts_on !== undefined && result.ends_on !== undefined && result.ends_on < result.starts_on) {
+        throw invalid(file, "ends_on cannot be before starts_on.", `${at}.ends_on`);
+      }
+    }
+    for (const field of READ_ONLY_KEYS) {
+      if (record[field] === undefined) continue;
+      // Kept on the validated record so `link build` can read the state a pull recorded; a push ignores it.
+      result[field] = record[field];
+      if (field === "state" && !MARKETING_STATES.includes(record.state)) {
+        throw invalid(file, `state is read-only and one of ${MARKETING_STATES.join(", ")}.`, `${at}.state`);
+      }
+      if (field === "state" && record.state === MARKETING_STATE_ARCHIVED) {
+        throw invalid(
+          file,
+          "a record cannot be archived by writing its state. Remove it from the file and push with --archive.",
+          `${at}.state`,
+        );
+      }
+      if (field === "counted_from" && !isCalendarDate(record.counted_from)) {
+        throw invalid(file, "counted_from is read-only and a day written YYYY-MM-DD.", `${at}.counted_from`);
+      }
+    }
+    return result;
+  });
+}
+
+/**
+ * The record as a file writes it, in one canonical key order, so the same record is always the same
+ * bytes: what the author decides, then what the site reports.
+ */
+export function projectMarketingRecord(kind, record) {
+  const projected = { key: record.key, name: record.name };
+  if (MARKETING_KINDS[kind].withLabels) {
+    if (record.note !== undefined && record.note !== "") projected.note = record.note;
+    if (record.starts_on !== undefined) projected.starts_on = record.starts_on;
+    if (record.ends_on !== undefined) projected.ends_on = record.ends_on;
+  }
+  if (record.state !== undefined) projected.state = record.state;
+  if (record.counted_from !== undefined) projected.counted_from = record.counted_from;
+  return projected;
+}
+
+/** The file's whole document for a list of records, ordered by key. */
+export function projectMarketingDocument(kind, records) {
+  return {
+    [MARKETING_KINDS[kind].listProperty]: [...records]
+      .sort((left, right) => (left.key < right.key ? -1 : left.key > right.key ? 1 : 0))
+      .map((record) => projectMarketingRecord(kind, record)),
+  };
+}
+
+/** The state word a creator reads for a wire state of this kind, or undefined for one this CLI does not know. */
+export function marketingStateFromWire(kind, value) {
+  if (value === undefined || value === "") return undefined;
+  return MARKETING_STATE_WIRE[kind][value];
+}
+
+/** What a creator loses until a picked campaign or placement is live, in the link builder. */
+export const BUILDER_NOT_LIVE_CONSEQUENCE = "Until it is live, page views count under the source only.";
+
+/**
+ * One sentence for a campaign or placement that is not live yet, or empty when it is live. The wording
+ * follows the record's state, because "publishing" is only true while its release runs. The words are the
+ * Marketing link builder's; a test in the app keeps them equal.
+ */
+export function notLiveNote(name, state) {
+  switch (state) {
+    case "publishing":
+      return `${name} is publishing. ${BUILDER_NOT_LIVE_CONSEQUENCE}`;
+    case "goes_live_with_first_publish":
+      return `${name} goes live with your first publish. ${BUILDER_NOT_LIVE_CONSEQUENCE}`;
+    case "not_in_current_release":
+      return `${name} is not in the current release; it goes live with your next publish. ${BUILDER_NOT_LIVE_CONSEQUENCE}`;
+    default:
+      return "";
+  }
+}

package/src/marketing-workspace.js

@@ -0,0 +1,77 @@
+import {
+  MARKETING_KIND_NAMES,
+  MARKETING_KINDS,
+  MARKETING_LIMITS,
+  validateMarketingDocument,
+} from "./marketing-contract.js";
+import { readWorkspaceJson, workspaceFileExists } from "./workspace.js";
+
+/**
+ * Reads the workspace's marketing files and keeps their baseline in the pull manifest (TR01301).
+ *
+ * A kind with no file is simply not read: a workspace that never held a placement is not telling the site to
+ * archive them all. Within a file, a record left out is a request to archive it, and only `marketing push
+ * --archive` honors that request.
+ */
+export const MARKETING_MANIFEST_KEY = "marketing";
+
+/** The records of every kind (or of the named kinds) whose file the workspace holds, validated. */
+export async function readWorkspaceMarketing(workspaceDir, kinds = MARKETING_KIND_NAMES) {
+  const found = new Map();
+  for (const kind of kinds) {
+    const { file } = MARKETING_KINDS[kind];
+    if (!await workspaceFileExists(workspaceDir, file)) continue;
+    const document_ = await readWorkspaceJson(workspaceDir, file, MARKETING_LIMITS.fileBytes);
+    found.set(kind, validateMarketingDocument(kind, document_));
+  }
+  return found;
+}
+
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * What a baseline remembers of a record: its id, whether it was archived, the labels an author decides, and the state
+ * the site reported when it was written. The state is the one `link build` trusts for its note; a file's own `state`
+ * is whatever the author left there, which is wrong for a key that was renamed from a live one.
+ */
+export function baselineEntry(kind, record) {
+  const entry = { id: record.id, archived: record.archived === true, name: record.name };
+  if (record.state !== undefined) entry.state = record.state;
+  if (MARKETING_KINDS[kind].withLabels) {
+    if (record.note !== undefined && record.note !== "") entry.note = record.note;
+    if (record.starts_on !== undefined) entry.starts_on = record.starts_on;
+    if (record.ends_on !== undefined) entry.ends_on = record.ends_on;
+  }
+  return entry;
+}
+
+/** The recorded baseline of one kind, by key. Empty when this workspace never pulled that kind. */
+export function recordedMarketing(manifest, kind) {
+  const items = manifest[MARKETING_MANIFEST_KEY]?.[kind]?.items;
+  const recorded = new Map();
+  if (!isObject(items)) return recorded;
+  for (const [key, entry] of Object.entries(items)) {
+    if (isObject(entry) && typeof entry.id === "string" && typeof entry.archived === "boolean") {
+      recorded.set(key, entry);
+    }
+  }
+  return recorded;
+}
+
+/** Whether a remembered baseline and a record from the site agree on the labels an author decides. */
+export function sameLabels(kind, left, right) {
+  if (left.name !== right.name) return false;
+  if (!MARKETING_KINDS[kind].withLabels) return true;
+  return (left.note ?? "") === (right.note ?? "")
+    && left.starts_on === right.starts_on
+    && left.ends_on === right.ends_on;
+}
+
+/** The manifest with one kind's baseline replaced by `entries` (key to baseline entry), in key order. */
+export function withRecordedMarketing(manifest, kind, entries) {
+  const current = isObject(manifest[MARKETING_MANIFEST_KEY]) ? manifest[MARKETING_MANIFEST_KEY] : {};
+  const items = Object.fromEntries([...entries].sort(([left], [right]) => (left < right ? -1 : 1)));
+  return { ...manifest, [MARKETING_MANIFEST_KEY]: { ...current, [kind]: { items } } };
+}

package/src/redirects-contract.js

@@ -12,7 +12,6 @@ import {
   RULE_REDIRECT_SOURCE_INVALID,
   RULE_REDIRECT_SOURCE_NOT_STORABLE,
   RULE_REDIRECT_SOURCE_RUNTIME_MIRROR,
-  RULE_REDIRECT_SOURCE_SHARE_LINK,
 } from "./site-checks.js";
 
 export { normalizeRedirectPath };
@@ -110,8 +109,6 @@ const SOURCE_RULE_REASONS = Object.freeze({
     + "a redirect source, and the page or home file there is generated.",
   [RULE_REDIRECT_SOURCE_INTEGRATION_DATA]: (first) =>
     `'/${first}' is reserved for integration data, so nothing under it can be a redirect source.`,
-  [RULE_REDIRECT_SOURCE_SHARE_LINK]: () =>
-    "'/s/' is reserved for share links, so nothing under it can be a redirect source.",
   [RULE_REDIRECT_SOURCE_RUNTIME_MIRROR]: () => RUNTIME_MIRROR_PATH_REASON,
   [RULE_REDIRECT_SOURCE_GENERATED_FILE]: (first) =>
     `'/${first}' is a file the site generates, so neither it nor anything under it can be a redirect source.`,

package/src/reference-help.js

@@ -50,6 +50,13 @@ import {
   FORM_SINKS,
   FORMS_DIRECTORY,
 } from "./forms-contract.js";
+import {
+  LINK_SOURCES,
+  MARKETING_KEY_RULE,
+  MARKETING_KINDS,
+  MARKETING_STATES,
+  maximumActive,
+} from "./marketing-contract.js";
 import {
   formatPresentationReference,
   getAppearanceReference,
@@ -88,7 +95,7 @@ import {
 
 export { getAppearanceReference, getFooterReference, getSettingsReference, getThemeReference };
 
-export const REFERENCE_VERSION = 42;
+export const REFERENCE_VERSION = 43;
 
 // The date-limit examples `help forms` prints; tests run them through the form validator.
 export const FORM_DATE_WINDOW_FIELD = Object.freeze({
@@ -422,6 +429,16 @@ export const REFERENCE_TOPICS = Object.freeze([
     usage: `${CLI_BINARY_NAME} help forms`,
     summary: "Author a form as forms/<key>.json: file shape, field types, validate, pull, push, and placing it on a page.",
   }),
+  Object.freeze({
+    name: "marketing",
+    usage: `${CLI_BINARY_NAME} help marketing`,
+    summary: "Keep a site's campaigns and placements as marketing/*.json: file shape, pull, push, archive, and what an agent may do.",
+  }),
+  Object.freeze({
+    name: "link",
+    usage: `${CLI_BINARY_NAME} help link`,
+    summary: "Build a tracked address: path, source, optional campaign and placement; what counts and when it goes live.",
+  }),
   Object.freeze({
     name: "media",
     usage: `${CLI_BINARY_NAME} help media`,
@@ -903,6 +920,95 @@ const WORKFLOW_REFERENCES = Object.freeze({
       }),
     }),
   }),
+  marketing: Object.freeze({
+    title: "Campaigns and placements workspace contract",
+    summary: "A site's campaigns and placements are two JSON files under marketing/. 'marketing pull' reads the site's, "
+      + "'marketing push' creates, updates, restores and (with --archive) archives to match them, and 'link build' prints "
+      + "an address that uses them.",
+    usage: `${CLI_BINARY_NAME} marketing pull | ${CLI_BINARY_NAME} marketing push [--archive]`,
+    details: Object.freeze([
+      "Run 'pull' once first: both verbs need the pulled workspace's manifest, which records what each record looked "
+      + "like when this workspace last read it. The site's licence must include analytics, and the site must be a Standard site.",
+      `A campaign groups links from one push; a placement names the spot a link appears, such as a newsletter footer. `
+      + `Both are public keys the site's release admits, so page views carry them: a campaign as utm_campaign, a placement as `
+      + `utm_content. ${MARKETING_KINDS.campaigns.file} is { campaigns: [ { key, name, note?, starts_on?, ends_on? } ] }; `
+      + `${MARKETING_KINDS.placements.file} is { placements: [ { key, name } ] }. Records are listed by key.`,
+      `A key is ${MARKETING_KEY_RULE}. It is public URL text and never changes or returns to use, even after the record is `
+      + "archived, because page views already counted under it keep the key. A name (at most "
+      + `${MARKETING_KINDS.campaigns.rules.nameMaxLength} characters), a campaign's note (at most ${MARKETING_KINDS.campaigns.rules.noteMaxLength}) `
+      + "and its starts_on and ends_on days (YYYY-MM-DD, labels only) are private and can change.",
+      `A pull also writes two read-only fields: state (${MARKETING_STATES.join(", ")}) and counted_from, the day the key first `
+      + "went live and page views began to count under it. A push ignores both. A record is live once the silent release "
+      + "that carries its key has run; until then page views count under the source only.",
+      "'marketing push' validates both files and compares every record with the site before the first write. "
+      + "A key the file names that the site lacks is created. A record whose labels differ is updated. A key the file "
+      + "names that the site has archived is restored (and updated if its labels differ). Nothing else is touched: a "
+      + "record the file leaves out stays unless you pass --archive, and --archive archives only records this workspace "
+      + "pulled. A changed key is therefore a new record plus, if you want the old one gone, an explicit --archive.",
+      "A record that changed on the site since the last pull is refused as marketing.concurrent_modification, a key "
+      + "the site has that this workspace never pulled as marketing.pull_required; reconcile with 'marketing pull' and "
+      + "retry. Taproot refuses a key outside the grammar, a key already used by an archived record, and a record over "
+      + `the quota (${maximumActive("campaigns")} unarchived campaigns, ${maximumActive("placements")} unarchived placements, and a larger cap on archived ones `
+      + "together); the refusal is shown as Taproot returns it. Archive one to make room, or restore an archived one.",
+      "'marketing pull' reports, per kind, file, total, items ([{ key, state }], at most 200), archived keys (at most 200, "
+      + "with archivedTotal and archivedTruncated), canManage and maxActive. 'marketing push' reports, per kind, the keys it "
+      + "created, updated, restored, archived, left unchanged, left on the site because the file omits them (unlisted) and found "
+      + "on the site but never pulled (unpulled), each list capped at 50 with the true totals in counts and the capped lists "
+      + "named in truncated; written is { items, count } across both kinds.",
+      "Creating or restoring a key queues a silent production release that starts admitting it; no 'deploy' is needed and "
+      + "none is waited for. 'marketing pull' later shows the state. Archiving queues no release: the key stops being admitted from the next one.",
+      "The delegation.content capability carries the permissions this needs: site.analytics.view to read and also "
+      + "site.pages.publish_any to change, because a new key publishes a release. Platform-wide, an administrator can pause external "
+      + "authoring; a push is then refused with the rollout field. A refusal names a missing permission.",
+    ]),
+    example: Object.freeze({
+      campaigns: Object.freeze({
+        campaigns: Object.freeze([
+          Object.freeze({
+            key: "spring-launch",
+            name: "Spring launch",
+            note: "Newsletter and social push",
+            starts_on: "2026-03-01",
+            ends_on: "2026-03-31",
+          }),
+        ]),
+      }),
+      placements: Object.freeze({
+        placements: Object.freeze([Object.freeze({ key: "nl-footer", name: "Newsletter footer" })]),
+      }),
+      commands: Object.freeze([
+        `${CLI_BINARY_NAME} marketing pull`,
+        `${CLI_BINARY_NAME} marketing push`,
+        `${CLI_BINARY_NAME} link build --path /recipes/spring-salad --source newsletter --campaign spring-launch --placement nl-footer`,
+      ]),
+    }),
+  }),
+  link: Object.freeze({
+    title: "Tracked link builder",
+    summary: "'link build' prints one address that counts under a source, and optionally a campaign and a placement. It saves nothing.",
+    usage: `${CLI_BINARY_NAME} link build --path <page> --source <key> [--campaign <key>] [--placement <key>] [--domain <host>]`,
+    details: Object.freeze([
+      "--path is the page on this site, such as /recipes/spring-salad; / or an empty value is the home page. A query or #fragment "
+      + "is kept; a full address is accepted only if it is on this site's own host. --source is where the link will be posted: "
+      + `${LINK_SOURCES.map((source) => source.key).join(", ")}. The medium (social or email) is set by the source and cannot be chosen. 'reader' is not offered: `
+      + "a published page's own share action sets it.",
+      "The address is https://<public host><path>?utm_source=<source>&utm_medium=<medium>[&utm_campaign=<campaign>][&utm_content=<placement>]. "
+      + "A utm_source, utm_medium, utm_campaign or utm_content already on the path is replaced, never duplicated. Page views carry these values into the site's "
+      + "analytics only for campaigns and placements the site admits; anything else is dropped.",
+      "The host is the site's public address, read from the signed-in site; a site credential alone cannot read it, so "
+      + "pass --domain <host> then. A site with no public address yet has nothing to build a link to.",
+      "A campaign or placement is checked first. When the workspace has marketing/campaigns.json or marketing/placements.json "
+      + "(from 'marketing pull'), the file is the record of what exists; otherwise the live site is asked. A key it does not "
+      + "hold, or one the site has archived, is refused, because it would not be counted. A key that exists but is not live yet is "
+      + "allowed, and the result carries a note: 'publishing' while its release runs, 'goes live with your first publish' for a site "
+      + "that has not published, or 'not in the current release' after a rollback. Until it is live, page views count under the source only. A note read from a file says it is as of the last marketing pull or push, so run 'marketing pull' for the current state.",
+      "The result is { link: { address, host, path, source, medium, campaign?, placement? }, notes? }.",
+    ]),
+    example: Object.freeze({
+      command: `${CLI_BINARY_NAME} link build --path /recipes/spring-salad --source newsletter --campaign spring-launch --placement nl-footer`,
+      address: "https://example.com/recipes/spring-salad?utm_source=newsletter&utm_medium=email&utm_campaign=spring-launch&utm_content=nl-footer",
+    }),
+  }),
   media: Object.freeze({
     title: "Media upload contract",
     summary: "Upload workspace-root-relative raster files and videos; images are recorded in .taproot-site-media.json and videos report their ids.",

package/src/session.js

@@ -86,7 +86,7 @@ function keyMissingError() {
  * The exchange's own answer is checked again afterwards, because the
  * recording can be stale.
  */
-function requireRecordedSurface(invocation, config) {
+export function requireRecordedSurface(invocation, config) {
   if (invocation.surface === undefined || config.authoringSurface === undefined) return;
   if (!surfaceAllows(config.authoringSurface, invocation.surface)) {
     throw surfaceRefusal(invocation.verb ?? "This verb", config.authoringSurface, { source: "config" });

package/src/site-check-findings.js

@@ -36,7 +36,6 @@ export const SITE_CHECK_WORDING = Object.freeze({
   "redirect.source_invalid": () => "has a source that is not an absolute site path",
   "redirect.source_index_html": () => "has a source ending in index.html",
   "redirect.source_integration_data": () => "has a source under the integration data root",
-  "redirect.source_share_link": () => "has a source under the share-link root",
   "redirect.source_runtime_mirror": () => "has a source under the published-site runtime",
   "redirect.source_generated_file": () => "has a source naming a file the site generates",
   "redirect.source_not_storable": () => "has a source the publisher cannot store",

package/src/site-check-rules.json

@@ -16,7 +16,6 @@
     { "id": "redirect.source_invalid", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "none" },
     { "id": "redirect.source_index_html", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "first_segment" },
     { "id": "redirect.source_integration_data", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "first_segment" },
-    { "id": "redirect.source_share_link", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "first_segment" },
     { "id": "redirect.source_runtime_mirror", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "first_segment" },
     { "id": "redirect.source_generated_file", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "first_segment" },
     { "id": "redirect.source_not_storable", "severity": "error", "scope": "site", "runsAt": ["save", "validate"], "subject": "redirect_source", "detail": "first_segment" },

package/src/site-checks.js

@@ -19,7 +19,6 @@ export const RULE_FORM_KEY_UNKNOWN = "form.key_unknown";
 export const RULE_REDIRECT_SOURCE_INVALID = "redirect.source_invalid";
 export const RULE_REDIRECT_SOURCE_INDEX_HTML = "redirect.source_index_html";
 export const RULE_REDIRECT_SOURCE_INTEGRATION_DATA = "redirect.source_integration_data";
-export const RULE_REDIRECT_SOURCE_SHARE_LINK = "redirect.source_share_link";
 export const RULE_REDIRECT_SOURCE_RUNTIME_MIRROR = "redirect.source_runtime_mirror";
 export const RULE_REDIRECT_SOURCE_GENERATED_FILE = "redirect.source_generated_file";
 export const RULE_REDIRECT_SOURCE_NOT_STORABLE = "redirect.source_not_storable";
@@ -282,7 +281,6 @@ export function normalizeRedirectPath(value) {
 }
 const GENERATED_ROOT_FILES = ["404.html", "sitemap.xml", "robots.txt", "favicon.ico"];
 const INTEGRATION_DATA_ROOT = "integrations";
-const SHARE_LINK_ROOT = "s";
 const MAX_MARKER_SEGMENT_BYTES = 200;
 const MAX_OUTPUT_PATH_LENGTH = 1_024;
 const WINDOWS_DEVICE_STEMS = new Set(["con", "prn", "aux", "nul"]);
@@ -317,10 +315,6 @@ export function redirectSourceRule(edgePath) {
     }
     if (first.toLowerCase() === INTEGRATION_DATA_ROOT)
         return refuse(RULE_REDIRECT_SOURCE_INTEGRATION_DATA);
-    const shareSegments = decoded.replace(/^\/+|\/+$/gu, "").split("/");
-    if (shareSegments.length > 1 && shareSegments[1].length > 0 && shareSegments[0].toLowerCase() === SHARE_LINK_ROOT) {
-        return refuse(RULE_REDIRECT_SOURCE_SHARE_LINK);
-    }
     if (isRuntimeMirrorPath(decoded))
         return refuse(RULE_REDIRECT_SOURCE_RUNTIME_MIRROR);
     if (GENERATED_ROOT_FILES.includes(first.toLowerCase()))