@nextcommerce/campaigns-os 1.43.1 → 1.46.0

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/install-invocation.mjs

@@ -0,0 +1,29 @@
+// How this install spells the commands it prints. ROOT resolves `..` from this
+// file, so the module must stay directly under src/ to name the package root.
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { invocationPrefixFor } from "./install-mode.mjs";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+// Every command this CLI PRODUCES for an operator or agent to copy is spelled
+// once, here, for the install it runs from (see install-mode.mjs): bare
+// `campaigns-os` from a checkout, `npx --no-install campaigns-os` from a
+// campaign folder that pins the toolkit, `npx --yes <spec>` from an npx cache.
+// Result payloads are never rewritten after the fact — a path, a quoted
+// argument or a data value that happens to contain the words is left exactly
+// as it is.
+function cmd(verb, rest = "") {
+  const prefix = invocationPrefixFor(ROOT);
+  return `${prefix} ${verb}${rest ? ` ${rest}` : ""}`;
+}
+
+// A registry command (gate actions, checkpoint remediations) is stored in its
+// canonical bare form so internal bookkeeping can match on it; this spells
+// it for the current install at the moment it is emitted.
+function asInvocation(command) {
+  if (typeof command !== "string" || !command.startsWith("campaigns-os ")) return command;
+  return `${invocationPrefixFor(ROOT)} ${command.slice("campaigns-os ".length)}`;
+}
+
+export { ROOT, cmd, asInvocation };

package/src/invocation.mjs

@@ -0,0 +1,183 @@
+// Invocation policy: which cross-cutting steps run around a command, and in
+// what order. One owner for rules that used to be restated at each step — the
+// pre-dispatch bypasses, the stale-session sweep and its root, the ambient
+// run-session read, the lifecycle wrapper, the journal exemptions, the
+// commands that implement --dry-run, and the QA auto-end trigger.
+//
+// The declaration below is data: a class, a sweep root kind and a few flags
+// per command, and per subcommand only where the subcommand differs from its
+// command. It describes kernel behaviour and is never a permission
+// interpreter: contracts/effects.v1.json is bound to it by a test, never read
+// here. The steps themselves (the sweep, the ambient read, the journal append,
+// the auto-end, every handler) stay in cli.mjs and are handed to
+// runInvocation() as functions; this module decides only whether and when each
+// runs. It imports nothing from cli.mjs.
+
+import { runWithRefusalScope, withCommandLifecycle } from "./lifecycle.mjs";
+
+// Frozen all the way down, so a caller handed a subcommand list cannot edit it.
+const frozen = (value) => { if (value && typeof value === "object") Object.values(value).forEach(frozen); return Object.freeze(value); };
+
+// The steps each pre-dispatch class runs. `auth` and `inline` commands run
+// their handler in place: no sweep, no ambient read, no wrapper, no journal.
+// `inspection` still resolves the ambient session and is wrapped, but never
+// sweeps or journals. `projection` (`readback`) is wrapped only: its --packet
+// is an override naming the Build Packet to project, not a session locator.
+// Read as one, the named file was loaded whole past readback's own size bound,
+// and a valid override exited 1 whenever some active session was bound to a
+// different packet; neither belongs to a command declared read-only.
+const CLASS_STEPS = frozen({
+  auth: [], inline: [],
+  inspection: ["wrapper", "ambient"],
+  projection: ["wrapper"],
+  standard: ["wrapper", "ambient", "sweep", "journal"],
+});
+
+// Every top-level command, in the order did-you-mean breaks ties. Fields:
+// `class` (default "standard"); `sweepRoot` ("target": the --target directory,
+// "session": the run-session root; default none); `dryRun` (the command
+// implements --dry-run); `journalExempt`; `journalExemptWhen` (exempt when the
+// `given` flag is set and the `unlessBare` flag is not bare: an inspection must
+// not append to a delivered campaign's active run);
+// `subcommands` (the only subcommand names that resolve; others inherit the
+// command's entry and are refused by the handler).
+//
+// `dryRun` marks only the commands that IMPLEMENT the flag. It reaches every
+// handler through a permissive parseArgs, and an exemption scoped to the flag
+// alone once fired on commands that ignore it: `qa run --dry-run` placed orders
+// while writing no journal entry, and carried the flag into its own auto-end,
+// which assembled no Run Record and left the session open. A command without
+// `dryRun` given --dry-run journals if it otherwise would, and is not refused.
+const COMMANDS = frozen({
+  help: { journalExempt: true },
+  login: { class: "auth" },
+  logout: { class: "auth" },
+  demo: { class: "inline" },
+  tooling: { subcommands: ["diagnose", "setup", "status"] },
+  sdk: { subcommands: ["storage-check"] },
+  readback: { class: "projection" },
+  start: { sweepRoot: "target" },
+  "prepare-build": { sweepRoot: "target" },
+  build: { sweepRoot: "target" },
+  doctor: { journalExemptWhen: { given: "packet", unlessBare: "write" } },
+  bundle: { subcommands: ["check"] },
+  standardize: {},
+  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 },
+  "page-kit": { subcommands: ["parity", "sync"] },
+  spec: { subcommands: ["derive"] },
+  next: { subcommands: ["build", "deploy", "polish", "qa", "setup"] },
+  qa: { subcommands: ["install-browser", "parity", "policy", "promote", "publish", "resolve", "run", "waive"] },
+  findings: { subcommands: ["add", "export", "harvest", "list"] },
+  "run-record": { dryRun: true },
+  telemetry: { subcommands: ["list", "off", "on", "status"] },
+  run: { subcommands: ["end", "start", "status"] },
+});
+
+// Where a subcommand's policy differs from its command's entry. Matched on the
+// explicit subcommand token only: bare `run` defaults to `status` inside its
+// handler, but is not `run status` here, so it journals.
+const SUBCOMMAND_OVERRIDES = frozen({
+  "tooling diagnose": { class: "inline" },
+  "tooling setup": { class: "inline" },
+  "sdk storage-check": { class: "inspection" },
+  "theme waive": { dryRun: true },
+  "checkpoint waive": { dryRun: true },
+  "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 },
+  "run status": { journalExempt: true },
+});
+
+export const commandNames = () => Object.keys(COMMANDS);
+
+export const subcommandNames = (command) => (Object.hasOwn(COMMANDS, command) && COMMANDS[command].subcommands) || frozen([]);
+
+// A run opted out of sessions altogether: no stale sweep, and no intake
+// auto-start (which reads this predicate from here).
+export const optsOutOfRunSession = (args) => args["no-run-session"] === true;
+
+// The policy for one invocation. Two --dry-run predicates are deliberate and
+// differ: on a command implementing the flag, its PRESENCE suppresses the
+// sweep (a valued flag the handler will refuse still does nothing first), while
+// only a bare `--dry-run` exempts the journal (the install commands accept a
+// valued flag as a dry run and still journal it). The sweep writes a Run
+// Record, deletes the session file and (under consent) remits — every effect
+// --dry-run promises not to have — so the stale session stays stale until a
+// real invocation closes it. --no-write suppresses both too: inheriting it
+// into the closeout suppressed the Run Record but still deleted the session
+// file. A refused invocation never journals either; that rule is per outcome,
+// not per argv, and stays with the journal append.
+export function resolveInvocationPolicy(command, args) {
+  const subcommand = subcommandNames(command).includes(args._[1]) ? args._[1] : null;
+  const rule = { class: "standard", ...(Object.hasOwn(COMMANDS, command) && COMMANDS[command]), ...(subcommand && SUBCOMMAND_OVERRIDES[`${command} ${subcommand}`]) };
+  const steps = CLASS_STEPS[rule.class];
+  const noWrite = args["no-write"] === true;
+  const implementsDryRun = rule.dryRun === true;
+  const sweepSuppressed = optsOutOfRunSession(args) || noWrite || (Object.hasOwn(args, "dry-run") && implementsDryRun);
+  const inspection = Boolean(rule.journalExemptWhen && args[rule.journalExemptWhen.given] && args[rule.journalExemptWhen.unlessBare] !== true);
+  return Object.freeze({
+    class: rule.class,
+    wrapper: steps.includes("wrapper"), ambient: steps.includes("ambient"),
+    sweepRoot: steps.includes("sweep") && !sweepSuppressed ? rule.sweepRoot || null : null,
+    journalExempt: !steps.includes("journal") || rule.journalExempt === true || noWrite || (args["dry-run"] === true && implementsDryRun) || inspection,
+    implementsDryRun, autoEnd: rule.autoEnd === true,
+  });
+}
+
+// The sequence main() delegates to. `steps` are cli.mjs mechanisms:
+//   dispatch(command, args, { recorder?, ambient?, sessionHolder? }?)
+//   closeOutStaleRunSessions(rootKind, args) -> the closed-out stale sessions
+//   ambientRunSession(args) -> the active session, or null
+//   lifecycleIdentity(args, ambient) -> { argvShape, runId }
+//   persistLifecycle(args, command, lifecycle, sessionHolder, thrown)
+//   autoEndAfterQa(args, sessionHolder, thrown, implementsDryRun)
+// Order: normalise argv, open the refusal scope, run an unwrapped class in
+// place, else sweep, read the ambient session, and wrap dispatch; on finish
+// (success or error) journal unless exempt, then run the QA auto-end. The
+// sweep precedes the ambient read so a stale session at the root is closed out
+// (findRunSession ignores it) rather than abandoned with no Run Record. The
+// wrapper re-throws unchanged, so the exit code is the command's own; a
+// command that throws is recorded too. Persistence stays opt-in: with no
+// --lifecycle-journal, CAMPAIGNS_OS_LIFECYCLE_LOG or active session nothing is
+// written.
+export async function runInvocation(args, steps) {
+  // `npx … campaigns-os <command>` hands the bin its own name as the first
+  // positional: it is the program name, not a command.
+  if (args._[0] === "campaigns-os") args._.shift();
+  const command = args._[0] || "help";
+  const policy = resolveInvocationPolicy(command, args);
+  // One refusal scope per invocation, so a refusal is visible only to this
+  // invocation's persistence step.
+  return runWithRefusalScope(async () => {
+    if (!policy.wrapper) return steps.dispatch(command, args);
+    const sweptStale = policy.sweepRoot ? await steps.closeOutStaleRunSessions(policy.sweepRoot, args) : [];
+    const ambient = policy.ambient ? steps.ambientRunSession(args) : null;
+    // Per invocation, never module state: an intake that opens or joins a run
+    // session mid-command publishes it here, so this command's own entry is
+    // persisted into it.
+    const sessionHolder = { current: ambient, autoStarted: false, adopted: false, qaResult: null, sweptStale };
+    await withCommandLifecycle(
+      {
+        command,
+        ...steps.lifecycleIdentity(args, ambient),
+        onFinish: async (lifecycle, thrown) => {
+          if (!policy.journalExempt) steps.persistLifecycle(args, command, lifecycle, sessionHolder, thrown);
+          if (policy.autoEnd) await steps.autoEndAfterQa(args, sessionHolder, thrown, policy.implementsDryRun);
+        },
+      },
+      (recorder) => steps.dispatch(command, args, { recorder, ambient, sessionHolder }),
+    );
+  });
+}