@taprootio/site-authoring 0.23.1 → 0.26.0

package/src/utm-link.js

@@ -0,0 +1,214 @@
+// Generated from ux/client/src/common/utm-link.ts by scripts/sync-field-validation.mjs. Do not edit.
+/**
+ * UTM parameters on an address, as string work so every byte the creator typed is kept (TR01273). One module
+ * serves the Marketing link builder and the page editor's placement picker, so the two cannot disagree about
+ * what a query string means.
+ *
+ * Parameter names are compared the way the published-site Worker compares them: decoded once and lowercased.
+ */
+/** The parameters the link builder owns; a pasted copy of any is replaced, never duplicated. */
+export const BUILDER_UTM_PARAMETERS = new Set([
+    "utm_source",
+    "utm_medium",
+    "utm_campaign",
+    "utm_content",
+]);
+/** A placement rides in `utm_content`. */
+export const PLACEMENT_PARAMETER = "utm_content";
+/**
+ * Outside-link destinations the engagement beacon records: lowercase ASCII host names with a letter-led final
+ * label. A copy of `ENGAGEMENT_HOST_PATTERN` in `generator/src/edge/analytics-engagement.ts`; a test keeps them equal.
+ */
+export const ENGAGEMENT_HOST_PATTERN = /^(?=.{3,100}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$/u;
+export function splitAddress(address) {
+    const hash = address.indexOf("#");
+    const beforeFragment = hash < 0 ? address : address.slice(0, hash);
+    const fragment = hash < 0 ? "" : address.slice(hash + 1);
+    const mark = beforeFragment.indexOf("?");
+    return {
+        base: mark < 0 ? beforeFragment : beforeFragment.slice(0, mark),
+        query: mark < 0 ? "" : beforeFragment.slice(mark + 1),
+        fragment,
+    };
+}
+function normalizedName(raw) {
+    try {
+        return decodeURIComponent(raw).toLowerCase();
+    }
+    catch {
+        return raw.toLowerCase();
+    }
+}
+/**
+ * A pair's value as the beacon reads it: `+` as a space, decoded once, then trimmed and lowercased. Empty when it
+ * cannot decode or holds a control character, which the beacon rejects before it trims (so `%0Abio-link` is not
+ * the placement `bio-link`).
+ */
+function normalizedValue(raw) {
+    try {
+        const decoded = decodeURIComponent(raw.replace(/\+/gu, " "));
+        return /[\u0000-\u001f\u007f-\u009f]/u.test(decoded) ? "" : decoded.trim().toLowerCase();
+    }
+    catch {
+        return "";
+    }
+}
+function pairsOf(query) {
+    return query.split("&").filter(pair => pair !== "").map(raw => {
+        const equals = raw.indexOf("=");
+        return {
+            raw,
+            name: normalizedName(equals < 0 ? raw : raw.slice(0, equals)),
+            value: equals < 0 ? "" : normalizedValue(raw.slice(equals + 1)),
+        };
+    });
+}
+/**
+ * Applies a change to an address's query string and returns the address. Pairs the change does not touch are kept
+ * byte for byte and in order; empty pairs are dropped, so a bare `?` or `&&` never leaves a stray separator; no
+ * remaining pair means no `?`; the fragment goes back last.
+ */
+export function rewriteQuery(address, change) {
+    const { base, query, fragment } = splitAddress(address);
+    const kept = pairsOf(query)
+        .filter(pair => !change.remove?.has(pair.name) && !change.removeWhen?.(pair.name, pair.value))
+        .map(pair => pair.raw);
+    const added = (change.append ?? []).map(([name, value]) => `${encodeURIComponent(name)}=${encodeURIComponent(value)}`);
+    const pairs = [...kept, ...added];
+    return `${base}${pairs.length ? `?${pairs.join("&")}` : ""}${fragment ? `#${fragment}` : ""}`;
+}
+/** Every `utm_content` value in an address, normalized the way the beacon reads one. */
+export function placementValues(address) {
+    return pairsOf(splitAddress(address).query).filter(pair => pair.name === PLACEMENT_PARAMETER).map(pair => pair.value);
+}
+/**
+ * Writes a placement into an address. A key replaces every `utm_content` (the beacon drops a click's label unless
+ * exactly one exists). No key removes a `utm_content` only when it is one of the site's own placement keys, so a
+ * value another tool wrote stays.
+ */
+export function withPlacement(address, key, siteKeys) {
+    return key
+        ? rewriteQuery(address, { remove: new Set([PLACEMENT_PARAMETER]), append: [[PLACEMENT_PARAMETER, key]] })
+        : rewriteQuery(address, {
+            removeWhen: (name, value) => name === PLACEMENT_PARAMETER && siteKeys.has(value),
+        });
+}
+/**
+ * Whether the beacon would record a click on this address as an outbound click from the site: an absolute
+ * `http(s)` address whose host differs from the site's (exact comparison, as the beacon does, so `www.` counts as
+ * different) and fits the host grammar the beacon accepts (dotted, letter-led final label, so IP addresses and
+ * single-label hosts never count). A site with no public address yet has no host to differ from.
+ */
+export function isOutsideLink(address, siteHost) {
+    let url;
+    try {
+        url = new URL(address.trim());
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return false;
+    const host = url.hostname.toLowerCase();
+    return host !== siteHost.trim().toLowerCase() && ENGAGEMENT_HOST_PATTERN.test(host);
+}
+const SITE_AUTHORITY = /^(?:https?:)?\/\/([^/?#]*)([\s\S]*)$/iu;
+/** Lowercased, a leading `www.` dropped. It does not trim: a space inside a pasted address is not part of a host. */
+function bareHost(host) {
+    return host.toLowerCase().replace(/^www\./u, "");
+}
+/**
+ * Reads an address that starts with `http(s)://` or `//` and names the site's own host: no userinfo, no port,
+ * a leading `www.` ignored on either side. Returns what follows the authority, or undefined for anything else.
+ * One rule for the builder's path box and for a link in an email (TR01302), judged on the raw authority so an
+ * explicit default port is refused the same way in both.
+ */
+export function ownSiteAuthority(address, siteHost) {
+    const match = SITE_AUTHORITY.exec(address.trim());
+    if (!match)
+        return undefined;
+    const host = match[1].toLowerCase();
+    if (host === "" || /[@:]/u.test(host) || bareHost(host) !== bareHost(siteHost.trim()))
+        return undefined;
+    return { rest: match[2] };
+}
+/** Whether an address is an absolute `http(s)` link to the site's own host (an email link the toggle applies to). */
+export function isOwnSiteLink(address, siteHost) {
+    return /^https?:\/\//iu.test(address.trim()) && ownSiteAuthority(address, siteHost) !== undefined;
+}
+export const OTHER_SITE_ERROR = "Enter a path on this site.";
+/**
+ * Turns what a creator typed into a path on their own site: starting with `/`, with an existing query and
+ * fragment kept. A pasted address must be on the site's own host (a leading `www.` on either side is ignored,
+ * with no userinfo or port); its host is removed so a pasted address can never point the result elsewhere.
+ * Spaces, control characters and non-ASCII characters are percent-encoded; every other byte is kept.
+ */
+export function normalizeSitePath(input, siteHost) {
+    let rest = input.trim();
+    if (SITE_AUTHORITY.test(rest)) {
+        const own = ownSiteAuthority(rest, siteHost);
+        if (!own)
+            return { ok: false, error: OTHER_SITE_ERROR };
+        rest = own.rest;
+    }
+    else if (/^[a-z][a-z0-9+.-]*:/iu.test(rest)) {
+        return { ok: false, error: OTHER_SITE_ERROR };
+    }
+    else {
+        // An address pasted without its scheme ("example.com/blog") is the site's own host followed by a path.
+        const lead = /^([^/?#]+)([\s\S]*)$/u.exec(rest);
+        if (lead && bareHost(lead[1]) === bareHost(siteHost.trim()))
+            rest = lead[2];
+    }
+    const { base, query, fragment } = splitAddress(rest);
+    const path = base === "" ? "/" : base.startsWith("/") ? base : `/${base}`;
+    // A lone surrogate (a truncated emoji) cannot be percent-encoded and would throw; it becomes U+FFFD first.
+    const wellFormed = (value) => value.replace(/[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/gu, "\ufffd");
+    const encode = (value) => wellFormed(value).replace(/[^\x21-\x7e]/gu, character => encodeURIComponent(character));
+    return {
+        ok: true,
+        path: encode(`${path}${query ? `?${query}` : ""}${fragment ? `#${fragment}` : ""}`),
+    };
+}
+/** The medium and source the builder appends, then the optional campaign and placement. */
+export function trackedAddress(siteHost, path, parts) {
+    const append = [["utm_source", parts.source], ["utm_medium", parts.medium]];
+    if (parts.campaign)
+        append.push(["utm_campaign", parts.campaign]);
+    if (parts.placement)
+        append.push([PLACEMENT_PARAMETER, parts.placement]);
+    return `https://${siteHost.trim().toLowerCase()}${rewriteQuery(path, { remove: BUILDER_UTM_PARAMETERS, append })}`;
+}
+/** What an address carries of a tracking, read the way the Worker reads it. `on` needs exactly one source and one medium that match. */
+export function readEmailTracking(address, tracking) {
+    const pairs = pairsOf(splitAddress(address).query);
+    const values = (name) => pairs.filter(pair => pair.name === name).map(pair => pair.value);
+    const sources = values("utm_source"), mediums = values("utm_medium");
+    return {
+        on: sources.length === 1 && sources[0] === tracking.source && mediums.length === 1
+            && mediums[0] === tracking.medium,
+        campaigns: values("utm_campaign"),
+        placements: values(PLACEMENT_PARAMETER),
+    };
+}
+/** Writes an email tracking into an address, replacing any source, medium, campaign or placement already on it. */
+export function withEmailTracking(address, tracking) {
+    const append = [["utm_source", tracking.source], ["utm_medium", tracking.medium]];
+    if (tracking.campaign)
+        append.push(["utm_campaign", tracking.campaign]);
+    if (tracking.placement)
+        append.push([PLACEMENT_PARAMETER, tracking.placement]);
+    return rewriteQuery(address, { remove: BUILDER_UTM_PARAMETERS, append });
+}
+/**
+ * Takes an email tracking back out: only what the switch writes. The source and medium go when they are the
+ * Newsletter pair, a campaign or placement goes when it is one of the site's own keys, and any other value stays.
+ */
+export function withoutEmailTracking(address, tracking, siteKeys) {
+    return rewriteQuery(address, {
+        removeWhen: (name, value) => (name === "utm_source" && value === tracking.source)
+            || (name === "utm_medium" && value === tracking.medium)
+            || (name === "utm_campaign" && siteKeys.campaigns.has(value))
+            || (name === PLACEMENT_PARAMETER && siteKeys.placements.has(value)),
+    });
+}

package/src/verbs/approve.js

@@ -8,6 +8,7 @@ import {
 import { VERB_APPROVE } from "../constants.js";
 import { SiteAuthoringError } from "../errors.js";
 import { boundedByBytes, boundedList, openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
+import { isLegalTemplateType } from "../typed-pages.js";
 import { displayPagePath, normalizePagePath, readManifest, writeManifest } from "../workspace.js";
 
 /**
@@ -45,7 +46,7 @@ export async function approve(invocation) {
 
   // Positional arguments narrow the selection to those page paths; `cli.js`
   // hands them over as `pagePaths`, and a programmatic caller can supply the
-  // same key directly. With none, every draft the manifest tracks is staged.
+  // same key directly. With none, legal drafts are skipped and the other tracked drafts are staged.
   //
   // A path this CLI cannot use is refused by name rather than dropped. Dropping
   // it silently is the worst available outcome: the remaining selection would
@@ -80,16 +81,29 @@ export async function approve(invocation) {
       );
     }
     const pathOf = (summary) => normalizePagePath(summary.path) ?? summary.path;
-    const candidates = pages.filter((summary) =>
-      !isGonePage(summary)
-      && summary.hasDraft
-      && manifestByPageId.has(summary.pageId)
-      && (requestedPaths === undefined || requestedPaths.has(pathOf(summary))));
+    const tracked = pages.filter((summary) => !isGonePage(summary) && manifestByPageId.has(summary.pageId));
+    const isLegal = (page) => isLegalTemplateType(page.templateType)
+      || isLegalTemplateType(manifestByPageId.get(page.pageId)?.templateType);
+    if (requestedPaths !== undefined && tracked.some((page) => requestedPaths.has(pathOf(page)) && isLegal(page))) {
+      throw new SiteAuthoringError("approve.legal_not_allowed", "Legal drafts must be approved in the app. Nothing was approved.", { field: "pages" });
+    }
+    const selected = tracked.filter((summary) =>
+      summary.hasDraft && (requestedPaths === undefined || requestedPaths.has(pathOf(summary))));
+    const legalDrafts = requestedPaths === undefined ? selected.filter(isLegal) : [];
+    const candidates = selected.filter((page) => !isLegal(page));
 
     // A requested page with nothing to approve is reported, not refused, so
     // one already-approved path does not stop the rest of the batch. A path
     // that names no page this workspace tracks is still refused by name.
-    const skipped = [];
+    const skipped = legalDrafts.map((page) => ({
+      pageId: page.pageId,
+      path: displayPagePath(pathOf(page)),
+      status: page.status,
+      reason: "legal_requires_app",
+    }));
+    if (legalDrafts.length > 0) {
+      onProgress(`Skipping ${legalDrafts.length} legal draft${legalDrafts.length === 1 ? "" : "s"}; approve ${legalDrafts.length === 1 ? "it" : "them"} in the app.`);
+    }
     if (requestedPaths !== undefined) {
       const matched = new Set(candidates.map(pathOf));
       const unknown = [];
@@ -137,7 +151,9 @@ export async function approve(invocation) {
 
     if (candidates.length === 0) {
       onProgress(
-        skipped.length > 0
+        legalDrafts.length > 0
+          ? "No ordinary drafts to approve; approve the skipped legal drafts in the app."
+          : skipped.length > 0
           ? "Nothing to approve: the requested page(s) have no pending draft."
           : "No page in this workspace is carrying a draft; there is nothing to approve.",
       );
@@ -145,7 +161,7 @@ export async function approve(invocation) {
         approved: { total: 0, items: [] },
         ...skippedResult,
         stagedNotDeployed: true,
-        nextStep: "deploy --staging",
+        nextStep: legalDrafts.length > 0 ? "approve legal drafts in the app" : "deploy --staging",
       });
     }
 

package/src/verbs/index.js

@@ -11,8 +11,11 @@ import {
   VERB_FORMS_PULL,
   VERB_FORMS_PUSH,
   VERB_FORMS_VALIDATE,
+  VERB_LINK_BUILD,
   VERB_LOGIN,
   VERB_LOGOUT,
+  VERB_MARKETING_PULL,
+  VERB_MARKETING_PUSH,
   VERB_MEDIA_UPLOAD,
   VERB_NAV_PUSH,
   VERB_PAGES_DELETE,
@@ -49,8 +52,11 @@ import { footerPush } from "./footer-push.js";
 import { formsPull } from "./forms-pull.js";
 import { formsPush } from "./forms-push.js";
 import { formsValidate } from "./forms-validate.js";
+import { linkBuild } from "./link-build.js";
 import { login } from "./login.js";
 import { logout } from "./logout.js";
+import { marketingPull } from "./marketing-pull.js";
+import { marketingPush } from "./marketing-push.js";
 import { mediaUpload } from "./media-upload.js";
 import { navPush } from "./nav-push.js";
 import { pagesDelete } from "./pages-delete.js";
@@ -91,6 +97,9 @@ import { whoami } from "./whoami.js";
  *   quiet,         // --quiet; suppresses progress, never the JSON result
  *   keyName,       // --name; `login` only, undefined everywhere else
  *   planHash,      // --plan; `apply` only: the plan it may run
+ *   archive,       // --archive; `marketing push` only: archive a record the file leaves out
+ *   linkPath, linkSource, linkCampaign, linkPlacement, linkDomain,
+ *                  // --path, --source, --campaign, --placement, --domain; `link build` only
  *   onProgress,    // human progress sink (stderr, or a no-op when quiet)
  *   fetch,         // injectable fetch, for tests
  *   signal,        // optional AbortSignal
@@ -174,6 +183,9 @@ export const VERB_HANDLERS = Object.freeze({
   [VERB_FORMS_PULL]: formsPull,
   [VERB_FORMS_PUSH]: formsPush,
   [VERB_FORMS_VALIDATE]: formsValidate,
+  [VERB_MARKETING_PULL]: marketingPull,
+  [VERB_MARKETING_PUSH]: marketingPush,
+  [VERB_LINK_BUILD]: linkBuild,
   [VERB_MEDIA_UPLOAD]: mediaUpload,
   [VERB_APPROVE]: approve,
   [VERB_DEPLOY]: deploy,

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 }),
+  });
+}