@nextcommerce/campaigns-os 1.33.0

package/src/run-session.mjs

@@ -0,0 +1,226 @@
+// Run Telemetry — ambient run session for Campaigns OS.
+// See docs/workflow-findings-sidecar.md (Run Telemetry).
+//
+// A run session makes telemetry AMBIENT: `run start` writes one small file to
+// the project's .campaign-runtime/, and every subsequent command auto-discovers
+// it (walking up from cwd) to share one run_id and one lifecycle journal —
+// WITHOUT the operator threading --run-id / --lifecycle-journal on each call.
+// `run end` assembles the aggregated Run Record and clears the session. This is
+// the experience for "talk to your agent and build": the agent runs `run start`
+// once, builds, then `run end`. No flag bookkeeping.
+//
+// The session file is transient, machine-local, and lives under the
+// scrubber-ignored .campaign-runtime/. No network, no credentials.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { homedir } from "node:os";
+import { dirname, join, parse, resolve, sep } from "node:path";
+
+import { LIFECYCLE_JOURNAL_REL_PATH } from "./lifecycle.mjs";
+import { sameFile } from "./fs-identity.mjs";
+
+export const RUN_SESSION_SCHEMA = "campaigns-os-run-session/v0";
+export const RUN_SESSION_REL_PATH = ".campaign-runtime/run-session.json";
+export const RUN_SESSION_TTL_MS = 12 * 60 * 60 * 1000;
+
+// Files that mark a project root. Session discovery never climbs ABOVE the
+// nearest project root, so a stray session in an unrelated ancestor (e.g.
+// $HOME or a shared /tmp) can't hijack commands run inside a real project.
+const PROJECT_ROOT_MARKERS = [".git", "package.json"];
+
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function isProjectRoot(dir) {
+  return PROJECT_ROOT_MARKERS.some((marker) => existsSync(join(dir, marker)));
+}
+
+/** Canonical session path for a project root: <root>/.campaign-runtime/run-session.json */
+export function resolveRunSessionPath(rootDir = process.cwd()) {
+  return join(resolve(rootDir), RUN_SESSION_REL_PATH);
+}
+
+/**
+ * Walk up from `cwd` to find an active run session, so commands run from a
+ * subdirectory still share the project's session. Best-effort: never throws; a
+ * missing or malformed session file simply means "no active session".
+ * Returns `{ session, path, dir }` or null.
+ *
+ * Scope is bounded to the project to prevent a stray ancestor session from
+ * hijacking unrelated commands:
+ *  - the walk STOPS at the nearest project root (a dir with .git/package.json),
+ *    so a session in an ancestor ABOVE the project is never adopted;
+ *  - a session located at $HOME, ANY ancestor of $HOME (e.g. /Users), or the
+ *    filesystem root is never honored — those are shared dirs, not project roots.
+ *
+ * `home` is injectable for tests.
+ */
+export function isRunSessionStale(session, { now = new Date(), ttlMs = RUN_SESSION_TTL_MS } = {}) {
+  if (!session || typeof session !== "object" || Array.isArray(session)) return false;
+  if (!Number.isFinite(ttlMs) || ttlMs < 0) return false;
+  const activity = isNonEmptyString(session.updated_at) ? session.updated_at : session.started_at;
+  const timestamp = Date.parse(activity || "");
+  if (!Number.isFinite(timestamp)) return false;
+  return now.getTime() - timestamp > ttlMs;
+}
+
+export function isRunSessionTerminal(session) {
+  if (!session || typeof session !== "object" || Array.isArray(session)) return false;
+  return session.terminal === true
+    || session.status === "terminal";
+}
+
+export function findRunSession(cwd = process.cwd(), { home = homedir(), now = new Date(), ttlMs = RUN_SESSION_TTL_MS } = {}) {
+  let dir = resolve(cwd);
+  const { root } = parse(dir);
+  const resolvedHome = resolve(home);
+  // True when `dir` is $HOME itself or a strict ancestor of it (e.g. /Users).
+  const isHomeOrAncestor = (d) => d === resolvedHome || resolvedHome.startsWith(d + sep);
+  for (let depth = 0; depth < 64; depth += 1) {
+    const candidate = join(dir, RUN_SESSION_REL_PATH);
+    if (existsSync(candidate)) {
+      // A session at the filesystem root, $HOME, or an ancestor of $HOME is not
+      // a project session — honoring it would capture every command beneath it.
+      if (dir === root || isHomeOrAncestor(dir)) return null;
+      try {
+        const session = JSON.parse(readFileSync(candidate, "utf8"));
+        if (session && typeof session === "object" && !Array.isArray(session) && isNonEmptyString(session.run_id) && !isRunSessionStale(session, { now, ttlMs })) {
+          return { session, path: candidate, dir };
+        }
+      } catch {
+        // malformed session file => treat as no active session
+      }
+      return null;
+    }
+    // Don't climb past the project boundary: the session must live within the
+    // project being built, not in an unrelated ancestor directory.
+    if (isProjectRoot(dir)) break;
+    if (dir === root) break;
+    dir = dirname(dir);
+  }
+  return null;
+}
+
+/**
+ * The session file at `rootDir` when it exists but is STALE (idle past the
+ * TTL). findRunSession deliberately ignores such a file so a new work session
+ * never inherits an old run_id — but ignoring it also meant abandoning it: the
+ * file lingered, its lifecycle journal was never assembled into a Run Record,
+ * and nothing was ever remitted for that run. Callers that are about to open a
+ * new session (start / prepare-build / run start) use this to close the old
+ * one out first. Exact-path only, no upward walk: sweeping is a write, and it
+ * must never reach into an ancestor project. Never throws.
+ */
+export function findStaleRunSession(rootDir = process.cwd(), { home = homedir(), now = new Date(), ttlMs = RUN_SESSION_TTL_MS } = {}) {
+  const dir = resolve(rootDir);
+  // Same boundary findRunSession enforces: the filesystem root, $HOME, or an
+  // ancestor of $HOME is a shared directory, never a project — and this
+  // caller goes on to assemble, remit, and delete.
+  const { root } = parse(dir);
+  const resolvedHome = resolve(home);
+  if (dir === root || dir === resolvedHome || resolvedHome.startsWith(dir + sep)) return null;
+  const path = resolveRunSessionPath(dir);
+  if (!existsSync(path)) return null;
+  try {
+    const session = JSON.parse(readFileSync(path, "utf8"));
+    if (!session || typeof session !== "object" || Array.isArray(session) || !isNonEmptyString(session.run_id)) return null;
+    if (!isRunSessionStale(session, { now, ttlMs })) return null;
+    return { session, path, dir: resolve(rootDir) };
+  } catch {
+    return null;
+  }
+}
+
+/** Mint the session's canonical run_id (same shape as the run-record minter). */
+export function mintSessionRunId(now = new Date()) {
+  return `run_${now.getTime()}_${randomBytes(4).toString("hex")}`;
+}
+
+/** Build the session object (its own schema_version, the run_id, the journal it owns, an optional packet, and a timestamp). */
+export function buildRunSession({ runId, lifecycleJournal, packet = null, now = new Date() }) {
+  const createdAt = now.toISOString();
+  return {
+    schema_version: RUN_SESSION_SCHEMA,
+    run_id: runId,
+    lifecycle_journal: lifecycleJournal,
+    packet: isNonEmptyString(packet) ? packet : null,
+    started_at: createdAt,
+    updated_at: createdAt,
+  };
+}
+
+/** Atomically write the session file under <rootDir>/.campaign-runtime/. */
+export function writeRunSession(rootDir, session) {
+  const path = resolveRunSessionPath(rootDir);
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(session, null, 2)}\n`);
+  renameSync(tmp, path);
+  return path;
+}
+
+/** Remove the active session file so the next `run start` is clean. Non-fatal. */
+export function clearRunSession(sessionPath) {
+  try {
+    rmSync(sessionPath, { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Is this session `packetPath`'s? A session records the packet it was opened
+// for; one opened with none is every packet's. The comparison is on the real
+// path, so a packet reached through a symlinked checkout and the same file
+// reached directly are one packet. `boundPacket` is returned for the caller's
+// message when the answer is no.
+export function sessionBoundTo(session, packetPath) {
+  const boundPacket = isNonEmptyString(session?.packet) ? session.packet : null;
+  if (!boundPacket) return { same: true, boundPacket };
+  if (!isNonEmptyString(packetPath)) return { same: false, boundPacket };
+  return { same: sameFile(boundPacket, packetPath), boundPacket };
+}
+
+
+/**
+ * Open a run session at `rootDir`, or join the one already there. The two
+ * openers — `run start` and the auto-start behind `start`/`prepare-build` —
+ * write the same session and differ only in what an already-open one means:
+ * `run start` refuses it unless `force` replaces it; the auto-start joins it
+ * when it is bound to this packet (`join`) and stands off when it is bound to
+ * another. Returns `{ found, joined, existing, binding }`: `found` is the open
+ * session as findRunSession reports it ({ session, path, dir }) or null when
+ * the existing one could not be joined, in which case `existing` is that
+ * session and `binding` says which packet holds it. Nothing is written on a
+ * join or a refusal.
+ */
+export function openRunSession(rootDir, {
+  runId = null,
+  lifecycleJournal = null,
+  packet = null,
+  lastRecommendation = null,
+  join: joinExisting = false,
+  force = false,
+  now = new Date(),
+} = {}) {
+  const dir = resolve(rootDir);
+  const existing = force ? null : findRunSession(dir, { now });
+  if (existing) {
+    const binding = sessionBoundTo(existing.session, packet);
+    if (joinExisting && binding.same) return { found: existing, joined: true, existing: null, binding };
+    return { found: null, joined: false, existing, binding };
+  }
+  const session = {
+    ...buildRunSession({
+      runId: runId || mintSessionRunId(now),
+      lifecycleJournal: lifecycleJournal || join(dir, LIFECYCLE_JOURNAL_REL_PATH),
+      packet: isNonEmptyString(packet) ? resolve(packet) : null,
+      now,
+    }),
+    ...(lastRecommendation ? { last_recommendation: lastRecommendation } : {}),
+  };
+  const path = writeRunSession(dir, session);
+  return { found: { session, path, dir }, joined: false, existing: null, binding: null };
+}

package/src/runtime-state-ignore.mjs

@@ -0,0 +1,113 @@
+// Which .campaign-runtime/ entries are meant for the campaign repository's git
+// history, and which are not. Three kinds share the directory:
+//
+//   1. The readback bundle (build-context, assembly-report, doctor-output,
+//      qa-verdict) — current readback truth; docs/migration-sidecar-bundle.md
+//      names it and `bundle check` validates it. Committed by design.
+//   2. Handoff inputs and agent context (input/, theme/, agent-context/,
+//      setup-handoff.json) — durable build handoff. Committed by design.
+//   3. Telemetry, sessions, caches, and evidence — per-machine, append-only,
+//      or carrying live URLs and absolute paths. Never meant for the repo, and
+//      nothing wrote a rule for them: three campaign repositories were found
+//      carrying another operator's run-session.json (absolute home path and
+//      all), lifecycle journals, and deviation logs.
+//
+// This module writes the rule for kind 3, once, into the target's .gitignore.
+// A deny-list by name rather than "ignore the directory, re-include the
+// bundle": git cannot re-include a file beneath an ignored directory, and a
+// new sidecar should default to visible so someone has to decide about it.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+export const RUNTIME_STATE_IGNORE_MARKER = "# campaigns-os: machine-local runtime state (managed block; edit the list, keep the marker)";
+
+export const RUNTIME_STATE_IGNORED_PATHS = [
+  ".campaign-runtime/run-session.json",
+  ".campaign-runtime/command-lifecycle.jsonl",
+  ".campaign-runtime/agent-deviations.jsonl",
+  ".campaign-runtime/workflow-findings.jsonl",
+  ".campaign-runtime/run-records/",
+  ".campaign-runtime/fetched-specs/",
+  ".campaign-runtime/polish-evidence/",
+  ".campaign-runtime/evidence/",
+  // Full QA verdicts carry live storefront URLs and order references; the
+  // committed form is the .campaign-runtime/qa-verdict.json projection.
+  "qa-output/",
+  ".campaign-runtime/*.log",
+  ".campaign-runtime/*.tmp",
+  ".campaign-runtime/**/*.tmp",
+];
+
+// Entries the toolkit adds to an existing managed block when they are
+// missing from the file. The block is otherwise the operator's to edit, but
+// these name directories the toolkit itself fills with live URLs and order
+// references, so a target set up before the entry existed must gain it on the
+// next setup command rather than on the next accidental commit. An entry an
+// operator has placed anywhere else in the file counts as present.
+export const RUNTIME_STATE_REQUIRED_IGNORED_PATHS = ["qa-output/"];
+
+export const RUNTIME_STATE_IGNORE_BLOCK = [
+  RUNTIME_STATE_IGNORE_MARKER,
+  "# Sessions, journals, Run Records, spec caches, capture evidence, and full",
+  "# QA verdicts are per-machine. The readback bundle (build-context, assembly-report,",
+  "# doctor-output, qa-verdict), input/, theme/, and agent-context/ are meant",
+  "# to be committed and are deliberately not listed here.",
+  ...RUNTIME_STATE_IGNORED_PATHS,
+].join("\n");
+
+function ignoreRuleLines(text) {
+  return new Set(text.split("\n").map((line) => line.trim()).filter((line) => line && !line.startsWith("#")));
+}
+
+// Append the missing required entries at the end of the managed block: after
+// the marker, up to the first blank line or the end of the file.
+function withRequiredEntries(existing, missing) {
+  const lines = existing.split("\n");
+  const markerIndex = lines.findIndex((line) => line.trim() === RUNTIME_STATE_IGNORE_MARKER);
+  let end = markerIndex + 1;
+  while (end < lines.length && lines[end].trim() !== "") end += 1;
+  lines.splice(end, 0, ...missing);
+  return lines.join("\n");
+}
+
+/**
+ * Ensure the target's .gitignore carries the runtime-state block. Idempotent
+ * on the marker line: an existing block, however edited beneath it, is left
+ * alone — except for RUNTIME_STATE_REQUIRED_IGNORED_PATHS, which are appended
+ * to an existing block when the file carries them nowhere. Never throws for
+ * an unwritable target — the build must not fail on housekeeping — but
+ * reports what happened so callers can surface it.
+ * Returns `{ path, action: "added" | "updated" | "present" | "skipped", reason?, added_entries? }`.
+ */
+export function ensureRuntimeStateIgnored(targetRepo, { dryRun = false } = {}) {
+  const path = join(resolve(targetRepo), ".gitignore");
+  let existing = "";
+  if (existsSync(path)) {
+    try {
+      existing = readFileSync(path, "utf8");
+    } catch (error) {
+      return { path, action: "skipped", reason: `unreadable: ${error.message}` };
+    }
+    if (existing.includes(RUNTIME_STATE_IGNORE_MARKER)) {
+      const present = ignoreRuleLines(existing);
+      const missing = RUNTIME_STATE_REQUIRED_IGNORED_PATHS.filter((entry) => !present.has(entry));
+      if (missing.length === 0) return { path, action: "present" };
+      if (dryRun) return { path, action: "updated", dry_run: true, added_entries: missing };
+      try {
+        writeFileSync(path, withRequiredEntries(existing, missing));
+      } catch (error) {
+        return { path, action: "skipped", reason: `unwritable: ${error.message}` };
+      }
+      return { path, action: "updated", added_entries: missing };
+    }
+  }
+  if (dryRun) return { path, action: "added", dry_run: true };
+  const separator = existing.length === 0 || existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+  try {
+    writeFileSync(path, `${existing}${separator}${RUNTIME_STATE_IGNORE_BLOCK}\n`);
+  } catch (error) {
+    return { path, action: "skipped", reason: `unwritable: ${error.message}` };
+  }
+  return { path, action: "added" };
+}

package/src/sdk-attribute-index.mjs

@@ -0,0 +1,212 @@
+// The Campaign Cart SDK attribute index, vendored for the static SDK markup
+// checks (#303).
+//
+// Source: docs/attribute-index.md in NextCommerceCo/campaign-cart at tag
+// v0.4.38 (the SDK pin every certified starter family ships today), which is
+// generated from the feature manifests. Only the data-next-* names are kept:
+// the checks that read this list ask "does the SDK read this data-next-*
+// attribute at all", and the SDK's other attribute families (data-item-*,
+// data-package-*, plain data-*) are not what an agent kit misspells.
+//
+// This is a hardcoded copy and says so, rather than restating the SDK in
+// prose that then drifts (the partner kit's mistake): the list is regenerated
+// whole from the index at a named tag, never edited by hand.
+//
+//   git -C ../campaign-cart show v0.4.38:docs/attribute-index.md \
+//     | grep -oE '`data-[a-z0-9-]+(\s*/\s*data-[a-z0-9-]+)*`' \
+//     | tr -d '`' | tr '/' '\n' | tr -d ' ' | grep '^data-next-' | sort -u
+//
+// A name ending in "-" (data-next-class-) is a prefix the SDK reads with any
+// suffix.
+
+export const SDK_ATTRIBUTE_INDEX_VERSION = "0.4.38";
+
+export const SDK_DATA_NEXT_ATTRIBUTES = Object.freeze([
+  "data-next-accordion",
+  "data-next-accordion-panel",
+  "data-next-accordion-text",
+  "data-next-accordion-trigger",
+  "data-next-action",
+  "data-next-active",
+  "data-next-await",
+  "data-next-bump",
+  "data-next-bundle-card",
+  "data-next-bundle-display",
+  "data-next-bundle-id",
+  "data-next-bundle-items",
+  "data-next-bundle-name",
+  "data-next-bundle-price",
+  "data-next-bundle-qty-for",
+  "data-next-bundle-selector",
+  "data-next-bundle-selector-id",
+  "data-next-bundle-slot-template",
+  "data-next-bundle-slot-template-id",
+  "data-next-bundle-slots",
+  "data-next-bundle-slots-for",
+  "data-next-bundle-template",
+  "data-next-bundle-template-id",
+  "data-next-bundle-vouchers",
+  "data-next-bundles",
+  "data-next-cart-item-id",
+  "data-next-cart-items",
+  "data-next-cart-selector",
+  "data-next-cart-summary",
+  "data-next-checkout",
+  "data-next-checkout-field",
+  "data-next-checkout-payment",
+  "data-next-checkout-review",
+  "data-next-checkout-step",
+  "data-next-checkout-submit",
+  "data-next-class-",
+  "data-next-clear-cart",
+  "data-next-component",
+  "data-next-component-location",
+  "data-next-confirm",
+  "data-next-confirm-message",
+  "data-next-coupon",
+  "data-next-default-property",
+  "data-next-discounts",
+  "data-next-display",
+  "data-next-enhancer",
+  "data-next-error-for",
+  "data-next-exclude-property",
+  "data-next-express-checkout",
+  "data-next-fallback",
+  "data-next-format",
+  "data-next-hide",
+  "data-next-id",
+  "data-next-in-cart",
+  "data-next-include-shipping",
+  "data-next-is-upsell",
+  "data-next-item-properties",
+  "data-next-loading",
+  "data-next-max-quantity",
+  "data-next-min-quantity",
+  "data-next-multiply-quantity",
+  "data-next-next-url",
+  "data-next-order-items",
+  "data-next-package",
+  "data-next-package-id",
+  "data-next-package-price",
+  "data-next-package-selector",
+  "data-next-package-selector-id",
+  "data-next-package-sync",
+  "data-next-package-template",
+  "data-next-package-template-id",
+  "data-next-package-toggle",
+  "data-next-packages",
+  "data-next-payment-form",
+  "data-next-payment-method",
+  "data-next-payment-state",
+  "data-next-product-sync",
+  "data-next-property",
+  "data-next-property-container",
+  "data-next-quantity",
+  "data-next-quantity-decrease",
+  "data-next-quantity-display",
+  "data-next-quantity-increase",
+  "data-next-quantity-selector-id",
+  "data-next-quantity-text",
+  "data-next-remove-item",
+  "data-next-required",
+  "data-next-scroll-target",
+  "data-next-scroll-threshold",
+  "data-next-sdk-loading",
+  "data-next-selected",
+  "data-next-selection-mode",
+  "data-next-selector-card",
+  "data-next-selector-id",
+  "data-next-shipping-id",
+  "data-next-show",
+  "data-next-slot-index",
+  "data-next-step-number",
+  "data-next-timer",
+  "data-next-timer-display",
+  "data-next-timer-expired",
+  "data-next-toggle",
+  "data-next-toggle-card",
+  "data-next-toggle-container",
+  "data-next-toggle-display",
+  "data-next-toggle-image",
+  "data-next-toggle-price",
+  "data-next-toggle-template",
+  "data-next-toggle-template-id",
+  "data-next-tooltip",
+  "data-next-tooltip-class",
+  "data-next-tooltip-delay",
+  "data-next-tooltip-max-width",
+  "data-next-tooltip-offset",
+  "data-next-tooltip-placement",
+  "data-next-tracking-tag",
+  "data-next-upsell",
+  "data-next-upsell-action",
+  "data-next-upsell-action-for",
+  "data-next-upsell-context",
+  "data-next-upsell-item",
+  "data-next-upsell-option",
+  "data-next-upsell-quantity",
+  "data-next-upsell-quantity-toggle",
+  "data-next-upsell-section",
+  "data-next-upsell-select",
+  "data-next-upsell-selector",
+  "data-next-url",
+  "data-next-validate",
+  "data-next-variant-code",
+  "data-next-variant-option",
+  "data-next-variant-option-template-id",
+  "data-next-variant-options",
+  "data-next-variant-selector-template-id",
+  "data-next-variant-selectors",
+]);
+
+// The fixed data-next-checkout-field names, from the same tag. The SDK maps a
+// field to the order by this value, so an unlisted name is a silent no-op: the
+// input renders, the shopper fills it, nothing reaches the order. Sources at
+// v0.4.38: src/features/checkout/README.md ("Standard field names"), the
+// checkout-form enhancer and its validation/persistence tables, the hosted
+// payment field slots (cc-number, cvv, cc-month/cc-year and their exp-*
+// spellings), payment-method, and accepts_marketing. Billing fields are the
+// same names behind a "billing-" prefix and the SDK passes any billing-*
+// suffix through (billing-field-routing.ts), so the prefix is accepted with
+// any suffix rather than enumerated.
+export const SDK_CHECKOUT_FIELD_NAMES = Object.freeze([
+  "email",
+  "fname",
+  "lname",
+  "phone",
+  "address1",
+  "address2",
+  "city",
+  "province",
+  "postal",
+  "country",
+  "payment-method",
+  "accepts_marketing",
+  "cc-number",
+  "cc-month",
+  "cc-year",
+  "exp-month",
+  "exp-year",
+  "cvv",
+  // Legacy spellings the README at v0.4.38 still lists.
+  "card-number",
+  "card-expiry",
+  "card-cvv",
+  "card-name",
+]);
+
+export const SDK_CHECKOUT_FIELD_PREFIXES = Object.freeze(["billing-"]);
+
+const exact = new Set(SDK_DATA_NEXT_ATTRIBUTES.filter((name) => !name.endsWith("-")));
+const prefixes = SDK_DATA_NEXT_ATTRIBUTES.filter((name) => name.endsWith("-"));
+
+export function isIndexedSdkAttribute(name) {
+  const value = String(name || "").toLowerCase();
+  return exact.has(value) || prefixes.some((prefix) => value.startsWith(prefix) && value.length > prefix.length);
+}
+
+export function isKnownCheckoutFieldName(value) {
+  const name = String(value ?? "");
+  return SDK_CHECKOUT_FIELD_NAMES.includes(name)
+    || SDK_CHECKOUT_FIELD_PREFIXES.some((prefix) => name.startsWith(prefix) && name.length > prefix.length);
+}