@nextcommerce/campaigns-os 1.54.0 → 1.57.0

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;
@@ -75,12 +157,31 @@ export function applyLocalPreviewToCheckpoint(gate, { packet, report, baseUrl =
 
 // The polish gate folds the checkpoint in, so it is carried forward only when
 // whatever it owns from the checkpoint was carried forward too.
+export function polishCarriedForwardForLadder(report, gate) {
+  return gate?.status === CARRIED_FORWARD
+    && !report?.theme?.waiver
+    && !report?.stages?.polish?.evidence?.visual_review?.page_load;
+}
+
 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 } = {}) {
@@ -88,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/login.mjs

@@ -1,4 +1,5 @@
 import { createCredentialStore } from './credential-store.mjs';
+import { timeOperatorWait } from './lifecycle.mjs';
 
 export const GATEWAY = 'https://mcp.nextcommerce.com';
 export const CLIENT_ID = 'campaigns-os-owned-store-pilot';
@@ -27,7 +28,7 @@ export function authenticationArguments(argv) {
 async function askStore() {
   const { createInterface } = await import('node:readline/promises');
   const prompt = createInterface({ input: process.stdin, output: process.stdout });
-  try { return await prompt.question('Store subdomain (or network domain): '); }
+  try { return await timeOperatorWait(() => prompt.question('Store subdomain (or network domain): ')); }
   finally { prompt.close(); }
 }
 const bindingFor = store => ({ gateway: GATEWAY, client_id: CLIENT_ID, store });

package/src/polish-browser.mjs

@@ -1012,6 +1012,10 @@ function polishBrowserMissing(kind, error) {
     ].join(" "));
 }
 
+// `networkIdleTimeoutMs`, like the deadlines, can only shorten its bound: the
+// wait for network idle after each navigation (NETWORKIDLE_TIMEOUT_MS). The
+// CLI never passes it; a test whose page holds a transfer open passes a
+// shorter window rather than wait out the production one on every cell.
 export async function createPolishBrowserAdapter({
   headed = false,
   authCookie = null,
@@ -1019,6 +1023,7 @@ export async function createPolishBrowserAdapter({
   cellDeadlineMs,
   cleanupDeadlineMs,
   startupDeadlineMs,
+  networkIdleTimeoutMs,
 } = {}) {
   const authCookies = parseAuthCookie(authCookie);
   const boundedCellDeadlineMs = boundedPolishDeadline(cellDeadlineMs, POLISH_BROWSER_CELL_DEADLINE_MS);
@@ -1030,6 +1035,7 @@ export async function createPolishBrowserAdapter({
     startupDeadlineMs,
     POLISH_BROWSER_STARTUP_DEADLINE_MS,
   );
+  const networkIdleMs = boundedPolishDeadline(networkIdleTimeoutMs, NETWORKIDLE_TIMEOUT_MS);
   let browser;
   let startupTimedOut = false;
   const startupAbort = new AbortController();
@@ -1234,7 +1240,7 @@ export async function createPolishBrowserAdapter({
         const initialMediaElements = await awaitActive(collectMediaElements(page));
         let networkidle;
         try {
-          await awaitActive(page.waitForLoadState("networkidle", { timeout: NETWORKIDLE_TIMEOUT_MS }));
+          await awaitActive(page.waitForLoadState("networkidle", { timeout: networkIdleMs }));
           networkidle = { status: "settled", duration_ms: durationSince(navigationStartedAt) };
         } catch (error) {
           if (!timeoutError(error)) throw error;
@@ -1327,7 +1333,7 @@ export async function createPolishBrowserAdapter({
           if (initialTree === BOUND_ENDED) return unmeasured(boundEnded());
           if (initialTree.error) return unmeasured("document_changed");
           const initialMainFrame = initialTree.value?.frameTree?.frame;
-          const idleTimeout = Math.max(1, Math.min(NETWORKIDLE_TIMEOUT_MS, Math.floor(addedLeft()), Math.floor(cellLeftMs())));
+          const idleTimeout = Math.max(1, Math.min(networkIdleMs, Math.floor(addedLeft()), Math.floor(cellLeftMs())));
           const idle = await awaitActive(steps.step(() => page.waitForLoadState("networkidle", { timeout: idleTimeout })));
           if (idle === BOUND_ENDED) return unmeasured(boundEnded());
           if (idle.error && !timeoutError(idle.error)) throw idle.error;

package/src/polish-node.mjs

@@ -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],
   };
 }
@@ -669,6 +669,7 @@ async function runPolishCapture({
   captureCellDeadlineMs,
   adapterCloseDeadlineMs,
   probeClock = null,
+  mediaProbeRunBudgetMs,
   targetRepo = null,
   now = new Date(),
 } = {}) {
@@ -687,6 +688,10 @@ async function runPolishCapture({
     adapterCloseDeadlineMs,
     POLISH_CAPTURE_CLOSE_DEADLINE_MS,
   );
+  // The 1.3 image probe's run budget. Like the deadlines it can only shorten:
+  // the CLI never passes it, and a test that spends the budget passes a
+  // smaller one so that fewer slow cells spend it.
+  const probeRunBudgetMs = boundedPolishDeadline(mediaProbeRunBudgetMs, MEDIA_PROBE_LIMITS.runBudgetMs);
 
   let adapter = null;
   // Failure is tracked apart from its reason: a rejection may carry any value,
@@ -806,7 +811,7 @@ async function runPolishCapture({
           const abortController = new AbortController();
           const imageProbe = {
             ...(isProbeClock(probeClock) ? { clock: probeClock } : {}),
-            remainingMs: MEDIA_PROBE_LIMITS.runBudgetMs - probeSpentMs,
+            remainingMs: probeRunBudgetMs - probeSpentMs,
             cellBoundMs: MEDIA_PROBE_LIMITS.cellBoundMs,
             imageCap: MEDIA_PROBE_LIMITS.imageCap,
           };

package/src/polish-readability.mjs

@@ -433,8 +433,8 @@ export function readabilityProbe(toolkit, limits, closedRoots, generatedText) {
   // ancestor matches. checkout_label and checkout_hint are read separately.
   const ROLES = [
     ["add_to_cart", "[data-next-action=\"add-to-cart\"]"],
-    ["upsell_accept", "[data-next-upsell-action=\"add\"]"],
-    ["upsell_decline", "[data-next-upsell-action=\"skip\"]"],
+    ["upsell_accept", "[data-next-upsell-action=\"add\"], [data-next-upsell-action=\"accept\"]"],
+    ["upsell_decline", "[data-next-upsell-action=\"skip\"], [data-next-upsell-action=\"decline\"]"],
     ["submit_control", "button.submit-button[os-checkout-payment=\"combo\"], button[os-checkout-payment=\"combo\"], button[type=\"submit\"], input[type=\"submit\"], input[type=\"button\"]"],
     ["sdk_action", "[data-next-action]"],
     ["bundle_card", "[data-next-bundle-card], [data-next-selector-card], [data-next-package-id], [data-next-bundle-id]"],