@nextcommerce/campaigns-os 1.43.2 → 1.46.0

package/src/doctor/inspect.mjs

@@ -8,10 +8,13 @@ import { commitAssemblyReport, recordProducerStageOutcome } from "../stage-ledge
 import { annotateDoctorIssueCauses } from "../finding-cause.mjs";
 import { DOCTOR_SIDECAR_SCHEMA } from "../doctor-sidecar.mjs";
 import { resolveCampaignWorkspace } from "../campaign-workspace.mjs";
+import { normalizePublicRouteSlug } from "../route-identity.mjs";
+import { DEFAULT_PROXY_BASE } from "../spec-fetch.mjs";
+import { disabledLiveRead, liveRefsDisabled, readLiveCampaignForPacket } from "../live-campaign-refs.mjs";
 import { evaluateThemeGate } from "../theme-gate.mjs";
 import { findForbiddenPriceHides } from "../template-brand-contract.mjs";
 import { resolveBuiltSiteScope, synthesizeMinimalBuildPacket } from "../built-site-scope.mjs";
-import { UPSELL_SELECTOR_SCOPE } from "../upsell-selector-scope.mjs";
+import { UPSELL_SELECTOR_SCOPE, builtPageTypeOverRouteGuess } from "../upsell-selector-scope.mjs";
 import { CAMPAIGN_IDENTITY } from "../campaign-identity.mjs";
 import { SDK_MARKUP } from "../sdk-markup.mjs";
 import { SCRIPT_SYNTAX, collectBuiltScriptSyntaxInputs } from "../built-script-syntax.mjs";
@@ -88,7 +91,38 @@ function relativizeDoctorOutput(result, baseDir) {
 // Sidecar producer name; see the producer comment above NEXT_PRODUCER in src/cli.mjs.
 const DOCTOR_PRODUCER = "doctor";
 
-export function doctorCommand(args, { runDoctor = doctorPacket } = {}) {
+// The live campaign read the `doctor` command makes before it inspects (#533):
+// packet mode only, only when the packet's built _site/<route>/ exists (with
+// no built page there is nothing to compare, so nothing is sent), and only
+// under the public Campaigns API key the packet, its local CampaignSpec or its
+// declared campaign-key env var resolves. One GET of {proxy-base}/api/campaign;
+// --proxy-base names the proxy, else the canonical one; --no-live-refs sends
+// nothing and records not_run with reason `disabled`. `undefined` means no
+// read was due, which doctor records as not_run; every other outcome,
+// failures included, is a readLiveCampaign result.
+export async function readDoctorLiveCampaign(args, { fetchImpl = globalThis.fetch, env = process.env, warn = undefined } = {}) {
+  if (((args.built || args.site) && !args.packet) || !isNonEmptyString(args.packet)) return undefined;
+  if (liveRefsDisabled(args)) return disabledLiveRead();
+  let workspace;
+  try {
+    workspace = resolveCampaignWorkspace(resolve(args.packet), { followContextPointer: false });
+  } catch {
+    // An unreadable packet is doctor's own blocker; there is nothing to read for.
+    return undefined;
+  }
+  const slug = normalizePublicRouteSlug(workspace.packet?.campaign?.public_route_slug);
+  if (!workspace.targetRepo || !slug || !existsSync(join(workspace.targetRepo, "_site", slug))) return undefined;
+  return readLiveCampaignForPacket({
+    packet: workspace.packet,
+    packetPath: workspace.packetPath,
+    env,
+    fetchImpl,
+    proxyBase: optionalString(args["proxy-base"]) || DEFAULT_PROXY_BASE,
+    ...(warn ? { warn } : {}),
+  });
+}
+
+export function doctorCommand(args, { runDoctor = doctorPacket, liveCampaign = undefined } = {}) {
   // Non-packet mode (learnings L7): doctor a `campaign-build`'d page-kit
   // campaign that has only a built _site/ and no full Build Packet. Resolves
   // scope from the built output and runs the built-output residue/text/
@@ -103,6 +137,9 @@ export function doctorCommand(args, { runDoctor = doctorPacket } = {}) {
     contextPath: args.context ? resolve(args.context) : explicitSidecarArgs ? null : undefined,
     reportPath: args.report ? resolve(args.report) : explicitSidecarArgs ? null : undefined,
     outputBaseDir: args["strip-paths"] === true ? dirname(packetPath) : null,
+    // A live campaign read (live-campaign-refs.mjs) the caller already made;
+    // absent, the live ref check is recorded not_run.
+    ...(liveCampaign !== undefined ? { liveCampaign } : {}),
   };
   const result = runDoctor(packetPath, doctorOptions);
   // Inspection and recording are separate operations. A laptop's untracked
@@ -234,20 +271,25 @@ export function doctorBuiltOutput(args) {
   // branch above: the defect is family-independent, and this mode is reached
   // without --family more often than with it. Page roles come from the built
   // route (resolveBuiltSiteScope infers them) and from each page's own
-  // next-page-type meta, so no packet or spec is needed. No assembly report
-  // exists on this path, so there are no waivers to assess — a blocker here is
-  // repaired in the source, or waived through the packet path.
+  // next-page-type meta, so no packet or spec is needed; a `checkout` meta the
+  // browser reads, declared unambiguously, replaces an ambiguous route guess
+  // such as "/checkout-oto-1/", never an explicit upsell or downsell route (#529). No
+  // assembly report exists on this path, so there are no waivers to assess — a
+  // blocker here is repaired in the source, or waived through the packet path.
   recordUpsellSelectorScopeGate({
     subject: {
       public_route_slug: scope.slug || null,
       site_root: relFromDir(targetRepo, scope.campaign_dir),
     },
-    pages: scope.pages.map((page) => ({
-      page_id: page.page_id,
-      page_type: page.page_type,
-      file: relFromDir(targetRepo, page.built_path),
-      content: readFileSync(page.built_path, "utf8"),
-    })),
+    pages: scope.pages.map((page) => {
+      const content = readFileSync(page.built_path, "utf8");
+      return {
+        page_id: page.page_id,
+        page_type: builtPageTypeOverRouteGuess({ route: page.route, route_type: page.page_type, content }),
+        file: relFromDir(targetRepo, page.built_path),
+        content,
+      };
+    }),
     waivers: null,
     errors,
     warnings,
@@ -374,7 +416,7 @@ export function doctorPacket(packetPath, options = {}) {
   return result;
 }
 
-function inspectDoctorPacket(packetPath, { contextPath = undefined, reportPath = undefined, outputBaseDir = null } = {}) {
+function inspectDoctorPacket(packetPath, { contextPath = undefined, reportPath = undefined, outputBaseDir = null, liveCampaign = undefined } = {}) {
   // The Build Context records where prepare-build wrote the report
   // (--report-out). `next` follows that pointer when no --report is given;
   // doctor reads the same report so its gates and its next block cannot
@@ -425,7 +467,7 @@ function inspectDoctorPacket(packetPath, { contextPath = undefined, reportPath =
     },
   };
 
-  validatePacket(packet, packetPath, errors, warnings, ready, derived, { context, report });
+  validatePacket(packet, packetPath, errors, warnings, ready, derived, { context, report, liveCampaign });
   runDoctorChecks(ARTIFACT_DOCTOR_CHECKS, { context, report, errors, warnings, ready, derived });
 
   // Doctor and the stage ladder must agree over one packet (#238): when the

package/src/doctor/source-provenance.mjs

@@ -0,0 +1,184 @@
+// Source-provenance checkpoint (#534). A CampaignSpec page whose design_source
+// is Figma makes doctor demand figma-sections-export provenance from the
+// source-html manifest (source_html.producer_provenance*). When the approved
+// source for that page is hand-written HTML and the Figma file is only a
+// render of it, no export exists to supply that provenance. This gate lets a
+// named human record that, per page, with a reason and a bound, through
+// `checkpoint waive --gate source_html.producer_provenance --page <page_id>`.
+//
+// A waiver never suppresses a finding. Doctor reports the provenance findings
+// once per Figma-typed page: as warnings carrying `waived: true` for a waived
+// page, and as errors for an unwaived one. The family is the
+// source_html.producer_provenance* codes plus source_html.files.partial and
+// source_html.files.asset, the export's own file-inventory shape, which only
+// a Figma-typed page is held to. When the manifest itself claims to be a
+// figma-sections-export output, the findings are the manifest's own: they
+// stay manifest-wide errors, the gate is not waivable, and any waiver
+// recorded for the page is inert. Every other source check (manifest
+// validity, wrapper policy, screenshot proof) is evaluated elsewhere and is
+// untouched by this gate.
+
+import {
+  assessCheckpointWaivers,
+  checkpointStateFingerprint,
+  projectCheckpointWaiverAssessment,
+} from "../checkpoint-waiver.mjs";
+
+export const SOURCE_PROVENANCE_SCOPE = "source_html.producer_provenance";
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function emptyWaiverAssessment() {
+  return { active: null, inert_counts: { stale: 0, foreign: 0, malformed: 0, expired: 0 } };
+}
+
+// True when a source-html manifest's generator names figma-sections-export in
+// any form: bare, `@<version>` or another suffix, any case, surrounding
+// whitespace. Such a manifest claims to be a real export, so its provenance
+// findings are its own and no page waiver clears them. Every reader of the
+// generator claim uses this one predicate.
+export function generatorClaimsFigmaExport(generator) {
+  if (typeof generator !== "string") return false;
+  return /(^|[^a-z0-9_-])figma-sections-export(?![a-z0-9_-])/i.test(generator.trim());
+}
+
+export function isSourceProvenanceCode(code) {
+  const value = String(code || "");
+  return value === SOURCE_PROVENANCE_SCOPE || value.startsWith(`${SOURCE_PROVENANCE_SCOPE}.`);
+}
+
+// The Figma-export file inventory: a manifest behind a Figma-typed page must
+// list section partials and exported assets. Hand-written HTML has neither, so
+// these two findings belong to the waivable family.
+export const FIGMA_EXPORT_FILE_CODES = Object.freeze(["source_html.files.partial", "source_html.files.asset"]);
+
+// The gate code when the manifest's generator claims figma-sections-export:
+// blocked, not waivable, and any waiver recorded for the page is inert.
+export const SOURCE_PROVENANCE_EXPORTER_CLAIM_CODE = `${SOURCE_PROVENANCE_SCOPE}.exporter_claim`;
+
+function waiveCommand(pageId) {
+  return `campaigns-os checkpoint waive --packet <packet> --gate ${SOURCE_PROVENANCE_SCOPE} --page ${pageId} --reason "<reason>" --waived-by "<named human>" --expires-at <ISO>`;
+}
+
+/**
+ * One checkpoint gate per Figma-typed page.
+ *
+ * @param {{
+ *   pages: Array<{ page_id: string, design_source: { type: string|null, file_url: string|null } }>,
+ *   blockingCodes: string[],
+ *   generatorClaimsExport?: boolean,
+ *   waivers?: unknown,
+ *   now?: string,
+ * }} input
+ */
+export function evaluateSourceProvenanceGates({ pages = [], blockingCodes = [], generatorClaimsExport = false, waivers = null, now = new Date().toISOString() } = {}) {
+  const records = (Array.isArray(waivers) ? waivers : [])
+    .filter((record) => isPlainObject(record) && record.scope === SOURCE_PROVENANCE_SCOPE);
+  const figmaPageIds = new Set(pages.map((page) => page.page_id));
+  const findings = [...new Set(blockingCodes)].sort();
+  let exporterClaimRecords = 0;
+
+  const gates = pages.map((page) => {
+    const subject = { page_id: page.page_id };
+    const state = { design_source: page.design_source, findings };
+    const base = {
+      id: SOURCE_PROVENANCE_SCOPE,
+      scope: SOURCE_PROVENANCE_SCOPE,
+      subject,
+      state,
+    };
+    if (findings.length === 0) {
+      return {
+        ...base,
+        status: "pass",
+        code: `${SOURCE_PROVENANCE_SCOPE}.pass`,
+        reason: `Page "${page.page_id}" has a Figma design source and the source-html manifest carries semantic figma-sections-export provenance.`,
+        waivable: false,
+        state_fingerprint: null,
+        waiver: null,
+        waiver_assessment: emptyWaiverAssessment(),
+        required_actions: [],
+      };
+    }
+    // Only this page's records are assessed here. Another page's waiver is
+    // not "foreign" history for this page; it belongs to that page's gate.
+    const pageRecords = records.filter((record) => isPlainObject(record.subject) && record.subject.page_id === page.page_id);
+    // An exporter claim takes precedence over every other inert kind: it makes
+    // each of this page's records inert whatever else is true of it (stale,
+    // expired, malformed), so each is counted once, as exporter_claim, and
+    // never assessed.
+    if (generatorClaimsExport) {
+      exporterClaimRecords += pageRecords.length;
+      return {
+        ...base,
+        status: "blocked",
+        code: SOURCE_PROVENANCE_EXPORTER_CLAIM_CODE,
+        reason: `Page "${page.page_id}" has a Figma design source and the source-html manifest's generator claims figma-sections-export, but the manifest lacks that export's provenance (${findings.join(", ")}). A real export carries it, so this is not waivable; re-run figma-sections-export, or, when the approved source is hand-written HTML, set the manifest's generator to name the real producer and record a page waiver.`,
+        waivable: false,
+        state_fingerprint: null,
+        waiver: null,
+        waiver_assessment: emptyWaiverAssessment(),
+        required_actions: [
+          {
+            id: "repair_target",
+            kind: "manual",
+            command: null,
+            description: "Re-run figma-sections-export so the source-html manifest carries semantic producer_provenance, or correct the manifest's generator when no export produced it, then re-run doctor.",
+          },
+        ],
+      };
+    }
+    const state_fingerprint = checkpointStateFingerprint({ scope: SOURCE_PROVENANCE_SCOPE, subject, state });
+    const checkpoint = { scope: SOURCE_PROVENANCE_SCOPE, subject, state_fingerprint };
+    const waiver_assessment = projectCheckpointWaiverAssessment(
+      assessCheckpointWaivers(pageRecords, checkpoint, { now }),
+      checkpoint,
+    );
+    const waiver = waiver_assessment.active;
+    return {
+      ...base,
+      status: waiver ? "waived" : "blocked",
+      code: waiver ? `${SOURCE_PROVENANCE_SCOPE}.waived` : SOURCE_PROVENANCE_SCOPE,
+      reason: waiver
+        ? `Page "${page.page_id}" has a Figma design source but no figma-sections-export provenance (${findings.join(", ")}); accepted under a named-human decision that its approved source is hand-written HTML.`
+        : `Page "${page.page_id}" has a Figma design source, so doctor requires figma-sections-export provenance in the source-html manifest (${findings.join(", ")}). Re-run figma-sections-export, or, when the approved source is hand-written HTML and the Figma file only renders it, record a named-human waiver for this page.`,
+      waivable: true,
+      state_fingerprint,
+      waiver,
+      waiver_assessment,
+      required_actions: waiver ? [] : [
+        {
+          id: "repair_target",
+          kind: "manual",
+          command: null,
+          description: "Re-run figma-sections-export for this page so the source-html manifest carries semantic producer_provenance, then re-run doctor.",
+        },
+        {
+          id: "waive_checkpoint",
+          kind: "command",
+          command: waiveCommand(page.page_id),
+          description: `When page "${page.page_id}"'s approved source is hand-written HTML, record a named-human waiver with a reason and a bound. Manifest, wrapper-policy and screenshot-proof checks still apply.`,
+        },
+      ],
+    };
+  });
+
+  // Records naming a page that no longer has a Figma design source (the
+  // page's design_source changed, or the page left the spec) can never
+  // satisfy a gate again.
+  const noFigmaSource = records.filter((record) => !isPlainObject(record.subject)
+    || !figmaPageIds.has(record.subject.page_id));
+  const counts = { stale: 0, foreign: 0, malformed: 0, expired: 0 };
+  for (const gate of gates) {
+    for (const kind of Object.keys(counts)) counts[kind] += gate.waiver_assessment?.inert_counts?.[kind] || 0;
+  }
+  counts.no_figma_source = noFigmaSource.length;
+  counts.exporter_claim = exporterClaimRecords;
+  const inertPages = [...new Set(noFigmaSource
+    .map((record) => (isPlainObject(record.subject) && typeof record.subject.page_id === "string" ? record.subject.page_id : null))
+    .filter(Boolean))].sort();
+
+  return { gates, inert: { counts, pages: inertPages } };
+}

package/src/invocation.mjs

@@ -65,6 +65,7 @@ const COMMANDS = frozen({
   theme: { subcommands: ["generate", "inspect", "waive"] },
   checkpoint: { subcommands: ["waive"] },
   polish: { subcommands: ["capture"] },
+  record: { subcommands: ["build", "polish", "setup"] },
   "validate-assembly-report": {},
   "install-agent-context": { dryRun: true },
   "install-skills": { dryRun: true },
@@ -90,6 +91,9 @@ const SUBCOMMAND_OVERRIDES = frozen({
   "page-kit sync": { dryRun: true },
   "spec derive": { dryRun: true },
   "qa publish": { dryRun: true },
+  "record build": { dryRun: true },
+  "record polish": { dryRun: true },
+  "record setup": { dryRun: true },
   "qa run": { autoEnd: true },
   "run start": { sweepRoot: "session" },
   "run end": { sweepRoot: "session", dryRun: true },