@nextcommerce/campaigns-os 1.37.2 → 1.41.2

package/src/qa-node.mjs

@@ -60,6 +60,10 @@ import {
 import { resolveConsent } from "./consent.mjs";
 import { markDoctorSidecarStale } from "./doctor-sidecar.mjs";
 import { commitAssemblyReport } from "./stage-ledger.mjs";
+// Tags a refusal raised before a qa handler runs, so the CLI's lifecycle
+// persist step suppresses the journal append from one place. lifecycle.mjs
+// imports nothing from this repository, so this cannot be circular.
+import { refused, refusing } from "./lifecycle.mjs";
 import { campaignSidecarPaths, explicitReportPath, resolveCampaignWorkspace, targetRepoFor } from "./campaign-workspace.mjs";
 import { loadParityFixture } from "./qa-parity-fixture.mjs";
 import { assessParityCapture, resolveParityScenario, runParityCapture } from "./qa-parity-capture.mjs";
@@ -99,7 +103,7 @@ Usage:
   campaigns-os qa policy set --packet <campaign-runtime.build.json> [--allowed-domains-confirmed true|false] [--deploy-target <target>] [--preview-url <url>] [--production-url <url>] [--order-path-depth <off|common|full>] [--json]
   campaigns-os qa waive --packet <campaign-runtime.build.json> --assertion analytics-correctness:purchase-fires --reason "<why>" [--waived-by <who>] [--report <assembly-report.json>] [--json]
   campaigns-os qa promote --packet <campaign-runtime.build.json> --verdict <full-verdict.json> [--json]   # project one explicit qa-output verdict to the committed .campaign-runtime/qa-verdict.json sidecar
-  campaigns-os qa publish --packet <campaign-runtime.build.json> [--verdict <full-verdict.json>] [--republish] [--proxy-base <url>] [--json]   # post an already-stored verdict to the QA portal; no re-run, no orders
+  campaigns-os qa publish --packet <campaign-runtime.build.json> [--verdict <full-verdict.json>] [--republish] [--proxy-base <url>] [--dry-run] [--json]   # post an already-stored verdict to the QA portal; no re-run, no orders
   campaigns-os qa resolve <map-id> --spec <campaign-spec.json> [--base-url <url>]
   campaigns-os qa run <map-id> --spec <campaign-spec.json> --base-url <url>
   campaigns-os qa run --site <page-kit-target-repo> --base-url <url> --family <family> [--slug <slug>] [--browser]   # L7: QA a built _site/ with no packet/spec
@@ -146,6 +150,10 @@ Options:
                                   per the Run Record (already_published), an untrusted one, or one for another
                                   campaign. Exit 2 on a refusal, 1 on a failed post, 0 when published.
   --republish                     qa publish: post a verdict its Run Record already records as published.
+  --dry-run                       qa publish: run every refusal check and print what would be posted (endpoint,
+                                  verdict run id, payload bytes) without the POST. Nothing is sent and the Run
+                                  Record is not stamped; a refusal still exits 2, a clean dry run exits 0
+                                  (--json: dry_run, would_publish, would_post).
   --no-remit                     When an ambient run session is active, write the local Run Record but skip Run Telemetry remit.
   --auth-cookie <cookie>          Cookie header for protected previews.
   --browser                       Run Playwright-rendered browser checks after static Node checks.
@@ -250,7 +258,7 @@ export async function runQaCli(args, { ambient = null } = {}) {
     return result;
   }
   if (subcommand === "policy") {
-    if (args._[2] !== "set") throw new Error(`Unknown qa policy command. Use: ${cmd("qa")} policy set --packet <campaign-runtime.build.json>`);
+    if (args._[2] !== "set") throw refused(`Unknown qa policy command. Use: ${cmd("qa")} policy set --packet <campaign-runtime.build.json>`);
     const result = updateQaPolicy(args);
     output(result, args);
     return result;
@@ -281,7 +289,7 @@ export async function runQaCli(args, { ambient = null } = {}) {
     process.exitCode = result.ok ? 0 : 1;
     return result;
   }
-  throw new Error(`Unknown qa command: ${subcommand}`);
+  throw refused(`Unknown qa command: ${subcommand}`);
 }
 
 // The package-owned browser install, runnable from any install mode. It is
@@ -338,7 +346,7 @@ async function resolveQaInputs(args, {
   loadCampaignEntry = loadPageKitCampaignEntry,
 } = {}) {
   if (args.packet && args.spec) {
-    throw new Error("Packet QA does not accept --spec; it always uses packet.spec.local_path.");
+    throw refused("Packet QA does not accept --spec; it always uses packet.spec.local_path.");
   }
   // Non-packet mode (learnings L7): QA a `campaign-build`'d page-kit campaign
   // that has only a built _site/ and a served URL — no Build Packet, no Map ID,
@@ -363,7 +371,15 @@ async function resolveQaInputs(args, {
   const mapId = stringArg(args["map-id"])
     || stringArg(args._[2])
     || stringArg(packet?.spec?.map_id);
-  if (!mapId) throw new Error("QA requires a Map ID. Provide --packet or positional <map-id>.");
+  // A refusal to identify a campaign, not a failure to QA one: with no
+  // --packet, no --site/--built and no positional <map-id>, every read above
+  // was skipped and `qa run` has nothing to work on. Tagged on both paths, not
+  // just the empty one — the journal question is whether the CLI reached a
+  // handler's WORK, and a missing-identity refusal decides that before any
+  // spec is fetched, any browser launches and anything is written. (When a
+  // packet WAS named, it has been read by here; the packet read is a lookup
+  // for the same identity question, and one message cannot be two verdicts.)
+  if (!mapId) throw refused("QA requires a Map ID. Provide --packet or positional <map-id>.");
 
   const proxyBase = stringArg(args["proxy-base"]) || DEFAULT_PROXY_BASE;
   const inputBaseUrl = normalizeBaseUrl(stringArg(args["base-url"]) || packet?.deploy?.preview_url || packet?.deploy?.production_url || null);
@@ -1726,7 +1742,7 @@ const REMOVED_QA_POLICY_FLAGS = ["test-orders-allowed", "sandbox-test-card-confi
 
 function updateQaPolicy(args) {
   const packetPath = args.packet ? resolve(args.packet) : null;
-  if (!packetPath) throw new Error("qa policy set requires --packet <campaign-runtime.build.json>.");
+  if (!packetPath) throw refused("qa policy set requires --packet <campaign-runtime.build.json>.");
   const packet = readJson(packetPath);
   packet.campaign ||= {};
   packet.deploy ||= {};
@@ -1735,12 +1751,15 @@ function updateQaPolicy(args) {
   // Test Orders have no permission flag. The two flags that once set one
   // were removed with their packet fields in supported surface 1.28.0; a
   // script still passing them gets told so instead of a silent no-op.
+  // This check and the setOptional* value checks below run after reading only
+  // the packet and before the packet write: refusals, so they journal nothing.
   const removedFlags = REMOVED_QA_POLICY_FLAGS.filter((flag) => flag in args);
   if (removedFlags.length) {
-    throw new Error(`qa policy set: ${removedFlags.map((flag) => `--${flag}`).join(" and ")} ${removedFlags.length > 1 ? "were" : "was"} removed in supported surface 1.28.0 (test orders run from --test-order <mode> alone; there is no permission flag). Drop the flag${removedFlags.length > 1 ? "s" : ""}. Accepted: --allowed-domains-confirmed, --deploy-target, --preview-url, --production-url, --order-path-depth.`);
+    throw refused(`qa policy set: ${removedFlags.map((flag) => `--${flag}`).join(" and ")} ${removedFlags.length > 1 ? "were" : "was"} removed in supported surface 1.28.0 (test orders run from --test-order <mode> alone; there is no permission flag). Drop the flag${removedFlags.length > 1 ? "s" : ""}. Accepted: --allowed-domains-confirmed, --deploy-target, --preview-url, --production-url, --order-path-depth.`);
   }
-  // Validated with the other argv checks, before anything is written.
-  const orderPathDepth = parseOrderPathDepthFlag(args, { command: "qa policy set" });
+  // Validated with the other argv checks, before anything is written: a
+  // refusal at this call site, like the removed-flag check above.
+  const orderPathDepth = refusing(() => parseOrderPathDepthFlag(args, { command: "qa policy set" }));
 
   const changed = [];
   setOptionalBoolean(packet.campaign, "allowed_domains_confirmed", args, "allowed-domains-confirmed", changed);
@@ -1810,21 +1829,24 @@ const WAIVABLE_QA_ASSERTIONS = Object.freeze(["analytics-correctness:purchase-fi
 // report.theme.waiver: { reason, waived_by, waived_at }.
 export function qaWaive(args) {
   const packetPath = args.packet ? resolve(args.packet) : null;
-  if (!packetPath) throw new Error("qa waive requires --packet <campaign-runtime.build.json>.");
+  if (!packetPath) throw refused("qa waive requires --packet <campaign-runtime.build.json>.");
   const packet = readJson(packetPath);
+  // The three flag checks run after reading only argv and the packet, ahead of
+  // the report lookup: refusals, so they journal nothing. The missing report
+  // below is a handler failure and is journaled.
   const assertionId = stringArg(args.assertion);
   if (!assertionId) {
-    throw new Error(`qa waive requires --assertion <id>. Waivable assertions: ${WAIVABLE_QA_ASSERTIONS.join(", ")}.`);
+    throw refused(`qa waive requires --assertion <id>. Waivable assertions: ${WAIVABLE_QA_ASSERTIONS.join(", ")}.`);
   }
   if (!WAIVABLE_QA_ASSERTIONS.includes(assertionId)) {
-    throw new Error(
+    throw refused(
       `qa waive does not accept --assertion "${assertionId}". The waiver lane is scoped to exactly: ${WAIVABLE_QA_ASSERTIONS.join(", ")}. `
       + "Extending the lane to another assertion is a design decision, not a flag.",
     );
   }
   const reason = stringArg(args.reason);
   if (!reason) {
-    throw new Error("qa waive requires --reason \"<why this failing blocker is acceptable for this campaign>\".");
+    throw refused("qa waive requires --reason \"<why this failing blocker is acceptable for this campaign>\".");
   }
   const workspace = resolveCampaignWorkspace(packetPath, {
     packet,
@@ -1998,15 +2020,25 @@ function parityReplayEvidence(bundle) {
   return { order, capture, baselineCapture, orders: Array.isArray(bundle.orders) ? bundle.orders : [order] };
 }
 
+// The up-front half of the `--max-order-creations` check. The validator is
+// SHARED with the order-creation budget, which every browser path builds after
+// a browser has launched and orders may already have been created; a throw from
+// there is a handler failure and must still be journaled, so the refusal tag
+// cannot live inside the validator. It goes here via `refusing()`, at the two
+// entries that check the flag before anything is resolved or launched, where a
+// bad value has cost the operator nothing. Message and exit code are the
+// validator's own.
+const refuseBadOrderCreationLimit = (args) => refusing(() => validatedOrderCreationLimit(args));
+
 async function runParityQa(args) {
   // Checked here as well as on the budget itself: the budget is built after a
   // browser has launched, and a flag the operator typed wrong should cost them
   // nothing. The budget stays the authority — this is fail-fast, not the gate.
-  validatedOrderCreationLimit(args);
+  refuseBadOrderCreationLimit(args);
   const fixturePath = stringArg(args.fixture);
   const scenarioId = stringArg(args.scenario) || stringArg(args._[2]);
-  if (!fixturePath) throw new Error("QA parity requires --fixture <parity-fixture.json>.");
-  if (!scenarioId) throw new Error("QA parity requires --scenario <scenario-id>.");
+  if (!fixturePath) throw refused("QA parity requires --fixture <parity-fixture.json>.");
+  if (!scenarioId) throw refused("QA parity requires --scenario <scenario-id>.");
 
   const fixture = await loadParityFixture(resolve(fixturePath));
   const scenario = resolveParityScenario(fixture, scenarioId);
@@ -2072,7 +2104,7 @@ async function runParityQa(args) {
 async function runQa(args, options = {}) {
   // Fail-fast before anything resolves or launches. The authoritative check
   // lives on the creation budget itself, which every browser path builds.
-  validatedOrderCreationLimit(args);
+  refuseBadOrderCreationLimit(args);
   const resolved = await resolveQaInputs(args);
   return runResolvedQa(args, resolved, options);
 }
@@ -3232,16 +3264,21 @@ function stringArg(value) {
   return typeof value === "string" && value.trim() ? value.trim() : null;
 }
 
+// setOptionalBoolean and setOptionalString serve `qa policy set` only, ahead of
+// its packet write, so a bad value there is a refusal. booleanArg itself stays
+// untagged: it is shared with `qa run`'s analytics leg, which calls it mid-run,
+// where a throw is a handler failure — so the tag goes on this call site
+// (`refusing()`), not in the validator.
 function setOptionalBoolean(target, property, args, key, changed) {
   if (!(key in args)) return;
-  const value = booleanArg(args[key], key);
+  const value = refusing(() => booleanArg(args[key], key));
   setIfChanged(target, property, value, changed);
 }
 
 function setOptionalString(target, property, args, key, changed) {
   if (!(key in args)) return;
   const value = stringArg(args[key]);
-  if (!value) throw new Error(`--${key} requires a value.`);
+  if (!value) throw refused(`--${key} requires a value.`);
   setIfChanged(target, property, value, changed);
 }
 

package/src/qa-publish.mjs

@@ -20,10 +20,12 @@ import { existsSync, readFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 
 import { campaignSidecarPaths, targetRepoFor } from "./campaign-workspace.mjs";
+import { refused } from "./lifecycle.mjs";
 import { SIDECAR_RELATIVE_PATH } from "./qa-sidecar.mjs";
 import { qaVerdictIdentityMatch } from "./qa-verdict-discovery.mjs";
-import { publishQaVerdict, qaPortalUrl, qaVerdictPublishBlock, QA_VERDICT_PUBLISHERS } from "./qa-verdict-publish.mjs";
+import { publishQaVerdict, qaPortalUrl, qaVerdictPublishBlock, QA_VERDICT_PUBLISH_ENDPOINT, QA_VERDICT_PUBLISHERS } from "./qa-verdict-publish.mjs";
 import { validateVerdict } from "./qa-verdict.mjs";
+import { assertFetchAvailable, assertSecureProxyBase, classifyRemitOutcome, describeRemitBaseKind } from "./remit.mjs";
 import { readRunRecordsForTarget, writeRunRecord } from "./run-record.mjs";
 import { identityMatches } from "./run-record-closeout.mjs";
 import { DEFAULT_PROXY_BASE } from "./spec-fetch.mjs";
@@ -32,6 +34,9 @@ import { singleLineFragment } from "./text-safety.mjs";
 
 export const QA_PUBLISH_STATUSES = Object.freeze({
   published: "published",
+  // --dry-run: every refusal check ran and none fired, so a real run would
+  // have posted. Nothing was sent, so this is neither published nor failed.
+  dry_run: "dry_run",
   refused: "refused",
   publish_failed: "publish_failed",
 });
@@ -55,6 +60,7 @@ export const QA_PUBLISH_REFUSALS = Object.freeze({
 
 export const QA_PUBLISH_EXIT_CODES = Object.freeze({
   [QA_PUBLISH_STATUSES.published]: 0,
+  [QA_PUBLISH_STATUSES.dry_run]: 0,
   [QA_PUBLISH_STATUSES.refused]: 2,
   [QA_PUBLISH_STATUSES.publish_failed]: 1,
 });
@@ -165,6 +171,25 @@ export function findRunRecordForVerdict({ records, packet, verdictRunId, verdict
  * the record stamping are assertable without a receiver or a filesystem.
  */
 export async function publishStoredVerdict(args, operations = {}) {
+  // `--dry-run` is a bare flag; `--dry-run true` must fail rather than quietly
+  // become a real POST.
+  // An up-front flag refusal, tagged like every other so the lifecycle
+  // journal records nothing for it (a plain Error here would be journaled as
+  // a handler failure).
+  if (Object.hasOwn(args, "dry-run") && args["dry-run"] !== true) {
+    throw refused(`--dry-run takes no value (got ${JSON.stringify(args["dry-run"])}); write \`--dry-run\` on its own, after the other flags.`);
+  }
+  const dryRun = args["dry-run"] === true;
+  const result = await attemptPublish(args, operations, dryRun);
+  if (!dryRun) return result;
+  // The envelope says what the real command would have done. A refusal is a
+  // refusal either way — same code, same exit — and so is a destination the
+  // transport gate turns down before any request; `would_publish` is true only
+  // when every check passed and the post is all that is left.
+  return { ...result, dry_run: true, would_publish: result.status === QA_PUBLISH_STATUSES.dry_run };
+}
+
+async function attemptPublish(args, operations, dryRun) {
   const ops = {
     readJsonFile: readJson,
     exists: existsSync,
@@ -268,6 +293,70 @@ export async function publishStoredVerdict(args, operations = {}) {
     );
   }
 
+  // Every refusal check above has run and none fired, so a real run would post
+  // now. Under --dry-run this is where it stops: nothing is sent, and the Run
+  // Record below is left exactly as it stands.
+  if (dryRun) {
+    // First, the checks the transport itself makes before it opens a socket.
+    // `publishQaVerdict` -> `remit` demands a fetch to send with
+    // (`assertFetchAvailable`) and then puts every destination through
+    // `assertSecureProxyBase`; a runtime with no global fetch, or a base that
+    // is not https (nor a loopback host for local testing), fails there,
+    // locally, with nothing sent: the real command reports publish_failed and
+    // exits 1. A preview may not approve a send the transport refuses, so both
+    // gates run here, in the transport's own order — the same functions, with
+    // the label and the (absent) credential the publish rail passes them — and
+    // the refusal is classified by the same classifier the real outcome goes
+    // through, so the message and the exit code are the real command's.
+    // `attempted: false` is the one difference: nothing was sent.
+    let destinationRefusal = null;
+    try {
+      assertFetchAvailable(globalThis.fetch);
+      assertSecureProxyBase(proxyBase, { label: "QA verdict publish", credential: null });
+    } catch (error) {
+      destinationRefusal = classifyRemitOutcome(error);
+    }
+    if (destinationRefusal) {
+      return {
+        ok: false,
+        action: "qa-publish",
+        status: QA_PUBLISH_STATUSES.publish_failed,
+        ...identity,
+        republished: republish && priorBlock?.state === "ok",
+        publish: {
+          attempted: false,
+          ok: destinationRefusal.ok,
+          error: destinationRefusal.error,
+          endpoint: QA_VERDICT_PUBLISH_ENDPOINT,
+          result: destinationRefusal.result,
+          http_status: destinationRefusal.http_status,
+          base_kind: describeRemitBaseKind(proxyBase),
+          published_at: null,
+        },
+        dashboard_url: null,
+        run_record: recordEntry ? { ...recordSummary(recordEntry, priorBlock), written: false, preserved: false } : null,
+        orders_placed: 0,
+      };
+    }
+    return {
+      ok: true,
+      action: "qa-publish",
+      status: QA_PUBLISH_STATUSES.dry_run,
+      ...identity,
+      republished: republish && priorBlock?.state === "ok",
+      would_post: {
+        endpoint: QA_VERDICT_PUBLISH_ENDPOINT,
+        base_kind: describeRemitBaseKind(proxyBase),
+        verdict_run_id: verdictRunId,
+        payload_bytes: Buffer.byteLength(JSON.stringify(verdict), "utf8"),
+      },
+      publish: { attempted: false, ok: null, error: null, endpoint: QA_VERDICT_PUBLISH_ENDPOINT, result: null, http_status: null, base_kind: describeRemitBaseKind(proxyBase), published_at: null },
+      dashboard_url: qaPortalUrl(proxyBase, mapId, verdictRunId),
+      run_record: recordEntry ? { ...recordSummary(recordEntry, priorBlock), written: false, preserved: false } : null,
+      orders_placed: 0,
+    };
+  }
+
   const outcome = await ops.post(verdict, proxyBase);
   const publishedAt = ops.now();
   const block = qaVerdictPublishBlock(outcome, { verdictRunId, publisher: QA_VERDICT_PUBLISHERS.publish, publishedAt });
@@ -332,6 +421,21 @@ export function qaPublishTextLines(result, { cmd = (verb) => `campaigns-os ${ver
     if (result.verdict_path) lines.push(`Verdict: ${result.verdict_path}${result.source_kind ? ` (${result.source_kind})` : ""}`);
     if (result.dashboard_url) lines.push(`QA portal: ${result.dashboard_url}`);
     lines.push("No order was placed and nothing was sent.");
+    if (result.dry_run) lines.push("Dry run (--dry-run): the real command refuses this the same way.");
+    return lines;
+  }
+  if (result.status === QA_PUBLISH_STATUSES.dry_run) {
+    const post = result.would_post || {};
+    lines.push("QA publish dry run (--dry-run): every refusal check passed and nothing was sent.");
+    lines.push(`Map ID: ${result.map_id}`);
+    lines.push(`Run ID: ${result.run_id}`);
+    lines.push(`Disposition: ${result.disposition}`);
+    lines.push(`Verdict: ${result.verdict_path} (${result.source_kind})`);
+    lines.push(`Would POST: ${post.endpoint} at ${result.proxy_base} [base: ${post.base_kind}] — verdict ${post.verdict_run_id}, ${post.payload_bytes} bytes`);
+    lines.push(result.run_record
+      ? `Run Record: ${result.run_record.run_id} would take the publish outcome (${result.run_record.path}); it was not touched.`
+      : "Run Record: none references this verdict under the packet's campaign, so a real publish would not be recorded on one.");
+    lines.push("Orders placed: 0 (qa publish never places orders).");
     return lines;
   }
   lines.push(result.status === QA_PUBLISH_STATUSES.published
@@ -356,7 +460,9 @@ export function qaPublishTextLines(result, { cmd = (verb) => `campaigns-os ${ver
   }
   lines.push("Orders placed: 0 (qa publish never places orders).");
   if (result.status === QA_PUBLISH_STATUSES.publish_failed) {
-    lines.push(`Re-run ${cmd("qa")} publish with network access; the local verdict is untouched.`);
+    lines.push(result.dry_run
+      ? `Dry run (--dry-run): nothing was sent, and the real command fails here the same way — the destination is refused before any request. ${result.publish?.error || ""}`.trimEnd()
+      : `Re-run ${cmd("qa")} publish with network access; the local verdict is untouched.`);
   }
   return lines;
 }