@nextcommerce/campaigns-os 1.46.0 → 1.48.0

package/src/doctor/inspect.mjs

@@ -1,5 +1,6 @@
 // Doctor entry points: the doctor command, packet inspection and built-output inspection.
 import { resolveCampaignIdentity } from "../spec-source-identity.mjs";
+import { applyLocalPreviewToCheckpoint, applyLocalPreviewToPolishGate, carriedForwardMessage, CARRIED_FORWARD } from "../local-preview-policy.mjs";
 import { withHtmlScanSnapshot } from "../html-scan.mjs";
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
@@ -506,16 +507,23 @@ function inspectDoctorPacket(packetPath, { contextPath = undefined, reportPath =
   }
   runPricingCssHideCheck({ packet, derived, warnings, ready, report });
 
-  const polishCheckpointGate = evaluateRecordedHiddenEagerMediaCheckpoint({ packet, report });
+  // The local preview policy (local-preview-policy.mjs) carries missing
+  // polish and page-load evidence forward as warnings on a local-serve packet.
+  const polishCheckpointGate = applyLocalPreviewToCheckpoint(
+    evaluateRecordedHiddenEagerMediaCheckpoint({ packet, report }),
+    { packet, report },
+  );
   derived.polish_checkpoint_gate = polishCheckpointGate;
-  const polishGate = evaluatePolishGate({
+  const polishGate = applyLocalPreviewToPolishGate(evaluatePolishGate({
     report,
     hiddenEagerMediaGate: polishCheckpointGate,
     currentOutputFingerprint: derived.build_output_fingerprint?.value || null,
-  });
+  }), { packet, checkpointGate: polishCheckpointGate });
   derived.polish_gate = polishGate;
   if (polishGate.status === "blocked" && !polishGate.owned_checkpoint_only) {
     pushGateIssue({ errors, warnings }, gateIssue("polish_gate", polishGate));
+  } else if (polishGate.status === CARRIED_FORWARD && !polishGate.owned_checkpoint_only) {
+    addIssue(warnings, polishGate.code, carriedForwardMessage(polishGate), { polish_gate: polishGate });
   } else if (polishGate.status === "waived" && !polishGate.owned_checkpoint_only) {
     ready.push(`Polish gate passed under waiver: ${polishGate.waiver?.reason || "(no reason recorded)"}`);
   } else if (polishGate.status === "pass") {
@@ -524,6 +532,8 @@ function inspectDoctorPacket(packetPath, { contextPath = undefined, reportPath =
 
   if (polishCheckpointGate.status === "blocked") {
     pushGateIssue({ errors, warnings }, gateIssue("polish_checkpoint_gate", polishCheckpointGate));
+  } else if (polishCheckpointGate.status === CARRIED_FORWARD) {
+    addIssue(warnings, polishCheckpointGate.code, carriedForwardMessage(polishCheckpointGate), { polish_checkpoint_gate: polishCheckpointGate });
   } else if (polishCheckpointGate.status === "waived") {
     addIssue(
       warnings,

package/src/doctor/next-step.mjs

@@ -1,5 +1,6 @@
 // The next step doctor recommends, and the gate issues `next` reads from doctor.
 import { campaignIdentitiesMatch } from "../spec-source-identity.mjs";
+import { CARRIED_FORWARD } from "../local-preview-policy.mjs";
 import { resolve } from "node:path";
 import { orderPathDepthDriftText } from "../proof-policy.mjs";
 import { anyAssemblyReportStageBlocked } from "../stage-ledger.mjs";
@@ -462,6 +463,9 @@ function pickNextStage(report, { errors = [], derived = null }, prepareBuildGate
   }
 
   for (const cliStage of NEXT_STAGE_ORDER) {
+    // On the local preview, missing polish is carried forward as a warning
+    // (local-preview-policy.mjs): the ladder moves on to deploy and QA.
+    if (cliStage === "polish" && polishGate.status === CARRIED_FORWARD) continue;
     const reportKey = reportKeyForCliStage(cliStage);
     const stage = report.stages[reportKey];
     if (!stage) {

package/src/gate-actions.mjs

@@ -62,6 +62,14 @@ export const HIDDEN_EAGER_MEDIA_ACTIONS = Object.freeze({
     command: null,
     description: localProofRebuildText(),
   }),
+  // Every mapped page is template stock: capture has no design route, so
+  // neither a recapture nor an authority repair can produce the evidence.
+  map_design_route: Object.freeze({
+    id: "polish.hidden_eager_media.map_design_route",
+    kind: "manual",
+    command: null,
+    description: "Every mapped page is template stock, so polish capture has nothing to measure. Map at least one page to its design source HTML (source_html.pages[].path) and rerun intake, or prove the campaign on the local preview (deploy.target local-serve served from localhost), where this missing evidence is carried forward as a warning.",
+  }),
 });
 
 const PACKET_PLACEHOLDER = "--packet <packet>";

package/src/local-preview-policy.mjs

@@ -0,0 +1,92 @@
+// The local preview policy: one place that decides which missing evidence a
+// localhost preview carries forward as a warning instead of a blocker.
+//
+// The local preview is a packet whose deploy target is `local-serve`, served
+// from a loopback host. There a campaign must still prove its commerce (store
+// and campaign binding, routes, SDK loading, prices, a typed-card order), but
+// evidence that only design work or launch produces may be missing. Missing
+// evidence is reported as missing, never as passed: a carried-forward gate is
+// a warning in doctor, `next` does not stop on it, and QA records it as a
+// `warn` row, so the verdict is at best `ready_with_exceptions`. A hosted
+// preview or production packet never takes this path, and every check not
+// named below keeps its meaning on every path.
+//
+// Doctor and QA apply this to the gates they evaluate; `next` reads doctor's
+// gates. Recording a stage (`record polish`) and the waiver commands keep the
+// strict gates.
+import { isLocalServePacket } from "./local-proof.mjs";
+import { isLoopbackHostname } from "./remit.mjs";
+
+export const LOCAL_PREVIEW_POLICY = "local_preview";
+export const CARRIED_FORWARD = "carried_forward";
+
+// The checks carried forward, one by one. Each is evidence the campaign does
+// not have yet, not evidence that something is wrong:
+// - polish was never recorded for this build;
+// - no page-load capture exists, either because polish capture never ran or
+//   because every mapped page is template stock and there is no design route
+//   to capture.
+const CARRIED_POLISH_CODES = Object.freeze(new Set([
+  "polish.report_missing",
+  "polish.evidence_missing",
+]));
+export const NO_CAPTURABLE_ROUTES_CODE = "polish.hidden_eager_media.no_capturable_routes";
+const MISSING_CAPTURE_CODE = "polish.hidden_eager_media.capture_malformed";
+
+// With no generatable brand theme the starter template is the design, so its
+// palette and chrome are expected on the local preview: residue findings are
+// warnings there, as they are under a waived theme gate.
+const STARTER_IS_THE_DESIGN_THEME_CODE = "theme_gate.nothing_generatable";
+
+function loopbackOrAbsent(url) {
+  if (url === undefined || url === null || url === "") return true;
+  try {
+    return isLoopbackHostname(new URL(String(url)).hostname);
+  } catch {
+    return false;
+  }
+}
+
+export function isLocalPreview(packet, { baseUrl = null } = {}) {
+  return isLocalServePacket(packet)
+    && loopbackOrAbsent(packet?.deploy?.preview_url)
+    && loopbackOrAbsent(baseUrl);
+}
+
+function pageLoadRecorded(report) {
+  return report?.stages?.polish?.evidence?.visual_review?.page_load != null;
+}
+
+function carried(gate) {
+  return {
+    ...gate,
+    status: CARRIED_FORWARD,
+    carried_forward: { policy: LOCAL_PREVIEW_POLICY, from_status: gate.status, evidence: "missing" },
+  };
+}
+
+// The hidden eager-media checkpoint, evaluated on its own.
+export function applyLocalPreviewToCheckpoint(gate, { packet, report, baseUrl = null } = {}) {
+  if (gate?.status !== "blocked" || !isLocalPreview(packet, { baseUrl })) return gate;
+  const missing = gate.code === NO_CAPTURABLE_ROUTES_CODE
+    || (gate.code === MISSING_CAPTURE_CODE && !pageLoadRecorded(report));
+  return missing ? carried(gate) : gate;
+}
+
+// The polish gate folds the checkpoint in, so it is carried forward only when
+// whatever it owns from the checkpoint was carried forward too.
+export function applyLocalPreviewToPolishGate(gate, { packet, checkpointGate = null, baseUrl = null } = {}) {
+  if (gate?.status !== "blocked" || !isLocalPreview(packet, { baseUrl })) return gate;
+  const checkpointCarried = checkpointGate?.status === CARRIED_FORWARD;
+  if (gate.owned_checkpoint_status === "blocked" && !checkpointCarried) return gate;
+  if (gate.owned_checkpoint_only) return checkpointCarried ? carried(gate) : gate;
+  return CARRIED_POLISH_CODES.has(gate.code) ? carried(gate) : gate;
+}
+
+export function starterResidueIsExpected(themeGate, { packet, baseUrl = null } = {}) {
+  return themeGate?.code === STARTER_IS_THE_DESIGN_THEME_CODE && isLocalPreview(packet, { baseUrl });
+}
+
+export function carriedForwardMessage(gate) {
+  return `Carried forward on the local preview: ${gate.reason} This evidence is missing, not passed; a hosted preview or production run requires it.`;
+}

package/src/page-kit-sdk-version.mjs

@@ -92,6 +92,10 @@ export function evaluatePageKitSdkVersion({
   waivers = [],
   required = true,
   now = new Date().toISOString(),
+  // { family, sdk_version } of the selected certified template family, when
+  // the caller knows it: the missing-pin reason names that verified SDK so the
+  // pin is not chosen by searching docs.
+  familyVerification = null,
 } = {}) {
   const pin = resolveSpecSdkPin(spec);
   const { has_canonical: hasCanonical, has_alias: hasAlias } = pin;
@@ -139,7 +143,10 @@ export function evaluatePageKitSdkVersion({
       scope: PAGE_KIT_SDK_VERSION_SCOPE,
       status: "blocked",
       code: "page_kit.sdk_version.spec_missing",
-      reason: "CampaignSpec is missing global_config.sdk_version (and the runtime.sdk_version alias); add an explicit released SDK pin before build or QA.",
+      reason: "CampaignSpec is missing global_config.sdk_version (and the runtime.sdk_version alias); add an explicit released SDK pin before build or QA."
+        + (isReleasedSdkVersion(familyVerification?.sdk_version) && typeof familyVerification?.family === "string"
+          ? ` The "${familyVerification.family}" template family was last verified against ${familyVerification.sdk_version}.`
+          : ""),
       waivable: false,
       subject,
       state: { spec_status: "missing" },

package/src/polish-node.mjs

@@ -1,4 +1,5 @@
 import { campaignIdentitiesMatch, localSpecIdentityFields } from "./spec-source-identity.mjs";
+import { NO_CAPTURABLE_ROUTES_CODE } from "./local-preview-policy.mjs";
 import { createHash } from "node:crypto";
 import { HIDDEN_EAGER_MEDIA_ACTIONS } from "./gate-actions.mjs";
 import { dirname, join, resolve } from "node:path";
@@ -93,6 +94,8 @@ function mappedSpecRoute(value, pageId) {
   return route;
 }
 
+const NO_CAPTURABLE_ROUTES_ERROR = "no_capturable_routes";
+
 export function planPolishCapture({ packet, baseUrl } = {}) {
   if (!isPlainObject(packet) || !Array.isArray(packet?.source_html?.pages) || packet.source_html.pages.length === 0) {
     throw new Error("polish capture requires packet.source_html.pages mappings.");
@@ -129,7 +132,14 @@ export function planPolishCapture({ packet, baseUrl } = {}) {
     });
   }
 
-  if (routes.length === 0) throw new Error("polish capture has no mapped non-skipped routes to capture.");
+  if (routes.length === 0) {
+    const error = new Error(
+      "polish capture has no mapped non-skipped routes to capture: every mapped page is template stock (skip_reason), so there is no design route to compare."
+      + " On a local-serve preview, missing polish evidence is carried forward as a warning; run `next` for the next stage.",
+    );
+    error.code = NO_CAPTURABLE_ROUTES_ERROR;
+    throw error;
+  }
   routes.sort((a, b) => a.requested_route.localeCompare(b.requested_route) || a.page_id.localeCompare(b.page_id));
   for (let index = 1; index < routes.length; index += 1) {
     if (routes[index - 1].requested_route === routes[index].requested_route) {
@@ -189,6 +199,19 @@ function recordedAuthorityBlock({ packet, report, plan = null, now } = {}) {
   };
 }
 
+// Every mapped page is template stock: there is nothing for polish capture to
+// measure, which is missing evidence rather than a malformed packet. It stays
+// a non-waivable block; the local preview policy carries it forward.
+function noCapturableRoutesBlock({ packet, report, now } = {}) {
+  const block = recordedAuthorityBlock({ packet, report, now });
+  return {
+    ...block,
+    code: NO_CAPTURABLE_ROUTES_CODE,
+    reason: "Every mapped page is template stock (skip_reason), so polish capture has no design route to capture and this build has no page-load evidence.",
+    required_actions: [HIDDEN_EAGER_MEDIA_ACTIONS.map_design_route],
+  };
+}
+
 function recordedCheckpointNotApplicable() {
   return {
     id: HIDDEN_EAGER_MEDIA_SCOPE,
@@ -219,7 +242,8 @@ export function evaluateRecordedHiddenEagerMediaCheckpoint({ packet, report, now
   let plan;
   try {
     plan = planPolishCapture({ packet, baseUrl: "https://polish-capture.invalid" });
-  } catch {
+  } catch (error) {
+    if (error?.code === NO_CAPTURABLE_ROUTES_ERROR) return noCapturableRoutesBlock({ packet, report, now });
     return recordedAuthorityBlock({ packet, report, now });
   }
 

package/src/progress-node.mjs

@@ -58,7 +58,11 @@ export function projectProgressObservation({workspace,context,report,doctor,cont
     binding:reportBound&&id(verdict.run_id)&&id(verdict.run_id)===id(report?.stages?.qa?.verdict_run_id)&&build&&qaSource===build&&doctor?.derived?.build_output_fingerprint?.status==='pass'&&hash(verdict.spec_hash)===localHash?'matching':'unconfirmed',
     publish_state:accepted(qaResult?.qa_verdict_publish?.state,['skipped','ok','failed']),
   }:null;
-  const gates=(Array.isArray(continuation?.gates)?continuation.gates:[]).slice(0,PROGRESS_GATE_LIMIT).map(gate=>({id:accepted(gate?.id,PROGRESS_GATE_IDS),state:PROGRESS_GATE_IDS.includes(gate?.id)?accepted(gate?.status,['pass','blocked','waived','not_applicable']):'unknown'}));
+  // The snapshot schema has no carried-forward state: a gate the local preview
+  // policy carried forward does not apply on this path, so it is not_applicable
+  // here (never pass).
+  const gateState=status=>accepted(status==='carried_forward'?'not_applicable':status,['pass','blocked','waived','not_applicable']);
+  const gates=(Array.isArray(continuation?.gates)?continuation.gates:[]).slice(0,PROGRESS_GATE_LIMIT).map(gate=>({id:accepted(gate?.id,PROGRESS_GATE_IDS),state:PROGRESS_GATE_IDS.includes(gate?.id)?gateState(gate?.status):'unknown'}));
   const actions=[...new Set((Array.isArray(continuation?.next_actions)?continuation.next_actions:[]).slice(0,64).map(action=>accepted(action?.id,PROGRESS_ACTION_IDS)))];
   const stage=accepted(continuation?.stage,PROGRESS_CONTINUATIONS);
   const preview=typeof packet?.deploy?.preview_url==='string'&&packet.deploy.preview_url?packet.deploy.preview_url:null;

package/src/qa-analytics-parity.mjs

@@ -547,6 +547,10 @@ function valuesEqual(a, b) {
 // flag carried-over-tag regressions for human review.
 // `options.url` is the candidate URL that was captured (the resolved capture
 // target) — stamped on every emitted assertion, pass and fail alike.
+// `options.candidatePage` describes the page the candidate was captured on when
+// the leg picked it automatically (#512): `{ receipt, source, page_type }`.
+// An explicit --analytics-candidate passes none and is treated as the receipt
+// the operator named.
 export function diffAnalyticsParity(baseline, candidate, options = {}) {
   const assertions = [];
   const auditedUrl = (typeof options.url === "string" && options.url.trim()) ? options.url.trim() : null;
@@ -561,13 +565,44 @@ export function diffAnalyticsParity(baseline, candidate, options = {}) {
   const cEff = effectivePurchase(c);
 
   // 1. Purchase present on candidate — the highest-value blocking check.
-  assertions.push(emit({
+  // #512: Purchase fires only on a receipt. When the candidate is known not to
+  // be one (the automatic capture page is the campaign root or a built entry),
+  // a missing Purchase is a page mismatch, not a regression, so it goes to
+  // manual review naming the mismatch. A receipt candidate, or one the
+  // operator named, still blocks.
+  const candidatePage = options.candidatePage && typeof options.candidatePage === "object" ? options.candidatePage : null;
+  if (!cEff.fired && candidatePage?.receipt === false) {
+    const baselineFired = effectivePurchase(b).fired;
+    assertions.push(emit({
+      id: "analytics-parity:purchase-present",
+      status: STATUS.MANUAL_REVIEW,
+      severity: SEVERITY.WARN,
+      expected: "a receipt candidate to check Purchase on; the automatic candidate is not a receipt, so pair receipts with --analytics-candidate",
+      actual: baselineFired
+        ? "baseline fired a Purchase but the automatic candidate is not a receipt page; pass --analytics-candidate <candidate receipt url> to compare receipts"
+        : "neither page fired a Purchase and the automatic candidate is not a receipt page; pass receipt URLs to --analytics-baseline and --analytics-candidate to compare Purchase",
+      evidence: {
+        via: cEff.via,
+        candidate_events: c.eventNames || [],
+        baseline_purchase: bp,
+        page_mismatch: {
+          reason: baselineFired ? "receipt_baseline_non_receipt_candidate" : "candidate_not_receipt",
+          baseline_fired_purchase: baselineFired,
+          candidate_receipt: candidatePage.receipt,
+          candidate_source: candidatePage.source ?? null,
+          candidate_page_type: candidatePage.page_type ?? null,
+        },
+      },
+    }));
+  } else assertions.push(emit({
     id: "analytics-parity:purchase-present",
     status: cEff.fired ? STATUS.PASS : STATUS.FAIL,
     severity: SEVERITY.BLOCKER,
     expected: "candidate fires a Purchase (dl_purchase, or Meta/GA4 pixel if the SDK event is blocked)",
     actual: cEff.fired ? `purchase fired via ${cEff.via}` : "no purchase fire captured on candidate (dataLayer, Meta, or GA4)",
-    evidence: { via: cEff.via, candidate_events: c.eventNames || [], candidate_signals: c.purchaseSignals || {}, baseline_purchase: bp },
+    // An automatic candidate's page is recorded even when it fired, so a pass on
+    // a non-receipt page reads as such.
+    evidence: { via: cEff.via, candidate_events: c.eventNames || [], candidate_signals: c.purchaseSignals || {}, baseline_purchase: bp, ...(candidatePage ? { candidate_page: candidatePage } : {}) },
   }));
 
   if (cEff.fired) {

package/src/qa-binding-evidence.mjs

@@ -1,11 +1,11 @@
 import { parse as parseHtml } from 'parse5';
 import { parse as parseJs } from 'acorn';
 import { createPageSourceLoader, resolveCommercialApiKey } from './qa-commercial-parity.mjs';
-import { HTML_NAMESPACE, baseInEffect, documentBases, frozenBaseUrl, parseFailureDiagnostic, scriptKind } from './built-script-syntax.mjs';
+import { HTML_NAMESPACE, baseInEffect, documentBases, endsUnclosed, frozenBaseUrl, parseFailureDiagnostic, scriptKind } from './built-script-syntax.mjs';
 
 export const BINDING_SCHEMA = 'campaigns-os-page-binding/v0';
 export const BINDING_LIMITS = Object.freeze({ scripts_per_page: 6, scripts_per_run: 24, script_bytes: 262144, timeout_ms: 5000 });
-const SDK = /^https:\/\/cdn\.jsdelivr\.net\/gh\/NextCommerceCo\/campaign-cart@[^/]+\/(?:dist\/index\.js|public\/loader\.js)(?:\?[^#]*)?$/;
+const SDK = /^https:\/\/cdn\.jsdelivr\.net\/gh\/NextCommerceCo\/campaign-cart@[^/]+\/(?:dist\/(?:index|loader)\.js|public\/loader\.js)(?:\?[^#]*)?$/;
 const str = value => typeof value === 'string' && value.length ? value : null;
 
 // The expected credential uses the existing producer resolver. Disagreement
@@ -124,8 +124,10 @@ export async function observeBinding({ source, page, expected, scriptLoader, par
     // Only an HTML-namespace <script> loads `src`. An SVG script runs from
     // href / xlink:href or its inline text, which this static read does not
     // model: it is not fetched and leaves the binding dynamic.
+    // A script the file ends inside never reaches its end tag, so the parser
+    // never prepares it: the browser neither fetches nor runs it (#515).
     if (node.tagName === 'script' && node.namespaceURI !== HTML_NAMESPACE) dynamic = true;
-    else if (node.tagName === 'script') scripts.push({ attrs, base: baseInEffect(bases, node), text: (node.childNodes || []).map(n => n.value || '').join('') });
+    else if (node.tagName === 'script' && !endsUnclosed(node)) scripts.push({ attrs, base: baseInEffect(bases, node), text: (node.childNodes || []).map(n => n.value || '').join('') });
     // parse5 keeps template content separate; it is inert, as is noscript at boot.
     if (node.tagName !== 'noscript') for (const child of node.childNodes || []) walk(child);
   };