@nextcommerce/campaigns-os 1.43.2 → 1.46.0

package/src/live-campaign-refs.mjs

@@ -0,0 +1,466 @@
+// Page refs against the live campaign (#533): the one comparison doctor and QA
+// share. A page's `data-next-shipping-id` / package refs were only ever checked
+// against the CampaignSpec, so a campaign whose shipping methods or packages
+// changed after the Map was saved passed both gates while the SDK silently fell
+// back to another method at checkout. This module reads what the live campaign
+// serves and says, separately:
+//
+//   - page vs live: a ref a page renders that the live campaign does not serve
+//     (`built_output.shipping_ref_live_missing` / `built_output.package_ref_live_missing`,
+//     blockers, whatever the Map says);
+//   - Map vs live: refs the CampaignSpec lists that the live campaign does not
+//     serve, or the reverse (`spec.campaign_drift`, a warning that never
+//     downgrades a page-level blocker).
+//
+// The read is one GET of `{proxy-base}/api/campaign` under `X-Campaign-Key`
+// (with `?ref_id=<id>` when the CampaignSpec names the campaign): NEXT's proxy
+// forwards it to the campaign retrieve the Campaign Cart SDK makes in the
+// browser and answers with an envelope, `{ ok, status, endpoint,
+// requested_ref_id, retrieved_at, data }`, whose `data` is that retrieve's
+// body — one campaign, or an array of them. The only credential is the
+// public Campaigns API key; no store or Admin credential is reachable from
+// here. It takes its fetch and the proxy base as arguments, so a caller that
+// passes neither reads nothing. Anything short of one parsed campaign —
+// no key, no fetch, a network error, a non-2xx, a timeout, `ok: false`, a body
+// that is not the envelope, several campaigns and no ref to pick one, a
+// campaign other than the one the CampaignSpec names — is
+// `not_run` with its reason, never a pass and never a fall back to the Map's
+// own list.
+import { parse as parseHtml } from "parse5";
+
+import { runWithDeadline } from "./deadline.mjs";
+import { assertSecureProxyBase } from "./remit.mjs";
+import { resolveCampaignsApiKeySource, describeCampaignKeyRejection } from "./campaigns-api-key.mjs";
+import { readJsonIfExists, resolveFromFile } from "./cli-helpers.mjs";
+
+export const LIVE_CAMPAIGN_PATH = "/api/campaign";
+
+export const LIVE_CAMPAIGN_TIMEOUT_MS = 10_000;
+export const LIVE_CAMPAIGN_MAX_BYTES = 2 * 1024 * 1024;
+const LIVE_CAMPAIGN_ERROR_MAX_BYTES = 64 * 1024;
+
+export const LIVE_REF_CODES = Object.freeze({
+  shipping: "built_output.shipping_ref_live_missing",
+  package: "built_output.package_ref_live_missing",
+  drift: "spec.campaign_drift",
+  notRun: "built_output.live_refs_not_run",
+});
+
+// The refs a page renders, read the way a browser reads the markup: parsed
+// with parse5, so any valid attribute syntax is seen (spaces around `=`,
+// unquoted or single-quoted values, upper-case names, entity-encoded values)
+// and markup the browser never builds into elements is not. One extractor
+// feeds the CampaignSpec ref check, the live check and commercial parity.
+//
+//   - attributes: `data-next-package-id` / `data-package-id` (packages) and
+//     `data-next-shipping-id` (shipping), on any element;
+//   - inline config: `packageId:` / `shippingId:` keys in `<script>` text and
+//     in attribute values (an inline handler or a JSON config attribute);
+//   - `<template>` content is read: the SDK clones templates into the live DOM,
+//     so a ref there is a ref the shopper can reach;
+//   - comments and `<noscript>` content are not: neither becomes an element
+//     while the SDK runs.
+const PACKAGE_REF_ATTRIBUTES = new Set(["data-next-package-id", "data-package-id"]);
+const SHIPPING_REF_ATTRIBUTES = new Set(["data-next-shipping-id"]);
+const PACKAGE_CONFIG_KEY = /["']?packageId["']?\s*:\s*(?:"([^"]+)"|'([^']+)'|([A-Za-z0-9_-]+))/gi;
+const SHIPPING_CONFIG_KEY = /["']?shippingId["']?\s*:\s*(?:"([^"]+)"|'([^']+)'|([A-Za-z0-9_-]+))/gi;
+
+export function extractRenderedRefs(content) {
+  const packageRefs = new Set();
+  const shippingRefs = new Set();
+  const readConfig = (text) => {
+    for (const match of String(text || "").matchAll(PACKAGE_CONFIG_KEY)) addRenderedRef(packageRefs, match[1] || match[2] || match[3]);
+    for (const match of String(text || "").matchAll(SHIPPING_CONFIG_KEY)) addRenderedRef(shippingRefs, match[1] || match[2] || match[3]);
+  };
+  const visit = (node) => {
+    const children = node.content ? node.content.childNodes : node.childNodes;
+    for (const child of children || []) {
+      if (!child.tagName) continue;
+      for (const attr of child.attrs || []) {
+        const name = attr.name.toLowerCase();
+        if (PACKAGE_REF_ATTRIBUTES.has(name)) addRenderedRef(packageRefs, attr.value);
+        else if (SHIPPING_REF_ATTRIBUTES.has(name)) addRenderedRef(shippingRefs, attr.value);
+        else readConfig(attr.value);
+      }
+      if (child.tagName.toLowerCase() === "script") {
+        readConfig((child.childNodes || []).map((text) => text.value || "").join(""));
+      }
+      visit(child);
+    }
+  };
+  visit(parseHtml(String(content || "")));
+  return { package_refs: packageRefs, shipping_refs: shippingRefs };
+}
+
+export function extractRenderedPackageRefs(content) {
+  return extractRenderedRefs(content).package_refs;
+}
+
+export function extractRenderedShippingRefs(content) {
+  return extractRenderedRefs(content).shipping_refs;
+}
+
+function addRenderedRef(refs, value) {
+  const ref = String(value || "").trim();
+  if (/^[A-Za-z0-9_-]+$/.test(ref)) refs.add(ref);
+}
+
+function notRun(reasonCode, reason, extra = {}) {
+  return { status: "not_run", reason_code: reasonCode, reason, ...extra };
+}
+
+// A ref as the campaign states it: a number or a non-empty string, compared as
+// its string form, so `5` on the page and `"5"` in the API are the same ref.
+function liveRef(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  if (typeof value === "string" && /^[A-Za-z0-9_-]+$/.test(value.trim())) return value.trim();
+  return null;
+}
+
+// The campaign body, or null when it is not one. Both lists must be arrays
+// (an empty one is a campaign that serves nothing of that kind) and every
+// entry must carry a ref, so a partial body is never read as "not served".
+export function liveCampaignRefs(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return null;
+  if (!Array.isArray(body.packages) || !Array.isArray(body.shipping_methods)) return null;
+  const packages = body.packages.map((pkg) => liveRef(pkg?.ref_id));
+  const shipping = body.shipping_methods.map((method) => liveRef(method?.ref_id));
+  if (packages.includes(null) || shipping.includes(null)) return null;
+  return { package_refs: [...new Set(packages)].sort(), shipping_refs: [...new Set(shipping)].sort() };
+}
+
+// The campaign's own ref as the CampaignSpec records it (`campaign.ref_id`,
+// the numeric platform id), or null when it names none the proxy's
+// `?ref_id=` would take.
+export function campaignRefIdFromSpec(spec) {
+  const value = spec?.campaign?.ref_id;
+  if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) return String(value);
+  if (typeof value === "string" && /^\d+$/.test(value.trim())) return value.trim();
+  return null;
+}
+
+// The proxy's error text as one short line: the envelope's `error` string,
+// whitespace collapsed, the key redacted if it were ever echoed, and capped.
+// Never the raw body.
+function proxyErrorText(body, apiKey) {
+  const raw = body && typeof body === "object" && !Array.isArray(body) && typeof body.error === "string" ? body.error : "";
+  let text = raw.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim();
+  if (apiKey && text.includes(apiKey)) text = text.split(apiKey).join("[key]");
+  if (text.length > 160) text = `${text.slice(0, 157)}...`;
+  return text;
+}
+
+function parseJson(text) {
+  try {
+    return { ok: true, value: JSON.parse(text) };
+  } catch {
+    return { ok: false };
+  }
+}
+
+// A campaign's own identity as the proxy reads it: `ref_id`, else `id`, a
+// scalar compared as its string form; null when it carries neither.
+function campaignIdentity(campaign) {
+  return liveRef(campaign?.ref_id ?? campaign?.id);
+}
+
+function campaignMismatch(refId, carried) {
+  return notRun("campaign_mismatch", `The live campaign read asked for campaign ref ${refId} but got ${carried}, so another campaign's refs were not compared against.`);
+}
+
+// The one campaign in the envelope's `data`: the object itself, or from an
+// array the entry whose identity is the one asked for (or the only entry, when
+// no ref was asked for). A campaign asked for by ref must carry that ref, in
+// either shape; an empty array does not carry it either. Returns { campaign }
+// or { notRun }.
+function pickCampaign(data, refId) {
+  if (!Array.isArray(data)) {
+    if (!refId) return { campaign: data };
+    const identity = campaignIdentity(data);
+    return identity === refId
+      ? { campaign: data }
+      : { notRun: campaignMismatch(refId, identity ? `campaign ref ${identity}` : "a campaign carrying no ref") };
+  }
+  if (refId) {
+    if (data.length === 0) return { notRun: campaignMismatch(refId, "no campaign") };
+    const matches = data.filter((entry) => campaignIdentity(entry) === refId);
+    if (matches.length === 1) return { campaign: matches[0] };
+    return matches.length === 0
+      ? { notRun: campaignMismatch(refId, `${data.length} campaign(s), none with that ref`) }
+      : { notRun: notRun("ambiguous_campaign", `The live campaign read returned ${matches.length} campaigns with ref ${refId}, so it could not tell which one the pages use.`) };
+  }
+  if (data.length === 1) return { campaign: data[0] };
+  return data.length === 0
+    ? { notRun: notRun("not_found", "The live campaign read returned no campaign for this key, so there was no live campaign to compare against.") }
+    : { notRun: notRun("ambiguous_campaign", `The live campaign read returned ${data.length} campaigns for this key and the CampaignSpec names no campaign.ref_id to pick one, so it could not tell which one the pages use.`) };
+}
+
+// One GET of the campaign the key belongs to, through the proxy. `apiKey` is
+// the public Campaigns API key; it travels as the X-Campaign-Key header the
+// proxy's other routes take and never appears in the result. `campaignRefId`,
+// when known, asks the proxy for that one campaign. The proxy base passes the
+// same transport gate as every other proxy request: https, or a loopback host
+// over http.
+export async function readLiveCampaign({
+  apiKey,
+  proxyBase = null,
+  fetchImpl = null,
+  campaignRefId = null,
+  timeoutMs = LIVE_CAMPAIGN_TIMEOUT_MS,
+  maxBytes = LIVE_CAMPAIGN_MAX_BYTES,
+  warn = undefined,
+} = {}) {
+  if (typeof apiKey !== "string" || !apiKey.trim()) {
+    return notRun("no_key", "No public Campaigns API key resolved, so the live campaign was not read.");
+  }
+  if (typeof proxyBase !== "string" || !proxyBase.trim()) {
+    return notRun("not_read", "This invocation does not read the live campaign.");
+  }
+  const refId = campaignRefId == null ? null : String(campaignRefId).trim();
+  if (refId !== null && !/^\d+$/.test(refId)) {
+    return notRun("unexpected_ref", "The CampaignSpec's campaign.ref_id is not a numeric campaign id, so the live campaign was not read.");
+  }
+  let url;
+  try {
+    const { base } = assertSecureProxyBase(proxyBase, { label: "Live campaign read", credential: "the public campaign key", ...(warn ? { warn } : {}) });
+    // Built with URL so a base that already carries a query keeps it and
+    // ref_id is added as one more parameter, not appended after it.
+    const target = new URL(base);
+    target.pathname = `${target.pathname.replace(/\/+$/, "")}${LIVE_CAMPAIGN_PATH}`;
+    if (refId) target.searchParams.set("ref_id", refId);
+    url = target.href;
+  } catch (error) {
+    return notRun("insecure_proxy_base", `The live campaign was not read: ${error.message}`);
+  }
+  if (typeof fetchImpl !== "function") {
+    return notRun("fetch_unavailable", "No fetch is available in this runtime, so the live campaign was not read.");
+  }
+  const controller = new AbortController();
+  let response;
+  let text;
+  try {
+    ({ response, text } = await runWithDeadline(async () => {
+      const value = await fetchImpl(url, {
+        method: "GET",
+        redirect: "error",
+        headers: { Accept: "application/json", "X-Campaign-Key": apiKey.trim() },
+        signal: controller.signal,
+      });
+      // Loaded here rather than at the top: QA's commercial parity imports
+      // this module's extractors, and a static import back would be a cycle.
+      const { readBoundedResponseText } = await import("./qa-commercial-parity.mjs");
+      if (!value?.ok) {
+        // A non-2xx body is read only for the proxy's error line; an
+        // unreadable one leaves the status to speak for itself.
+        let errorText = null;
+        try {
+          errorText = await readBoundedResponseText(value, { maxBytes: LIVE_CAMPAIGN_ERROR_MAX_BYTES, kind: "live_campaign" });
+        } catch {
+          // the status is the finding
+        }
+        return { response: value, text: errorText };
+      }
+      return { response: value, text: await readBoundedResponseText(value, { maxBytes, kind: "live_campaign" }) };
+    }, {
+      timeoutMs,
+      onTimeout: () => controller.abort(),
+      timeoutError: () => Object.assign(new Error(`timed out after ${timeoutMs}ms`), { code: "timeout" }),
+      label: "readLiveCampaign",
+    }));
+  } catch (error) {
+    if (error?.code === "timeout") return notRun("timeout", `The live campaign read timed out after ${timeoutMs}ms.`);
+    if (error?.code === "live_campaign_response_too_large") return notRun("too_large", `The live campaign response exceeded ${maxBytes} bytes.`);
+    return notRun("network_error", `The live campaign read failed before a response: ${error?.message || String(error)}.`);
+  }
+  const requested = refId ? { campaign_ref_id: refId } : {};
+  const parsed = typeof text === "string" ? parseJson(text) : { ok: false };
+  if (!response?.ok) {
+    const status = Number.isInteger(response?.status) ? response.status : null;
+    const said = parsed.ok ? proxyErrorText(parsed.value, apiKey.trim()) : "";
+    const because = said ? ` The proxy said: ${said}` : "";
+    return notRun(
+      status === 404 ? "not_found" : "http_status",
+      status === 404
+        ? `The live campaign read answered 404${refId ? ` for campaign ref ${refId}` : " for this key"}: no live campaign was found to compare against.${because}`
+        : `The live campaign read answered ${status ?? "an unknown status"}, so the live campaign was not read.${because}`,
+      { http_status: status, ...requested },
+    );
+  }
+  if (!parsed.ok) return notRun("unparseable", "The live campaign response was not JSON.", requested);
+  const envelope = parsed.value;
+  if (!envelope || typeof envelope !== "object" || Array.isArray(envelope) || typeof envelope.ok !== "boolean") {
+    return notRun("unexpected_body", "The live campaign response was not the proxy's envelope ({ ok, data }).", requested);
+  }
+  if (envelope.ok !== true) {
+    const said = proxyErrorText(envelope, apiKey.trim());
+    return notRun("proxy_error", `The proxy answered ok: false${said ? `: ${said}` : ""}, so the live campaign was not read.`, requested);
+  }
+  if (envelope.data == null || typeof envelope.data !== "object") {
+    // ok: true with no campaign; the proxy's error line, when it sent one, is
+    // the reason.
+    const said = proxyErrorText(envelope, apiKey.trim());
+    return said
+      ? notRun("proxy_error", `The proxy answered with no campaign in its data field: ${said}, so the live campaign was not read.`, requested)
+      : notRun("unexpected_body", "The live campaign response carried no campaign in its data field.", requested);
+  }
+  const picked = pickCampaign(envelope.data, refId);
+  if (picked.notRun) return { ...picked.notRun, ...requested };
+  const refs = liveCampaignRefs(picked.campaign);
+  if (!refs) return notRun("unexpected_body", "The live campaign did not carry package and shipping-method lists with a ref on every entry.", requested);
+  return { status: "read", ...requested, ...refs };
+}
+
+// The `--no-live-refs` opt-out on `doctor` and `qa run`: no request, and the
+// check recorded not_run with reason `disabled`, never a pass.
+export function liveRefsDisabled(args) {
+  return Boolean(args) && Object.hasOwn(args, "no-live-refs");
+}
+
+export function disabledLiveRead() {
+  return notRun("disabled", "--no-live-refs was given, so the live campaign was not read.");
+}
+
+// An env var whose name says it holds something other than a public campaign
+// key. The shared resolver only asks that the name contain CAMPAIGN, so
+// `CAMPAIGN_ADMIN_TOKEN` would pass it; this read sends the value off the
+// machine, so it also refuses these words.
+const NON_PUBLIC_KEY_ENV_WORD = /ADMIN|TOKEN|SECRET|PASSWORD|PRIVATE|STORE/i;
+
+function refusedEnvKeySource(packet, resolved) {
+  const source = typeof packet?.campaign?.api_key_source === "string" ? packet.campaign.api_key_source.trim() : "";
+  if (!source.startsWith("env:")) return null;
+  const envName = source.slice("env:".length).trim();
+  if (!NON_PUBLIC_KEY_ENV_WORD.test(envName)) return null;
+  // Only when the env source is the one in play: a key from the packet or its
+  // CampaignSpec wins over it, and a refused packet or CampaignSpec value is
+  // already reported as that.
+  const envInPlay = resolved.key
+    ? resolved.origin === `env:${envName}`
+    : !resolved.rejected || resolved.rejected.kind === "unsupported_env_name" || resolved.rejected.source === `env:${envName}`;
+  return envInPlay ? envName : null;
+}
+
+// The packet-local CampaignSpec, read the way the key resolver reads it;
+// undefined when the packet names none or it cannot be read.
+function readPacketLocalSpec(packet, packetPath) {
+  const localPath = packet?.spec?.local_path;
+  if (typeof localPath !== "string" || !localPath.trim() || typeof packetPath !== "string" || !packetPath.trim()) return undefined;
+  try {
+    return readJsonIfExists(resolveFromFile(packetPath, localPath)) ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// The key from the packet, its local CampaignSpec, or the declared
+// campaign-key env var (the resolver the remit and Map write use; its shape
+// and env-name gates apply, plus the stricter env-name gate above), then one
+// read, for the campaign the CampaignSpec's `campaign.ref_id` names when it
+// names one.
+export async function readLiveCampaignForPacket({ packet, packetPath = null, spec = undefined, env = process.env, fetchImpl = null, proxyBase = null, timeoutMs, warn } = {}) {
+  const localSpec = spec !== undefined ? spec : readPacketLocalSpec(packet, packetPath);
+  const resolved = resolveCampaignsApiKeySource(packet, packetPath, env, localSpec === undefined ? {} : { spec: localSpec });
+  const refusedEnv = refusedEnvKeySource(packet, resolved);
+  if (refusedEnv) {
+    return notRun(
+      "key_source_refused",
+      `api_key_source "env:${refusedEnv}" names a variable that holds an admin, store or secret credential rather than the public Campaigns API key, so its value was not sent and the live campaign was not read. Point api_key_source at the public campaign key (for example env:CAMPAIGNS_API_KEY).`,
+    );
+  }
+  if (!resolved.key) {
+    return resolved.rejected
+      ? notRun("key_rejected", describeCampaignKeyRejection(resolved.rejected))
+      : notRun("no_key", "No public Campaigns API key resolved from the packet, its local CampaignSpec or the declared env source, so the live campaign was not read.");
+  }
+  const result = await readLiveCampaign({
+    apiKey: resolved.key,
+    fetchImpl,
+    proxyBase,
+    campaignRefId: campaignRefIdFromSpec(localSpec),
+    ...(timeoutMs ? { timeoutMs } : {}),
+    ...(warn ? { warn } : {}),
+  });
+  return { ...result, key_source: resolved.origin };
+}
+
+function sortedRefs(values) {
+  return [...new Set([...values].map(String))].sort((a, b) => a.localeCompare(b, "en", { numeric: true }));
+}
+
+// pages: [{ page_id, file?, in_spec?, package_refs, shipping_refs }] (Sets or
+// arrays); `in_spec: false` marks a built page the CampaignSpec does not list.
+// map: { package_refs, shipping_refs } from the CampaignSpec. live: a
+// readLiveCampaign result, or undefined when the caller did not read.
+export function evaluateLiveCampaignRefs({ pages = [], map = {}, live } = {}) {
+  const checkedPages = pages.filter((page) => page && page.page_id != null);
+  if (!live) live = notRun("not_read", "This invocation does not read the live campaign.");
+  if (live.status !== "read") {
+    return {
+      status: "not_run",
+      reason_code: live.reason_code,
+      reason: live.reason,
+      // A read that was attempted and failed is the operator's to see; no key
+      // is already reported by the key check, a caller that does not read
+      // has nothing to report, and `--no-live-refs` asked for no read.
+      attempted: !["no_key", "key_rejected", "not_read", "disabled"].includes(live.reason_code),
+      ...(live.http_status !== undefined ? { http_status: live.http_status } : {}),
+      checked_pages: checkedPages.length,
+      page_findings: [],
+      drift: null,
+    };
+  }
+  const livePackages = new Set(live.package_refs);
+  const liveShipping = new Set(live.shipping_refs);
+  const pageFindings = [];
+  for (const page of checkedPages) {
+    const missingShipping = sortedRefs(page.shipping_refs || []).filter((ref) => !liveShipping.has(ref));
+    const missingPackages = sortedRefs(page.package_refs || []).filter((ref) => !livePackages.has(ref));
+    const where = { page_id: String(page.page_id), ...(page.file ? { file: page.file } : {}), ...(page.in_spec === false ? { in_spec: false } : {}) };
+    if (missingShipping.length) pageFindings.push({ code: LIVE_REF_CODES.shipping, kind: "shipping", ...where, refs: missingShipping });
+    if (missingPackages.length) pageFindings.push({ code: LIVE_REF_CODES.package, kind: "package", ...where, refs: missingPackages });
+  }
+  const mapPackages = sortedRefs(map.package_refs || []);
+  const mapShipping = sortedRefs(map.shipping_refs || []);
+  const drift = {
+    packages: {
+      map_only: mapPackages.filter((ref) => !livePackages.has(ref)),
+      live_only: sortedRefs(livePackages).filter((ref) => !mapPackages.includes(ref)),
+    },
+    shipping_methods: {
+      map_only: mapShipping.filter((ref) => !liveShipping.has(ref)),
+      live_only: sortedRefs(liveShipping).filter((ref) => !mapShipping.includes(ref)),
+    },
+  };
+  const hasDrift = Object.values(drift).some((side) => side.map_only.length || side.live_only.length);
+  return {
+    status: pageFindings.length ? "blocked" : "pass",
+    checked_pages: checkedPages.length,
+    live_package_count: livePackages.size,
+    live_shipping_count: liveShipping.size,
+    page_findings: pageFindings,
+    drift: hasDrift ? drift : null,
+  };
+}
+
+export function liveRefFindingMessage(finding) {
+  const noun = finding.kind === "shipping" ? "shipping ID(s)" : "package ID(s)";
+  const effect = finding.kind === "shipping"
+    ? "the SDK falls back to another shipping method and the order is charged that method's price"
+    : "the SDK cannot add a package the campaign does not serve";
+  const subject = finding.in_spec === false ? `Built page ${finding.file || finding.page_id} (not a CampaignSpec page)` : `Page "${finding.page_id}"`;
+  return `${subject} references ${noun} the live campaign does not serve: ${finding.refs.join(", ")}. The CampaignSpec is not the authority here; ${effect}. Point the page at a ${finding.kind === "shipping" ? "shipping method" : "package"} the campaign serves, or restore it in the campaign.`;
+}
+
+export function campaignDriftMessage(drift) {
+  const parts = [];
+  const side = (label, values) => { if (values.length) parts.push(`${label}: ${values.join(", ")}`); };
+  side("packages in the CampaignSpec but not the live campaign", drift.packages.map_only);
+  side("packages in the live campaign but not the CampaignSpec", drift.packages.live_only);
+  side("shipping methods in the CampaignSpec but not the live campaign", drift.shipping_methods.map_only);
+  side("shipping methods in the live campaign but not the CampaignSpec", drift.shipping_methods.live_only);
+  return `The saved CampaignSpec and the live campaign differ — ${parts.join("; ")}. Re-save the Map from the live campaign so doctor and QA compare against what checkout serves.`;
+}
+
+export function liveRefsNotRunMessage(result) {
+  return `The live campaign ref check did not run: ${result.reason} Page shipping and package refs were compared against the CampaignSpec only.`;
+}

package/src/login.mjs

@@ -2,8 +2,8 @@ import { createCredentialStore } from './credential-store.mjs';
 
 export const GATEWAY = 'https://mcp.nextcommerce.com';
 export const CLIENT_ID = 'campaigns-os-owned-store-pilot';
-export const RESOURCE = GATEWAY + '/campaigns';
-export const SCOPE = 'campaigns:read';
+export const RESOURCE = GATEWAY + '/mcp';
+export const SCOPE = 'campaigns.read';
 const DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
 const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
 const safeString = (value, max = 8192) => typeof value === 'string' && value.length > 0 && value.length <= max && !/[\u0000-\u001f\u007f]/u.test(value);

package/src/page-kit-store-profile.mjs

@@ -52,6 +52,38 @@ function normalizeFieldValue(value) {
   return { valid: true, value: normalizeStoreProfileValue(value) };
 }
 
+// An explicit empty spec value for one of the nine governed fields (`""`, or
+// whitespace only, which the gate compares as `""`) says the merchant has no
+// such value: sync blanks a starter demo value with it and the gate reads a
+// blank target as `intentionally_empty`. A real (non-demo) target value is
+// left as it is and still warns `target_only`. An absent or null key still
+// means "not provided", and an empty string outside the nine carries no such
+// meaning.
+export function isAuthoritativeEmptyStoreProfileValue(field, value) {
+  return PAGE_KIT_STORE_PROFILE_FIELDS.includes(field)
+    && typeof value === "string"
+    && normalizeStoreProfileValue(value) === "";
+}
+
+// The sentence naming the fields a gate reads as intentionally empty. Doctor
+// still requires campaign.store_url (its spec.store_profile check), so a ""
+// there is named but not treated as settled.
+export function storeProfileIntentionallyEmptyNote(fields) {
+  if (!fields.length) return "";
+  return ` Intentionally empty per the CampaignSpec: ${fields.join(", ")}.`
+    + (fields.includes("store_url")
+      ? " campaign.store_url is still required, so doctor's spec.store_profile check blocks on an empty store_url."
+      : "");
+}
+
+// The sentence for fields the spec sets to "" while the target holds a real,
+// non-demo value: sync blanks only a recognised starter demo value, so the
+// spec's "" was not applied and the value stays until someone removes it.
+export function storeProfileEmptyNotAppliedNote(fields, where) {
+  if (!fields.length) return "";
+  return ` The CampaignSpec sets ${fields.map((field) => `campaign.${field}`).join(", ")} to "" (none), but the target holds a real, non-demo value there; page-kit sync blanks only a recognised starter demo value, so it did not apply the "". Remove the value from ${where} by hand if the merchant has none.`;
+}
+
 export function isDemoResidue(field, value) {
   if (!value) return false;
   if (URL_FIELDS.has(field)) {
@@ -123,15 +155,21 @@ export function storeProfileSpecValueProblem(field, value) {
 // The edit a blocked row needs when sync cannot make it: a target-side
 // defect with no spec value behind it (a demo or malformed target value in a
 // field the spec does not carry) is corrected in the target, or the field is
-// added to the spec and synced; a present-but-unusable spec value is
-// corrected in the spec.
-function repairDescriptionForUnsyncableRows(rows, subject) {
+// added to the spec and synced; a non-demo target value under a spec "" is
+// removed or corrected in the target by hand; a present-but-unusable spec
+// value is corrected in the spec.
+function repairDescriptionForUnsyncableRows(rows, subject, authoritativeEmptyFields) {
   const where = `${subject.target_path}[${subject.public_route_slug}]`;
   const targetSide = rows.filter((row) => storeProfileSpecValueProblem(row.field, row.spec) === "missing");
+  const notCarried = targetSide.filter((row) => !authoritativeEmptyFields.has(row.field));
+  const specEmpty = targetSide.filter((row) => authoritativeEmptyFields.has(row.field));
   const specSide = rows.filter((row) => storeProfileSpecValueProblem(row.field, row.spec) !== "missing");
   const parts = [];
-  if (targetSide.length) {
-    parts.push(`Remove or correct ${where}.${targetSide.map((row) => row.field).join(", ")} (the CampaignSpec does not carry ${targetSide.length === 1 ? "this field" : "these fields"}, so page-kit sync has nothing to write over the target), or add campaign.${targetSide.map((row) => row.field).join(", campaign.")} to the spec and run page-kit sync.`);
+  if (notCarried.length) {
+    parts.push(`Remove or correct ${where}.${notCarried.map((row) => row.field).join(", ")} (the CampaignSpec does not carry ${notCarried.length === 1 ? "this field" : "these fields"}, so page-kit sync has nothing to write over the target), or add campaign.${notCarried.map((row) => row.field).join(", campaign.")} to the spec and run page-kit sync.`);
+  }
+  if (specEmpty.length) {
+    parts.push(`Remove or correct ${where}.${specEmpty.map((row) => row.field).join(", ")} by hand: the CampaignSpec sets campaign.${specEmpty.map((row) => row.field).join(", campaign.")} to "" (none), but page-kit sync blanks only a recognised starter demo value, so it did not apply the "" over this non-demo target value.`);
   }
   if (specSide.length) {
     parts.push(`Repair the CampaignSpec Store Profile field(s) ${specSide.map((row) => `${row.field} (${storeProfileSpecValueProblem(row.field, row.spec)})`).join(", ")}: page-kit sync writes only a well-shaped, non-demo spec value over the target. Fix the spec, then run page-kit sync.`);
@@ -141,10 +179,14 @@ function repairDescriptionForUnsyncableRows(rows, subject) {
 
 // Sync repairs a row by writing the spec's value over the target's, so it
 // needs a usable spec value: present, well-shaped for its field, and not the
-// starter demo value itself. matrixRow puts demo_residue ahead of the spec
-// comparison, so a residue row may have an empty (or itself demo) spec value.
-function syncRepairsRow(row) {
-  return SYNC_REPAIRABLE_KINDS.has(row.kind) && storeProfileSpecValueProblem(row.field, row.spec) === null;
+// starter demo value itself; or, for demo residue only, an explicit empty
+// value, which sync writes as "". matrixRow puts demo_residue ahead of the
+// spec comparison, so a residue row may have an absent (or itself demo) spec
+// value.
+function syncRepairsRow(row, authoritativeEmptyFields) {
+  return SYNC_REPAIRABLE_KINDS.has(row.kind)
+    && ((row.kind === "demo_residue" && authoritativeEmptyFields.has(row.field))
+      || storeProfileSpecValueProblem(row.field, row.spec) === null);
 }
 
 export function storeProfileDemoResidueFields(gate) {
@@ -171,6 +213,13 @@ function matrixRow(field, rawSpec, rawTarget) {
   if (isDemoResidue(field, target.value)) {
     return { field, kind: "demo_residue", spec: spec.value, target: target.value, severity: "blocker" };
   }
+  // The spec says the field is empty and a blank (or absent) target agrees. A
+  // real target value against a spec "" stays a target_only warning below:
+  // Maps saved "" for every cleared store field before "" meant empty, so it
+  // is not trusted over a value someone entered.
+  if (isAuthoritativeEmptyStoreProfileValue(field, rawSpec) && !target.value) {
+    return { field, kind: "intentionally_empty", spec: spec.value, target: target.value, severity: "clean" };
+  }
   if (spec.value && !target.value) {
     return { field, kind: "target_missing", spec: spec.value, target: target.value, severity: "blocker" };
   }
@@ -292,6 +341,11 @@ export function evaluatePageKitStoreProfile({
   const blocker_fields = matrix.filter((row) => row.severity === "blocker").map((row) => row.field);
   const warning_fields = matrix.filter((row) => row.severity === "warning").map((row) => row.field);
   const blockerRows = matrix.filter((row) => row.severity === "blocker");
+  const authoritativeEmptyFields = new Set(PAGE_KIT_STORE_PROFILE_FIELDS.filter((field) => isAuthoritativeEmptyStoreProfileValue(field, specCampaign?.[field])));
+  const intentionallyEmptyFields = matrix.filter((row) => row.kind === "intentionally_empty").map((row) => row.field);
+  const emptyNotAppliedFields = matrix
+    .filter((row) => row.kind === "target_only" && authoritativeEmptyFields.has(row.field))
+    .map((row) => row.field);
   const waivable = blockerRows.length > 0
     && blockerRows.every((row) => isStoreProfileDiscrepancyWaivable(row.kind));
   // Waiver history matters only while this exact checkpoint is blocked. Once
@@ -328,7 +382,10 @@ export function evaluatePageKitStoreProfile({
       ? `Target Store Profile has an active named-human waiver for blocking field(s): ${blocker_fields.join(", ")}.`
       : warning_fields.length
         ? `Target Store Profile has target-only value(s): ${warning_fields.join(", ")}.`
-        : "Target Store Profile exactly matches the CampaignSpec for all nine governed fields.";
+          + storeProfileEmptyNotAppliedNote(emptyNotAppliedFields, `${subject.target_path}[${subject.public_route_slug}]`)
+          + storeProfileIntentionallyEmptyNote(intentionallyEmptyFields)
+        : "Target Store Profile exactly matches the CampaignSpec for all nine governed fields."
+          + storeProfileIntentionallyEmptyNote(intentionallyEmptyFields);
   return {
     id: PAGE_KIT_STORE_PROFILE_SCOPE,
     scope: PAGE_KIT_STORE_PROFILE_SCOPE,
@@ -345,7 +402,7 @@ export function evaluatePageKitStoreProfile({
     waiver,
     waiver_assessment,
     required_actions: status === "blocked" ? [
-      blockerRows.every(syncRepairsRow)
+      blockerRows.every((row) => syncRepairsRow(row, authoritativeEmptyFields))
         ? {
           id: "repair_target",
           kind: "command",
@@ -356,7 +413,7 @@ export function evaluatePageKitStoreProfile({
           id: "repair_target",
           kind: "edit",
           command: null,
-          description: repairDescriptionForUnsyncableRows(blockerRows.filter((row) => !syncRepairsRow(row)), subject),
+          description: repairDescriptionForUnsyncableRows(blockerRows.filter((row) => !syncRepairsRow(row, authoritativeEmptyFields)), subject, authoritativeEmptyFields),
         },
       ...(waivable ? [{
         id: "waive_checkpoint",