@nextcommerce/campaigns-os 1.60.0 → 1.62.0

package/src/sdk-storage-compatibility.mjs

@@ -7,6 +7,7 @@ import { readFileSync, lstatSync, realpathSync, statSync } from 'node:fs';
 import { resolve, relative, dirname, posix, sep } from 'node:path';
 import { createHash } from 'node:crypto';
 import { isUtf8 } from 'node:buffer';
+import { singleLineFragment } from './text-safety.mjs';
 const digest = value => createHash('sha256').update(value).digest('hex');
 const version = value => {
   if (typeof value !== 'string' || !/^\d+\.\d+\.\d+$/.test(value))
@@ -49,6 +50,9 @@ function normalizeScope(value) {
     throw new Error('Scope and exclusions must be literal repository-relative files or directories.');
   return value.replace(/^\.\//, '').replace(/\/$/, '') || '.';
 }
+const PREFIX_SCAN_REASONS = new Set(['dynamic-key', 'unsupported-storage-method', 'storage-object-escape']);
+const LOOPS = new Set(['ForStatement', 'ForInStatement', 'ForOfStatement', 'WhileStatement', 'DoWhileStatement']);
+const ITERATION_METHODS = new Set(['forEach', 'filter', 'map', 'flatMap', 'find', 'findIndex', 'some', 'every', 'reduce']);
 const inside = (path, scope) => scope === '.' || path === scope || path.startsWith(scope + '/');
 export function readStorageManifest(path) {
   const bytes = readFileSync(path);
@@ -219,7 +223,72 @@ export function analyzeStorageJavaScript(source, { path = '<source>', lineOffset
       else
         reason = 'literal-unaffected-key';
     }
-    emit(node, { operation, area: storage.name, key, status, reason, replacement });
+    const prefixScan = status === 'unknown' && !storage.shadowed && PREFIX_SCAN_REASONS.has(reason) ? sdkPrefixScan(storage.name, node) : null;
+    emit(node, { operation, area: storage.name, key, status, reason, replacement, ...(prefixScan && { prefixScan }) });
+  }
+  // A loop that matches storage keys by a scoped SDK key's prefix: its key()/getItem(k) lines stay unknown, but are named.
+  // A prefix test counts only when it tests a key the loop read from storage itself: a `k = storage.key(i)` binding,
+  // a for-of/for-in variable over `Object.keys(storage)` or `storage`, or the element parameter of an array callback
+  // chained on `Object.keys(storage)`. A line is named only when it is that key's source or reads that key.
+  // Names are matched within the loop, not resolved through scopes; it is a hint only.
+  const stack = [];
+  const prefixCache = new WeakMap();
+  const callName = call => call?.type === 'CallExpression' && call.callee.type === 'MemberExpression' ? (call.callee.computed ? literal(call.callee.property, scopes.get(call)) : call.callee.property.name) : null;
+  const keysOf = node => node?.type === 'CallExpression' && node.callee.type === 'MemberExpression' && node.callee.object.type === 'Identifier' && node.callee.object.name === 'Object' && callName(node) === 'keys' ? node.arguments[0] : null;
+  function keySource(node) {
+    // Object.keys(storage).filter(...).forEach(...): the chain bottoms out at Object.keys.
+    while (node?.type === 'CallExpression' && ITERATION_METHODS.has(callName(node)))
+      node = node.callee.object;
+    return keysOf(node);
+  }
+  function prefixTests(loop) {
+    if (prefixCache.has(loop)) return prefixCache.get(loop);
+    const keys = new Map(), sources = new Map(), tests = [];
+    // source: the storage reference the key came from (the key() call, or the storage in Object.keys(storage) / for-in).
+    const bind = (id, storageNode, source = storageNode) => {
+      const storage = storageNode && area(storageNode, scopes.get(storageNode));
+      if (id?.type !== 'Identifier' || !storage) return;
+      keys.set(id.name, storage.name);
+      sources.set(source, id.name);
+    };
+    const loopVariable = left => left?.type === 'VariableDeclaration' ? left.declarations[0]?.id : left;
+    (function walk(n) {
+      if (n.type === 'VariableDeclarator' && callName(n.init) === 'key')
+        bind(n.id, n.init.callee.object, n.init);
+      if (n.type === 'AssignmentExpression' && n.operator === '=' && callName(n.right) === 'key')
+        bind(n.left, n.right.callee.object, n.right);
+      if (n.type === 'ForOfStatement')
+        bind(loopVariable(n.left), keysOf(n.right));
+      if (n.type === 'ForInStatement')
+        bind(loopVariable(n.left), n.right);
+      if (n.type === 'CallExpression' && ITERATION_METHODS.has(callName(n)) && ['ArrowFunctionExpression', 'FunctionExpression'].includes(n.arguments[0]?.type))
+        bind(n.arguments[0].params[callName(n) === 'reduce' ? 1 : 0], keySource(n.callee.object));
+      if (callName(n) === 'startsWith')
+        tests.push({ receiver: n.callee.object, prefix: literal(n.arguments[0], scopes.get(n)) });
+      if (n.type === 'BinaryExpression' && ['===', '==', '!==', '!='].includes(n.operator))
+        for (const [call, zero] of [[n.left, n.right], [n.right, n.left]])
+          if (zero.type === 'Literal' && zero.value === 0 && callName(call) === 'indexOf' && call.arguments.length === 1)
+            tests.push({ receiver: call.callee.object, prefix: literal(call.arguments[0], scopes.get(call)) });
+      for (const child of children(n)) walk(child);
+    })(loop);
+    const prefixes = tests.filter(t => t.prefix && t.receiver.type === 'Identifier' && keys.has(t.receiver.name)).map(t => ({ name: t.receiver.name, prefix: t.prefix, area: keys.get(t.receiver.name) }));
+    const result = { prefixes, sources };
+    prefixCache.set(loop, result);
+    return result;
+  }
+  function sdkPrefixScan(storageName, node) {
+    // The key this line reads (getItem(k), storage[k]), if it is a plain name.
+    const argument = node.type === 'CallExpression' ? node.arguments[0] : node.type === 'MemberExpression' && node.computed ? node.property : null;
+    // Nearest matching loop wins; a loop that does not test this line's key passes to the one around it.
+    for (const loop of [...stack].reverse()) {
+      if (!LOOPS.has(loop.type) && !(loop.type === 'CallExpression' && ITERATION_METHODS.has(callName(loop)))) continue;
+      const { prefixes, sources } = prefixTests(loop);
+      const names = [sources.get(node), argument?.type === 'Identifier' ? argument.name : null];
+      const tested = prefixes.filter(t => t.area === storageName && names.includes(t.name)).map(t => t.prefix);
+      const entry = manifest.keys.find(e => e.scoped && e.areas.includes(storageName) && e.key.split('{')[0] && tested.includes(e.key.split('{')[0]));
+      if (entry) return { prefix: entry.key.split('{')[0], key: entry.key, replacement: entry.replacement ?? null };
+    }
+    return null;
   }
   const handled = new WeakSet();
   const aliasInitialization = (node, parent) => parent?.type === 'VariableDeclarator' && parent.init === node && parent.id.type === 'Identifier' && binding(parent.id.name, scopes.get(parent))?.init === node;
@@ -229,6 +298,7 @@ export function analyzeStorageJavaScript(source, { path = '<source>', lineOffset
     (['LabeledStatement', 'BreakStatement', 'ContinueStatement'].includes(parent?.type) && parent.label === node)
   );
   function visit(node, parent) {
+    stack.push(node);
     const scope = scopes.get(node);
     if (node.type === 'CallExpression' && node.callee.type === 'MemberExpression') {
       const member = node.callee, storage = area(member.object, scope), method = member.computed ? literal(member.property, scope) : member.property.name;
@@ -258,6 +328,7 @@ export function analyzeStorageJavaScript(source, { path = '<source>', lineOffset
     }
     for (const child of children(node))
       visit(child, node);
+    stack.pop();
   }
   visit(ast, null);
   return findings;
@@ -291,6 +362,19 @@ function frontmatterScripts(text) {
   // linePos is 1-based within the YAML block, which starts on the file's line 2.
   return { scripts: scripts.items.map(item => ({ value: item.value, line: lineCounter.linePos(item.range[0]).line + 1 })) };
 }
+const INVENTORY_MAX_BYTES = 256 * 1024 * 1024;
+const INVENTORY_DETAIL_MAX = 200;
+
+// A missing git already fails at rev-parse, above the inventory.
+export function inventoryFailure(error) {
+  if (error.code === 'ENOBUFS') return `the tracked-file list under --scope is larger than ${INVENTORY_MAX_BYTES / 1024 / 1024} MiB; narrow --scope.`;
+  const stderr = typeof error.stderr === 'string' ? error.stderr : error.stderr?.toString() ?? '';
+  const detail = singleLineFragment(stderr.trim().split('\n')[0], `git exited ${error.status ?? error.signal ?? error.code ?? 'abnormally'} with no message`);
+  const chars = Array.from(detail);
+  const bounded = chars.length > INVENTORY_DETAIL_MAX ? `${chars.slice(0, INVENTORY_DETAIL_MAX).join('')}…` : detail;
+  return `${bounded.replace(/\.$/, '')}.`;
+}
+
 export function scanSdkStorageCompatibility({ cwd = process.cwd(), targetSdkVersion, manifestPath, scope, exclude = [] }) {
   version(targetSdkVersion);
   if (!Array.isArray(scope) || !scope.length)
@@ -305,16 +389,22 @@ export function scanSdkStorageCompatibility({ cwd = process.cwd(), targetSdkVers
   if (rootIdentity.dev !== targetIdentity.dev || rootIdentity.ino !== targetIdentity.ino)
     throw new Error('--target must be the Git repository root.');
   const { value: manifest, evidence } = readStorageManifest(manifestPath);
+  // Inventory only the scope: a whole-repository list can pass Node's 1 MiB
+  // default buffer on a large repository (#717). Scopes are literal paths.
   let tracked;
-  try { tracked = execFileSync('git', ['-C', root, 'ls-files', '-z'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).split('\0').filter(Boolean); }
-  catch { throw new Error('Cannot inventory tracked Git source files.'); }
+  try {
+    tracked = execFileSync('git', ['--literal-pathspecs', '-C', root, 'ls-files', '-z', '--', ...scope], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: INVENTORY_MAX_BYTES }).split('\0').filter(Boolean);
+  } catch (error) {
+    throw new Error(`Cannot inventory tracked Git source files: ${inventoryFailure(error)}`);
+  }
   for (const item of scope)
     if (!tracked.some(p => inside(p, item)))
       throw new Error(`Scope has no tracked files: ${item}`);
   const selected = tracked.filter(p => /\.(?:html?|[cm]?js)$/i.test(p) && scope.some(s => inside(p, s)) && !exclude.some(s => inside(p, s))).sort();
   const files = [], findings = [];
   const unknown = (path, reason, detail, line = 1) => findings.push({ path, line, column: 1, operation: 'unknown', area: null, key: null, status: 'unknown', reason, detail, replacement: null });
-  if (compare(targetSdkVersion, manifest.supportedSdkVersions.min) < 0 || compare(targetSdkVersion, manifest.supportedSdkVersions.max) > 0)
+  const targetCovered = compare(targetSdkVersion, manifest.supportedSdkVersions.min) >= 0 && compare(targetSdkVersion, manifest.supportedSdkVersions.max) <= 0;
+  if (!targetCovered)
     unknown(evidence.path, 'target-outside-manifest-range', targetSdkVersion);
   if (!selected.length)
     unknown('.', 'empty-source-scope', 'No tracked HTML or JavaScript files selected.');
@@ -412,9 +502,28 @@ export function scanSdkStorageCompatibility({ cwd = process.cwd(), targetSdkVers
     html(document);
   }
   const status = findings.some(f => f.status === 'incompatible') ? 'incompatible' : findings.some(f => f.status === 'unknown') ? 'unknown' : 'source-compatible';
-  return { schemaVersion: 1, targetSdkVersion, manifest: evidence, scope, exclude, files, findings, status, evidenceBoundary: 'Static tracked source compatibility only; no browser, order, or analytics proof.' };
+  return { schemaVersion: 1, targetSdkVersion, targetCovered, manifest: evidence, scope, exclude, files, findings, status, evidenceBoundary: 'Static tracked source compatibility only; no browser, order, or analytics proof.' };
 }
+const sdkRange = ({ min, max }) => min === max ? min : `${min} to ${max}`;
 export function formatStorageCompatibilityReport(result) {
   const counts = status => result.findings.filter(f => f.status === status).length;
-  return [`SDK storage compatibility: ${result.status} (target ${result.targetSdkVersion})`, `${result.files.length} tracked source files; ${counts('incompatible')} incompatible, ${counts('unknown')} unknown, ${counts('unaffected')} unaffected storage accesses.`, `Manifest ${result.manifest.sha256} (${result.manifest.source.verification})`, ...result.findings.filter(f => f.status !== 'unaffected').map(f => `${f.path}:${f.line}:${f.column} ${f.status}: ${f.reason}${f.key ? ` (${f.key})` : ''}${f.detail ? ` — ${f.detail}` : ''}`), result.evidenceBoundary].join('\n');
+  const target = result.targetSdkVersion, covered = sdkRange(result.manifest.supportedSdkVersions);
+  const outside = result.targetCovered === false;
+  const header = outside
+    ? [`SDK storage compatibility: ${result.status} (checked against SDK ${covered}, not the requested target ${target})`, `The manifest (Campaign Cart ${result.manifest.sdkVersion}) declares support for SDK ${covered} only, so this report does not speak for ${target}.`]
+    : [`SDK storage compatibility: ${result.status} (target ${target})`];
+  const summary = `${result.files.length} tracked source files; ${counts('incompatible')} incompatible, ${counts('unknown')} unknown, ${counts('unaffected')} unaffected storage accesses${outside ? ` (against SDK ${covered}, not ${target})` : ''}.`;
+  const line = f => `${f.path}:${f.line}:${f.column} ${f.status}: ${f.reason}${f.key ? ` (${f.key})` : ''}${f.detail ? ` — ${f.detail}` : ''}${f.prefixScan ? ` [prefix loop: ${f.prefixScan.prefix}]` : ''}`;
+  return [...header, summary, `Manifest ${result.manifest.sha256} (${result.manifest.source.verification})`, ...result.findings.filter(f => f.status !== 'unaffected').map(line), ...prefixScanNote(result.findings), result.evidenceBoundary].join('\n');
+}
+// One note for every [prefix loop] line, so a reader can tell them from unknowns with no known shape.
+function prefixScanNote(findings) {
+  const scans = findings.filter(f => f.prefixScan);
+  if (!scans.length) return [];
+  const prefixes = [...new Set(scans.map(f => f.prefixScan.prefix))];
+  const replacements = [...new Map(scans.filter(f => f.prefixScan.replacement).map(f => [f.prefixScan.prefix, f.prefixScan.replacement])).entries()];
+  return [
+    `${scans.length} unknown ${scans.length === 1 ? 'line is' : 'lines are'} [prefix loop]: a loop that matches storage keys starting with ${prefixes.join(', ')}. Such a loop finds the SDK key with or without its scope suffix, so the scoping rename alone does not break it. It stays unknown because on an origin shared with another campaign, or another top folder of this one, the same prefix also matches that copy; check which key the loop takes.`,
+    ...replacements.map(([prefix, r]) => `For ${prefix}, the manifest names the public ${r.export} export instead (${r.guide}).`),
+  ];
 }

package/src/source-html-intake.mjs

@@ -559,6 +559,20 @@ function addSpecHints(mapping, page) {
   if (variantLabels) mapping.variant_labels = variantLabels;
 }
 
+/**
+ * The page-kit projection of every page in `specPages` (a Map of page id to
+ * projection), as intake projects a mapped page: target path, public route,
+ * page_type and the frontmatter links to the other pages. `record spec`
+ * re-projects with it when routes move or, after handoff, when pages are
+ * added or removed (#531, #721); every page is re-projected because a page's
+ * next_url and decline_url read the routes of the pages it links to.
+ */
+export function projectPageKitTargets({ specPages = [], publicRouteSlug, outputDir }) {
+  const pages = Array.isArray(specPages) ? specPages : [];
+  const pageById = new Map(pages.map((page) => [page.id, page]));
+  return new Map(pages.map((page) => [page.id, pageKitProjectionForPage(page, { pageById, publicRouteSlug, outputDir, specPages: pages })]));
+}
+
 function pageKitProjectionForPage(page, { pageById, publicRouteSlug, outputDir, specPages = [] }) {
   const specRoute = publicRouteForPage(page);
   const relativeRoute = stripPublicRoutePrefix(specRoute, publicRouteSlug);
@@ -707,7 +721,7 @@ function normalizeRootedRoute(value) {
   return normalized ? `/${normalized}` : "/";
 }
 
-function cpkPageTypeForSpecType(type) {
+export function cpkPageTypeForSpecType(type) {
   if (type === "presell" || type === "landing") return "product";
   if (type === "thankyou" || type === "receipt") return "receipt";
   if (type === "upsell" || type === "downsell") return "upsell";

package/src/source-html-manifest.mjs

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { normalizeDesignFileReference } from "./design-file-reference.mjs";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 
@@ -165,6 +166,12 @@ function validateManifestPage(entry, index, add, addWarning = () => {}) {
     }
   }
   warnOnUnusableScreenshotRecords(entry, location, addWarning);
+  if (Object.hasOwn(entry, "design_file")) {
+    const { declaration, warnings } = normalizeDesignFileReference(entry.design_file);
+    for (const detail of warnings) {
+      addWarning(`${location}.design_file`, `${location}.design_file (page_id ${JSON.stringify(entry.page_id)}) ${declaration ? "has an ignored frame" : "is ignored as a design-file declaration"}: ${detail}. The rest of the manifest is used as written.`);
+    }
+  }
 }
 
 // Screenshot records are optional proof, so a malformed one is not a reason to

package/src/source-html-server.mjs

@@ -0,0 +1,129 @@
+import { createServer } from "node:http";
+import { constants, openSync, fstatSync, readSync, closeSync, realpathSync, lstatSync } from "node:fs";
+import { realpath, stat, lstat, open } from "node:fs/promises";
+import { resolve, relative, isAbsolute, extname } from "node:path";
+import { VISUAL_MAX_REFERENCE_BYTES } from "./png-header.mjs";
+
+// Declared inputs (packet, manifest and campaign files) are opened without
+// blocking and read only when the opened descriptor is a regular file within
+// `maxBytes`: a FIFO, socket, device or directory is refused before any read,
+// so no declared path can hold the event loop ahead of a deadline.
+// With a `root`, the path is opened first and only then resolved: the
+// descriptor must be the very file (dev and ino) the contained realpath names,
+// so a path replaced between the open and the check is refused, never read.
+// `noFollow` also refuses a final component that is a link.
+export const DECLARED_INPUT_MAX_BYTES = VISUAL_MAX_REFERENCE_BYTES;
+const READ_FLAGS = constants.O_RDONLY | (constants.O_NONBLOCK ?? 0);
+const NO_FOLLOW = constants.O_NOFOLLOW ?? 0;
+const refusal = (code) => Object.assign(new Error(code), { code });
+const inside = (root, path) => { const rel = relative(root, path); return !isAbsolute(rel) && rel !== ".." && !rel.startsWith("../"); };
+// The resolved target is read with lstat: a final component swapped for a link
+// after resolution is that link's own inode, which no opened file matches.
+const sameFile = (info, target) => !target.isSymbolicLink() && info.dev === target.dev && info.ino === target.ino;
+export function readRegularFileSync(path, { maxBytes = DECLARED_INPUT_MAX_BYTES, statOnly = false, root = null, noFollow = false } = {}) {
+  const fd = openSync(path, READ_FLAGS | (noFollow ? NO_FOLLOW : 0));
+  try {
+    const info = fstatSync(fd);
+    if (!info.isFile()) throw refusal("not_regular_file");
+    if (root !== null) {
+      const resolved = realpathSync(path);
+      if (!inside(realpathSync(root), resolved) || !sameFile(info, lstatSync(resolved))) throw refusal("outside_root");
+    }
+    if (info.size > maxBytes) throw refusal("too_large");
+    if (statOnly) return null;
+    const chunks = [];
+    let length = 0;
+    while (length <= maxBytes) {
+      const chunk = Buffer.alloc(Math.min(65536, maxBytes + 1 - length));
+      const n = readSync(fd, chunk, 0, chunk.length, null);
+      if (!n) break;
+      chunks.push(chunk.subarray(0, n)); length += n;
+    }
+    if (length > maxBytes) throw refusal("too_large");
+    return Buffer.concat(chunks, length);
+  } finally { closeSync(fd); }
+}
+// Whether a read of `path` would reach its bytes; the size is not judged here.
+export const isRegularFileSync = (path, { root = null } = {}) => {
+  try { readRegularFileSync(path, { statOnly: true, maxBytes: Infinity, root }); return true; } catch { return false; }
+};
+// The server's read: open, fstat, then resolve and match the descriptor against
+// the contained target. Returns the resolved path (for the type) and the bytes.
+async function readContainedFile(base, path, { maxBytes, statOnly }) {
+  const handle = await open(path, READ_FLAGS);
+  try {
+    const info = await handle.stat();
+    if (!info.isFile() || info.size > maxBytes) throw refusal("not_served");
+    const resolved = await realpath(path);
+    if (!inside(base, resolved) || !sameFile(info, await lstat(resolved))) throw refusal("not_served");
+    if (statOnly) return { resolved, bytes: null };
+    const chunks = [];
+    let length = 0;
+    while (length <= maxBytes) {
+      const { bytesRead, buffer } = await handle.read(Buffer.alloc(Math.min(65536, maxBytes + 1 - length)));
+      if (!bytesRead) break;
+      chunks.push(buffer.subarray(0, bytesRead)); length += bytesRead;
+    }
+    if (length > maxBytes) throw refusal("not_served");
+    return { resolved, bytes: Buffer.concat(chunks, length) };
+  } finally { await handle.close(); }
+}
+
+const TYPES = Object.freeze({ ".html": "text/html; charset=utf-8", ".css": "text/css", ".js": "text/javascript",
+  ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".svg": "image/svg+xml",
+  ".webp": "image/webp", ".avif": "image/avif", ".woff": "font/woff", ".woff2": "font/woff2", ".ttf": "font/ttf",
+  ".ico": "image/x-icon", ".json": "application/json" });
+// This listener is also the sealed browser's refusing proxy. There is no
+// outbound client: even absolute-form requests to our own origin are refused.
+export async function startSourceHtmlServer({ root, signal, maxBytes = DECLARED_INPUT_MAX_BYTES } = {}) {
+  const base = await realpath(root);
+  if (!(await stat(base)).isDirectory()) throw new Error("source_root_unavailable");
+  if (signal?.aborted) throw signal.reason;
+  const refusals = new Map();
+  let totalRefusals = 0;
+  const record = (target, connect = false) => {
+    totalRefusals++;
+    try {
+      const origin = new URL(connect ? `https://${target}` : target).origin;
+      if (refusals.has(origin) || refusals.size < 32) refusals.set(origin, (refusals.get(origin) || 0) + 1);
+    } catch { /* never persist a malformed target */ }
+  };
+  const server = createServer(async (req, res) => {
+    res.setHeader("cache-control", "no-store");
+    const end = (code) => { res.statusCode = code; res.end(); };
+    if (!req.url.startsWith("/") || req.url.startsWith("//")) { record(req.url); return end(403); }
+    if (!["GET", "HEAD"].includes(req.method)) return end(405);
+    try {
+      const pathname = decodeURIComponent(req.url.split("?")[0]);
+      if (pathname.includes("\0") || pathname.includes("\\")) return end(404);
+      const { resolved, bytes } = await readContainedFile(base, resolve(base, `.${pathname}`), { maxBytes, statOnly: req.method === "HEAD" });
+      res.setHeader("content-type", TYPES[extname(resolved).toLowerCase()] || "application/octet-stream");
+      res.statusCode = 200;
+      res.end(bytes);
+    } catch { end(404); }
+  });
+  server.on("connect", (req, socket) => {
+    record(req.url, true);
+    socket.end("HTTP/1.1 403 Forbidden\r\nCache-Control: no-store\r\nConnection: close\r\nContent-Length: 0\r\n\r\n");
+  });
+  server.on("upgrade", (req, socket) => {
+    record(req.url);
+    socket.end("HTTP/1.1 403 Forbidden\r\nConnection: close\r\nContent-Length: 0\r\n\r\n");
+  });
+  server.requestTimeout = 5_000;
+  server.headersTimeout = 5_000;
+  const sockets = new Set();
+  server.on("connection", (socket) => { sockets.add(socket); socket.on("close", () => sockets.delete(socket)); });
+  await new Promise((done, reject) => { server.once("error", reject); server.listen(0, "127.0.0.1", done); });
+  let closing;
+  const close = () => closing ||= new Promise((done, reject) => {
+    server.close((error) => error ? reject(error) : done());
+    for (const socket of sockets) socket.destroy();
+  });
+  signal?.addEventListener("abort", () => { void close().catch(() => {}); }, { once: true });
+  if (signal?.aborted) { await close(); throw signal.reason; }
+  const port = server.address().port;
+  return { origin: `http://127.0.0.1:${port}`, port,
+    refusedTotal: () => totalRefusals,
+    refused: () => [...refusals].sort(([a], [b]) => a.localeCompare(b)).map(([origin, count]) => ({ origin, count })), close };
+}

package/src/spec-derive-campaign.mjs

@@ -0,0 +1,216 @@
+// `campaigns-os spec derive`, live campaign half (#721): refresh the offer and
+// package fields the CampaignSpec mirrors from the Campaigns App.
+//
+// Field classes (#432): a page package's ref, name, price (recurring price
+// included), product, variant and availability are mirrored from the Campaigns App's packages; the offer
+// records (`offers[]`, and the copy a page carries in `pages[].offers[]`) are
+// mirrored from its offers. Which packages and offers a page carries, and a
+// package's qty and role flags (is_upsell, is_order_bump, default_selected,
+// configurable), are authored and never written here. A price is owned by the
+// Campaigns App: it reaches the spec only from the live campaign, never from
+// the repo.
+//
+// The live campaign is the body of the one read-only GET of
+// `{proxy-base}/api/campaign` that doctor and `qa run` already make under the
+// public campaign key (live-campaign-refs.mjs). This module is pure: it
+// plans rows in spec-derive.mjs's shape from the spec and that body, and
+// spec-derive.mjs applies them under its write guard.
+
+// The page package fields the live campaign is the authority for, as Map
+// Builder exports them: the recurring price fields a subscription package
+// carries, and `variant_attributes`, which the campaign states as
+// `product_variant_attribute_values`.
+export const MIRRORED_PACKAGE_FIELDS = Object.freeze([
+  "name",
+  "price",
+  "price_retail",
+  "product_name",
+  "product_sku",
+  "product_variant_name",
+  "product_purchase_availability",
+  "product_inventory_availability",
+  "image",
+  "is_recurring",
+  "price_recurring",
+  "interval",
+  "interval_count",
+  "variant_attributes",
+]);
+
+// A spec field whose live value sits under another key.
+const LIVE_FIELD = Object.freeze({ variant_attributes: "product_variant_attribute_values" });
+
+// The offer record fields (root `offers[]`), and the subset a page's copy
+// (`pages[].offers[]`) carries.
+export const MIRRORED_OFFER_FIELDS = Object.freeze(["name", "type", "code", "condition", "benefit", "packages"]);
+export const MIRRORED_PAGE_OFFER_FIELDS = Object.freeze(["name", "type", "code", "condition", "benefit"]);
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+// A ref as the campaign states it, compared as its string form (5 and "5"
+// are one ref), or null when the entry carries none.
+function refOf(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  if (typeof value === "string" && value.trim()) return value.trim();
+  return null;
+}
+
+function canonicalJson(value) {
+  if (value === undefined) return "undefined";
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+}
+
+function pathLabel(path) {
+  return path.map((segment, index) => (typeof segment === "number" ? `[${segment}]` : `${index ? "." : ""}${segment}`)).join("");
+}
+
+function clone(value) {
+  return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}
+
+// Every active page with the JSON path it lives at, as spec-derive.mjs reads
+// them (funnels[] first; the legacy funnel_pages[] only without it).
+function activePagesWithPaths(spec) {
+  const pages = [];
+  const visit = (page, path) => {
+    if (isPlainObject(page) && page.enabled !== false && typeof page.id === "string" && page.id.trim()) pages.push({ page, path });
+  };
+  if (Array.isArray(spec?.funnels)) {
+    spec.funnels.forEach((funnel, funnelIndex) => {
+      (Array.isArray(funnel?.pages) ? funnel.pages : []).forEach((page, pageIndex) => visit(page, ["funnels", funnelIndex, "pages", pageIndex]));
+    });
+  } else if (Array.isArray(spec?.funnel_pages)) {
+    spec.funnel_pages.forEach((page, index) => visit(page, ["funnel_pages", index]));
+  }
+  return pages;
+}
+
+function indexByRef(list) {
+  const map = new Map();
+  for (const entry of Array.isArray(list) ? list : []) {
+    const ref = isPlainObject(entry) ? refOf(entry.ref_id) : null;
+    if (ref && !map.has(ref)) map.set(ref, entry);
+  }
+  return map;
+}
+
+// The rows that bring one mirrored record in line with the live one: a field
+// the live record states is written when the spec's value differs, and only
+// where the spec already carries the key or the live value says something
+// (not null, false or an empty list, which is how Map Builder leaves a
+// one-time package's recurring fields out), so a refresh does not pad the
+// spec with empty keys.
+function mirrorRows({ record, live, fields, path, source, pageId = null }) {
+  const changes = [];
+  const unchanged = [];
+  for (const field of fields) {
+    const key = LIVE_FIELD[field] || field;
+    if (!Object.hasOwn(live, key) || live[key] === undefined) continue;
+    const value = live[key];
+    const before = Object.hasOwn(record, field) ? record[field] : undefined;
+    if (before === undefined && (value === null || value === false || (Array.isArray(value) && !value.length))) continue;
+    const row = { field: pathLabel([...path, field]), path: [...path, field], before: clone(before), after: clone(value), source, ...(pageId ? { page_id: pageId } : {}) };
+    if (canonicalJson(before) === canonicalJson(value)) unchanged.push(row);
+    else changes.push(row);
+  }
+  return { changes, unchanged };
+}
+
+/**
+ * The plan for the mirrored offer and package fields: `changes` and
+ * `unchanged` rows in spec-derive.mjs's shape, `not_derived` for a record the
+ * spec lists that the live campaign does not serve (reported, never removed:
+ * which records a page carries is authored), and `summary` counts. `campaign`
+ * is the live campaign body; `campaignRef` names it in each row's source.
+ */
+export function planCampaignMirrorDerive({ spec, campaign, campaignRef = null } = {}) {
+  const changes = [];
+  const unchanged = [];
+  const notDerived = [];
+  const ref = campaignRef || refOf(campaign?.ref_id ?? campaign?.id);
+  const source = `the Campaigns App campaign${ref ? ` ${ref}` : ""} (GET /api/campaign)`;
+  const livePackages = indexByRef(campaign?.packages);
+  const liveOffers = Array.isArray(campaign?.offers) ? indexByRef(campaign.offers) : null;
+  const summary = { packages_checked: 0, offers_checked: 0, offers_added: 0 };
+
+  for (const { page, path } of activePagesWithPaths(spec)) {
+    (Array.isArray(page.packages) ? page.packages : []).forEach((pkg, index) => {
+      if (!isPlainObject(pkg)) return;
+      const pkgRef = refOf(pkg.ref_id);
+      const pkgPath = [...path, "packages", index];
+      if (!pkgRef) return;
+      const live = livePackages.get(pkgRef);
+      if (!live) {
+        notDerived.push({ field: pathLabel(pkgPath), page_id: page.id, reason: "package_not_live", detail: `page "${page.id}" carries package ${pkgRef}, which the live campaign does not serve; nothing was changed. Point the page at a package the campaign serves, or restore it in the Campaigns App.` });
+        return;
+      }
+      summary.packages_checked += 1;
+      const rows = mirrorRows({ record: pkg, live, fields: MIRRORED_PACKAGE_FIELDS, path: pkgPath, source, pageId: page.id });
+      changes.push(...rows.changes);
+      unchanged.push(...rows.unchanged);
+    });
+    (Array.isArray(page.offers) ? page.offers : []).forEach((offer, index) => {
+      if (!isPlainObject(offer) || !liveOffers) return;
+      const offerRef = refOf(offer.ref_id);
+      const offerPath = [...path, "offers", index];
+      if (!offerRef) return;
+      const live = liveOffers.get(offerRef);
+      if (!live) {
+        notDerived.push({ field: pathLabel(offerPath), page_id: page.id, reason: "offer_not_live", detail: `page "${page.id}" carries offer ${offerRef}, which the live campaign does not serve; nothing was changed. Remove it from the page, or restore it in the Campaigns App.` });
+        return;
+      }
+      const rows = mirrorRows({ record: offer, live, fields: MIRRORED_PAGE_OFFER_FIELDS, path: offerPath, source, pageId: page.id });
+      changes.push(...rows.changes);
+      unchanged.push(...rows.unchanged);
+    });
+  }
+
+  if (!liveOffers) {
+    if (Array.isArray(spec?.offers) && spec.offers.length) {
+      notDerived.push({ field: "offers", reason: "offers_not_in_live_campaign", detail: "the live campaign read carried no offers list, so the spec's offer records were not refreshed." });
+    }
+  } else if (!Array.isArray(spec?.offers)) {
+    const records = [...liveOffers.values()].map((live) => recordFromLive(live));
+    if (records.length) {
+      changes.push({ field: "offers", path: ["offers"], before: spec?.offers === undefined ? undefined : clone(spec.offers), after: records, source });
+      summary.offers_added = records.length;
+    }
+  } else {
+    const seen = new Set();
+    spec.offers.forEach((offer, index) => {
+      if (!isPlainObject(offer)) return;
+      const offerRef = refOf(offer.ref_id);
+      if (!offerRef) return;
+      seen.add(offerRef);
+      const live = liveOffers.get(offerRef);
+      if (!live) {
+        notDerived.push({ field: `offers[${index}]`, reason: "offer_not_live", detail: `offer ${offerRef} is in the spec's offers but not in the live campaign; it was kept, since pages may still name it. Remove it, or restore it in the Campaigns App.` });
+        return;
+      }
+      summary.offers_checked += 1;
+      const rows = mirrorRows({ record: offer, live, fields: MIRRORED_OFFER_FIELDS, path: ["offers", index], source });
+      changes.push(...rows.changes);
+      unchanged.push(...rows.unchanged);
+    });
+    let next = spec.offers.length;
+    for (const [offerRef, live] of liveOffers) {
+      if (seen.has(offerRef)) continue;
+      changes.push({ field: `offers[${next}]`, path: ["offers", next], op: "insert", before: undefined, after: recordFromLive(live), source });
+      next += 1;
+      summary.offers_added += 1;
+    }
+  }
+  return { changes, unchanged, not_derived: notDerived, summary };
+}
+
+// An offer record as the spec stores one: its ref and the mirrored fields the
+// live offer states.
+function recordFromLive(live) {
+  const record = { ref_id: live.ref_id };
+  for (const field of MIRRORED_OFFER_FIELDS) if (Object.hasOwn(live, field) && live[field] !== undefined) record[field] = clone(live[field]);
+  return record;
+}