@nextcommerce/campaigns-os 1.33.0

package/src/deviation.mjs

@@ -0,0 +1,107 @@
+// Agent deviation telemetry: makes "the agent ignored Campaigns OS and
+// wandered" measurable instead of anecdotal.
+//
+// `campaigns-os next` records its recommendation (stage + the commands it
+// expects next) on the active run session. When a later pipeline-advancing
+// command does not match that recommendation, a deviation entry is appended to
+// a sidecar journal. Deviations are TELEMETRY, not blocks — hard gates live in
+// `next`/doctor/qa. An agent can declare intent with --deviation-reason so an
+// intentional detour is distinguishable from drift.
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+export const DEVIATION_SCHEMA = "campaigns-os-agent-deviation/v0";
+export const DEVIATION_JOURNAL_REL_PATH = ".campaign-runtime/agent-deviations.jsonl";
+
+// Commands that advance the pipeline. Read-only / bookkeeping commands
+// (doctor, next, findings, telemetry, run, validate-*) never deviate.
+export const TRACKED_STAGE_COMMANDS = Object.freeze(new Set(["start", "prepare-build", "theme", "polish", "qa", "run-record"]));
+
+// Commands every recommendation implicitly allows for its stage. Stage work is
+// agent/skill work, so the expected command set is small and explicit.
+const EXPECTED_COMMANDS_BY_STAGE = Object.freeze({
+  "prepare-build": ["prepare-build", "start"],
+  setup: ["theme"],
+  build: ["theme"],
+  polish: ["polish", "theme"],
+  deploy: [],
+  qa: ["qa", "theme"],
+  done: ["run-record"],
+});
+
+// The command word of a produced command line, whichever install prefix it
+// was spelled with (bare `campaigns-os`, `npx campaigns-os`, `npm run
+// campaigns-os --`, or `npx --yes <git-spec>` from an npx cache).
+export function commandWord(command) {
+  if (typeof command !== "string") return null;
+  const stripped = command
+    .replace(/^npx\s+--yes\s+\S+\s+/, "campaigns-os ")
+    .replace(/^npx\s+campaigns-os\s+/, "campaigns-os ")
+    .replace(/^npm\s+run\s+campaigns-os\s+--\s+/, "campaigns-os ");
+  return stripped.match(/^campaigns-os\s+([a-z-]+)/)?.[1] || null;
+}
+
+export function expectedCommandsForStage(stage, requiredActions = []) {
+  const base = EXPECTED_COMMANDS_BY_STAGE[stage] || [];
+  // Gate required_actions name exact commands ("campaigns-os theme generate
+  // ..."); their command words are expected too.
+  const fromActions = requiredActions
+    .map((action) => commandWord(action?.command))
+    .filter(Boolean);
+  return [...new Set([...base, ...fromActions])];
+}
+
+export function buildRecommendation({ stage, status, expectedCommands, now = new Date() }) {
+  return {
+    stage,
+    status,
+    expected_commands: expectedCommands,
+    issued_at: now.toISOString(),
+  };
+}
+
+/**
+ * Compare a pipeline-advancing command against the session's last
+ * recommendation. Returns a deviation entry or null.
+ */
+export function detectDeviation({ lastRecommendation, command, argvShape = [], runId = null, deviationReason = null, now = new Date() }) {
+  if (!TRACKED_STAGE_COMMANDS.has(command)) return null;
+  if (!lastRecommendation || !Array.isArray(lastRecommendation.expected_commands)) return null;
+  if (lastRecommendation.expected_commands.includes(command)) return null;
+  return {
+    schema_version: DEVIATION_SCHEMA,
+    observed_at: now.toISOString(),
+    run_id: runId,
+    recommended_stage: lastRecommendation.stage || null,
+    recommended_status: lastRecommendation.status || null,
+    recommended_commands: lastRecommendation.expected_commands,
+    recommendation_issued_at: lastRecommendation.issued_at || null,
+    actual_command: command,
+    actual_argv_shape: argvShape,
+    deviation_reason: typeof deviationReason === "string" && deviationReason.trim() ? deviationReason.trim() : null,
+  };
+}
+
+export function appendDeviation(journalPath, entry) {
+  const path = resolve(journalPath);
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, `${JSON.stringify(entry)}\n`);
+  return entry;
+}
+
+/** Best-effort read; malformed lines are skipped, a missing journal is empty. */
+export function readDeviations(journalPath) {
+  const path = resolve(journalPath);
+  if (!existsSync(path)) return [];
+  const entries = [];
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const entry = JSON.parse(line);
+      if (entry && typeof entry === "object" && entry.schema_version === DEVIATION_SCHEMA) entries.push(entry);
+    } catch {
+      // tolerate a torn line; telemetry must never block reads
+    }
+  }
+  return entries;
+}

package/src/doctor-check-registry.mjs

@@ -0,0 +1,49 @@
+function defineDoctorCheck({ id, phase = "doctor", run, when = null }, { registryId = "doctor", index = "unknown" } = {}) {
+  const location = `Doctor check registry "${registryId}" check at index ${index}`;
+  if (!isNonEmptyString(id)) throw new Error(`${location} needs a non-empty id.`);
+  const normalizedId = id.trim();
+  const checkLabel = `Doctor check registry "${registryId}" check "${normalizedId}"`;
+  if (!isNonEmptyString(phase)) throw new Error(`${checkLabel} needs a phase.`);
+  if (typeof run !== "function") throw new Error(`${checkLabel} needs a run function.`);
+  if (when != null && typeof when !== "function") throw new Error(`${checkLabel} has a non-function when predicate.`);
+
+  return Object.freeze({
+    id: normalizedId,
+    phase: phase.trim(),
+    run,
+    when,
+  });
+}
+
+export function createDoctorCheckRegistry(checks, { registryId = "doctor" } = {}) {
+  if (!Array.isArray(checks)) throw new Error(`Doctor check registry "${registryId}" must be an array.`);
+  const seen = new Map();
+  const normalized = checks.map((check, index) => {
+    if (!check || typeof check !== "object") {
+      throw new Error(`Doctor check registry "${registryId}" has a non-object check at index ${index}.`);
+    }
+    const doctorCheck = defineDoctorCheck(check, { registryId, index });
+    if (seen.has(doctorCheck.id)) {
+      throw new Error(`Doctor check registry "${registryId}" has duplicate check id "${doctorCheck.id}".`);
+    }
+    seen.set(doctorCheck.id, doctorCheck);
+    return doctorCheck;
+  });
+  return Object.freeze(normalized);
+}
+
+export function runDoctorCheckRegistry(checks, context, { phase = null } = {}) {
+  const phaseFilter = isNonEmptyString(phase) ? phase.trim() : null;
+  const executed = [];
+  for (const check of checks) {
+    if (phaseFilter && check.phase !== phaseFilter) continue;
+    if (check.when && !check.when(context)) continue;
+    check.run(context);
+    executed.push(check.id);
+  }
+  return executed;
+}
+
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}

package/src/doctor-sidecar.mjs

@@ -0,0 +1,106 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+export const DOCTOR_SIDECAR_REL_PATH = ".campaign-runtime/doctor-output.json";
+export const DOCTOR_SIDECAR_SCHEMA = "campaigns-os-doctor-output/v0";
+
+export function doctorSidecarPath(targetBaseDir) {
+  return join(targetBaseDir, DOCTOR_SIDECAR_REL_PATH);
+}
+
+// Atomic JSON write (tmp + rename) for the artifacts other commands may read
+// concurrently: the assembly report, the doctor sidecar, a run session. A
+// torn report would defeat the gate decision it records, and a torn sidecar
+// would itself break the freshness contract the stale stamp implements.
+export function writeJsonAtomic(path, value) {
+  const resolved = resolve(path);
+  mkdirSync(dirname(resolved), { recursive: true });
+  const tmp = `${resolved}.${randomUUID()}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
+  renameSync(tmp, resolved);
+}
+
+// #312: every retained sidecar names the command that persisted it, the way
+// a stale stamp already names the command that made it (`stale_marked_by`).
+// `generated_at` alone cannot tell a fresh `doctor --write` from a two-day-old
+// gitignored copy carried along by `cp -R` — which is exactly what got a
+// read-only command accused of writing this file. The name is the producer's
+// own: each producer function states it where it is defined (`doctor`,
+// `next`, `qa run`) or receives it from the dispatch that selected it (the
+// intake body serving `start` / `build`); it is never re-read from argv at
+// the write. A producer that forgets to say who it is fails loudly rather
+// than writing an anonymous artifact, and a name that is not a plain command
+// word (a control character, a stray newline) is refused here, at the seam,
+// so a consumer that greps or re-prints the sidecar reads one producer per
+// line. Placed beside `generated_at` so the two read together.
+const PRODUCER_NAME = /^[a-z0-9][a-z0-9 _-]*$/;
+
+export function stampDoctorProducer(doctor, command) {
+  if (typeof command !== "string" || !command.trim()) {
+    throw new TypeError("stampDoctorProducer requires command: the retained doctor sidecar names the command that produced it (generated_by).");
+  }
+  if (!PRODUCER_NAME.test(command.trim())) {
+    throw new TypeError(`stampDoctorProducer refuses producer name ${JSON.stringify(command)}: generated_by is a plain command word (${PRODUCER_NAME}).`);
+  }
+  if (!doctor || typeof doctor !== "object" || Array.isArray(doctor)) {
+    throw new TypeError("stampDoctorProducer requires a doctor result object.");
+  }
+  const { schema_version, generated_at, generated_by: _previous, ...rest } = doctor;
+  return {
+    ...(schema_version !== undefined ? { schema_version } : {}),
+    ...(generated_at !== undefined ? { generated_at } : {}),
+    generated_by: command.trim(),
+    ...rest,
+  };
+}
+
+// The one writer of the retained doctor sidecar: a wholesale, atomic rewrite
+// of a doctorPacket result stamped with its producer. Every producer —
+// `doctor --write`, `next`, `start`/`build`, the QA stage refresh — goes
+// through this (or through `stampDoctorProducer` when its own transactional
+// writer must do the rename), so `generated_by` cannot be skipped by one of
+// them the way #327's cause labels once were.
+export function writeDoctorSidecar(path, doctor, { command } = {}) {
+  writeJsonAtomic(path, stampDoctorProducer(doctor, command));
+  return path;
+}
+
+// #171 v1 freshness contract for the retained doctor sidecar: commands that
+// mutate doctor inputs WITHOUT recomputing doctor state (theme waive/generate,
+// qa policy set) stamp the retained snapshot stale instead of leaving a green
+// lie on disk, while commands that DO recompute (doctor, prepare-build/start,
+// next) rewrite the sidecar wholesale — which clears any stale stamp.
+export function markDoctorSidecarStale(targetBaseDir, { command = null, reason = null } = {}) {
+  const path = doctorSidecarPath(targetBaseDir);
+  if (!existsSync(path)) return null;
+  let sidecar;
+  try {
+    sidecar = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+  if (!sidecar || typeof sidecar !== "object" || Array.isArray(sidecar)) return null;
+  const stamped = {
+    ...sidecar,
+    stale: true,
+    stale_marked_by: command,
+    stale_marked_at: new Date().toISOString(),
+    stale_reason: reason
+      || "A later command changed doctor inputs after this snapshot was written. Re-run campaigns-os doctor (or campaigns-os next) for current state.",
+  };
+  writeJsonAtomic(path, stamped);
+  return path;
+}
+
+// The retained doctor sidecar records its own verdict twice: `ok` (boolean)
+// and `status` ("ready", "ready_with_warnings", "ready_with_waivers",
+// "blocked"). A bundle consumer must read that verdict rather than treat the
+// sidecar's presence, schema validity, or freshness as readiness: a blocked
+// doctor run is a perfectly well-formed artifact whose content says the
+// campaign cannot proceed. Either signal blocks; a sidecar that is not an
+// object reports nothing (its shape is the schema check's job, not this one's).
+export function doctorSidecarBlocked(sidecar) {
+  if (!sidecar || typeof sidecar !== "object" || Array.isArray(sidecar)) return false;
+  return sidecar.status === "blocked" || sidecar.ok === false;
+}