@nextcommerce/campaigns-os 1.33.0

package/src/sidecar-bundle.mjs

@@ -0,0 +1,399 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import Ajv2020 from "ajv/dist/2020.js";
+
+import { doctorSidecarBlocked } from "./doctor-sidecar.mjs";
+import { validateVerdict } from "./qa-verdict.mjs";
+import { specHashesMatch } from "./spec-identity.mjs";
+
+const ROOT = resolve(fileURLToPath(new URL("..", import.meta.url)));
+const CONTRACT_PATH = join(ROOT, "contracts/migration-sidecar-bundle.v0.json");
+const RFC3339_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/;
+
+export const SIDECAR_BUNDLE_CONFORMANCE_SCHEMA = "campaigns-os-sidecar-bundle-conformance/v0";
+export const SIDECAR_BUNDLE_CONTRACT = JSON.parse(readFileSync(CONTRACT_PATH, "utf8"));
+
+const schemaValidators = new Map();
+for (const artifact of SIDECAR_BUNDLE_CONTRACT.artifacts) {
+  const schema = JSON.parse(readFileSync(join(ROOT, artifact.schema_path), "utf8"));
+  const ajv = new Ajv2020({ strict: false, allErrors: true, validateFormats: false });
+  schemaValidators.set(artifact.kind, ajv.compile(schema));
+}
+
+function digest(value) {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.keys(value)
+      .sort()
+      .map((key) => [key, canonicalize(value[key])]),
+  );
+}
+
+function removePath(value, dottedPath) {
+  const parts = dottedPath.split(".");
+  let cursor = value;
+  for (let index = 0; index < parts.length - 1; index += 1) {
+    if (!cursor || typeof cursor !== "object") return;
+    cursor = cursor[parts[index]];
+  }
+  if (cursor && typeof cursor === "object") delete cursor[parts.at(-1)];
+}
+
+export function materialProjection(value, artifactContract) {
+  const projected = structuredClone(value);
+  for (const field of artifactContract.volatile_fields || []) removePath(projected, field);
+  return canonicalize(projected);
+}
+
+function artifactFinding(code, artifact, message, remedy) {
+  return { code, artifact, message, remedy };
+}
+
+function readJsonArtifact(path) {
+  const raw = readFileSync(path);
+  return { raw, value: JSON.parse(raw.toString("utf8")) };
+}
+
+function timestampOk(value) {
+  return typeof value === "string" && RFC3339_UTC.test(value) && Number.isFinite(Date.parse(value));
+}
+
+function valueAt(value, dottedPath) {
+  return dottedPath.split(".").reduce((current, key) => current?.[key], value);
+}
+
+// The two spec-identity fields compare through the shared spec-hash
+// comparator so a `sha256:` prefix, hex case or whitespace difference between
+// producers is not reported as drift. The set is explicit, not inferred from
+// the field name: a future `*_hash` field with a different prefix convention
+// must opt in here rather than have its prefix silently stripped. Every other
+// identity field (map_id, slugs, paths) stays an exact compare.
+const SPEC_HASH_IDENTITY_FIELDS = new Set(["spec_hash", "spec_material_hash"]);
+
+function identityValuesAgree(identityField, left, right) {
+  if (SPEC_HASH_IDENTITY_FIELDS.has(identityField.name)) return specHashesMatch(left, right);
+  return left === right;
+}
+
+function compareIdentity(errors, records, identityField) {
+  const label = identityField.name;
+  const present = [];
+  for (const [kind, path] of Object.entries(identityField.artifact_paths)) {
+    if (!records.has(kind)) continue;
+    const value = valueAt(records.get(kind).value, path);
+    if (value == null || value === "") {
+      errors.push(artifactFinding(
+        `bundle.identity.${label}_missing`,
+        kind,
+        `${kind} is missing required bundle identity ${path}.`,
+        "Regenerate the sidecars from the same root Build Packet and explicit QA verdict.",
+      ));
+      continue;
+    }
+    present.push({ kind, value });
+  }
+  if (present.length < 2) return;
+  const expected = present[0].value;
+  const mismatch = present.find((entry) => !identityValuesAgree(identityField, entry.value, expected));
+  if (!mismatch) return;
+  errors.push(artifactFinding(
+    `bundle.identity.${label}_mismatch`,
+    mismatch.kind,
+    `${label} disagrees across bundle artifacts (${present.map((entry) => `${entry.kind}=${entry.value}`).join(", ")}).`,
+    "Regenerate the sidecars from the same root Build Packet and explicit QA verdict.",
+  ));
+}
+
+function compareSpecMaterialIdentity(errors, records, identityField) {
+  const contextMaterial = valueAt(records.get("build_context")?.value, identityField.artifact_paths.build_context);
+  const reportMaterial = valueAt(records.get("assembly_report")?.value, identityField.artifact_paths.assembly_report);
+
+  if (!contextMaterial && !reportMaterial) {
+    // The ordinary spec_hash identity field already compares the two legacy
+    // producer values. QA's spec_hash is semantic material identity even for
+    // legacy bundles, so it must never participate in the raw-byte check.
+    return;
+  }
+
+  const present = [];
+  const missing = [];
+  for (const [kind, path] of Object.entries(identityField.artifact_paths)) {
+    if (!records.has(kind)) continue;
+    const value = valueAt(records.get(kind).value, path);
+    if (value == null || value === "") missing.push({ kind, path });
+    else present.push({ kind, value });
+  }
+
+  if (missing.length) {
+    errors.push(artifactFinding(
+      "bundle.identity.spec_material_hash_incomplete",
+      missing[0].kind,
+      `Material spec identity is partially regenerated; missing ${missing.map((entry) => `${entry.kind}:${entry.path}`).join(", ")}.`,
+      "Regenerate Build Context, Assembly Report, and any required QA sidecar from the same CampaignSpec.",
+    ));
+    return;
+  }
+
+  const expected = present[0]?.value;
+  const mismatch = present.find((entry) => !identityValuesAgree(identityField, entry.value, expected));
+  if (mismatch) {
+    errors.push(artifactFinding(
+      "bundle.identity.spec_material_hash_mismatch",
+      mismatch.kind,
+      `spec_material_hash disagrees across bundle artifacts (${present.map((entry) => `${entry.kind}=${entry.value}`).join(", ")}).`,
+      "Regenerate the sidecars from the same CampaignSpec and explicit QA verdict.",
+    ));
+  }
+}
+
+function bundleRootFor(packetPath) {
+  const absolute = resolve(packetPath);
+  if (basename(dirname(absolute)) === ".campaign-runtime") return dirname(dirname(absolute));
+  return dirname(absolute);
+}
+
+function normalizeRepositoryRelativePath(value) {
+  if (typeof value !== "string" || !value.trim()) return null;
+  const path = value.trim();
+  if (path.startsWith("/") || path.includes("\\") || /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(path)) return null;
+  const segments = path.split("/");
+  if (segments.includes("..")) return null;
+  return segments.filter((segment) => segment && segment !== ".").join("/") || ".";
+}
+
+export function inspectSidecarBundle({ packetPath, requireQa = false } = {}) {
+  if (!packetPath || typeof packetPath !== "string") {
+    throw new Error("bundle check requires --packet <campaign-runtime.build.json>.");
+  }
+
+  const root = bundleRootFor(packetPath);
+  const absolutePacket = resolve(packetPath);
+  const canonicalPacket = join(root, SIDECAR_BUNDLE_CONTRACT.packet_discovery.canonical_path);
+  const errors = [];
+  const warnings = [];
+  const records = new Map();
+  const artifacts = [];
+
+  if (absolutePacket !== canonicalPacket) {
+    const legacy = absolutePacket === join(root, SIDECAR_BUNDLE_CONTRACT.packet_discovery.legacy_path);
+    errors.push(artifactFinding(
+      legacy ? "bundle.packet.legacy_path" : "bundle.packet.noncanonical_path",
+      "build_packet",
+      legacy
+        ? `Build Packet is at the legacy sidecar path ${SIDECAR_BUNDLE_CONTRACT.packet_discovery.legacy_path}; default discovery reads only the repository root.`
+        : `Build Packet must be at repository-root ${SIDECAR_BUNDLE_CONTRACT.packet_discovery.canonical_path}.`,
+      legacy
+        ? SIDECAR_BUNDLE_CONTRACT.packet_discovery.legacy_remedy
+        : SIDECAR_BUNDLE_CONTRACT.packet_discovery.noncanonical_remedy,
+    ));
+  }
+
+  for (const artifactContract of SIDECAR_BUNDLE_CONTRACT.artifacts) {
+    const path = join(root, artifactContract.path);
+    const required = artifactContract.requirement === "required" || (artifactContract.kind === "qa_verdict" && requireQa);
+    const record = {
+      kind: artifactContract.kind,
+      path: artifactContract.path,
+      requirement: artifactContract.requirement,
+      present: existsSync(path),
+      schema_version: null,
+      generated_at: null,
+      sha256: null,
+      material_sha256: null,
+    };
+    artifacts.push(record);
+
+    if (!record.present) {
+      const finding = artifactFinding(
+        `bundle.${artifactContract.kind}.missing`,
+        artifactContract.kind,
+        `Missing canonical JSON artifact ${artifactContract.path}.`,
+        artifactContract.kind === "qa_verdict"
+          ? "Run QA, or explicitly promote one named full verdict with campaigns-os qa promote; never select a verdict by mtime."
+          : artifactContract.kind === "doctor_output"
+            ? "Run campaigns-os doctor --packet campaign-runtime.build.json --write --strip-paths to refresh it."
+            : "Regenerate the bundle with Campaigns OS while preserving authored packet, context, and assembly inputs.",
+      );
+      (required ? errors : warnings).push(finding);
+      continue;
+    }
+
+    try {
+      const parsed = readJsonArtifact(path);
+      records.set(artifactContract.kind, parsed);
+      record.schema_version = parsed.value?.schema_version ?? null;
+      record.generated_at = valueAt(parsed.value, artifactContract.freshness_field) ?? null;
+      record.sha256 = digest(parsed.raw);
+      record.material_sha256 = digest(JSON.stringify(materialProjection(parsed.value, artifactContract)));
+    } catch {
+      errors.push(artifactFinding(
+        `bundle.${artifactContract.kind}.invalid_json`,
+        artifactContract.kind,
+        `${artifactContract.path} is not valid JSON.`,
+        "Regenerate the artifact with its Campaigns OS producer; do not repair generated JSON by hand.",
+      ));
+      continue;
+    }
+
+    if (record.schema_version !== artifactContract.schema_version) {
+      errors.push(artifactFinding(
+        `bundle.${artifactContract.kind}.schema_version`,
+        artifactContract.kind,
+        `Expected schema_version ${artifactContract.schema_version}; found ${record.schema_version ?? "missing"}.`,
+        `Regenerate ${artifactContract.path} with a compatible Campaigns OS release.`,
+      ));
+    }
+    if (!timestampOk(record.generated_at)) {
+      errors.push(artifactFinding(
+        `bundle.${artifactContract.kind}.generated_at`,
+        artifactContract.kind,
+        `${artifactContract.path} needs a strict RFC3339 UTC generated_at timestamp.`,
+        `Regenerate ${artifactContract.path}; freshness is never inferred from filesystem mtime.`,
+      ));
+    }
+    const validateSchema = schemaValidators.get(artifactContract.kind);
+    if (!validateSchema(records.get(artifactContract.kind).value)) {
+      const details = validateSchema.errors
+        .slice(0, 5)
+        .map((error) => `${error.instancePath || "/"} ${error.message}`)
+        .join("; ");
+      errors.push(artifactFinding(
+        `bundle.${artifactContract.kind}.schema`,
+        artifactContract.kind,
+        `${artifactContract.path} failed ${artifactContract.schema_path}: ${details}`,
+        `Regenerate ${artifactContract.path} with its Campaigns OS producer; do not repair generated JSON by hand.`,
+      ));
+    }
+  }
+
+  const packet = records.get("build_packet")?.value;
+  const context = records.get("build_context")?.value;
+  const report = records.get("assembly_report")?.value;
+  const doctor = records.get("doctor_output")?.value;
+  const qaVerdict = records.get("qa_verdict")?.value;
+
+  if (context && normalizeRepositoryRelativePath(context.packet_path) !== "campaign-runtime.build.json") {
+    errors.push(artifactFinding(
+      "bundle.build_context.packet_path",
+      "build_context",
+      "Build Context packet_path must name repository-root campaign-runtime.build.json.",
+      "Regenerate the Build Context with canonical repository-relative output paths.",
+    ));
+  }
+  if (report && normalizeRepositoryRelativePath(report.inputs?.packet_path) !== "campaign-runtime.build.json") {
+    errors.push(artifactFinding(
+      "bundle.assembly_report.packet_path",
+      "assembly_report",
+      "Assembly Report inputs.packet_path must name repository-root campaign-runtime.build.json.",
+      "Regenerate the Assembly Report with canonical repository-relative output paths.",
+    ));
+  }
+  if (doctor?.stale === true) {
+    errors.push(artifactFinding(
+      "bundle.doctor_output.stale",
+      "doctor_output",
+      "Doctor output is explicitly marked stale after a later mutation.",
+      "Re-run campaigns-os doctor --packet campaign-runtime.build.json --write --strip-paths.",
+    ));
+  }
+  // A blocked doctor run is still a conformant artifact — the sidecars agree
+  // with each other and the contract — but its content says the campaign
+  // cannot proceed. Conformance is not readiness: surface the block as a
+  // warning by default and, under --require-qa, as an error, because a
+  // QA-complete handoff cannot ride a doctor that refused the build.
+  if (doctorSidecarBlocked(doctor)) {
+    (requireQa ? errors : warnings).push(artifactFinding(
+      "bundle.doctor_output.blocked",
+      "doctor_output",
+      `Doctor output records a blocked run (status ${doctor.status ?? "missing"}, ok ${doctor.ok ?? "missing"}); the campaign cannot proceed${requireQa ? ", so it cannot satisfy QA-complete handoff" : " even though the sidecars agree with each other"}.`,
+      "Resolve the doctor errors, then re-run campaigns-os doctor --packet campaign-runtime.build.json --write --strip-paths so the retained sidecar records a ready run.",
+    ));
+  }
+  if (qaVerdict) {
+    const qaErrors = validateVerdict(qaVerdict);
+    if (qaErrors.length) {
+      errors.push(artifactFinding(
+        "bundle.qa_verdict.shape",
+        "qa_verdict",
+        `QA Verdict sidecar failed its public shape: ${qaErrors.join("; ")}`,
+        "Re-run QA or explicitly promote a valid named full verdict with campaigns-os qa promote.",
+      ));
+    }
+    for (const field of ["entry_urls", "page_urls", "tested_urls", "test_orders"]) {
+      if (!Array.isArray(qaVerdict[field]) || qaVerdict[field].length !== 0) {
+        errors.push(artifactFinding(
+          `bundle.qa_verdict.${field}`,
+          "qa_verdict",
+          `Committed QA sidecar field ${field} must be an empty array.`,
+          "Regenerate the allowlist projection with campaigns-os qa promote; do not commit a full URL/order-bearing verdict.",
+        ));
+      }
+    }
+    // A blocked verdict on disk is always reported, so the Readiness line
+    // reads it whether or not QA is part of conformance; --require-qa is what
+    // turns the same finding into an error, because only then does the bundle
+    // claim QA-complete handoff.
+    if (qaVerdict.disposition === "blocked") {
+      (requireQa ? errors : warnings).push(artifactFinding(
+        "bundle.qa_verdict.blocked",
+        "qa_verdict",
+        requireQa
+          ? "QA Verdict is schema-valid but blocked, so it cannot satisfy QA-complete handoff."
+          : "QA Verdict is schema-valid but blocked; the bundle is conformant, but the campaign is not QA-ready.",
+        "Resolve the failing QA blockers and promote the resulting named verdict explicitly.",
+      ));
+    }
+  }
+
+  for (const identityField of SIDECAR_BUNDLE_CONTRACT.identity_fields) {
+    if (identityField.name === "spec_material_hash") compareSpecMaterialIdentity(errors, records, identityField);
+    else compareIdentity(errors, records, identityField);
+  }
+
+  const materialEntries = artifacts
+    .filter((artifact) => artifact.present && artifact.material_sha256)
+    .map((artifact) => [artifact.kind, artifact.material_sha256]);
+  const materialDigest = materialEntries.length
+    ? digest(JSON.stringify(materialEntries))
+    : null;
+
+  return {
+    schema_version: SIDECAR_BUNDLE_CONFORMANCE_SCHEMA,
+    bundle_id: SIDECAR_BUNDLE_CONTRACT.bundle_id,
+    ok: errors.length === 0,
+    status: errors.length === 0 ? "conformant" : "nonconformant",
+    // stage_blocked keeps its published meaning (a required QA verdict is
+    // blocked); the doctor case is carried by the bundle.doctor_output.blocked
+    // finding until the conformance schema is bumped to widen it.
+    stage_blocked: requireQa && qaVerdict?.disposition === "blocked",
+    root,
+    packet_generated_at: packet?.generated_at ?? null,
+    material_digest: materialDigest,
+    artifacts,
+    errors,
+    warnings,
+  };
+}
+
+// One line, distinct from `status`, for the operator reading text output:
+// "conformant" only says the sidecars agree with each other and the contract.
+// Whether doctor or QA passed is carried by the blocked findings (and, for a
+// required QA verdict, stage_blocked); this line reads those so nobody has to
+// infer readiness from "ok: true".
+export function sidecarBundleReadinessLine(result) {
+  const blockers = [...(result.errors || []), ...(result.warnings || [])]
+    .filter((finding) => finding.code === "bundle.doctor_output.blocked" || finding.code === "bundle.qa_verdict.blocked")
+    .map((finding) => (finding.artifact === "doctor_output" ? "doctor run is blocked" : "QA verdict is blocked"));
+  if (result.stage_blocked || blockers.length) {
+    return `Readiness: BLOCKED (${blockers.join("; ") || "stage_blocked"}); conformant only means the sidecars agree with each other and the contract.`;
+  }
+  return "Readiness: no doctor or QA block recorded by the sidecars present (a missing sidecar is listed under Warnings); conformant only means the sidecars agree with each other and the contract.";
+}