@nextcommerce/campaigns-os 1.43.1 → 1.46.0

package/src/page-kit-sync.mjs

@@ -14,6 +14,7 @@
 // every other file are left as they are. This module is pure: the CLI does
 // the reading, the writing, and the printing.
 import {
+  isAuthoritativeEmptyStoreProfileValue,
   isDemoResidue,
   normalizeStoreProfileValue,
   PAGE_KIT_STORE_PROFILE_FIELDS,
@@ -25,17 +26,23 @@ export const PAGE_KIT_SYNC_FIELDS = Object.freeze([...PAGE_KIT_STORE_PROFILE_FIE
 
 // The field-by-field plan: what the entry holds, what the spec says, and
 // whether a write is owed. `changes` are the fields whose value will move,
-// `unchanged` already match, `not_in_spec` are governed fields the spec does
-// not carry (left as they are; doctor's `target_only` warning still applies),
-// and `not_synced` are fields the target cannot be made authoritative for: an
-// invalid or conflicting spec SDK pin, a spec value of the wrong type or
-// shape (or the demo value itself), or starter demo residue in a field the
-// spec does not carry. Absent, null and blank spec values are "not carried".
+// `unchanged` already match, `not_in_spec` are governed fields left as they
+// are because the spec does not carry them or because its "" was not applied
+// (doctor's `target_only` warning still applies), and `not_synced` are fields
+// the target cannot be made authoritative for: an invalid or conflicting spec
+// SDK pin, a spec value of the wrong type or shape (or the demo value itself),
+// or starter demo residue in a field the spec does not carry. Absent and null
+// spec values are "not carried"; an explicit empty (or whitespace-only) string
+// blanks the starter demo value and otherwise leaves the target as it is.
+// `spec_empty_not_applied` names that last case, the not_in_spec fields the
+// spec sets to "" over a real, non-demo target value, which only a hand edit
+// removes.
 export function planPageKitSync({ spec, entry, waivedGates = [] } = {}) {
   const target = entry && typeof entry === "object" && !Array.isArray(entry) ? entry : {};
   const changes = [];
   const unchanged = [];
   const notInSpec = [];
+  const specEmptyNotApplied = [];
   const notSynced = [];
   // A gate under an ACTIVE named-human waiver recorded a human accepting the
   // target's current values; sync must not silently reverse that decision.
@@ -61,8 +68,15 @@ export function planPageKitSync({ spec, entry, waivedGates = [] } = {}) {
   for (const field of PAGE_KIT_STORE_PROFILE_FIELDS) {
     const raw = spec?.campaign?.[field];
     const current = Object.hasOwn(target, field) ? target[field] : undefined;
-    const carried = raw !== undefined && raw !== null && !(typeof raw === "string" && !raw.trim());
-    if (!carried) {
+    // An explicit empty value blanks only the starter demo value, and confirms
+    // a target that already reads as empty. Any other target value is left as
+    // it is, as for a field the spec does not carry (doctor's target_only
+    // warning): Maps saved "" for every cleared store field before "" meant
+    // empty, so it never wipes a value someone entered.
+    const authoritativeEmpty = isAuthoritativeEmptyStoreProfileValue(field, raw);
+    const targetBlankOrDemo = current === undefined || current === null
+      || (typeof current === "string" && (!normalizeStoreProfileValue(current) || isDemoResidue(field, normalizeStoreProfileValue(current))));
+    if (raw === undefined || raw === null || (authoritativeEmpty && !targetBlankOrDemo)) {
       // Starter demo residue in a field the spec does not carry is the one
       // state sync cannot end: doctor blocks on it without a waiver and there
       // is no spec value to write over it. Say so instead of reporting a
@@ -75,13 +89,16 @@ export function planPageKitSync({ spec, entry, waivedGates = [] } = {}) {
         });
       } else {
         notInSpec.push(field);
+        if (authoritativeEmpty) specEmptyNotApplied.push(field);
       }
       continue;
     }
     // A carried value the target cannot be made authoritative for: the wrong
     // type (doctor's spec_invalid_type), the demo value itself, or a shape a
     // template would put into an href unescaped.
-    const problem = typeof raw !== "string" ? "spec_invalid_type" : storeProfileSpecValueProblem(field, raw);
+    // An explicit empty value reaching here is written as "" over the starter
+    // demo value.
+    const problem = typeof raw !== "string" ? "spec_invalid_type" : authoritativeEmpty ? null : storeProfileSpecValueProblem(field, raw);
     if (problem) {
       notSynced.push({ field, reason: problem, detail: NOT_SYNCED_DETAIL[problem](field, raw) });
       continue;
@@ -91,9 +108,11 @@ export function planPageKitSync({ spec, entry, waivedGates = [] } = {}) {
     const row = { field, before, after, source: `campaign.${field}` };
     // The gate compares normalized forms, so a target that differs only in
     // surrounding whitespace or Unicode normalization already passes; a
-    // rewrite would report a change doctor never saw.
+    // rewrite would report a change doctor never saw. For the same reason an
+    // absent or null target already agrees with an explicit empty value.
     const alreadyMatches = before === after
-      || (typeof before === "string" && normalizeStoreProfileValue(before) === after);
+      || (typeof before === "string" && normalizeStoreProfileValue(before) === after)
+      || (authoritativeEmpty && (before === undefined || before === null));
     if (alreadyMatches) unchanged.push(row);
     else if (storeProfileWaiver) notSynced.push({ field, reason: "waived", detail: waivedDetail(field, storeProfileWaiver, "page_kit.store_profile") });
     else changes.push(row);
@@ -130,7 +149,7 @@ export function planPageKitSync({ spec, entry, waivedGates = [] } = {}) {
     });
   }
 
-  return { changes, unchanged, not_in_spec: notInSpec, not_synced: notSynced };
+  return { changes, unchanged, not_in_spec: notInSpec, spec_empty_not_applied: specEmptyNotApplied, not_synced: notSynced };
 }
 
 // Apply a plan to the parsed campaigns.json document. Mutates ONLY the

package/src/private-template-source.mjs

@@ -83,7 +83,7 @@ function privateTemplateSourcesPath() {
 }
 
 // No caching, recomputed per call — matches certifiedTemplateFamilies()'s
-// existing convention (cli.mjs) so a long-lived process never serves a stale
+// existing convention (src/doctor/checks.mjs) so a long-lived process never serves a stale
 // allowlist after an edit.
 export function loadPrivateTemplateSources() {
   const path = privateTemplateSourcesPath();

package/src/progress-node.mjs

@@ -1,15 +1,18 @@
 import { campaignSpecIdentity, campaignIdentitiesMatch, localSpecIdentityFields } from "./spec-source-identity.mjs";
 // Best-effort producer adapter. Sanitized immutable bytes are durable before delivery.
 import {randomBytes,createHash} from 'node:crypto';
-import {mkdirSync,readFileSync,writeFileSync,renameSync,rmSync,readdirSync,lstatSync} from 'node:fs';
+import {mkdirSync,readFileSync,writeFileSync,renameSync,rmSync,readdirSync} from 'node:fs';
 import {join,resolve,dirname} from 'node:path';
 import {PROGRESS_SCHEMA_VERSION,PROGRESS_STAGES,PROGRESS_STAGE_STATUSES,PROGRESS_CONTINUATIONS,PROGRESS_ACTION_IDS,PROGRESS_GATE_IDS,canonicalProgressJson,progressSnapshotId,verifyProgressSnapshot} from './progress.mjs';
 import {specMaterialHash} from './spec-identity.mjs';
 import {sameFile} from './fs-identity.mjs';
+import {withDirectoryLock} from './directory-lock.mjs';
 import {resolveConsent,CANONICAL_REMIT_SCOPE,normalizeConsentScope,announceDefaultOnTelemetry} from './consent.mjs';
 import {boundedResponseText,isLoopbackHostname} from './remit.mjs';
 export const PROGRESS_OBSERVATION = Symbol('canonical progress observation');
 export const PROGRESS_ENDPOINT = '/api/progress';
+// A projection keeps the first PROGRESS_GATE_LIMIT continuation gates (the snapshot schema's gates maxItems).
+export const PROGRESS_GATE_LIMIT = 16;
 const accepted = (value,values,fallback='unknown')=>values.includes(value)?value:fallback;
 const hash = value=>typeof value==='string'&&/^(?:sha256:)?[0-9a-f]{64}$/i.test(value)?`sha256:${value.replace(/^sha256:/i,'').toLowerCase()}`:null;
 const id = value=>typeof value==='string'&&/^[A-Za-z0-9_-]{1,64}$/.test(value)?value:null;
@@ -55,7 +58,7 @@ export function projectProgressObservation({workspace,context,report,doctor,cont
     binding:reportBound&&id(verdict.run_id)&&id(verdict.run_id)===id(report?.stages?.qa?.verdict_run_id)&&build&&qaSource===build&&doctor?.derived?.build_output_fingerprint?.status==='pass'&&hash(verdict.spec_hash)===localHash?'matching':'unconfirmed',
     publish_state:accepted(qaResult?.qa_verdict_publish?.state,['skipped','ok','failed']),
   }:null;
-  const gates=(Array.isArray(continuation?.gates)?continuation.gates:[]).slice(0,16).map(gate=>({id:accepted(gate?.id,PROGRESS_GATE_IDS),state:PROGRESS_GATE_IDS.includes(gate?.id)?accepted(gate?.status,['pass','blocked','waived','not_applicable']):'unknown'}));
+  const gates=(Array.isArray(continuation?.gates)?continuation.gates:[]).slice(0,PROGRESS_GATE_LIMIT).map(gate=>({id:accepted(gate?.id,PROGRESS_GATE_IDS),state:PROGRESS_GATE_IDS.includes(gate?.id)?accepted(gate?.status,['pass','blocked','waived','not_applicable']):'unknown'}));
   const actions=[...new Set((Array.isArray(continuation?.next_actions)?continuation.next_actions:[]).slice(0,64).map(action=>accepted(action?.id,PROGRESS_ACTION_IDS)))];
   const stage=accepted(continuation?.stage,PROGRESS_CONTINUATIONS);
   const preview=typeof packet?.deploy?.preview_url==='string'&&packet.deploy.preview_url?packet.deploy.preview_url:null;
@@ -71,39 +74,9 @@ export function projectProgressObservation({workspace,context,report,doctor,cont
     continuation:{stage,blocked:continuation?.ok!==true||(Array.isArray(continuation?.divergences)&&continuation.divergences.length>0)||stage==='unknown'||gates.some(gate=>['blocked','unknown'].includes(gate.state))||actions.includes('unknown'),divergent:Array.isArray(continuation?.divergences)&&continuation.divergences.length>0,action_ids:actions,gates},qa,
   };
 }
-async function lock(dir,fn,{budgetMs=1500}={}) {
-  const path=join(dir,'.allocation-lock'); const start=Date.now();const token=randomBytes(16).toString('hex');
-  const abandoned=(unownedMtime=null)=>{
-    try {
-      const stat=lstatSync(path);if(!stat.isDirectory()||stat.isSymbolicLink())return false;
-      const owner=read(join(path,'owner.json'));
-      if(Number.isInteger(owner?.pid)&&owner.pid>0&&typeof owner.token==='string') {
-        try {process.kill(owner.pid,0);return false;}catch(error){return error.code==='ESRCH';}
-      }
-      // A killed process can leave the directory before writing its owner.
-      // Give a live allocator ample time to finish that tiny synchronous gap.
-      return Date.now()-(unownedMtime??stat.mtimeMs)>10000;
-    }catch{return false;}
-  };
-  const recover=()=>{
-    if(!abandoned())return;
-    let originalMtime;try{originalMtime=lstatSync(path).mtimeMs;}catch{return;}
-    const claim=join(path,'.recovery');
-    // Only this exclusive claimant can rename the old lock. An interrupted
-    // recovery claim fails closed for explicit offline recovery; recursively
-    // stealing recovery claims would reintroduce a check/rename race.
-    try {mkdirSync(claim);atomic(join(claim,'owner.json'),{pid:process.pid,token});}catch{return;}
-    let moved=false;
-    try {
-      if(!abandoned(originalMtime))return;
-      const tomb=`${path}.abandoned-${token}`;
-      renameSync(path,tomb);moved=true;rmSync(tomb,{recursive:true,force:true});
-    }catch{}finally{if(!moved&&read(join(claim,'owner.json'))?.token===token){try{rmSync(claim,{recursive:true,force:true});}catch{}}}
-  };
-  while (true) {
-    try {mkdirSync(path);atomic(join(path,'owner.json'),{pid:process.pid,token});break;}catch(error){if(error.code!=='EEXIST'||Date.now()-start>=budgetMs)throw new Error('progress.lock_unavailable');recover();await new Promise(resolve=>setTimeout(resolve,20));}
-  }
-  try{return await fn();}finally{if(read(join(path,'owner.json'))?.token===token)rmSync(path,{recursive:true,force:true});}
+function lock(dir,fn,{budgetMs=1500}={}) {
+  const lockPath=join(dir,'.allocation-lock');
+  return withDirectoryLock(lockPath,fn,{budgetMs,unavailable:()=>Object.assign(new Error('progress.lock_unavailable'),{lockPath})});
 }
 export async function persistProgressObservation(observation,{dir,now=()=>new Date(),historyLimit=32}={}) {
   mkdirSync(dir,{recursive:true,mode:0o700});
@@ -171,7 +144,7 @@ export async function observeProgress(args,continuation,{qaResult=null,packageVe
     if(remit.state==='failed')warn('[campaigns-os] Progress delivery pending; the local observation is retained. Lifecycle result is unchanged.');
     return {...remit,snapshot_id:snapshot.snapshot_id,reused};
   } catch(error) {
-    if(error?.message==='progress.lock_unavailable')warn('[campaigns-os] Progress allocation lock occupied; wait for the current writer. For abandoned or interrupted recovery, stop target writers and follow the offline lock recovery in docs/progress-snapshots.md. Lifecycle result is unchanged.');
+    if(error?.message==='progress.lock_unavailable')warn(`[campaigns-os] Progress allocation lock occupied${error.lockPath?` at ${error.lockPath}`:''}; wait for the current writer. If it stays occupied (an abandoned, ownerless or interrupted lock), stop all campaigns-os writers for this target, then remove that lock directory (docs/progress-snapshots.md). Lifecycle result is unchanged.`);
     else warn('[campaigns-os] Progress observation unavailable; lifecycle result is unchanged.');
     return {state:'failed',reason:'capture_unavailable'};
   }

package/src/proof-policy.mjs

@@ -4,7 +4,7 @@
 //
 // `qa.proof_policy.order_path_depth` is seeded by prepare-build/start and
 // mirrored into `report.proof_policy` at the same moment. The two are compared
-// by `assessPurchaseProofCoverage` (cli.mjs): a disagreement is `unknown`,
+// by `assessPurchaseProofCoverage` (src/doctor/next-step.mjs): a disagreement is `unknown`,
 // never one side's value. Doctor, `next` and the coverage reason all describe
 // that state through the single action below, so the command an operator is
 // told to run is spelled once. A leaf: gate-actions only.

package/src/qa-analytics-correctness.mjs

@@ -228,6 +228,9 @@ export function assessReceiptPurchase(receiptAnalytics = {}, options = {}) {
     receipts.push({
       plan_id: planId,
       receipt_url: redactUrlQuery(attempt.receiptUrl),
+      // The settled document location the receipt capture was read from
+      // (#500); null when it was not recorded.
+      receipt_document_url: redactUrlQuery(attempt.receiptDocumentUrl) || null,
       measured,
       scope: measured ? scope : null,
       purchase_fired: measured && !!effective.fired,

package/src/qa-binding-evidence.mjs

@@ -1,6 +1,7 @@
 import { parse as parseHtml } from 'parse5';
 import { parse as parseJs } from 'acorn';
 import { createPageSourceLoader, resolveCommercialApiKey } from './qa-commercial-parity.mjs';
+import { HTML_NAMESPACE, baseInEffect, documentBases, frozenBaseUrl, parseFailureDiagnostic, scriptKind } from './built-script-syntax.mjs';
 
 export const BINDING_SCHEMA = 'campaigns-os-page-binding/v0';
 export const BINDING_LIMITS = Object.freeze({ scripts_per_page: 6, scripts_per_run: 24, script_bytes: 262144, timeout_ms: 5000 });
@@ -55,12 +56,15 @@ function literalObject(node) {
   if (node?.type === 'ObjectExpression') return node.properties.every(p => p.type === 'Property' && !p.computed && p.kind === 'init' && !p.method && !p.shorthand && literalObject(p.value));
   return false;
 }
-function declarations(text) {
+function declarations(text, { module = false } = {}) {
   // Only whole, unconditional literal assignments are accepted. No evaluation,
   // constant propagation, getters, spreads, callbacks, aliases, or branch guesses.
+  // A script that does not parse is not dynamic: the browser throws on it and
+  // nothing in it runs. It is its own state, reported with its position (#480).
   let ast;
-  try { ast = parseJs(text, { ecmaVersion: 2022, sourceType: 'script' }); }
-  catch { return { values: [], dynamic: true }; }
+  try { ast = parseJs(text, { ecmaVersion: 'latest', sourceType: module ? 'module' : 'script', locations: true }); }
+  // The message is a fixed category: acorn echoes source text into some.
+  catch (error) { return { values: [], dynamic: false, unparsable: parseFailureDiagnostic(error) }; }
   const values = [];
   let dynamic = false;
   for (const statement of ast.body) {
@@ -78,7 +82,23 @@ function declarations(text) {
   return { values, dynamic };
 }
 
-export async function observeBinding({ source, page, expected, scriptLoader }) {
+// A path for a script, for findings: never a full URL, query or fragment. A
+// script served from another origin keeps its host, so same-named files on two
+// CDNs stay distinguishable.
+function scriptPath(src, pageUrl) {
+  try {
+    const url = new URL(src, pageUrl);
+    let pageOrigin = null;
+    try { pageOrigin = new URL(pageUrl).origin; } catch {}
+    return pageOrigin && url.origin !== pageOrigin ? `${url.host}${url.pathname}` : url.pathname;
+  } catch { return null; }
+}
+
+// `parseFailures`, when given, receives one record per page script that does
+// not parse ({ source_kind, script, line, column, message }). It is kept off
+// the page-binding evidence, whose shape is a closed contract; the caller
+// reports it as its own assertion.
+export async function observeBinding({ source, page, expected, scriptLoader, parseFailures = null }) {
   const kinds = new Set();
   const result = (outcome, reason) => ({ schema_version: BINDING_SCHEMA, observation: 'static_declaration',
     outcome, reason, source_kinds: [...kinds].sort(), identity: 'not_verified' });
@@ -94,33 +114,68 @@ export async function observeBinding({ source, page, expected, scriptLoader }) {
   const values = [];
   const scripts = [];
   let dynamic = false;
+  let bases = [];
   const walk = node => {
     const attrs = Object.fromEntries((node.attrs || []).map(a => [a.name, a.value]));
     if (node.tagName === 'base' || Object.entries(attrs).some(([name, value]) => /^on/i.test(name) || /^\s*javascript:/i.test(value))) dynamic = true;
     if (node.tagName === 'meta' && attrs.name === 'next-api-key') { values.push(attrs.content ?? ''); kinds.add('meta'); }
-    if (node.tagName === 'script') scripts.push({ attrs, text: (node.childNodes || []).map(n => n.value || '').join('') });
+    // Each script keeps the <base href> in effect when the parser prepares it
+    // at its end tag (see baseInEffect; #502).
+    // Only an HTML-namespace <script> loads `src`. An SVG script runs from
+    // href / xlink:href or its inline text, which this static read does not
+    // model: it is not fetched and leaves the binding dynamic.
+    if (node.tagName === 'script' && node.namespaceURI !== HTML_NAMESPACE) dynamic = true;
+    else if (node.tagName === 'script') scripts.push({ attrs, base: baseInEffect(bases, node), text: (node.childNodes || []).map(n => n.value || '').join('') });
     // parse5 keeps template content separate; it is inert, as is noscript at boot.
     if (node.tagName !== 'noscript') for (const child of node.childNodes || []) walk(child);
   };
-  try { walk(parseHtml(source.html)); } catch { return result('unknown', 'dynamic_unresolved'); }
+  try {
+    const document = parseHtml(source.html, { sourceCodeLocationInfo: true });
+    bases = documentBases(document);
+    walk(document);
+  } catch { return result('unknown', 'dynamic_unresolved'); }
+  // A script src resolves against the base in effect when the script is
+  // prepared: the frozen base URL of that <base href>, where a
+  // data:, javascript: or unparsable base falls back to the page URL (HTML
+  // "set the frozen base URL"), else the page URL. The loader still scopes
+  // the result to the page origin, so a cross-origin base leaves those
+  // scripts unavailable.
+  const scriptRef = (src, base) => { try { return new URL(src, frozenBaseUrl(base, pageUrl)).href; } catch { return null; } };
   let count = 0, unavailable = false;
   for (const script of scripts) {
     const { attrs } = script;
+    // Classified as the browser does (type trimmed of ASCII whitespace,
+    // case-insensitive). A module script ignores nomodule; a classic nomodule
+    // script is never fetched or run by a module-capable browser, so it cannot
+    // fail on load there: not fetched, not parsed, still not static.
+    const scriptType = scriptKind(attrs);
+    const { nomodule: _nomodule, ...withoutNomodule } = attrs;
+    const classicNomodule = scriptType === null && 'nomodule' in attrs && scriptKind(withoutNomodule) === 'classic';
     // Data-block types (e.g. JSON-LD) are not fetched and consume no config-request budget.
-    if (attrs.type && !['text/javascript', 'application/javascript', 'module'].includes(attrs.type.toLowerCase())) continue;
-    if (attrs.src && SDK.test(attrs.src)) continue;
+    if (scriptType === null && !classicNomodule) continue;
+    // Matched on the URL as the parser reads it (tab and newline removed,
+    // host case-folded), against the base in effect for this script.
+    if (attrs.src && SDK.test(scriptRef(attrs.src, script.base) ?? attrs.src)) continue;
+    if (classicNomodule) { dynamic = true; continue; }
     let text = script.text;
     let kind = 'inline';
     if (attrs.src) {
       kind = 'config_script';
       if (++count > BINDING_LIMITS.scripts_per_page) { unavailable = true; continue; }
-      const loaded = await scriptLoader(attrs.src, pageUrl);
+      const ref = script.base === null ? attrs.src : scriptRef(attrs.src, script.base);
+      const loaded = ref ? await scriptLoader(ref, pageUrl) : { ok: false };
       if (!loaded.ok) { unavailable = true; continue; }
       text = loaded.html;
     }
-    const found = declarations(text);
+    const found = declarations(text, { module: scriptType === 'module' });
+    if (found.unparsable) {
+      // The declarations in an unparsable script are unavailable, not dynamic.
+      unavailable = true;
+      if (Array.isArray(parseFailures)) parseFailures.push({ source_kind: kind, script: attrs.src ? scriptPath(scriptRef(attrs.src, script.base) ?? attrs.src, pageUrl) : null, ...found.unparsable });
+      continue;
+    }
     if (found.values.length) { kinds.add(kind); values.push(...found.values); }
-    if (found.dynamic || 'async' in attrs || 'nomodule' in attrs || attrs.type === 'module') dynamic = true;
+    if (found.dynamic || 'async' in attrs || scriptType === 'module') dynamic = true;
   }
   if (new Set(values).size > 1) return result('unknown', 'conflicting_declarations');
   if (expected?.conflict) return result('unknown', 'conflicting_expected');
@@ -138,3 +193,13 @@ export function bindingAssertion(page, evidence) {
     ...(evidence.outcome === 'match' ? {} : { severity: evidence.outcome === 'mismatch' ? 'blocker' : 'warn' }),
     expected: 'expected credential declaration', actual: evidence.outcome, evidence };
 }
+
+// A page script that does not parse throws a SyntaxError on every load (#480).
+// One blocker per page, naming each script and the parse position.
+export function scriptParseAssertion(page, failures) {
+  if (!Array.isArray(failures) || failures.length === 0) return null;
+  const where = failures.map(f => `${f.script || 'inline script'}:${f.line}:${f.column}`).join(', ');
+  return { id: `script-parse:${page.page_id}`, family: 'api-metadata', page: page.page_id, status: 'fail', severity: 'blocker',
+    expected: 'every page script parses', actual: `unparsable: ${where}`,
+    evidence: { observation: 'static_parse', scripts: failures.map(f => ({ source_kind: f.source_kind, script: f.script, line: f.line, column: f.column, message: f.message })) } };
+}