@nextcommerce/campaigns-os 1.54.0 → 1.57.0

package/src/brand-theme.mjs

@@ -256,8 +256,11 @@ function inferDesignIntentTokens(content, rootTokens = {}) {
     const lower = name.toLowerCase();
     if (isTargetContractToken(lower)) continue;
     const parts = tokenNameParts(lower);
+    const decorativeName = hasTokenPart(parts, DECORATIVE_NAME_PARTS);
+    const namedRole = hasTokenPart(parts, EXPLICIT_BRAND_PARTS);
     const ctaName = hasTokenPart(parts, ["cta", "button", "btn"]);
-    if (!ctaName && (hasTokenSequence(parts, ["brand"], ["primary", "main"]) || (hasTokenPart(parts, ["primary"]) && !hasTokenPart(parts, ["text", "foreground", "surface", "background", "bg", "border", "outline"])))) {
+    if (!ctaName && (!decorativeName || namedRole)
+      && (hasTokenSequence(parts, ["brand"], ["primary", "main"]) || (hasTokenPart(parts, ["primary"]) && !hasTokenPart(parts, ["text", "foreground", "surface", "background", "bg", "border", "outline"])))) {
       addToken("--brand-primary", color);
     }
     if (ctaName) {
@@ -281,7 +284,7 @@ function inferDesignIntentTokens(content, rootTokens = {}) {
     if (hasTokenPart(parts, ["rating", "star", "review"])) addToken("--rating-star", color);
   }
 
-  const rulePattern = /([^{}]+)\{([^{}]+)\}/g;
+  const rulePattern = /([^{};]+)\{([^{}]+)\}/g;
   for (const match of stripCssComments(content).matchAll(rulePattern)) {
     const selector = match[1] || "";
     for (const declaration of match[2].split(";")) {
@@ -291,9 +294,11 @@ function inferDesignIntentTokens(content, rootTokens = {}) {
       const color = resolveDeclarationColor(rawValue, rootTokens);
       if (!color) continue;
       if (["background", "background-color"].includes(name)) {
-        if (/(header|nav|announcement|brand|hero)/i.test(selector) && isStrongBrandColor(color)) {
+        if (hasPrimarySelectorRole(selector)
+          && isStrongBrandColor(color)) {
           addToken("--brand-primary", color);
-        } else if (isCtaLikeSelector(selector) && isStrongBrandColor(color)) {
+        }
+        if (isCtaLikeSelector(eligibleSelectorText(selector)) && isStrongBrandColor(color)) {
           addToken("--button-primary-bg", color);
           addToken("--brand-cta", color);
           addToken("--brand-accent", color);
@@ -319,6 +324,32 @@ function inferDesignIntentTokens(content, rootTokens = {}) {
   return tokens;
 }
 
+const DECORATIVE_NAME_PARTS = ["sale", "discount", "badge", "rating", "star", "strike", "border", "announcement"];
+const EXPLICIT_BRAND_PARTS = ["brand", "primary", "cta", "button", "btn"];
+
+function selectorSubjectParts(compound) {
+  return [...compound.classes, ...compound.ids].flatMap(tokenNameParts);
+}
+
+function subjectHasDecorativeRole(compound) {
+  // A button or submit input is a control whatever its classes say.
+  if (compound.type === "button") return false;
+  if (compound.type === "input" && compound.attributes.some((attribute) => /^\s*type\s*=\s*(["']?)submit\1\s*(?:i\s*)?$/i.test(attribute))) return false;
+  const parts = selectorSubjectParts(compound);
+  return hasTokenPart(parts, DECORATIVE_NAME_PARTS) && !hasTokenPart(parts, EXPLICIT_BRAND_PARTS);
+}
+
+function eligibleSelectorText(selector) {
+  const compounds = rightmostCompounds(selector);
+  if (!compounds) return selector;
+  return compounds.filter((compound) => !subjectHasDecorativeRole(compound))
+    .map((compound) => compound.selectorText).join(", ");
+}
+
+function hasPrimarySelectorRole(selector) {
+  return /(header|nav|announcement|brand|hero)/i.test(eligibleSelectorText(selector));
+}
+
 function isCtaLikeSelector(selector) {
   return /(?:^|[.#\s:_-])(?:cta|button|btn|submit|cart|buy|order)(?:$|[.#\s:_-])/i.test(String(selector || ""));
 }
@@ -337,11 +368,12 @@ const SELECTOR_ARGUMENT_PSEUDOS = new Set(["not", "is", "where", "has"]);
 function rightmostCompounds(selectorList) {
   const text = String(selectorList || "");
   const compounds = [];
-  const fresh = () => ({ type: null, classes: [], attributes: [], pseudos: [] });
-  const isEmpty = (compound) => !compound.type && !compound.classes.length && !compound.attributes.length && !compound.pseudos.length;
+  const fresh = () => ({ type: null, classes: [], ids: [], attributes: [], pseudos: [] });
+  const isEmpty = (compound) => !compound.type && !compound.classes.length && !compound.ids.length && !compound.attributes.length && !compound.pseudos.length;
   let current = fresh();
   let afterCombinator = false;
   let i = 0;
+  let selectorStart = 0;
   const readName = () => {
     const start = i;
     while (i < text.length && (/[A-Za-z0-9_\- -￿]/.test(text[i]) || text[i] === "\\")) i += text[i] === "\\" ? 2 : 1;
@@ -371,10 +403,12 @@ function rightmostCompounds(selectorList) {
     if (/[\s>+~]/.test(ch)) { afterCombinator = true; i += 1; continue; }
     if (ch === ",") {
       if (isEmpty(current)) return null;
+      current.selectorText = text.slice(selectorStart, i);
       compounds.push(current);
       current = fresh();
       afterCombinator = false;
       i += 1;
+      selectorStart = i;
       continue;
     }
     if (afterCombinator) { current = fresh(); afterCombinator = false; }
@@ -383,6 +417,7 @@ function rightmostCompounds(selectorList) {
       const name = readName();
       if (!name) return null;
       if (ch === ".") current.classes.push(name);
+      else current.ids.push(name);
     } else if (ch === "[") {
       const attribute = readGroup("[", "]");
       if (attribute === null) return null;
@@ -404,6 +439,7 @@ function rightmostCompounds(selectorList) {
     }
   }
   if (isEmpty(current)) return null;
+  current.selectorText = text.slice(selectorStart);
   compounds.push(current);
   return compounds;
 }
@@ -469,7 +505,7 @@ function splitDeclarations(body) {
 // declaredCtaForegroundValue.
 function collectCtaLabelRules(content, rootTokens = {}) {
   const rules = [];
-  for (const match of stripCssComments(content).matchAll(/([^{}]+)\{([^{}]+)\}/g)) {
+  for (const match of stripCssComments(content).matchAll(/([^{};]+)\{([^{}]+)\}/g)) {
     if (!isButtonSelector(match[1])) continue;
     let color = null;
     let background = null;
@@ -975,7 +1011,7 @@ function mapTokens(tokens, targetTokens, { rootTokens = {}, ctaLabelRules = [] }
   const hasCta = mappings.some((mapping) => mapping.target === "--brand--color--cta-primary");
   if (!hasCta && isNonEmptyString(tokens["--brand-accent"])) {
     addMapping("--brand-accent", "--brand--color--cta-primary", tokens["--brand-accent"].trim(), "medium", { method: "cta-fallback-from-brand-accent" });
-    warnings.push(issue("theme.cta.fallback", "No explicit CTA token was found; using --brand-accent as --brand--color--cta-primary."));
+    warnings.push(issue("theme.cta.fallback", "No explicit CTA token or button background was found; using --brand-accent as --brand--color--cta-primary. This may be a rating or decorative accent; confirm the CTA colour against the design."));
   } else if (!hasCta && isNonEmptyString(tokens["--brand-primary"])) {
     addMapping("--brand-primary", "--brand--color--cta-primary", tokens["--brand-primary"].trim(), "medium", { method: "cta-fallback-from-brand-primary" });
     warnings.push(issue("theme.cta.fallback", "No explicit CTA token was found; using --brand-primary as --brand--color--cta-primary."));

package/src/build-brief.mjs

@@ -3,6 +3,7 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { basename, extname, join, resolve } from "node:path";
 import { parse as parseYaml } from "yaml";
 
+import { CHECKOUT_FLOW_PAGE_TYPES } from "../campaign-spec/dist/index.js";
 import { cmd } from "./install-invocation.mjs";
 import { canonicalJson } from "./polish-capture.mjs";
 import { escapeRegExp } from "./repo-scan.mjs";
@@ -537,7 +538,7 @@ function draftCampaignBuildBrief({ spec, activePages, pageMappings, templateFami
 
   const variantSignals = collectVariantSignals(spec, sourceAssetCrawl);
   const paymentMethods = collectSpecPaymentMethods(spec);
-  const hasExitPop = activePages?.some((page) => page?.type === "checkout" && page?.exit_intent?.enabled === true) === true;
+  const hasExitPop = activePages?.some((page) => isCheckoutFlowPage(page) && page?.exit_intent?.enabled === true) === true;
   const hasOrderBump = hasOrderBumpSignals(spec);
   // With no CampaignSpec surface to fill them, the template's promo
   // placeholders are removed: "none" for both.
@@ -718,8 +719,15 @@ function addQuestion(questions, id, { detail = null, options = [] } = {}) {
   });
 }
 
+// select, checkout_step and checkout all render the SDK checkout surface, so
+// payment-page features (exit pop, promo input) and the conversion goal apply
+// to each of them (campaigns-os#641).
+function isCheckoutFlowPage(page) {
+  return CHECKOUT_FLOW_PAGE_TYPES.includes(page?.type);
+}
+
 function inferConversionGoal(activePages = []) {
-  const hasCheckout = activePages.some((page) => page?.type === "checkout");
+  const hasCheckout = activePages.some((page) => isCheckoutFlowPage(page));
   const hasUpsell = activePages.some((page) => /upsell|downsell/i.test(String(page?.type || "")));
   if (hasCheckout && hasUpsell) return "direct response funnel with post-purchase offers";
   if (hasCheckout) return "single-product direct response funnel";
@@ -837,9 +845,10 @@ function templatePromoSurfaces({ spec = null, activePages = [] } = {}) {
     surfaces.push("promo codes (funnels[].promo_codes)");
   }
   const pages = Array.isArray(activePages) ? activePages : [];
-  // Checkout-only and enabled: true, the rule hasExitPop, doctor's exit-pop
-  // contract and QA's coupon orders use for these surfaces.
-  const checkoutSurface = (page, key) => page?.type === "checkout" && page?.[key]?.enabled === true;
+  // Checkout-flow pages only (select, checkout_step, checkout) and enabled:
+  // true, the rule hasExitPop, doctor's exit-pop contract and QA's coupon
+  // orders use for these surfaces.
+  const checkoutSurface = (page, key) => isCheckoutFlowPage(page) && page?.[key]?.enabled === true;
   if (pages.some((page) => checkoutSurface(page, "exit_intent"))) {
     surfaces.push("an exit-intent offer (exit_intent)");
   }

package/src/campaign-identity.mjs

@@ -45,6 +45,7 @@ export const CAMPAIGN_IDENTITY = "built_output.campaign_identity";
 // Finding kinds, each with its own issue code under the gate id.
 export const CAMPAIGN_IDENTITY_KINDS = Object.freeze({
   api_key_drift: `${CAMPAIGN_IDENTITY}.api_key_drift`,
+  api_key_mismatch: `${CAMPAIGN_IDENTITY}.api_key_mismatch`,
   funnel_drift: `${CAMPAIGN_IDENTITY}.funnel_drift`,
   funnel_missing: `${CAMPAIGN_IDENTITY}.funnel_missing`,
   attribution_drift: `${CAMPAIGN_IDENTITY}.attribution_drift`,
@@ -270,7 +271,7 @@ function gateBase(subject) {
  *   file?: string|null, content: string, spec_page?: boolean,
  *   scripts?: Array<{ src: string, file?: string|null, content: string }> }> }} input
  */
-export function evaluateCampaignIdentity({ subject, pages = [] } = {}) {
+export function evaluateCampaignIdentity({ subject, pages = [], expectedApiKey = null } = {}) {
   const all = Array.isArray(pages) ? pages : [];
   const skipped = all
     .filter((page) => isParkedPage(page.route ?? page.file ?? page.page_id))
@@ -298,7 +299,7 @@ export function evaluateCampaignIdentity({ subject, pages = [] } = {}) {
   //    value. Meta and config are compared together on purpose: a page whose
   //    meta names one campaign while its config.js names another is drift
   //    inside a single page, and the SDK's precedence rule only hides it.
-  const keyObservations = identities.flatMap((identity) => identity.api_keys.map((key) => ({ page_id: identity.page_id, ...key })));
+  const keyObservations = identities.flatMap((identity) => identity.api_keys.map((key) => ({ page_id: identity.page_id, page_file: identity.file || identity.page_id, ...key })));
   const firstKey = keyObservations[0] || null;
   for (const observation of keyObservations.slice(1)) {
     if (observation.value === firstKey.value) continue;
@@ -312,6 +313,32 @@ export function evaluateCampaignIdentity({ subject, pages = [] } = {}) {
     });
     break; // one finding per kind names the first pair; the rest follow from the same edit
   }
+  const wrongKeys = new Map();
+  if (expectedApiKey?.key) {
+    for (const observation of keyObservations) {
+      if (observation.value === expectedApiKey.key) continue;
+      if (!wrongKeys.has(observation.value)) wrongKeys.set(observation.value, new Map());
+      const sources = wrongKeys.get(observation.value);
+      const sourceId = `${observation.where}\u0000${observation.source}`;
+      if (!sources.has(sourceId)) sources.set(sourceId, { file: observation.where, source: observation.source, pages: new Set() });
+      sources.get(sourceId).pages.add(observation.page_file);
+    }
+  }
+  const wrongSourceFiles = [...new Set([...wrongKeys.values()].flatMap((sources) => [...sources.values()].map((source) => source.file)))];
+  if (wrongKeys.size) {
+    const firstWrong = keyObservations.find((observation) => observation.value !== expectedApiKey.key);
+    const wrongDetails = [...wrongKeys].map(([value, sources]) =>
+      `${[...sources.values()].map(({ file, source, pages }) => `${file} (${source}; used by ${[...pages].join(", ")})`).join(" and ")} has ${quote(value)}`,
+    ).join("; ");
+    findings.push({
+      kind: "api_key_mismatch",
+      code: CAMPAIGN_IDENTITY_KINDS.api_key_mismatch,
+      a: { page_id: null, file: expectedApiKey.source, value: expectedApiKey.key },
+      b: { page_id: firstWrong.page_id, file: firstWrong.where, source: firstWrong.source, value: firstWrong.value },
+      evidence: `Built API key in ${wrongDetails} differs from the Campaigns API key in ${expectedApiKey.source}.`,
+      message: `Built API key in ${wrongDetails} differs from the Campaigns API key ${quote(expectedApiKey.key)} in ${expectedApiKey.source}. Replace the built key in the named source with the campaign's own key, then rebuild.`,
+    });
+  }
 
   // 2. next-funnel: one value across pages, and present wherever the SDK is
   //    bootstrapped (a page that declares next-page-type is SDK-bound).
@@ -422,7 +449,7 @@ export function evaluateCampaignIdentity({ subject, pages = [] } = {}) {
     // Short on purpose; the per-edit prose is findings[].message, which is
     // what each doctor error carries. A reason that concatenates them is
     // truncated by every single-line renderer.
-    reason: `${findings.length} campaign identity drift finding(s) across ${scanned.length} built page(s) (${[...new Set(findings.map((finding) => finding.kind))].join(", ")}); see findings[] for the two files and two values of each.`,
+    reason: `${findings.length} campaign identity ${findings.every((finding) => finding.kind === "api_key_mismatch") ? "API key mismatch" : "drift"} finding(s) across ${scanned.length} built page(s) (${[...new Set(findings.map((finding) => finding.kind))].join(", ")}); see findings[] for the sources and values to repair.`,
     findings,
     pages_scanned: scanned.length,
     pages_skipped: skipped,
@@ -432,7 +459,9 @@ export function evaluateCampaignIdentity({ subject, pages = [] } = {}) {
         id: "repair_identity",
         kind: "edit",
         command: null,
-        description: `Make every page name the same campaign: ${findings.map((finding) => `${finding.b?.file || finding.a.file} (${finding.kind.replace(/_/g, " ")})`).join("; ")}. Not waivable: two campaign identities on one funnel cannot both be intended.`,
+        description: findings.map((finding) => finding.kind === "api_key_mismatch"
+          ? `Replace the built key in ${wrongSourceFiles.join(", ")} with the campaign's key, then rebuild.`
+          : `Make every page name the same campaign: ${finding.b?.file || finding.a.file} (${finding.kind.replace(/_/g, " ")}).`).join(" "),
       },
     ],
   };

package/src/cli-helpers.mjs

@@ -79,6 +79,134 @@ function isLocalAbsolutePath(value) {
   return isNonEmptyString(value) && !isAbsoluteHttpUrl(value) && isAbsolute(value);
 }
 
+// Commit-ready JSON has a finite set of filesystem fields. Route roots and URL
+// paths are deliberately absent: a leading slash does not make one a file.
+function portableArtifactPath(targetRepo, path, { baseDir = targetRepo } = {}) {
+  const rel = relative(resolve(baseDir), resolve(path));
+  return !rel ? "." : rel.startsWith(".") ? rel : `./${rel}`;
+}
+
+const ARTIFACT_PATH_FIELDS = Object.freeze({
+  "campaign-runtime-build-packet/v0": [
+    "spec.local_path", "design_source_package.path", "source_html.root",
+    "source_html.pages.*.path", "source_html.pages.*.page_kit.target_path",
+    "source_html.pages.*.page_kit.output_path", "build_brief.input_path",
+    "build_brief.normalized_path", "assembly.target_repo", "assembly.output_dir",
+    "assembly.commerce_catalog.path",
+  ],
+  "campaign-runtime-build-context/v0": [
+    "packet_path", "report_path", "intake.spec_path", "intake.source_root",
+    "intake.target_repo", "intake.brief_path", "intake.design_manifest_path",
+    "intake.packet_path", "design_source_package.path", "spec.path", "source.root",
+    "build_brief.input_path", "build_brief.normalized_path",
+    "page_map.*.source_path", "page_map.*.output_path",
+    "page_map.*.page_kit.target_path", "page_map.*.page_kit.output_path",
+    "scaffold.target_repo", "scaffold.output_dir", "scaffold.handoff_artifact",
+    "theme.source_files.*.path", "theme.generated.css_path", "theme.generated.report_path",
+  ],
+  "campaign-runtime-assembly-report/v0": [
+    "inputs.packet_path", "inputs.context_path", "inputs.build_brief_path",
+    "inputs.spec_path", "inputs.source.root", "inputs.target_repo",
+    "design_source_package.path", "build_brief.input_path", "build_brief.normalized_path",
+    // `**` also reaches each stage's archived entries.
+    "theme.css_path", "stages.**.inputs.*", "stages.**.outputs.*",
+  ],
+  "campaigns-os-doctor-output/v0": [
+    "packet_path", "assembly_report_path", "spec_path", "emitted_packet_path",
+    "derived.packet_path", "derived.assembly_report_path", "derived.spec_path",
+    "derived.target_repo", "derived.source_root", "derived.output_dir", "derived.target_output_dir",
+    "errors.*.detail.spec_path", "errors.*.detail.input_path",
+    "warnings.*.detail.spec_path", "warnings.*.detail.input_path",
+  ],
+  "campaigns-os-build-brief/v1": ["_meta.input_path"],
+});
+
+const ARTIFACT_COMMAND_FIELDS = Object.freeze({
+  "campaign-runtime-build-packet/v0": ["source_html.pages.*.skip_reason"],
+  "campaign-runtime-build-context/v0": [
+    "decisions.*.decision", "decisions.*.evidence.*",
+    "prompts_required.*.message", "page_map.*.skip_reason", "source.manifest_warnings.*",
+  ],
+  "campaign-runtime-assembly-report/v0": [
+    "next.command", "stages.**.commands.*",
+    "decisions.*.decision", "decisions.*.evidence.*",
+    "**.message", "**.blockers.*", "**.warnings.*",
+  ],
+  "campaigns-os-doctor-output/v0": [
+    "next.command", "next.actions.*", "next_actions.*.command", "**.message", "**.blockers.*", "**.warnings.*",
+  ],
+});
+
+function fieldMatches(pattern, segments) {
+  const parts = pattern.split(".");
+  function matches(at, index) {
+    if (at === parts.length) return index === segments.length;
+    if (parts[at] === "**") return matches(at + 1, index) || (index < segments.length && matches(at, index + 1));
+    return index < segments.length && (parts[at] === "*" || parts[at] === segments[index]) && matches(at + 1, index + 1);
+  }
+  return matches(0, 0);
+}
+
+function portableArtifactPaths(value, targetRepo, { artifactPath = null } = {}) {
+  const schema = isObject(value) ? value.schema_version : null;
+  const pathFields = ARTIFACT_PATH_FIELDS[schema] || [];
+  const commandFields = ARTIFACT_COMMAND_FIELDS[schema] || [];
+  const artifactDir = artifactPath ? dirname(resolve(artifactPath)) : null;
+  const packet = schema === "campaign-runtime-build-packet/v0";
+  const context = schema === "campaign-runtime-build-context/v0";
+  const report = schema === "campaign-runtime-assembly-report/v0";
+  const sourceField = packet ? value.source_html?.root : context ? value.source?.root : report ? value.inputs?.source?.root : null;
+  const sourceBase = packet ? artifactDir : targetRepo;
+  const sourceRoot = isNonEmptyString(sourceField) && sourceBase ? resolve(sourceBase, sourceField) : null;
+  const outputField = packet ? value.assembly?.output_dir : context ? value.scaffold?.output_dir : null;
+  const outputBase = targetRepo;
+  const outputDir = isNonEmptyString(outputField) && outputBase ? resolve(outputBase, outputField) : null;
+  const roots = [...new Set([targetRepo, sourceRoot].filter(Boolean).flatMap((root) => [resolve(root), canonicalPath(root)]))]
+    .filter((root) => root !== "/")
+    .sort((left, right) => right.length - left.length);
+  function fieldBase(segments) {
+    const path = segments.join(".");
+    if (packet) {
+      if (path === "source_html.pages.*.path") return sourceRoot;
+      if (path === "source_html.pages.*.page_kit.target_path") return outputDir;
+      if (path === "source_html.pages.*.page_kit.output_path") return targetRepo;
+      if (path === "assembly.output_dir") return targetRepo;
+      return artifactDir;
+    }
+    if (context) {
+      if (path === "page_map.*.source_path") return sourceRoot;
+      if (path === "page_map.*.page_kit.target_path") return outputDir;
+      if (path === "design_source_package.path") return artifactDir;
+    }
+    if (report && path === "design_source_package.path") return artifactDir;
+    if (schema === "campaigns-os-build-brief/v1") return artifactDir;
+    return targetRepo;
+  }
+  function portableCommand(command) {
+    let output = command;
+    for (const root of roots) {
+      const escaped = root.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const replacement = portableArtifactPath(targetRepo, root);
+      output = output.replace(new RegExp(`(^|[\\s"'\`(=,;\\[<])${escaped}(?=$|[/\\s"'\`.,:;)\\]>])`, "g"),
+        (_match, prefix) => `${prefix}${replacement}`);
+    }
+    return output;
+  }
+  function visit(entry, segments = []) {
+    if (Array.isArray(entry)) return entry.map((item) => visit(item, [...segments, "*"]));
+    if (isObject(entry)) return Object.fromEntries(Object.entries(entry).map(([field, item]) => [field, visit(item, [...segments, field])]));
+    if (typeof entry !== "string") return entry;
+    if (Array.isArray(value) && segments.length === 1 && isLocalAbsolutePath(entry)) return portableArtifactPath(targetRepo, entry);
+    if (pathFields.some((pattern) => fieldMatches(pattern, segments)) && isLocalAbsolutePath(entry)) {
+      const baseDir = fieldBase(segments);
+      return baseDir ? portableArtifactPath(targetRepo, entry, { baseDir }) : entry;
+    }
+    if (commandFields.some((pattern) => fieldMatches(pattern, segments))) return portableCommand(entry);
+    return entry;
+  }
+  return visit(value);
+}
+
 function resolveFromFile(filePath, targetPath) {
   if (!isNonEmptyString(targetPath)) return null;
   if (isAbsoluteHttpUrl(targetPath)) return targetPath;
@@ -111,6 +239,7 @@ export {
   sha256File,
   relFromDir,
   isLocalAbsolutePath,
+  portableArtifactPaths,
   resolveFromFile,
   filesystemPathsMatch,
   extractFrontmatterValue,