@nextcommerce/campaigns-os 1.33.0

package/src/findings.mjs

@@ -0,0 +1,326 @@
+// Workflow Findings — the human/agent findings channel within Run Telemetry
+// (the "Findings Sidecar" lane). See docs/workflow-findings-sidecar.md (Run
+// Telemetry); the Run Record embeds a per-run snapshot of these findings.
+//
+// This module owns local finding capture only: validate, append, list, and
+// export Workflow Findings. It deliberately does NOT cluster, route, create
+// Linear issues, or remit — remit lives behind consent in remit.mjs /
+// run-record.mjs, and aggregation is internal tooling's job. Capturing a
+// finding must never require Linear access or NEXT internal context, so this
+// module has no network or credential dependencies.
+
+import { randomBytes } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+export const WORKFLOW_FINDING_SCHEMA = "campaigns-os-workflow-finding/v0";
+export const FINDINGS_JOURNAL_REL_PATH = ".campaign-runtime/workflow-findings.jsonl";
+
+export const FINDING_STAGES = [
+  "overall",
+  "intake",
+  "start",
+  "doctor",
+  "setup",
+  "build",
+  "polish",
+  "deploy",
+  "qa",
+  "test-order",
+  "next",
+];
+
+export const FINDING_KINDS = [
+  "positive_signal",
+  "friction",
+  "missing_prompt",
+  "blocker",
+  "docs_gap",
+  "automation_gap",
+  "idea",
+];
+
+export const FINDING_AUTHOR_TYPES = ["operator", "agent", "system"];
+
+export const FINDING_EVIDENCE_QUALITY = [
+  "operator_report",
+  "artifact_referenced",
+  "artifact_attached",
+  "system_observed",
+];
+
+// Required core fields. Strict here; permissive about optional context.
+const REQUIRED_FIELDS = ["schema_version", "id", "created_at", "stage", "kind", "summary"];
+
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+/**
+ * Hand-rolled validator matching the repo convention (no AJV). Checks the
+ * required core and the closed enums; leaves optional context fields
+ * permissive. Returns `{ ok, errors }` where each error is `{ code, message }`.
+ */
+export function validateWorkflowFinding(finding) {
+  const errors = [];
+  const add = (code, message) => errors.push({ code, message });
+
+  if (!finding || typeof finding !== "object" || Array.isArray(finding)) {
+    add("finding.type", "Workflow Finding must be a JSON object.");
+    return { ok: false, errors };
+  }
+
+  for (const field of REQUIRED_FIELDS) {
+    if (!isNonEmptyString(finding[field])) {
+      add(`finding.${field}`, `Missing or empty required field "${field}".`);
+    }
+  }
+
+  if (finding.schema_version != null && finding.schema_version !== WORKFLOW_FINDING_SCHEMA) {
+    add("finding.schema_version", `Expected schema_version "${WORKFLOW_FINDING_SCHEMA}".`);
+  }
+  if (isNonEmptyString(finding.stage) && !FINDING_STAGES.includes(finding.stage)) {
+    add("finding.stage", `Unknown stage "${finding.stage}". Allowed: ${FINDING_STAGES.join(", ")}.`);
+  }
+  if (isNonEmptyString(finding.kind) && !FINDING_KINDS.includes(finding.kind)) {
+    add("finding.kind", `Unknown kind "${finding.kind}". Allowed: ${FINDING_KINDS.join(", ")}.`);
+  }
+  if (finding.author_type != null && !FINDING_AUTHOR_TYPES.includes(finding.author_type)) {
+    add("finding.author_type", `Unknown author_type "${finding.author_type}". Allowed: ${FINDING_AUTHOR_TYPES.join(", ")}.`);
+  }
+  if (finding.evidence_quality != null && !FINDING_EVIDENCE_QUALITY.includes(finding.evidence_quality)) {
+    add("finding.evidence_quality", `Unknown evidence_quality "${finding.evidence_quality}". Allowed: ${FINDING_EVIDENCE_QUALITY.join(", ")}.`);
+  }
+  if (finding.artifact_paths != null && !Array.isArray(finding.artifact_paths)) {
+    add("finding.artifact_paths", "artifact_paths must be an array of strings when present.");
+  }
+  if (finding.command_exit_status != null && !Number.isInteger(finding.command_exit_status)) {
+    add("finding.command_exit_status", "command_exit_status must be an integer when present.");
+  }
+  if (finding.safe_to_share != null && typeof finding.safe_to_share !== "boolean") {
+    add("finding.safe_to_share", "safe_to_share must be a boolean when present.");
+  }
+  if (finding.run_id != null && typeof finding.run_id !== "string") {
+    add("finding.run_id", "run_id must be a string or null when present.");
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * Resolve the journal path. Precedence:
+ *   1. explicit `--journal <path>`
+ *   2. packet-adjacent target repo when `--packet <path>` is supplied
+ *   3. current working directory otherwise
+ */
+export function resolveJournalPath(args, cwd = process.cwd()) {
+  if (isNonEmptyString(args.journal)) return resolve(args.journal);
+  if (isNonEmptyString(args.packet)) {
+    return join(dirname(resolve(args.packet)), FINDINGS_JOURNAL_REL_PATH);
+  }
+  return join(resolve(cwd), FINDINGS_JOURNAL_REL_PATH);
+}
+
+function generateFindingId(now) {
+  return `wf_${now.getTime()}_${randomBytes(4).toString("hex")}`;
+}
+
+function coerceBoolean(value) {
+  if (value === true || value === "true") return true;
+  if (value === false || value === "false") return false;
+  return null;
+}
+
+/**
+ * Build a Workflow Finding object from parsed CLI flags. Generated values
+ * (id, created_at, schema_version) and sensible defaults (author_type,
+ * evidence_quality) are filled here so the JSONL line is self-describing.
+ */
+export function buildFinding(input, { now = new Date() } = {}) {
+  const finding = {
+    schema_version: WORKFLOW_FINDING_SCHEMA,
+    id: isNonEmptyString(input.id) ? input.id : generateFindingId(now),
+    created_at: isNonEmptyString(input.created_at) ? input.created_at : now.toISOString(),
+    stage: isNonEmptyString(input.stage) ? input.stage.trim() : undefined,
+    kind: isNonEmptyString(input.kind) ? input.kind.trim() : undefined,
+    summary: isNonEmptyString(input.summary) ? input.summary.trim() : undefined,
+  };
+
+  const artifactPaths = parseArtifactPaths(input.artifact_paths);
+  const optional = {
+    details: input.details,
+    expected: input.expected,
+    actual: input.actual,
+    severity: input.severity,
+    command: input.command,
+    source_type: input.source_type,
+    template_family: input.template_family,
+    map_id: input.map_id,
+    campaign_slug: input.campaign_slug,
+    target_repo: input.target_repo,
+    packet_path: input.packet_path,
+    assembly_report_path: input.assembly_report_path,
+    qa_run_id: input.qa_run_id,
+    run_id: input.run_id,
+    suggested_owner: input.suggested_owner,
+  };
+  for (const [key, value] of Object.entries(optional)) {
+    if (isNonEmptyString(value)) finding[key] = value.trim();
+  }
+  if (artifactPaths.length) finding.artifact_paths = artifactPaths;
+  if (Number.isInteger(input.command_exit_status)) finding.command_exit_status = input.command_exit_status;
+
+  const safeToShare = coerceBoolean(input.safe_to_share);
+  if (safeToShare !== null) finding.safe_to_share = safeToShare;
+
+  // author_type: default operator for manual CLI adds; explicit flag wins.
+  finding.author_type = FINDING_AUTHOR_TYPES.includes(input.author_type) ? input.author_type : "operator";
+
+  // evidence_quality: explicit flag wins; otherwise infer artifact_referenced
+  // when artifact paths were supplied, else operator_report.
+  if (FINDING_EVIDENCE_QUALITY.includes(input.evidence_quality)) {
+    finding.evidence_quality = input.evidence_quality;
+  } else {
+    finding.evidence_quality = artifactPaths.length ? "artifact_referenced" : "operator_report";
+  }
+
+  return finding;
+}
+
+function parseArtifactPaths(value) {
+  if (Array.isArray(value)) return value.filter(isNonEmptyString).map((entry) => entry.trim());
+  if (isNonEmptyString(value)) {
+    return value
+      .split(",")
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+  }
+  return [];
+}
+
+/**
+ * Append exactly one validated finding as one JSONL line. Never rewrites
+ * existing entries — the journal is append-only.
+ */
+export function appendFinding(journalPath, finding) {
+  const validation = validateWorkflowFinding(finding);
+  if (!validation.ok) {
+    const detail = validation.errors.map((error) => `[${error.code}] ${error.message}`).join("; ");
+    throw new Error(`Workflow Finding failed validation: ${detail}`);
+  }
+  mkdirSync(dirname(resolve(journalPath)), { recursive: true });
+  appendFileSync(resolve(journalPath), `${JSON.stringify(finding)}\n`);
+  return finding;
+}
+
+/**
+ * Read the journal. Returns `{ findings, malformed }`. Malformed lines are
+ * preserved as `{ line, raw, error }` rather than throwing, so one bad line
+ * never blocks listing or export of the rest of the Learning Trail.
+ */
+export function readJournal(journalPath) {
+  const resolved = resolve(journalPath);
+  if (!existsSync(resolved)) return { findings: [], malformed: [] };
+  const text = readFileSync(resolved, "utf8");
+  const findings = [];
+  const malformed = [];
+  const lines = text.split("\n");
+  for (let index = 0; index < lines.length; index += 1) {
+    const raw = lines[index];
+    if (!raw.trim()) continue;
+    try {
+      findings.push(JSON.parse(raw));
+    } catch (error) {
+      malformed.push({ line: index + 1, raw, error: error.message });
+    }
+  }
+  return { findings, malformed };
+}
+
+function groupByStageThenKind(findings) {
+  // Internal aggregation groups by Observation Stage first, Finding Kind
+  // second. The local export mirrors that ordering so a pasted summary reads
+  // the same way the dashboard will later.
+  const byStage = new Map();
+  for (const finding of findings) {
+    const stage = isNonEmptyString(finding.stage) ? finding.stage : "(unknown)";
+    const kind = isNonEmptyString(finding.kind) ? finding.kind : "(unknown)";
+    if (!byStage.has(stage)) byStage.set(stage, new Map());
+    const byKind = byStage.get(stage);
+    if (!byKind.has(kind)) byKind.set(kind, []);
+    byKind.get(kind).push(finding);
+  }
+  const stageOrder = (stage) => {
+    const index = FINDING_STAGES.indexOf(stage);
+    return index === -1 ? FINDING_STAGES.length : index;
+  };
+  const kindOrder = (kind) => {
+    const index = FINDING_KINDS.indexOf(kind);
+    return index === -1 ? FINDING_KINDS.length : index;
+  };
+  return [...byStage.entries()]
+    .sort((a, b) => stageOrder(a[0]) - stageOrder(b[0]) || a[0].localeCompare(b[0]))
+    .map(([stage, byKind]) => ({
+      stage,
+      kinds: [...byKind.entries()]
+        .sort((a, b) => kindOrder(a[0]) - kindOrder(b[0]) || a[0].localeCompare(b[0]))
+        .map(([kind, items]) => ({ kind, items })),
+    }));
+}
+
+/**
+ * Markdown summary grouped by Observation Stage then Finding Kind. Includes
+ * counts and short summaries and references (artifact paths, run IDs) only —
+ * never artifact contents. Pasteable into Linear/GitHub/Slack.
+ */
+export function exportSummaryMarkdown(findings) {
+  const lines = ["# Campaigns OS Workflow Findings", ""];
+  lines.push(`Total findings: ${findings.length}`, "");
+  if (!findings.length) {
+    lines.push("_No findings recorded yet._");
+    return `${lines.join("\n")}\n`;
+  }
+  for (const { stage, kinds } of groupByStageThenKind(findings)) {
+    const stageCount = kinds.reduce((sum, group) => sum + group.items.length, 0);
+    lines.push(`## ${stage} (${stageCount})`, "");
+    for (const { kind, items } of kinds) {
+      lines.push(`### ${kind} (${items.length})`);
+      for (const finding of items) {
+        const refs = [];
+        if (Array.isArray(finding.artifact_paths) && finding.artifact_paths.length) {
+          refs.push(`artifacts: ${finding.artifact_paths.join(", ")}`);
+        }
+        if (isNonEmptyString(finding.qa_run_id)) refs.push(`qa_run: ${finding.qa_run_id}`);
+        if (isNonEmptyString(finding.map_id)) refs.push(`map: ${finding.map_id}`);
+        const refSuffix = refs.length ? ` — _${refs.join("; ")}_` : "";
+        lines.push(`- ${finding.summary || "(no summary)"}${refSuffix}`);
+      }
+      lines.push("");
+    }
+  }
+  return `${lines.join("\n").replace(/\n+$/, "")}\n`;
+}
+
+/**
+ * Structured JSON export for internal ingestion. Validates each entry and
+ * strips nothing but also adds nothing — artifact contents are never present
+ * because findings only ever store references.
+ */
+export function exportJson(findings) {
+  const invalid = [];
+  for (const finding of findings) {
+    const validation = validateWorkflowFinding(finding);
+    if (!validation.ok) invalid.push({ id: finding?.id || null, errors: validation.errors });
+  }
+  if (invalid.length) {
+    const detail = invalid
+      .map((entry) => `${entry.id || "(no id)"}: ${entry.errors.map((error) => error.code).join(", ")}`)
+      .join(" | ");
+    throw new Error(`Findings Journal has invalid entries; refusing to export: ${detail}`);
+  }
+  return {
+    schema_version: WORKFLOW_FINDING_SCHEMA,
+    count: findings.length,
+    findings,
+  };
+}

package/src/fs-identity.mjs

@@ -0,0 +1,68 @@
+// Path identity, answered once for every module that asks "is this the same
+// file" or "which spelling of this path do I record".
+//
+// A path reached through a symlinked checkout and the same file reached
+// directly are one file; two lexically different spellings of a path that
+// does not exist cannot be shown to be one file. Every caller used to pick a
+// policy for the second case on its own — one compared missing paths by
+// spelling, another refused to treat them as equal — so the two decisions
+// that key on packet identity (session join/refuse, context-to-report
+// binding) could disagree on the same checkout. The policy is now an
+// argument. A leaf: node built-ins only.
+
+import { realpathSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+
+// The path as the filesystem knows it: the real path when it exists, else
+// the real path of its nearest existing ancestor with the missing tail
+// re-appended. What run sessions, Run Record artifact refs and portable
+// (`--strip-paths`) output record. Canonicalising only the side that exists
+// is worse than canonicalising neither — a real base and a lexical target
+// relativize to `../<link>/…` — so a path that is not there yet still
+// resolves through the directory links above it.
+export function canonicalPath(path) {
+  const resolved = resolve(path);
+  const missing = [];
+  let cursor = resolved;
+  for (;;) {
+    try {
+      return join(realpathSync(cursor), ...missing);
+    } catch (error) {
+      if (!absentOrMalformed(error)) throw error;
+      const parent = dirname(cursor);
+      if (parent === cursor) return resolved;
+      missing.unshift(basename(cursor));
+      cursor = parent;
+    }
+  }
+}
+
+// The same file. Equal once resolved, or one file behind any symlinks. With
+// `requireExisting`, a side that is not on disk is never the same file as
+// anything spelled differently; without it, a missing path compares by its
+// canonical spelling (the directory links above it resolved).
+export function sameFile(left, right, { requireExisting = false } = {}) {
+  const resolvedLeft = resolve(left);
+  const resolvedRight = resolve(right);
+  if (resolvedLeft === resolvedRight) return true;
+  if (!requireExisting) return canonicalPath(resolvedLeft) === canonicalPath(resolvedRight);
+  const real = (path) => {
+    try {
+      return realpathSync(path);
+    } catch (error) {
+      if (absentOrMalformed(error)) return null;
+      throw error;
+    }
+  };
+  const realLeft = real(resolvedLeft);
+  return realLeft !== null && realLeft === real(resolvedRight);
+}
+
+// The errors a best-effort read may treat as "nothing there": the path is
+// absent (ENOENT), a component of it is not a directory (ENOTDIR), or the
+// bytes are not JSON (SyntaxError). A permission failure, EISDIR, EIO and
+
+// every other error are not absence and must reach the caller.
+export function absentOrMalformed(error) {
+  return error?.code === "ENOENT" || error?.code === "ENOTDIR" || error instanceof SyntaxError;
+}

package/src/gate-actions.mjs

@@ -0,0 +1,105 @@
+// Gate actions: the vocabulary a checkpoint gate publishes as
+// `required_actions[]` and the one rule that turns an action into the text an
+// operator reads.
+//
+// A gate's action is `{ id, kind, command, description }`: a runnable command
+// carrying the `--packet <packet>` placeholder, or a manual step with no
+// command. Doctor, `next`, the QA runner's resolve printer and its theme-gate
+// printer each rendered that shape for themselves — four spellings of the
+// placeholder substitution — and the polish checkpoint's actions were declared
+// once in polish-node and copied byte for byte into polish-gate, which
+// polish-node imports and so could not import from. A leaf: shell-token only.
+
+import { shellToken } from "./shell-token.mjs";
+import { localProofRebuildText } from "./local-proof.mjs";
+import { invocationPrefixFor } from "./install-mode.mjs";
+import { dirname as installModeDirname, resolve as installModeResolve } from "node:path";
+import { fileURLToPath as installModeFileUrl } from "node:url";
+const PACKAGE_ROOT = installModeResolve(installModeDirname(installModeFileUrl(import.meta.url)), "..");
+
+// The recorded actions of the hidden eager-media checkpoint, keyed by the
+// short name each producer reaches for. The gate evaluators publish these
+// objects unchanged; renderers never re-spell their text.
+export const HIDDEN_EAGER_MEDIA_ACTIONS = Object.freeze({
+  capture: Object.freeze({
+    id: "polish.hidden_eager_media.capture",
+    kind: "command",
+    command: "campaigns-os polish capture --packet <packet> --base-url <url>",
+    description: "Capture package-owned page-load evidence for every mapped route and fixed viewport.",
+  }),
+  install_browser: Object.freeze({
+    id: "polish.hidden_eager_media.install_browser",
+    kind: "command",
+    command: "campaigns-os qa install-browser",
+    description: "Install the package-owned Playwright Chromium runtime before rerunning polish capture (npm run qa:install-browser from a checkout).",
+  }),
+  waive: Object.freeze({
+    id: "polish.hidden_eager_media.waive",
+    kind: "command",
+    command: "campaigns-os checkpoint waive --packet <packet> --gate polish.hidden_eager_media --reason \"<why>\" --waived-by \"<named human>\" --review-condition \"<trigger>\"",
+    description: "Record an exact named-human waiver for the current hidden eager-media findings.",
+  }),
+  repair: Object.freeze({
+    id: "polish.hidden_eager_media.repair",
+    kind: "manual",
+    command: null,
+    description: "Make each reported hidden media element visible, defer it with exact preload=none/metadata, or reduce its aggregate transferred bytes to at most 1,048,576; then recapture.",
+  }),
+  repair_authority: Object.freeze({
+    id: "polish.hidden_eager_media.repair_authority",
+    kind: "manual",
+    command: null,
+    description: "Repair the packet or Assembly Report campaign identity, build fingerprint, and mapped route plan before capture.",
+  }),
+  // A capture over plain HTTP whose ledger shows a failed cross-origin http:
+  // dependency is a production build served locally: its protocol-relative
+  // vendor loaders resolved to http:// and failed. The action is to rebuild in
+  // the development environment (local proof mode), never to edit the
+  // generated include that emits the loader.
+  local_proof_rebuild: Object.freeze({
+    id: "polish.hidden_eager_media.local_proof_rebuild",
+    kind: "manual",
+    command: null,
+    description: localProofRebuildText(),
+  }),
+});
+
+const PACKET_PLACEHOLDER = "--packet <packet>";
+
+// The placeholder becomes the packet this run read, shell-quoted, so the
+// command is copy-pasteable. A function replacement, so `$&`, `$$` or `$1`
+// inside the path are inserted literally instead of being read as
+// replacement patterns. No packet, or no command: returned as given.
+export function substitutePacket(command, packetPath) {
+  if (typeof command !== "string" || typeof packetPath !== "string" || !packetPath) return command;
+  return command.replace(PACKET_PLACEHOLDER, () => `--packet ${shellToken(packetPath)}`);
+}
+
+// Whole-token match against the declared TEMPLATE, never the substituted
+// string: a packet path that happens to contain "--report" must not be
+// mistaken for an option the action declared, and a flag that merely shares
+// the prefix (say --report-format) is not the option itself.
+function templateDeclares(template, flag) {
+  return typeof template === "string" && template.split(/\s+/).includes(flag);
+}
+
+// The text an operator acts on: the runnable command with the packet
+// substituted, else the manual description, else nothing. With `reportPath`,
+// a packet-scoped command that does not already name a report gains
+// `--report <path>`, so a remediation acts on the report the inspection read
+// rather than on the default sidecar it would otherwise resolve.
+export function requiredActionText(action, { packetPath = null, reportPath = null } = {}) {
+  const template = typeof action?.command === "string" ? action.command : null;
+  let command = substitutePacket(template, packetPath);
+  if (command && reportPath && templateDeclares(template, "--packet") && !templateDeclares(template, "--report")) {
+    command = `${command} --report ${shellToken(reportPath)}`;
+  }
+  // Registry commands are stored bare; the printed text is spelled for the
+  // install this package runs from (bare from a checkout, `npx campaigns-os`
+  // from a campaign folder), once, here.
+  if (command && command.startsWith("campaigns-os ")) {
+    return `${invocationPrefixFor(PACKAGE_ROOT)} ${command.slice("campaigns-os ".length)}`;
+  }
+  if (command) return command;
+  return typeof action?.description === "string" && action.description ? action.description : null;
+}

package/src/html-scan.mjs

@@ -0,0 +1,53 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+// A synchronous doctor's snapshot ends with the invocation. No file contents
+// survive into another command, even when a host imports the CLI once and reuses it.
+const snapshots = new AsyncLocalStorage();
+const MAX_RETAINED_BYTES = 16 * 1024 * 1024;
+const MAX_RETAINED_FILES = 4096;
+export function withHtmlScanSnapshot(operation, { reuse = false } = {}) {
+  if (reuse && snapshots.getStore()?.active) return operation();
+  const snapshot = { files: new Map(), retainedBytes: 0, active: true };
+  return snapshots.run(snapshot, () => {
+    try {
+      return operation();
+    } finally {
+      // AsyncLocalStorage propagates to queued callbacks too. Expire the store
+      // at synchronous return, even if a future caller returns a Promise.
+      snapshot.active = false;
+      snapshot.files.clear();
+      snapshot.retainedBytes = 0;
+    }
+  });
+}
+
+function file(path) {
+  const snapshot = snapshots.getStore();
+  if (!snapshot?.active) return { bytes: readFileSync(path) };
+  const key = resolve(path);
+  if (snapshot.files.has(key)) return snapshot.files.get(key);
+  const entry = { bytes: readFileSync(path) };
+  // Budget buffer + worst-case decoded UTF-16 text together. Oversize files
+  // retain the original read-per-use behavior; tiny files are count-bounded.
+  const cost = entry.bytes.length * 3;
+  if (snapshot.files.size < MAX_RETAINED_FILES && snapshot.retainedBytes + cost <= MAX_RETAINED_BYTES) {
+    snapshot.files.set(key, entry);
+    snapshot.retainedBytes += cost;
+  }
+  return entry;
+}
+
+export function readHtmlScanText(path) {
+  const entry = file(path);
+  return entry.text ??= entry.bytes.toString('utf8');
+}
+
+// Byte-preserving generic digest; only an active read-only scan scope caches it.
+// Callers that write artifacts must hash outside that scope to observe new bytes.
+export function htmlScanDigest(path) {
+  const entry = file(path);
+  return entry.digest ??= createHash('sha256').update(entry.bytes).digest('hex');
+}