@nextcommerce/campaigns-os 1.55.0 → 1.59.0

package/src/input-refresh.mjs

@@ -26,7 +26,7 @@ import {
   loadCampaignBuildBriefFile,
 } from "./build-brief.mjs";
 import { resolveCampaignWorkspace, targetRepoFor } from "./campaign-workspace.mjs";
-import { isObject, optionalString, relFromDir, resolveFromFile } from "./cli-helpers.mjs";
+import { isObject, optionalString, portableArtifactPaths, relFromDir, resolveFromFile } from "./cli-helpers.mjs";
 import { writeJsonAtomic } from "./doctor-sidecar.mjs";
 import { activeSpecPages, specIdentityMismatch } from "./doctor/checks.mjs";
 import {
@@ -475,9 +475,9 @@ function saveBriefUnderLock({ packetPath, explicitBrief, sidecars, lockedTarget,
     if (!dryRun) {
       // Intake's publication order, the report last: a failure between files
       // leaves the report bound to the old material, which reads as owed.
-      writeJsonAtomic(packetPath, nextPacket);
-      writeJsonAtomic(normalizedPath, buildBrief.artifact);
-      writeJsonAtomic(contextPath, saved.nextContext);
+      writeJsonAtomic(packetPath, portableArtifactPaths(nextPacket, targetRepo, { artifactPath: packetPath }));
+      writeJsonAtomic(normalizedPath, portableArtifactPaths(buildBrief.artifact, targetRepo, { artifactPath: normalizedPath }));
+      writeJsonAtomic(contextPath, portableArtifactPaths(saved.nextContext, targetRepo, { artifactPath: contextPath }));
       commitAssemblyReport(workspace, () => nextReport, {
         command: "record brief",
         staleReason: "The Campaign Build Brief was saved after this doctor snapshot. Re-run doctor (or next) for current state.",
@@ -674,8 +674,8 @@ function refreshSpecUnderLock({ packetPath, sidecars, lockedTarget, dryRun, time
     if (!dryRun) {
       // Intake's publication order, the report last: a failure between files
       // leaves the report bound to the old spec material, which reads as owed.
-      if (briefWritten) writeJsonAtomic(normalizedPath, brief.buildBrief.artifact);
-      writeJsonAtomic(contextPath, nextContext);
+      if (briefWritten) writeJsonAtomic(normalizedPath, portableArtifactPaths(brief.buildBrief.artifact, targetRepo, { artifactPath: normalizedPath }));
+      writeJsonAtomic(contextPath, portableArtifactPaths(nextContext, targetRepo, { artifactPath: contextPath }));
       commitAssemblyReport(workspace, () => nextReport, {
         command: "record spec",
         staleReason: "The CampaignSpec was bound with record spec after this doctor snapshot. Re-run doctor (or next) for current state.",

package/src/local-preview-policy.mjs

@@ -1,5 +1,5 @@
-// The local preview policy: one place that decides which missing evidence a
-// localhost preview carries forward as a warning instead of a blocker.
+// Preview policy: one place that decides which missing evidence a preview
+// carries forward as a warning instead of a blocker.
 //
 // The local preview is a packet whose deploy target is `local-serve`, served
 // from a loopback host. There a campaign must still prove its commerce (store
@@ -8,16 +8,20 @@
 // evidence is reported as missing, never as passed: a carried-forward gate is
 // a warning in doctor, `next` does not stop on it, and QA records it as a
 // `warn` row, so the verdict is at best `ready_with_exceptions`. A hosted
-// preview or production packet never takes this path, and every check not
-// named below keeps its meaning on every path.
+// preview carries forward only the all-template no-capturable-routes
+// shape and the missing Polish report/evidence it owns. QA against the
+// packet's production URL stays strict. Every other check keeps its meaning.
 //
 // Doctor and QA apply this to the gates they evaluate; `next` reads doctor's
 // gates. Recording a stage (`record polish`) and the waiver commands keep the
 // strict gates; `record deploy` follows next past a carried-forward polish.
 import { isLocalServePacket } from "./local-proof.mjs";
 import { isLoopbackHostname } from "./remit.mjs";
+import { hostedTemplateQaAction, HOSTED_TEMPLATE_PREVIEW_URL_ACTION } from "./gate-actions.mjs";
+import { normalizePublicRouteSlug } from "./route-identity.mjs";
 
 export const LOCAL_PREVIEW_POLICY = "local_preview";
+export const HOSTED_TEMPLATE_PREVIEW_POLICY = "hosted_template_preview";
 export const CARRIED_FORWARD = "carried_forward";
 
 // The checks carried forward, one by one. Each is evidence the campaign does
@@ -30,6 +34,9 @@ const CARRIED_POLISH_CODES = Object.freeze(new Set([
   "polish.report_missing",
   "polish.evidence_missing",
 ]));
+export function polishGateCanCarryPreview(gate) {
+  return Boolean(gate?.owned_checkpoint_only || CARRIED_POLISH_CODES.has(gate?.code));
+}
 export const NO_CAPTURABLE_ROUTES_CODE = "polish.hidden_eager_media.no_capturable_routes";
 const MISSING_CAPTURE_CODE = "polish.hidden_eager_media.capture_malformed";
 
@@ -53,21 +60,96 @@ export function isLocalPreview(packet, { baseUrl = null } = {}) {
     && loopbackOrAbsent(baseUrl);
 }
 
+function comparableUrl(value) {
+  try {
+    const url = new URL(String(value));
+    if (!/^https?:$/.test(url.protocol)) return null;
+    return `${url.origin}${url.pathname.replace(/\/+$/, "") || "/"}`;
+  } catch {
+    return null;
+  }
+}
+
+export function ensureUrlTrailingSlash(value) {
+  try {
+    const url = new URL(value);
+    if (!url.pathname.endsWith("/")) url.pathname += "/";
+    return url.toString();
+  } catch {
+    return value.endsWith("/") ? value : `${value}/`;
+  }
+}
+
+// QA composes a campaign slug onto a site root before testing it. Preview
+// policy compares those same targets, ignoring only query and fragment.
+export function normalizeQaBaseUrl(value, publicRouteSlug) {
+  const baseUrl = typeof value === "string" && value.trim() ? value.trim() : null;
+  if (!baseUrl) return null;
+  const slug = normalizePublicRouteSlug(publicRouteSlug);
+  if (!slug) return ensureUrlTrailingSlash(baseUrl);
+  try {
+    const url = new URL(ensureUrlTrailingSlash(baseUrl));
+    const segments = url.pathname.split("/").filter(Boolean);
+    if (segments.at(-1) === slug) return ensureUrlTrailingSlash(url.toString());
+    return new URL(`${slug}/`, url).toString();
+  } catch {
+    return ensureUrlTrailingSlash(baseUrl);
+  }
+}
+
+function comparableQaTarget(value, packet) {
+  const slug = packet?.campaign?.public_route_slug || packet?.deploy?.live_url_path;
+  return comparableUrl(normalizeQaBaseUrl(value, slug));
+}
+
+function isHostedTemplatePreview(packet, { baseUrl = null } = {}) {
+  const preview = comparableQaTarget(packet?.deploy?.preview_url, packet);
+  const production = comparableQaTarget(packet?.deploy?.production_url, packet);
+  const tested = baseUrl == null ? preview : comparableQaTarget(baseUrl, packet);
+  return Boolean(packet?.deploy?.target && packet.deploy.target !== "local-serve"
+    && preview && tested === preview && preview !== production
+    && !isLoopbackHostname(new URL(preview).hostname));
+}
+
+export function hostedTemplateNeedsUsablePreview(packet, gate) {
+  return gate?.code === NO_CAPTURABLE_ROUTES_CODE
+    && packet?.deploy?.target && packet.deploy.target !== "local-serve"
+    && !isHostedTemplatePreview(packet);
+}
+
+export function hostedTemplateNeedsPreviewUrl(packet, gate) {
+  return gate?.code === NO_CAPTURABLE_ROUTES_CODE
+    && packet?.deploy?.target && packet.deploy.target !== "local-serve"
+    && !packet.deploy.preview_url;
+}
+
 function pageLoadRecorded(report) {
   return report?.stages?.polish?.evidence?.visual_review?.page_load != null;
 }
 
-function carried(gate) {
+export function carried(gate, policy = LOCAL_PREVIEW_POLICY, packet = null) {
+  const previewUrl = packet?.deploy?.preview_url;
+  if (policy === HOSTED_TEMPLATE_PREVIEW_POLICY && !comparableUrl(previewUrl)) return gate;
   return {
     ...gate,
     status: CARRIED_FORWARD,
-    carried_forward: { policy: LOCAL_PREVIEW_POLICY, from_status: gate.status, evidence: "missing" },
+    ...(policy === HOSTED_TEMPLATE_PREVIEW_POLICY
+      ? { required_actions: [hostedTemplateQaAction(previewUrl)] }
+      : {}),
+    carried_forward: { policy, from_status: gate.status, evidence: "missing" },
   };
 }
 
 // The hidden eager-media checkpoint, evaluated on its own.
 export function applyLocalPreviewToCheckpoint(gate, { packet, report, baseUrl = null } = {}) {
-  if (gate?.status !== "blocked" || !isLocalPreview(packet, { baseUrl })) return gate;
+  if (gate?.status !== "blocked") return gate;
+  if (hostedTemplateNeedsUsablePreview(packet, gate)) {
+    return { ...gate, required_actions: [HOSTED_TEMPLATE_PREVIEW_URL_ACTION] };
+  }
+  if (gate.code === NO_CAPTURABLE_ROUTES_CODE && isHostedTemplatePreview(packet, { baseUrl })) {
+    return carried(gate, HOSTED_TEMPLATE_PREVIEW_POLICY, packet);
+  }
+  if (!isLocalPreview(packet, { baseUrl })) return gate;
   const missing = gate.code === NO_CAPTURABLE_ROUTES_CODE
     || (gate.code === MISSING_CAPTURE_CODE && !pageLoadRecorded(report));
   return missing ? carried(gate) : gate;
@@ -82,11 +164,24 @@ export function polishCarriedForwardForLadder(report, gate) {
 }
 
 export function applyLocalPreviewToPolishGate(gate, { packet, checkpointGate = null, baseUrl = null } = {}) {
-  if (gate?.status !== "blocked" || !isLocalPreview(packet, { baseUrl })) return gate;
+  if (gate?.status !== "blocked") return gate;
+  // A template-stock map has no route that capture can measure, even when
+  // the preview is strict. Do not keep an impossible recapture action.
+  const actionableGate = checkpointGate?.code === NO_CAPTURABLE_ROUTES_CODE
+    ? { ...gate, required_actions: (gate.required_actions || []).filter((action) => action.id !== "polish.hidden_eager_media.capture") }
+    : gate;
+  if (polishGateCanCarryPreview(gate) && hostedTemplateNeedsUsablePreview(packet, checkpointGate)) {
+    return { ...actionableGate, required_actions: [HOSTED_TEMPLATE_PREVIEW_URL_ACTION] };
+  }
+  const hostedTemplate = checkpointGate?.code === NO_CAPTURABLE_ROUTES_CODE
+    && checkpointGate?.carried_forward?.policy === HOSTED_TEMPLATE_PREVIEW_POLICY
+    && isHostedTemplatePreview(packet, { baseUrl });
+  if (!hostedTemplate && !isLocalPreview(packet, { baseUrl })) return actionableGate;
   const checkpointCarried = checkpointGate?.status === CARRIED_FORWARD;
-  if (gate.owned_checkpoint_status === "blocked" && !checkpointCarried) return gate;
-  if (gate.owned_checkpoint_only) return checkpointCarried ? carried(gate) : gate;
-  return CARRIED_POLISH_CODES.has(gate.code) ? carried(gate) : gate;
+  if (gate.owned_checkpoint_status === "blocked" && !checkpointCarried) return actionableGate;
+  const policy = hostedTemplate ? HOSTED_TEMPLATE_PREVIEW_POLICY : LOCAL_PREVIEW_POLICY;
+  if (gate.owned_checkpoint_only) return checkpointCarried ? carried(actionableGate, policy, packet) : actionableGate;
+  return CARRIED_POLISH_CODES.has(gate.code) ? carried(actionableGate, policy, packet) : actionableGate;
 }
 
 export function starterResidueIsExpected(themeGate, { packet, baseUrl = null } = {}) {
@@ -94,5 +189,8 @@ export function starterResidueIsExpected(themeGate, { packet, baseUrl = null } =
 }
 
 export function carriedForwardMessage(gate) {
-  return `Carried forward on the local preview: ${gate.reason} This evidence is missing, not passed; a hosted preview or production run requires it.`;
+  if (gate?.carried_forward?.policy === HOSTED_TEMPLATE_PREVIEW_POLICY) {
+    return `Carried forward on the hosted preview: ${gate.reason} This evidence is missing, not passed; production QA still requires it.`;
+  }
+  return `Carried forward on the local preview: ${gate.reason} This evidence is missing, not passed; production QA still requires it.`;
 }

package/src/polish-node.mjs

@@ -3,7 +3,7 @@ import { NO_CAPTURABLE_ROUTES_CODE } from "./local-preview-policy.mjs";
 import { createHash } from "node:crypto";
 import { HIDDEN_EAGER_MEDIA_ACTIONS } from "./gate-actions.mjs";
 import { dirname, join, resolve } from "node:path";
-import { computeBuildFingerprint } from "./built-site-scope.mjs";
+import { computeBuildFingerprint, describeBuildOutputDrift } from "./built-site-scope.mjs";
 import {
   buildPageLoadCapture,
   MAX_POLISH_CAPTURE_URL_LENGTH,
@@ -160,7 +160,7 @@ export function planPolishCapture({ packet, baseUrl } = {}) {
   if (routes.length === 0) {
     const error = new Error(
       "polish capture has no mapped non-skipped routes to capture: every mapped page is template stock (skip_reason), so there is no design route to compare."
-      + " On a local-serve preview, missing polish evidence is carried forward as a warning; run `next` for the next stage.",
+      + " On a local or hosted preview, missing polish evidence is carried forward as a warning; run `next` for the next stage.",
     );
     error.code = NO_CAPTURABLE_ROUTES_ERROR;
     throw error;
@@ -226,13 +226,13 @@ function recordedAuthorityBlock({ packet, report, plan = null, now } = {}) {
 
 // Every mapped page is template stock: there is nothing for polish capture to
 // measure, which is missing evidence rather than a malformed packet. It stays
-// a non-waivable block; the local preview policy carries it forward.
+// a non-waivable block; the preview policy carries it forward.
 function noCapturableRoutesBlock({ packet, report, now } = {}) {
   const block = recordedAuthorityBlock({ packet, report, now });
   return {
     ...block,
     code: NO_CAPTURABLE_ROUTES_CODE,
-    reason: "Every mapped page is template stock (skip_reason), so polish capture has no design route to capture and this build has no page-load evidence.",
+    reason: "Every mapped page is template stock (skip_reason), so this build has no design route to compare and no page-load evidence.",
     required_actions: [HIDDEN_EAGER_MEDIA_ACTIONS.map_design_route],
   };
 }
@@ -402,7 +402,7 @@ export function createPolishCaptureBinding({ packet, report, plan, packetPath, t
   // an output that has drifted from what build recorded would be evidence
   // about a build that no longer exists, and an output that changes during the
   // browser pass fails the unchanged-binding assertion after it.
-  const outputFingerprint = boundOutputFingerprint(join(resolve(targetRepo), "_site", slug), slug, buildFingerprint);
+  const outputFingerprint = boundOutputFingerprint(join(resolve(targetRepo), "_site", slug), slug, buildFingerprint, report.stages.assembly);
   const runId = nonemptyString(report.run_id);
   const reportPacketPath = nonemptyString(report?.inputs?.packet_path);
   if (!runId || !reportPacketPath) {
@@ -585,7 +585,7 @@ function uncapturedPages(packet, plan) {
 // (permissions, a file vanishing mid-walk), or an output that no longer
 // matches what build recorded. None of them may surface as an uncaught
 // filesystem error, and none may bind as a null.
-function boundOutputFingerprint(outputRoot, slug, buildFingerprint) {
+function boundOutputFingerprint(outputRoot, slug, buildFingerprint, assembly = null) {
   let current;
   try {
     current = computeBuildFingerprint(outputRoot);
@@ -604,7 +604,8 @@ function boundOutputFingerprint(outputRoot, slug, buildFingerprint) {
   if (current.fingerprint !== buildFingerprint) {
     throw new Error(
       `polish capture refuses: built output under _site/${slug}/ no longer matches stages.assembly.build_fingerprint `
-      + `(recorded ${buildFingerprint}, current ${current.fingerprint}). Re-run build and record the current fingerprint first.`,
+      + `(recorded ${buildFingerprint}, current ${current.fingerprint}). ${describeBuildOutputDrift(assembly, current).summary} `
+      + "Re-run build and record the current fingerprint first.",
     );
   }
   return current.fingerprint;