@nextcommerce/campaigns-os 1.37.3 → 1.43.1

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",
 });
@@ -41,6 +46,7 @@ export const QA_PUBLISH_STATUSES = Object.freeze({
 // thrown error, so --json readers get a code to branch on.
 export const QA_PUBLISH_REFUSALS = Object.freeze({
   packet_required: "packet_required",
+  local_spec: "local_spec",
   order_flags_refused: "order_flags_refused",
   verdict_missing: "verdict_missing",
   verdict_unreadable: "verdict_unreadable",
@@ -55,6 +61,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 +172,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,
@@ -193,6 +219,9 @@ export async function publishStoredVerdict(args, operations = {}) {
     return refusal(QA_PUBLISH_REFUSALS.packet_required, `Build Packet ${packetPath} is not readable (${error.code || error.message}).`);
   }
 
+  if (packet?.spec?.local_spec_id != null) {
+    return refusal(QA_PUBLISH_REFUSALS.local_spec, "Local-spec QA has no saved Map destination; keep its verdict in the repository. Portal publication requires a saved Map and fresh evidence.");
+  }
   const source = resolveStoredVerdictSource({ args, packetPath, packet, readJsonFile: ops.readJsonFile, exists: ops.exists });
   if (source.error) return source.error;
   let verdict;
@@ -268,6 +297,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 +425,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 +464,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;
 }

package/src/qa-sidecar.mjs

@@ -1,3 +1,4 @@
+import { localSpecIdentityFields } from "./spec-source-identity.mjs";
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { dirname, join, resolve } from "node:path";
@@ -77,6 +78,7 @@ export function projectVerdictForSidecar(verdict, { generatedAt }) {
     schema_version: verdict.schema_version,
     run_id: verdict.run_id,
     campaign_slug: verdict.campaign_slug,
+    ...localSpecIdentityFields(verdict),
     ...(verdict.public_route_slug != null ? { public_route_slug: verdict.public_route_slug } : {}),
     ...(verdict.campaign_ref_id != null ? { campaign_ref_id: verdict.campaign_ref_id } : {}),
     spec_version: verdict.spec_version,

package/src/qa-verdict-discovery.mjs

@@ -1,3 +1,4 @@
+import { resolveCampaignIdentity, localQaIdentifier } from "./spec-source-identity.mjs";
 // QA verdict discovery: the one walk over the local verdicts a campaign has
 // written, with the projections each reader needs.
 //
@@ -28,11 +29,20 @@ function qaVerdictSlug(packet) {
 // the slug as identity. A verdict is this campaign's when its campaign_slug
 // is one of them.
 export function qaVerdictIdentifiers(packet) {
+  if (packet?.spec?.local_spec_id != null) {
+    const identity = resolveCampaignIdentity(packet.spec);
+    return identity?.kind === "local_spec" ? [localQaIdentifier(identity.id)] : [];
+  }
   return [...new Set([optionalString(packet?.spec?.map_id), qaVerdictSlug(packet)].filter(Boolean))];
 }
 
 export function qaVerdictIdentityMatch(verdict, packet) {
   const slug = optionalString(verdict?.campaign_slug);
+  if (packet?.spec?.local_spec_id != null || verdict?.local_spec_id != null) {
+    const identity = resolveCampaignIdentity(packet?.spec);
+    return identity?.kind === "local_spec" && verdict?.local_spec_id === identity.id
+      && slug === localQaIdentifier(identity.id);
+  }
   return Boolean(slug) && qaVerdictIdentifiers(packet).includes(slug);
 }
 
@@ -174,6 +184,7 @@ export function qaVerdictCandidateScore(candidate, packet) {
   const mapId = optionalString(packet?.spec?.map_id);
   const slug = qaVerdictSlug(packet);
   let score = 0;
+  if (packet?.spec?.local_spec_id && qaVerdictIdentityMatch(verdict, packet)) score += 100;
   if (mapId && verdict.campaign_slug === mapId) score += 100;
   if (slug && verdict.campaign_slug === slug) score += 80;
   if (verdict.schema_version === "1.0" || verdict.schema_version === "campaigns-os-qa-verdict/v0") score += 10;

package/src/qa-verdict-publish.mjs

@@ -42,6 +42,7 @@ export const QA_VERDICT_PUBLISH_STATES = Object.freeze(["skipped", "ok", "failed
  * must not claim a credential is travelling in clear.
  */
 export async function publishQaVerdict(verdict, proxyBase, { fetchImpl = globalThis.fetch, remitImpl = remit } = {}) {
+  if (verdict?.local_spec_id != null) return { ...skippedQaVerdictPublish(), reason: "local_spec" };
   let httpStatus = null;
   let response = null;
   let failure = null;

package/src/qa-verdict.mjs

@@ -1,3 +1,4 @@
+import { resolveCampaignIdentity, localQaIdentifier } from "./spec-source-identity.mjs";
 export const QA_SCHEMA_VERSION = "1.0";
 
 export const STATUS = Object.freeze({
@@ -95,6 +96,7 @@ function dispositionWithCommercial(assertions, commercial) {
 export function createVerdict({
   runId,
   mapId,
+  localSpecId = null,
   publicRouteSlug = null,
   campaignRefId = null,
   specVersion,
@@ -126,7 +128,8 @@ export function createVerdict({
     run_id: runId,
     // campaign_slug carries the Map ID for schema back-compat; the true public
     // route slug rides alongside so consumers stop conflating the two.
-    campaign_slug: mapId,
+    campaign_slug: localSpecId ? localQaIdentifier(localSpecId) : mapId,
+    ...(localSpecId ? { local_spec_id: localSpecId } : {}),
     public_route_slug: optionalString(publicRouteSlug),
     campaign_ref_id: campaignRefId,
     spec_version: specVersion,
@@ -208,6 +211,10 @@ export function deriveExceptions(assertions = []) {
 
 export function validateVerdict(verdict) {
   const errors = [];
+  if (verdict?.local_spec_id != null && (!resolveCampaignIdentity({ local_spec_id: verdict.local_spec_id })
+    || verdict.campaign_slug !== localQaIdentifier(verdict.local_spec_id))) {
+    errors.push("Local-spec verdict requires a valid local_spec_id and its local QA identifier.");
+  }
   if (!verdict || typeof verdict !== "object" || Array.isArray(verdict)) {
     return ["verdict: must be an object"];
   }