@nextcommerce/campaigns-os 1.33.0

package/src/template-reference.mjs

@@ -0,0 +1,81 @@
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+export const UNRESOLVED_TEMPLATE_FAMILIES = Object.freeze(["auto", "undecided"]);
+
+export function isUnresolvedTemplateFamily(value) {
+  const family = nonEmptyString(value);
+  return !family || UNRESOLVED_TEMPLATE_FAMILIES.includes(family);
+}
+
+export const TEMPLATE_FAMILY_FLAG_SOURCE = "--template-family";
+export const TEMPLATE_FAMILY_HINT_SOURCE = "CampaignSpec preferred_template_family";
+
+/**
+ * Resolve the template family an entry-point command will build on, from the
+ * two channels an operator has: the `--template-family` flag and the
+ * CampaignSpec authoring hint. The flag wins — that was always the behaviour
+ * (docs/build-packet.md "Authoring-Time Hints") — but it used to win in
+ * silence, so a spec hinting one family and a flag naming another produced a
+ * packet with no trace of the discarded hint. The resolution is returned as
+ * data, including `overridden`, so the caller can say which value won.
+ */
+export function resolveTemplateFamilySelection({ flag = null, hint = null } = {}) {
+  const flagValue = nonEmptyString(flag);
+  const hintValue = nonEmptyString(hint);
+  const value = flagValue || hintValue || "undecided";
+  const source = flagValue
+    ? TEMPLATE_FAMILY_FLAG_SOURCE
+    : hintValue
+      ? TEMPLATE_FAMILY_HINT_SOURCE
+      : "default";
+  return {
+    value,
+    source,
+    flag: flagValue,
+    hint: hintValue,
+    // Only a disagreement is an override. A flag that merely repeats the hint
+    // confirms it, and warning there would train operators to ignore the line.
+    overridden: Boolean(flagValue && hintValue && flagValue !== hintValue),
+  };
+}
+
+/**
+ * Resolve the selected catalog family into the input shape consumed by the
+ * Design Source Package synthesizer. A family without published proof remains
+ * a family-only input so the DSP emits its existing missing-reference blocker.
+ */
+export function resolveTemplateFamilyDesignSource(catalog, family) {
+  const normalizedFamily = nonEmptyString(family);
+  if (isUnresolvedTemplateFamily(normalizedFamily)) return null;
+
+  const entry = isObject(catalog?.families?.[normalizedFamily])
+    ? catalog.families[normalizedFamily]
+    : null;
+  const reference = isObject(entry?.templateReference)
+    ? entry.templateReference
+    : isObject(entry?.template_reference)
+      ? entry.template_reference
+      : null;
+  if (!reference) return { family: normalizedFamily };
+
+  const referenceFamily = nonEmptyString(reference.family);
+  if (referenceFamily && referenceFamily !== normalizedFamily) {
+    throw new TypeError(
+      `Template Reference family ${JSON.stringify(referenceFamily)} does not match selected family ` +
+        `${JSON.stringify(normalizedFamily)}.`,
+    );
+  }
+
+  const version = nonEmptyString(reference.version);
+  return {
+    family: normalizedFamily,
+    ...(version ? { version } : {}),
+    template_reference: structuredClone(reference),
+  };
+}

package/src/template-slot-manifest.mjs

@@ -0,0 +1,150 @@
+// Template slot manifests: the content-slot contract for certified template
+// families. One shared content-slot core declares every content slot on the
+// shared pages (semantic description, length band, source policy, proof and
+// urgency flags); per-family manifests extend it with family-specific overlay
+// keys and the list of commerce-owned pages the content layer never touches.
+//
+// Files live at contracts/template-slot-manifest.<family>.v0.json and
+// contracts/template-slot-manifest.shared-content-core.v0.json. Family
+// manifests `extends` the shared core; object values merge, arrays and
+// scalars replace (same semantics as template brand contracts).
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+export const TEMPLATE_SLOT_MANIFEST_SCHEMA = "template-slot-manifest/v0";
+
+export const SLOT_SOURCE_POLICIES = Object.freeze([
+  "generated",
+  "merchant_asset_required",
+  "spec_truth",
+  "brand",
+  "template_static",
+]);
+
+export function templateSlotManifestPath(family) {
+  if (typeof family !== "string" || !family.trim()) return null;
+  return join(ROOT, "contracts", `template-slot-manifest.${family.trim()}.v0.json`);
+}
+
+export function sharedContentCorePath() {
+  return join(ROOT, "contracts", "template-slot-manifest.shared-content-core.v0.json");
+}
+
+export function loadTemplateSlotManifest(family) {
+  const path = templateSlotManifestPath(family);
+  if (!path || !existsSync(path)) return null;
+  const manifest = loadManifestFile(path);
+  if (manifest.family !== family) {
+    throw slotManifestError(
+      "family_mismatch",
+      `Template slot manifest ${path} declares family "${manifest.family}"; expected "${family}".`,
+    );
+  }
+  return manifest;
+}
+
+function loadManifestFile(path, seen = new Set()) {
+  let manifest = null;
+  try {
+    manifest = JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    throw slotManifestError(
+      "parse_error",
+      `Template slot manifest ${path} failed to parse: ${error instanceof Error ? error.message : String(error)}.`,
+      error,
+    );
+  }
+  return resolveExtendsChain(manifest, { dir: dirname(path), label: path, seen });
+}
+
+function resolveExtendsChain(manifest, { dir, label = dir, seen = new Set() } = {}) {
+  if (seen.has(label)) throw slotManifestError("extends_cycle", `Template slot manifest extends cycle at ${label}.`);
+  seen.add(label);
+  if (!isPlainObject(manifest) || manifest.schema_version !== TEMPLATE_SLOT_MANIFEST_SCHEMA) {
+    throw slotManifestError(
+      "schema_mismatch",
+      `Template slot manifest ${label} has schema_version "${manifest?.schema_version}"; expected "${TEMPLATE_SLOT_MANIFEST_SCHEMA}".`,
+    );
+  }
+  const parentRef = typeof manifest.extends === "string" && manifest.extends.trim() ? manifest.extends.trim() : null;
+  if (!parentRef) return manifest;
+  const parentPath = join(dir, parentRef);
+  if (!existsSync(parentPath)) {
+    throw slotManifestError("extends_missing_parent", `Template slot manifest ${label} extends missing file "${parentRef}".`);
+  }
+  const merged = mergeObjects(loadManifestFile(parentPath, seen), manifest);
+  delete merged.extends;
+  return merged;
+}
+
+function slotManifestError(code, message, cause = undefined) {
+  const error = new Error(message, cause ? { cause } : undefined);
+  error.code = code;
+  return error;
+}
+
+function mergeObjects(parent, child) {
+  const merged = { ...parent };
+  for (const [key, value] of Object.entries(child)) {
+    if (isPlainObject(value) && isPlainObject(parent?.[key])) {
+      merged[key] = mergeObjects(parent[key], value);
+    } else {
+      merged[key] = value;
+    }
+  }
+  return merged;
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function sectionsOf(pageEntry) {
+  return Array.isArray(pageEntry?.sections) ? pageEntry.sections : [];
+}
+
+// Every slot entry declared for a page: shared-core slots plus the family
+// overlay's slots. Returns [] for commerce-owned or unknown pages.
+export function manifestPageSlots(manifest, page) {
+  if (!isPlainObject(manifest)) return [];
+  const slots = [];
+  for (const source of [manifest.pages?.[page], manifest.overlay?.pages?.[page]]) {
+    for (const section of sectionsOf(source)) {
+      for (const slot of Array.isArray(section.slots) ? section.slots : []) {
+        if (isPlainObject(slot) && typeof slot.key === "string") slots.push(slot);
+      }
+    }
+  }
+  return slots;
+}
+
+export function declaredSlotKeys(manifest, page) {
+  return new Set(manifestPageSlots(manifest, page).map((slot) => slot.key));
+}
+
+// Pages the content layer never validates key-by-key: commerce-owned pages
+// declared by the family manifest plus pages the shared core marks
+// commerce_owned (checkout).
+export function commerceOwnedPages(manifest) {
+  const pages = new Set(
+    Array.isArray(manifest?.commerce_owned_pages) ? manifest.commerce_owned_pages.map(String) : [],
+  );
+  for (const [page, entry] of Object.entries(manifest?.pages || {})) {
+    if (isPlainObject(entry) && entry.commerce_owned === true) pages.add(page);
+  }
+  return pages;
+}
+
+// Slots whose chrome may render only under verified offer urgency.
+export function urgencySlots(manifest, page) {
+  return manifestPageSlots(manifest, page).filter((slot) => slot.enabled_by_verified_urgency === true);
+}
+
+// Proof surfaces (counts, ratings, reviews, UGC, byline identity) — the slots
+// the attestation lane and the rendered-residue doctor checks care about.
+export function proofSlots(manifest, page) {
+  return manifestPageSlots(manifest, page).filter((slot) => slot.proof_surface === true);
+}

package/src/text-safety.mjs

@@ -0,0 +1,62 @@
+// Text flattening for values this toolkit prints but did not author.
+//
+// A leaf module on purpose: every function here is pure string work with no
+// imports, and all of them are published as the `./text-safety` package export so
+// a consumer that renders toolkit-derived values (a run id, a path, a quoted
+// loader message) into its own single-line notice can flatten them the same
+// way instead of reimplementing the escape set and drifting from it.
+
+// One line, no control characters. These values land in operator notices
+// that are single-line by construction, so a run id or a path carrying a
+// newline, a carriage return, or an ANSI escape could split a notice,
+// overwrite it, or dress a fabricated line up as toolkit output. Neither value
+// is toolkit-authored: the path comes from a packet-derived target directory
+// and the id can be handed in with --run-id. Replaced, never dropped, so a
+// mangled value stays visible as mangled rather than silently shortening the
+// message.
+export function singleLineField(value, fallback = "") {
+  const raw = typeof value === "string" ? value : value == null ? "" : String(value);
+  if (!raw) return fallback;
+  // C0, DEL and C1, which covers CR, LF, TAB and the ESC that starts ANSI.
+  return raw.replace(/[\u0000-\u001f\u007f-\u009f]/g, "\uFFFD");
+}
+
+// One trimmed line for a value folded INTO a sentence rather than printed as
+// its own field: a gate's repair command quoted in a notice, a loader message
+// quoted in an advisory. The control-character half is `singleLineField`'s and
+// is not duplicated; what is added is the reading a sentence gives whitespace.
+// Line breaks and tabs become spaces — a newline inside a quoted instruction
+// or JSON fragment is a word boundary, and U+FFFD there reads as mojibake —
+// and runs of whitespace collapse, because the value is read as words, not
+// compared as an identifier. ESC, DEL and the rest still become the
+// replacement character, since those have no reading as text. A value that is
+// compared against a known word (a disposition) keeps `singleLineField`.
+export function singleLineFragment(value, fallback = "") {
+  const spaced = String(value ?? "").replace(/[\r\n\t\v\f]+/g, " ");
+  const flattened = singleLineField(spaced).replace(/\s+/g, " ").trim();
+  return flattened || fallback;
+}
+
+export const ADVISORY_DETAIL_MAX = 300;
+
+// One trimmed line, no control characters, no Markdown that could restyle the
+// rest of the description or a rendered bullet.
+//
+// The folding is `singleLineFragment`'s. Two things are added on top of it,
+// because this input is different in kind from a repair command: a loader
+// message QUOTES FILE CONTENT, so it can be long and can carry Markdown.
+export function singleLineDetail(detail, max = ADVISORY_DETAIL_MAX) {
+  const flattened = singleLineFragment(detail).replace(/[`*_[\]<>]/g, "\\$&");
+  if (!flattened) return "(no detail reported)";
+  // A published export: the result never exceeds `max` characters, and it
+  // never fabricates. A non-finite max means the default budget; a derived or
+  // mistaken max below one floors at one character, since a budget of zero
+  // would print nothing at all in place of a real message. The ellipsis
+  // itself costs a character, so a budget of one cannot hold it: at that
+  // width the cut is bare rather than an ellipsis standing in for the whole
+  // detail.
+  const limit = Number.isFinite(max) ? Math.max(1, Math.floor(max)) : ADVISORY_DETAIL_MAX;
+  if (flattened.length <= limit) return flattened;
+  if (limit < 2) return flattened.slice(0, limit);
+  return `${flattened.slice(0, limit - 1).trimEnd()}\u2026`;
+}

package/src/theme-gate.mjs

@@ -0,0 +1,185 @@
+// Theme gate: turns the advisory "theme inspect found a generatable brand
+// theme" signal into a deterministic stage gate.
+//
+// Doctrine: when theme inspect proves a brand layer CAN be generated and the
+// campaign ships commerce pages, polish/deploy/QA must not proceed until the
+// brand layer is generated and applied after next-core.css — or an operator
+// records an explicit waiver with a reason. Advisory prose is exactly what
+// agents skipped in the recovery-relief-stack-v1 dogfood run; this module is
+// the single decision point every consumer (next, doctor, qa) shares.
+const COMMERCE_PAGE_TYPES = new Set(["checkout", "upsell", "downsell", "receipt", "thankyou"]);
+
+function isCommercePage(page) {
+  return COMMERCE_PAGE_TYPES.has(String(page?.type || "")) || String(page?.role || "") === "runtime";
+}
+
+function pageKey(page) {
+  return String(page?.page_id || page?.route || page?.type || "");
+}
+
+/**
+ * The campaign's commerce surface, split by whether this build produced it.
+ *
+ * "Does this campaign ship commerce pages?" is a question about the campaign,
+ * not about one build's output. A partial build parks declared checkout/upsell
+ * pages in `out_of_scope_pages`, which used to leave `built_pages` with no
+ * commerce page and retire the gate on a nine-page commerce funnel (#274).
+ * Reading only the built half made the gate's answer depend on build scope,
+ * which is the one input it must not key off.
+ */
+export function commerceScopeFromScope(scope) {
+  const built = (Array.isArray(scope?.built_pages) ? scope.built_pages : []).filter(isCommercePage);
+  const builtKeys = new Set(built.map(pageKey));
+  const outOfScope = (Array.isArray(scope?.out_of_scope_pages) ? scope.out_of_scope_pages : [])
+    .filter(isCommercePage)
+    .filter((page) => !builtKeys.has(pageKey(page)));
+  return { built, out_of_scope: outOfScope, all: [...built, ...outOfScope] };
+}
+
+// An expiry `theme waive --expires-at` recorded is honoured here: at or after
+// that instant the record no longer waives the gate (inclusive boundary, the
+// same rule the checkpoint and polish lanes apply), so the gate falls back to
+// its normal evaluation and asks for a fresh decision.
+export function themeWaiverExpired(waiver, now = new Date().toISOString()) {
+  const expiresAt = waiver?.expires_at;
+  if (typeof expiresAt !== "string" || !expiresAt.trim()) return false;
+  const expiresMs = Date.parse(expiresAt);
+  return !Number.isFinite(expiresMs) || expiresMs <= Date.parse(now);
+}
+
+export function themeWaiverFrom(reportTheme, ephemeralWaiver = null, { now = new Date().toISOString() } = {}) {
+  if (typeof ephemeralWaiver === "string" && ephemeralWaiver.trim()) {
+    return { reason: ephemeralWaiver.trim(), waived_by: "cli_flag", waived_at: null };
+  }
+  const waiver = reportTheme?.waiver;
+  if (waiver && typeof waiver === "object" && typeof waiver.reason === "string" && waiver.reason.trim()) {
+    return themeWaiverExpired(waiver, now) ? null : waiver;
+  }
+  return null;
+}
+
+/**
+ * Evaluate the theme gate for a campaign.
+ *
+ * @param {object} options
+ * @param {object|null} options.reportTheme   Assembly report theme block.
+ * @param {object|null} options.contextTheme  Build-context theme block (theme inspect result).
+ * @param {object|null} options.scope         Doctor derived scope ({ built_pages: [...] }).
+ * @param {string|null} options.packetPath    Build packet path, used to render exact commands.
+ * @param {string|null} options.waive         Ephemeral waiver reason from a CLI flag (--theme-waive).
+ * @param {string}      options.now           Evaluation instant (ISO); a recorded waiver expired by then is ignored.
+ *
+ * @returns {{
+ *   status: "pass"|"blocked"|"waived"|"not_applicable",
+ *   code: string,
+ *   reason: string,
+ *   commerce_pages: string[],
+ *   commerce_pages_out_of_scope: string[],
+ *   waiver: object|null,
+ *   required_actions: Array<{ id: string, kind: "command"|"manual", command: string|null, description: string }>,
+ * }}
+ */
+export function evaluateThemeGate({ reportTheme = null, contextTheme = null, scope = null, packetPath = null, waive = null, now = new Date().toISOString() } = {}) {
+  const packetArg = packetPath || "<campaign-runtime.build.json>";
+  const commerceScope = commerceScopeFromScope(scope);
+  const pageLabel = (page) => page.page_id || page.route || page.type;
+  const commercePages = commerceScope.all.map(pageLabel);
+  const commercePagesOutOfScope = commerceScope.out_of_scope.map(pageLabel);
+  const result = (status, code, reason, requiredActions = [], waiver = null) => ({
+    status,
+    code,
+    reason,
+    commerce_pages: commercePages,
+    commerce_pages_out_of_scope: commercePagesOutOfScope,
+    waiver,
+    required_actions: requiredActions,
+  });
+
+  const policy = contextTheme?.policy || null;
+  if (policy === "off") {
+    return result("not_applicable", "theme_gate.policy_off", "Theme policy is off; brand layer is explicitly out of scope for this run.");
+  }
+  if (!commercePages.length) {
+    return result("not_applicable", "theme_gate.no_commerce_pages", "Campaign ships no commerce pages; the brand-layer gate does not apply.");
+  }
+
+  const waiver = themeWaiverFrom(reportTheme, waive, { now });
+  if (waiver) {
+    return result("waived", "theme_gate.waived", `Theme gate waived: ${waiver.reason}`, [], waiver);
+  }
+
+  const reportStatus = String(reportTheme?.status || "");
+  const loadOrder = String(reportTheme?.load_order || "");
+  const canGenerate = contextTheme?.generated?.can_generate === true;
+
+  if (reportStatus === "applied") {
+    if (loadOrder !== "after-next-core") {
+      return result(
+        "blocked",
+        "theme_gate.load_order",
+        `Brand theme is recorded as applied but load_order is "${loadOrder || "unknown"}"; commerce pages must load brand-theme.css after next-core.css.`,
+        [
+          {
+            id: "fix_load_order",
+            kind: "manual",
+            command: null,
+            description: "List brand-theme.css after next-core.css in commerce-page frontmatter styles, rebuild, then record report.theme.load_order=after-next-core.",
+          },
+        ],
+      );
+    }
+    return result("pass", "theme_gate.applied", "Brand theme is applied after next-core.css on commerce pages.");
+  }
+
+  if (reportStatus === "skipped" && !canGenerate) {
+    return result("pass", "theme_gate.nothing_generatable", "No generatable brand theme was found; the gate passes without a brand layer.");
+  }
+
+  if (!canGenerate && !reportStatus) {
+    return result("not_applicable", "theme_gate.no_theme_context", "No theme context exists for this campaign; run prepare-build/theme inspect to populate it.");
+  }
+
+  if (!canGenerate) {
+    // needs_review/blocked without a generatable artifact: the operator must
+    // decide. Treat as blocked so the decision is recorded, not improvised.
+    return result(
+      "blocked",
+      "theme_gate.needs_decision",
+      `Assembly report theme status is "${reportStatus || "missing"}" and no generatable brand theme exists; record an applied brand layer or waive the gate with a reason.`,
+      [
+        {
+          id: "waive_theme",
+          kind: "command",
+          command: `campaigns-os theme waive --packet ${packetArg} --reason "<why the starter palette is acceptable>" --waived-by "<named human>"`,
+          description: "Record an explicit operator waiver if shipping without a campaign brand layer is intentional.",
+        },
+      ],
+    );
+  }
+
+  return result(
+    "blocked",
+    "theme_gate.generatable_not_applied",
+    "theme inspect proved a brand theme can be generated, but it has not been generated and applied to commerce pages. Starter-template commerce families consume --brand--* tokens; without the brand layer they ship the starter palette.",
+    [
+      {
+        id: "theme_generate",
+        kind: "command",
+        command: `campaigns-os theme generate --packet ${packetArg}`,
+        description: "Generate .campaign-runtime/theme/brand-theme.css from the inspected source tokens.",
+      },
+      {
+        id: "apply_brand_layer",
+        kind: "manual",
+        command: null,
+        description: "Copy brand-theme.css into the campaign assets/css folder, list it after next-core.css in checkout/upsell/downsell/receipt frontmatter styles, rebuild, then record report.theme.status=applied, load_order=after-next-core, and commerce_pages.",
+      },
+      {
+        id: "waive_theme",
+        kind: "command",
+        command: `campaigns-os theme waive --packet ${packetArg} --reason "<why the starter palette is acceptable>" --waived-by "<named human>"`,
+        description: "Or record an explicit operator waiver instead of applying the brand layer.",
+      },
+    ],
+  );
+}