@nextcommerce/campaigns-os 1.50.0 → 1.53.0

package/src/build-brief.mjs

@@ -1,10 +1,27 @@
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { basename, extname, join, resolve } from "node:path";
 import { parse as parseYaml } from "yaml";
 
+import { cmd } from "./install-invocation.mjs";
+import { canonicalJson } from "./polish-capture.mjs";
 import { escapeRegExp } from "./repo-scan.mjs";
 
 export const BUILD_BRIEF_SCHEMA = "campaigns-os-build-brief/v1";
+// The brief value of a packet that carries no Campaign Build Brief, for both
+// material partitions and for every stage stamp made against it.
+export const BRIEF_ABSENT = "absent";
+// The fields the campaign intent summary prints, in its order. `<page>` stands
+// for each page id present in design_authority; _meta.field_sources keys use
+// the concrete id (design_authority.checkout.source).
+export const SUMMARY_FIELDS = Object.freeze(["campaign_intent.audience", "campaign_intent.conversion_goal", "campaign_intent.tone", "brand.commerce_palette_source", "brand.primary_accent", "brand.cta_style", "brand.avoid", "design_authority.<page>.source", "template_residue_policy.block_placeholders"]);
+const BRIEF_MODE_SOURCES = Object.freeze({ FIELD: "field", LEGACY_REPORT: "legacy_report", GENERATED: "generated" });
+// Codes of the errors normalization itself raises. They block in either mode;
+// evaluation gates block only a prepared brief.
+const NORMALIZATION_ERROR_CODES = Object.freeze(new Set(["build_brief.type", "build_brief.schema_version", "build_brief.brief_mode"]));
+// Top-level keys that never count as material: normalization and evaluation
+// output, and the declared mode. qa_policy.enforcement is fixed package text.
+const NON_MATERIAL_BRIEF_KEYS = Object.freeze(new Set(["_meta", "status", "questions", "gates", "confidence", "schema_version", "brief_mode"]));
 export const BUILD_BRIEF_NORMALIZED_REL_PATH = ".campaign-runtime/input/campaign-build-brief.normalized.json";
 export const BUILD_BRIEF_CANDIDATE_FILENAMES = Object.freeze([
   "campaign-build-brief.yaml",
@@ -12,11 +29,15 @@ export const BUILD_BRIEF_CANDIDATE_FILENAMES = Object.freeze([
   "campaign-build-brief.json",
 ]);
 
+// answer_fields: the brief fields whose values close the question, as
+// evaluateCampaignBuildBrief reads them. The guided-questions warning names
+// them so an answer given in conversation can be written where it counts.
 const REQUIRED_HIGH_IMPACT_FIELDS = Object.freeze([
   {
     id: "page_design_authority",
     priority: 1,
     field: "design_authority",
+    answer_fields: ["design_authority.<page_id>.source"],
     question: "Which source controls each campaign page: the provided design export, the selected template, or a template adapted to another page?",
     reason: "Page-by-page authority prevents checkout, OTO, and receipt pages from drifting into unrelated starter-template composition.",
   },
@@ -24,6 +45,7 @@ const REQUIRED_HIGH_IMPACT_FIELDS = Object.freeze([
     id: "brand_palette_cta",
     priority: 2,
     field: "brand",
+    answer_fields: ["brand.commerce_palette_source", "brand.cta_style"],
     question: "Which palette and CTA style should commerce pages use?",
     reason: "Commerce pages need a business-approved brand layer instead of silent template defaults.",
   },
@@ -31,6 +53,7 @@ const REQUIRED_HIGH_IMPACT_FIELDS = Object.freeze([
     id: "variant_media_rules",
     priority: 3,
     field: "media",
+    answer_fields: ["media.sold_variants", "media.allow_other_variant_colors"],
     question: "Which product variants or colors are actually sold, and may media show other variants?",
     reason: "Variant ambiguity often creates wrong-color carousels and unavailable-product claims.",
   },
@@ -38,6 +61,7 @@ const REQUIRED_HIGH_IMPACT_FIELDS = Object.freeze([
     id: "bundle_pricing_presentation",
     priority: 4,
     field: "offer_presentation.bundle_cards",
+    answer_fields: ["offer_presentation.bundle_cards.primary_price"],
     question: "How should bundle cards present pricing: simple unit price, savings-led, or full accounting?",
     reason: "CampaignSpec owns prices; the brief owns which shopper-facing price story is appropriate.",
   },
@@ -45,13 +69,16 @@ const REQUIRED_HIGH_IMPACT_FIELDS = Object.freeze([
     id: "promo_urgency_copy",
     priority: 5,
     field: "promo_urgency",
-    question: "Which promo, savings, and urgency language is approved for timers, banners, and exit-pop surfaces?",
-    reason: "Promo placeholders and unsupported scarcity claims are business decisions, not implementation details.",
+    answer_fields: ["promo_urgency.header_claim_source", "promo_urgency.timer_label"],
+    answer_hint: 'promo_urgency.header_claim_source "campaign_offers" and promo_urgency.timer_label the template timer\'s label to fill them, or both "none" to remove them',
+    question: "Should the starter template's own promo placeholders (demo countdown timers, promo banners, placeholder voucher codes, exit-pop offers) be filled from this campaign's promo codes and offers, or removed?",
+    reason: "Template promo placeholders must not go live with demo values. The source design's own promo, proof and urgency copy is the merchant's content: it is built as designed and is not part of this question.",
   },
   {
     id: "payment_methods_trust",
     priority: 6,
     field: "commerce_surfaces.payment_methods_allowed",
+    answer_fields: ["commerce_surfaces.payment_methods_allowed"],
     question: "Which payment methods and trust badges may appear?",
     reason: "Templates often carry demo wallets or badges that must not survive without approval.",
   },
@@ -59,6 +86,7 @@ const REQUIRED_HIGH_IMPACT_FIELDS = Object.freeze([
     id: "canonical_display_names",
     priority: 7,
     field: "canonical_display.product_name_source",
+    answer_fields: ["canonical_display.product_name_source"],
     question: "Should CampaignSpec display names win, or may runtime/catalog names override them?",
     reason: "Name drift across source, spec, and runtime data is hard to spot after assembly.",
   },
@@ -66,6 +94,7 @@ const REQUIRED_HIGH_IMPACT_FIELDS = Object.freeze([
     id: "regulated_claims",
     priority: 8,
     field: "campaign_intent.compliance",
+    answer_fields: ["campaign_intent.compliance.approved_benefit_language", "campaign_intent.compliance.forbidden_claims"],
     question: "Are there regulated claims, forbidden phrases, or approved benefit statements the build must follow?",
     reason: "Health, financial, and other regulated offers need explicit copy boundaries.",
     conditional: "regulated",
@@ -157,6 +186,32 @@ export function loadCampaignBuildBriefFile(path) {
   return { path: resolvedPath, format, value: parsed };
 }
 
+// The mode a brief file declares, in rule order: brief_mode "prepared" or
+// "guided"; without brief_mode, prepared only when the report this write
+// replaces already recorded a prepared brief for the campaign (so it keeps the
+// blocking it was built under); otherwise guided. Any other brief_mode value
+// is a normalization error. The file's own _meta is never read.
+function briefModeFor(loaded, boundReportMode, errors) {
+  if (!loaded) return { mode: "guided_draft", source: BRIEF_MODE_SOURCES.GENERATED };
+  const declared = isObject(loaded.value) && Object.hasOwn(loaded.value, "brief_mode");
+  if (declared && loaded.value.brief_mode === "prepared") return { mode: "prepared", source: BRIEF_MODE_SOURCES.FIELD };
+  if (declared && loaded.value.brief_mode === "guided") return { mode: "guided_draft", source: BRIEF_MODE_SOURCES.FIELD };
+  if (declared) {
+    errors.push({
+      code: "build_brief.brief_mode",
+      field: "brief_mode",
+      message: `Campaign Build Brief brief_mode must be "prepared" or "guided" (got ${JSON.stringify(loaded.value.brief_mode)}); omit it for a guided brief.`,
+    });
+    return { mode: "guided_draft", source: BRIEF_MODE_SOURCES.FIELD };
+  }
+  if (boundReportMode === "prepared") return { mode: "prepared", source: BRIEF_MODE_SOURCES.LEGACY_REPORT };
+  return { mode: "guided_draft", source: BRIEF_MODE_SOURCES.GENERATED };
+}
+
+// `boundReportMode`: build_brief.mode on the Assembly Report this write
+// replaces, when that report belongs to the same campaign (mode rule 3).
+// `previousNormalizedBrief`: the normalized brief on disk before this write,
+// read for field provenance only.
 export function createCampaignBuildBriefArtifact({
   inputPath = null,
   inputSource = null,
@@ -166,19 +221,24 @@ export function createCampaignBuildBriefArtifact({
   templateFamily = null,
   sourceAssetCrawl = null,
   commerceZoneFindings = [],
+  boundReportMode = null,
+  previousNormalizedBrief = null,
 } = {}) {
   const loaded = inputPath ? loadCampaignBuildBriefFile(inputPath) : null;
-  const mode = loaded ? "prepared" : "guided_draft";
+  const errors = [];
+  const { mode, source: modeSource } = briefModeFor(loaded, boundReportMode, errors);
   const baseBrief = loaded
     ? cloneJsonOrEmpty(loaded.value)
     : draftCampaignBuildBrief({ spec, activePages, pageMappings, templateFamily, sourceAssetCrawl });
 
-  const errors = [];
   const normalized = normalizeCampaignBuildBrief(baseBrief, {
     mode,
+    modeSource,
     inputPath: loaded?.path || null,
     inputFormat: loaded?.format || "generated",
     inputSource,
+    fileValue: loaded ? loaded.value : null,
+    previousNormalizedBrief,
     spec,
     activePages,
     pageMappings,
@@ -210,9 +270,11 @@ export function createCampaignBuildBriefArtifact({
   normalized.questions = evaluation.questions;
   normalized.gates = gates;
 
+  // A prepared brief blocks on every blocker gate; a guided one only on the
+  // gates its normalization errors produced (the first errors.length gates).
   const blocking = mode === "prepared"
     ? blockerGates
-    : [];
+    : gates.slice(0, errors.length);
 
   return {
     mode,
@@ -227,7 +289,18 @@ export function createCampaignBuildBriefArtifact({
   };
 }
 
-export function validateCampaignBuildBriefArtifact(brief, { spec = null } = {}) {
+// "brand_palette_cta (brand.commerce_palette_source, brand.cta_style)": each
+// open question with the brief fields that close it.
+function describeOpenQuestions(questions) {
+  return questions.map((question) => {
+    const entry = REQUIRED_HIGH_IMPACT_FIELDS.find((candidate) => candidate.id === question?.id);
+    if (isNonEmptyString(entry?.answer_hint)) return `${question?.id} (${entry.answer_hint})`;
+    const fields = entry?.answer_fields || (isNonEmptyString(question?.field) ? [question.field] : []);
+    return fields.length ? `${question?.id} (${fields.join(", ")})` : String(question?.id);
+  }).join(", ");
+}
+
+export function validateCampaignBuildBriefArtifact(brief, { spec = null, normalizedPath = BUILD_BRIEF_NORMALIZED_REL_PATH } = {}) {
   const errors = [];
   const warnings = [];
   const ready = [];
@@ -255,18 +328,26 @@ export function validateCampaignBuildBriefArtifact(brief, { spec = null } = {})
     if (questions.length) {
       errors.push({
         code: "build_brief.questions_unanswered",
-        message: `Prepared Campaign Build Brief has ${questions.length} unresolved business question(s): ${questions.map((question) => question.id).join(", ")}.`,
+        message: `Prepared Campaign Build Brief has ${questions.length} unresolved business question(s): ${describeOpenQuestions(questions)}. Set those fields in the brief file and save it with ${cmd("record")} brief --packet <packet>.`,
       });
     }
   } else {
     if (questions.length) {
+      // An answer given in conversation is not recorded until it is in a
+      // brief file saved with record brief: the guided draft is regenerated
+      // on every intake, and a brief file replaces it whole.
       warnings.push({
         code: "build_brief.guided_questions",
-        message: `Generated Campaign Build Brief draft has ${questions.length} high-impact business question(s) to confirm: ${questions.map((question) => question.id).join(", ")}.`,
+        message: `Guided Campaign Build Brief has ${questions.length} high-impact business question(s) to confirm: ${describeOpenQuestions(questions)}. `
+          + `An answer counts only once it is saved: copy ${normalizedPath} to campaign-build-brief.json in the target repo, set those fields, and run ${cmd("record")} brief --packet <packet> `
+          + "(the file is found there automatically, or pass --brief <file>). The file replaces the draft, so start from the copy to keep the fields the draft already filled. "
+          + "Saving keeps every stage's recorded evidence unless the brief's content changes.",
       });
     }
+    // Input errors block in both modes; evaluation gates stay warnings here.
     for (const gate of blockerGates) {
-      warnings.push({ code: gate.code || "build_brief.blocker", message: gate.message || "Generated Campaign Build Brief draft has an unresolved blocker." });
+      const target = brief.status === "invalid" && NORMALIZATION_ERROR_CODES.has(gate.code) ? errors : warnings;
+      target.push({ code: gate.code || "build_brief.blocker", message: gate.message || "Guided Campaign Build Brief has an unresolved blocker." });
     }
   }
 
@@ -322,6 +403,7 @@ function normalizeCampaignBuildBrief(value, meta, errors) {
   brief._meta = {
     generated_at: new Date().toISOString(),
     mode: meta.mode,
+    mode_source: meta.modeSource,
     input_path: meta.inputPath || null,
     input_format: meta.inputFormat || null,
     input_source: meta.inputSource || null,
@@ -339,25 +421,127 @@ function normalizeCampaignBuildBrief(value, meta, errors) {
   brief.template_residue_policy = normalizeResiduePolicy(brief.template_residue_policy);
   brief.qa_policy = normalizeQaPolicy(brief.qa_policy);
   brief.confidence = objectOrEmpty(brief.confidence);
+  brief._meta.field_sources = summaryFieldSources(brief, meta);
 
   return brief;
 }
 
+// The concrete summary field paths of a normalized brief: one
+// design_authority.<page>.source per page the brief lists.
+function summaryFieldPaths(brief) {
+  return SUMMARY_FIELDS.flatMap((path) => (path === "design_authority.<page>.source"
+    ? Object.keys(objectOrEmpty(brief.design_authority)).map((page) => `design_authority.${page}.source`)
+    : [path]));
+}
+
+// The value at a dotted path, reading the segment after `design_authority`
+// as one page id (a page id may itself contain a dot).
+function valueAtPath(value, path) {
+  const parts = path.startsWith("design_authority.") && path.endsWith(".source")
+    ? ["design_authority", path.slice("design_authority.".length, -".source".length), "source"]
+    : path.split(".");
+  let node = value;
+  for (const part of parts) {
+    if (!isObject(node) || !Object.hasOwn(node, part)) return undefined;
+    node = node[part];
+  }
+  return node;
+}
+
+function valueFingerprint(value) {
+  return `sha256:${createHash("sha256").update(canonicalJson(value)).digest("hex")}`;
+}
+
+// Whether `path` is one of the answer_fields of a question still open in the
+// previous normalized brief (design_authority.<page_id>.source matches any page).
+function answersOpenQuestion(path, previous) {
+  const questions = Array.isArray(previous?.questions) ? previous.questions : [];
+  return questions.some((question) => {
+    const entry = REQUIRED_HIGH_IMPACT_FIELDS.find((candidate) => candidate.id === question?.id);
+    return (entry?.answer_fields || []).some((field) => field === path
+      || (field === "design_authority.<page_id>.source" && path.startsWith("design_authority.") && path.endsWith(".source")));
+  });
+}
+
+// _meta.field_sources: {kind, value_fingerprint} per summary field. A
+// generated draft stamps every non-null value `default` (no draft value is
+// copied verbatim from a structured source field). From a file: a value absent
+// or null in the file is `default` when normalization filled one; a value the
+// file sets is `stated` when it answers an open question of the previous
+// brief or differs from the previous value (or there is no previous brief),
+// and otherwise keeps the previous entry. A null value gets no entry.
+function summaryFieldSources(brief, meta) {
+  const previous = isObject(meta.previousNormalizedBrief) ? meta.previousNormalizedBrief : null;
+  const previousSources = isObject(previous?._meta?.field_sources) ? previous._meta.field_sources : {};
+  const fromFile = isObject(meta.fileValue);
+  const sources = {};
+  for (const path of summaryFieldPaths(brief)) {
+    const value = valueAtPath(brief, path);
+    if (value === undefined || value === null) continue;
+    const entry = (kind) => ({ kind, value_fingerprint: valueFingerprint(value) });
+    const inFile = fromFile ? valueAtPath(meta.fileValue, path) : undefined;
+    if (!fromFile || inFile === undefined || inFile === null) {
+      sources[path] = entry("default");
+    } else if (answersOpenQuestion(path, previous) || !previous || canonicalJson(valueAtPath(previous, path) ?? null) !== canonicalJson(value)) {
+      sources[path] = entry("stated");
+    } else if (Object.hasOwn(previousSources, path) && fieldSourceEntryMatches(previousSources[path], value)) {
+      sources[path] = { kind: previousSources[path].kind, value_fingerprint: previousSources[path].value_fingerprint };
+    }
+  }
+  return sources;
+}
+
+const FIELD_SOURCE_KINDS = Object.freeze(["stated", "source", "default"]);
+
+/**
+ * Whether a _meta.field_sources entry can be read for `value`: exactly
+ * {kind, value_fingerprint}, a known kind, and the fingerprint of `value`.
+ * Any other entry is ignored.
+ */
+export function fieldSourceEntryMatches(entry, value) {
+  return isObject(entry)
+    && Object.keys(entry).length === 2
+    && FIELD_SOURCE_KINDS.includes(entry.kind)
+    && entry.value_fingerprint === valueFingerprint(value);
+}
+
+// The brief's material content, from the normalized artifact: `qa_policy`
+// (without its fixed enforcement note) and `presentation`, every other
+// top-level key that is not normalization output or the declared mode,
+// including keys the operator added.
+export function briefMaterialProjection(normalized) {
+  const brief = isObject(normalized) ? normalized : {};
+  // Entry-wise copies, so an operator key named __proto__ stays data.
+  const presentation = Object.fromEntries(Object.entries(brief).filter(([key]) => !NON_MATERIAL_BRIEF_KEYS.has(key) && key !== "qa_policy"));
+  const qaPolicy = Object.fromEntries(Object.entries(objectOrEmpty(brief.qa_policy)).filter(([key]) => key !== "enforcement"));
+  return { presentation, qa_policy: qaPolicy };
+}
+
+// Each partition as "sha256:<hex>" of its canonical JSON: key order,
+// whitespace, an explicit default and _meta never change it.
+export function briefMaterialFingerprint(normalized) {
+  const projection = briefMaterialProjection(normalized);
+  return { presentation: valueFingerprint(projection.presentation), qa_policy: valueFingerprint(projection.qa_policy) };
+}
+
 function draftCampaignBuildBrief({ spec, activePages, pageMappings, templateFamily, sourceAssetCrawl }) {
   const pageMap = new Map((pageMappings || []).map((page) => [page.page_id, page]));
-  const designAuthority = {};
-  for (const page of activePages || []) {
+  // Entry-wise, so a page id named __proto__ stays a page.
+  const designAuthority = Object.fromEntries((activePages || []).map((page) => {
     const mapped = pageMap.get(page.id);
-    designAuthority[page.id] = {
+    return [page.id, {
       source: mapped?.path ? "provided_design_export" : "template",
       reference: mapped?.path || mapped?.skip_reason || `${page.type || "page"} from selected template`,
-    };
-  }
+    }];
+  }));
 
   const variantSignals = collectVariantSignals(spec, sourceAssetCrawl);
   const paymentMethods = collectSpecPaymentMethods(spec);
   const hasExitPop = activePages?.some((page) => page?.type === "checkout" && 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.
+  const fillsTemplatePromo = templatePromoSurfaces({ spec, activePages }).length > 0;
 
   return {
     schema_version: BUILD_BRIEF_SCHEMA,
@@ -394,8 +578,8 @@ function draftCampaignBuildBrief({ spec, activePages, pageMappings, templateFami
       },
     },
     promo_urgency: {
-      header_claim_source: hasPromoSignals(spec) ? "campaign_offers" : "none",
-      timer_label: hasPromoSignals(spec) ? null : "Limited-time offer",
+      header_claim_source: fillsTemplatePromo ? "campaign_offers" : "none",
+      timer_label: fillsTemplatePromo ? null : "none",
       show_promo_code_in_timer: false,
       exit_pop: {
         enabled: hasExitPop,
@@ -427,7 +611,7 @@ function draftCampaignBuildBrief({ spec, activePages, pageMappings, templateFami
       brand: "low",
       media: variantSignals.length === 1 ? "medium" : "low",
       offer_presentation: "low",
-      promo_urgency: hasPromoSignals(spec) ? "low" : "medium",
+      promo_urgency: fillsTemplatePromo ? "low" : "medium",
       commerce_surfaces: paymentMethods.length ? "medium" : "low",
       template_family: templateFamily || null,
     },
@@ -466,10 +650,11 @@ function evaluateCampaignBuildBrief(brief, { spec, activePages, pageMappings, so
       options: ["discounted unit price", "savings-led", "full accounting"],
     });
   }
-  if (hasPromoSignals(spec) && (!isNonEmptyString(brief.promo_urgency?.header_claim_source) || !isNonEmptyString(brief.promo_urgency?.timer_label))) {
+  const promoSurfaces = templatePromoSurfaces({ spec, activePages });
+  if (promoSurfaces.length && (!isNonEmptyString(brief.promo_urgency?.header_claim_source) || !isNonEmptyString(brief.promo_urgency?.timer_label))) {
     addQuestion(questions, "promo_urgency_copy", {
-      detail: "CampaignSpec appears to include promo/offer signals, but promo copy authority is incomplete.",
-      options: ["actual voucher code", "bundle savings claim", "no promo banner"],
+      detail: `CampaignSpec maps ${promoSurfaces.join(" and ")}, which would fill the template's promo placeholders. Missing promo_urgency.header_claim_source ("campaign_offers" or "none") or promo_urgency.timer_label (the template timer's label, or "none").`,
+      options: ["fill from the campaign's promo codes and offers", "remove the template's promo placeholders"],
     });
   }
   if (!normalizePaymentList(brief.commerce_surfaces?.payment_methods_allowed).length) {
@@ -638,16 +823,30 @@ export function collectSpecPaymentMethods(spec) {
   return [...methods].sort();
 }
 
-function hasPromoSignals(spec) {
-  let found = false;
-  visitValues(spec, (value, keyPath) => {
-    if (found) return;
-    const path = keyPath.join(".").toLowerCase();
-    if (/(promo|voucher|coupon|discount|offer|timer|urgency|exit_intent)/.test(path) && value != null && value !== false) {
-      found = true;
-    }
-  });
-  return found;
+// The CampaignSpec surfaces that fill a starter template's own promo
+// placeholders: the template's promo banner and countdown timer read
+// funnels[].promo_codes, and its exit-pop offer reads a page's exit_intent or
+// promo_code_input. The campaign's offer catalog and discount pricing are not
+// among them (bundle_pricing_presentation covers those), and neither is any
+// promo, proof or urgency copy of the source design: that is the merchant's
+// content, built as designed.
+function templatePromoSurfaces({ spec = null, activePages = [] } = {}) {
+  const surfaces = [];
+  const funnels = Array.isArray(spec?.funnels) ? spec.funnels : [];
+  if (funnels.some((funnel) => Array.isArray(funnel?.promo_codes) && funnel.promo_codes.length > 0)) {
+    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;
+  if (pages.some((page) => checkoutSurface(page, "exit_intent"))) {
+    surfaces.push("an exit-intent offer (exit_intent)");
+  }
+  if (pages.some((page) => checkoutSurface(page, "promo_code_input"))) {
+    surfaces.push("a promo-code input (promo_code_input)");
+  }
+  return surfaces;
 }
 
 function hasOrderBumpSignals(value, keyPath = []) {

package/src/built-site-scope.mjs

@@ -16,6 +16,8 @@ import { createHash } from "node:crypto";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, join, relative, sep } from "node:path";
 
+import { isFileReadFailure } from "./cart-placeholders.mjs";
+
 const HTML_EXT = ".html";
 
 // The route tokens inferPageType reads for the funnel roles, exported so a
@@ -56,7 +58,26 @@ export function inferPageType(routeOrName) {
   return "page";
 }
 
-function listHtmlFiles(root) {
+// Whether a symbolic link may stand for a built page: its name ends in .html,
+// or its target is a directory, or its target cannot be inspected (missing,
+// EACCES, ELOOP, any file-system error). A link to a regular file (or any
+// other non-directory) not named .html is no page. Only file-system errors
+// are caught; anything else throws.
+function linkMayBePage(full, name) {
+  if (name.toLowerCase().endsWith(HTML_EXT)) return true;
+  try {
+    return statSync(full).isDirectory();
+  } catch (error) {
+    if (!isFileReadFailure(error)) throw error;
+    return true;
+  }
+}
+
+// `links`, when given, collects every symbolic link that may stand for a page
+// (see linkMayBePage). They are never pages themselves (build output holds no
+// links, and a link is not followed), but a caller that must account for every
+// built page can name them.
+function listHtmlFiles(root, links = null) {
   const files = [];
   if (!existsSync(root) || !statSync(root).isDirectory()) return files;
   const walk = (dir) => {
@@ -67,9 +88,11 @@ function listHtmlFiles(root) {
       const full = join(dir, entry.name);
       if (entry.isDirectory()) walk(full);
       else if (entry.isFile() && entry.name.toLowerCase().endsWith(HTML_EXT)) files.push(full);
+      else if (links && entry.isSymbolicLink() && linkMayBePage(full, entry.name)) links.push(full);
     }
   };
   walk(root);
+  links?.sort();
   return files.sort();
 }
 
@@ -101,7 +124,13 @@ function resolveSiteRoot(targetRepo) {
  *
  * @param {string} targetRepo Absolute path to the page-kit target repo (or a
  *   `_site/` directory, or a campaign directory).
- * @param {{ slug?: string|null }} [options]
+ * @param {{ slug?: string|null, includeLinkedPages?: boolean }} [options]
+ *   `includeLinkedPages` adds `linked_pages`: every symbolic link under the
+ *   campaign directory that may stand for a page (named .html, or its target
+ *   a directory, or its target not inspectable; each one entry, its
+ *   `built_path` the link itself; skipped as pages, not followed), in the
+ *   same shape as `pages`. A link to a regular file not named .html is
+ *   dropped. Off by default; without it the result is unchanged.
  * @returns {{
  *   ok: boolean,
  *   error?: string,
@@ -114,7 +143,7 @@ function resolveSiteRoot(targetRepo) {
  *   slug_candidates?: string[],
  * }}
  */
-export function resolveBuiltSiteScope(targetRepo, { slug = null } = {}) {
+export function resolveBuiltSiteScope(targetRepo, { slug = null, includeLinkedPages = false } = {}) {
   const base = { ok: false, target_repo: targetRepo, site_root: null, slug: "", campaign_dir: null, pages: [], html_count: 0 };
   if (!targetRepo || !existsSync(targetRepo) || !statSync(targetRepo).isDirectory()) {
     return { ...base, error: `Built campaign directory does not exist: ${targetRepo}` };
@@ -149,7 +178,7 @@ export function resolveBuiltSiteScope(targetRepo, { slug = null } = {}) {
     return { ...base, site_root: siteRoot, slug: resolvedSlug, error: `Campaign directory does not exist: ${campaignDir}` };
   }
 
-  const pages = listHtmlFiles(campaignDir).map((file) => {
+  const toPage = (file) => {
     const route = routeForFile(campaignDir, file);
     return {
       page_id: pageIdForRoute(route),
@@ -157,10 +186,13 @@ export function resolveBuiltSiteScope(targetRepo, { slug = null } = {}) {
       route,
       built_path: file,
     };
-  });
+  };
+  const links = includeLinkedPages ? [] : null;
+  const pages = listHtmlFiles(campaignDir, links).map(toPage);
+  const linked = links ? { linked_pages: links.map(toPage) } : {};
 
   if (!pages.length) {
-    return { ...base, site_root: siteRoot, slug: resolvedSlug, campaign_dir: campaignDir, error: `No built HTML pages found under ${campaignDir}.` };
+    return { ...base, site_root: siteRoot, slug: resolvedSlug, campaign_dir: campaignDir, ...linked, error: `No built HTML pages found under ${campaignDir}.` };
   }
 
   return {
@@ -171,6 +203,7 @@ export function resolveBuiltSiteScope(targetRepo, { slug = null } = {}) {
     campaign_dir: campaignDir,
     pages,
     html_count: pages.length,
+    ...linked,
   };
 }