@nextcommerce/campaigns-os 1.37.3 → 1.43.1

package/src/remit.mjs

@@ -81,6 +81,22 @@ export function assertSecureProxyBase(proxyBase, { label = "Remit", credential =
   throw new Error(`${label}: --proxy-base must be https (or a loopback host for local testing); declining to send ${subject} over ${url.protocol}//${url.host}.`);
 }
 
+/**
+ * The transport's OTHER precondition, checked before the destination gate: a
+ * fetch to send with. Exported because a preview must make it too — `qa
+ * publish --dry-run` and `run-record --dry-run` call this exact function, so a
+ * runtime without a global fetch refuses the dry path by the same message the
+ * real send throws, instead of previewing a POST that cannot be made.
+ * Throws; returns nothing. There is no default: the caller passes the fetch it
+ * would actually send with, so `assertFetchAvailable(undefined)` is a refusal
+ * rather than a silent fallback to the global that may not be there either.
+ */
+export function assertFetchAvailable(fetchImpl) {
+  if (typeof fetchImpl !== "function") {
+    throw new Error("Global fetch is not available. Upgrade to Node 18+ or pass fetchImpl.");
+  }
+}
+
 function byteLength(value) {
   return Buffer.byteLength(String(value), "utf8");
 }
@@ -158,9 +174,7 @@ export async function remit(path, payload, proxyBase, {
   credential = undefined,
   onResponse = null,
 } = {}) {
-  if (typeof fetchImpl !== "function") {
-    throw new Error("Global fetch is not available. Upgrade to Node 18+ or pass fetchImpl.");
-  }
+  assertFetchAvailable(fetchImpl);
   // What the gate says must match what this request actually carries. A caller
   // that names its credential wins; otherwise infer it from the headers this
   // module knows carry one (never from a bare Accept or Content-Type), so a

package/src/run-record-closeout.mjs

@@ -1,3 +1,4 @@
+import { campaignIdentitiesMatch } from "./spec-source-identity.mjs";
 // Run Record closeout recognition.
 //
 // `next` at stage "done" used to demand a Run Record unconditionally, because
@@ -93,13 +94,11 @@ function qaVerdictDigests(record) {
  * satisfy closeout — and `run-record` never re-emits under its id.
  */
 export function identityMatches(record, packet) {
-  const mapId = text(packet?.spec?.map_id);
   const slug = text(packet?.campaign?.public_route_slug);
   const identity = isObject(record?.identity) ? record.identity : {};
-  const recordMapId = text(identity.map_id);
   const recordSlug = text(identity.campaign_slug);
-  if (!mapId || !slug || !recordMapId || !recordSlug) return false;
-  return recordMapId === mapId && recordSlug === slug;
+  if (!slug || !recordSlug) return false;
+  return campaignIdentitiesMatch(identity, packet?.spec) && recordSlug === slug;
 }
 
 function outcome(reason_code, detail, entry = null) {

package/src/run-record.mjs

@@ -1,3 +1,4 @@
+import { localSpecIdentityFields, resolveCampaignIdentity } from "./spec-source-identity.mjs";
 // Run Telemetry — per-run Run Record capture for Campaigns OS.
 // See docs/workflow-findings-sidecar.md (Run Telemetry).
 //
@@ -155,6 +156,8 @@ export function validateRunRecord(record) {
   if (record.identity != null) {
     if (typeof record.identity !== "object" || Array.isArray(record.identity)) {
       add("record.identity", "identity must be an object when present.");
+    } else if (record.identity.local_spec_id != null && resolveCampaignIdentity(record.identity)?.kind !== "local_spec") {
+      add("record.identity.local_spec_id", "local_spec_id must be a canonical local ID with no saved Map identity.");
     }
   }
 
@@ -449,6 +452,7 @@ export function selectRunFindingIds(journal, runId) {
 function normalizeIdentity(identity = {}) {
   return {
     map_id: identity.map_id ?? null,
+    ...localSpecIdentityFields(identity),
     campaign_slug: identity.campaign_slug ?? null,
     template_family: identity.template_family ?? null,
     entry_point_shape: identity.entry_point_shape ?? null,

package/src/sidecar-bundle.mjs

@@ -84,6 +84,27 @@ function identityValuesAgree(identityField, left, right) {
 }
 
 function compareIdentity(errors, records, identityField) {
+  const local = identityField.local_spec_alternative;
+  if (local && records.get("build_packet")?.value?.spec?.local_spec_id != null) {
+    compareIdentity(errors, records, local);
+    // A local identity can never borrow a Map identity from another artifact.
+    for (const [kind, path] of Object.entries(identityField.artifact_paths)) {
+      if (kind === "qa_verdict") continue; // campaign_slug is the local QA storage key.
+      if (valueAt(records.get(kind)?.value, path) != null) {
+        errors.push(artifactFinding("bundle.identity.map_id_mismatch", kind,
+          "Local-spec bundle carries a saved Map identity.", "Regenerate artifacts from the same local CampaignSpec."));
+      }
+    }
+    return;
+  }
+  if (local) {
+    for (const [kind, path] of Object.entries(local.artifact_paths)) {
+      if (valueAt(records.get(kind)?.value, path) != null) {
+        errors.push(artifactFinding("bundle.identity.local_spec_id_mismatch", kind,
+          "Saved-Map bundle carries local-spec evidence.", "Regenerate artifacts from the same saved Map."));
+      }
+    }
+  }
   const label = identityField.name;
   const present = [];
   for (const [kind, path] of Object.entries(identityField.artifact_paths)) {

package/src/spec-source-identity.mjs

@@ -0,0 +1,44 @@
+// Stable campaign identity is separate from both the public route and the
+// material spec hash. Local IDs never identify a saved Map or a portal URL.
+export const LOCAL_SPEC_ID_PATTERN = "^[A-Za-z0-9_-]{1,64}$";
+const localIdPattern = new RegExp(LOCAL_SPEC_ID_PATTERN);
+const text = value => typeof value === "string" && value.trim() ? value.trim() : null;
+
+export function campaignSpecIdentity(spec) {
+  return {
+    map_id: spec?.spec_identity?.map_id ?? spec?.map_id ?? null,
+    local_spec_id: spec?.spec_identity?.local_spec_id ?? null,
+  };
+}
+
+export function resolveCampaignIdentity(fields) {
+  // Saved Map IDs retain their existing whitespace normalization. Local IDs
+  // are canonical, repository-owned tokens: never trim one into another ID.
+  const mapId = text(fields?.map_id);
+  const localId = fields?.local_spec_id;
+  if (localId != null) {
+    if (fields?.map_id != null || typeof localId !== "string" || !localIdPattern.test(localId)) return null;
+    return { kind: "local_spec", id: localId };
+  }
+  return mapId ? { kind: "saved_map", id: mapId } : null;
+}
+
+export function campaignIdentitiesMatch(left, right) {
+  const a = resolveCampaignIdentity(left);
+  const b = resolveCampaignIdentity(right);
+  return !!a && !!b && a.kind === b.kind && a.id === b.id;
+}
+
+export function localSpecIdentityFields(fields) {
+  if (fields?.local_spec_id == null) return {};
+  const identity = resolveCampaignIdentity(fields);
+  // Omitting a malformed marker would let a conflicting identity fall back to
+  // its Map ID. Writers must refuse it rather than silently change its kind.
+  if (identity?.kind !== "local_spec") throw new Error("Invalid local_spec_id or conflicting saved Map identity.");
+  return { local_spec_id: identity.id };
+}
+
+export function localQaIdentifier(localSpecId) {
+  if (typeof localSpecId !== "string" || !localIdPattern.test(localSpecId)) throw new Error("Invalid local_spec_id.");
+  return `local-spec-${localSpecId}`;
+}

package/src/stage-ledger.mjs

@@ -1,3 +1,4 @@
+import { campaignIdentitiesMatch } from "./spec-source-identity.mjs";
 import { existsSync, readFileSync } from "node:fs";
 import { markDoctorSidecarStale, writeDoctorSidecar, writeJsonAtomic } from "./doctor-sidecar.mjs";
 import { STATUS as QA_STATUS } from "./qa-verdict.mjs";
@@ -377,7 +378,9 @@ export function qaGatePassedForCurrentBuild(report, gate, { buildFingerprint })
  */
 export function assemblyReportMatchesPacket(report, packet) {
   return isPlainObject(report)
-    && optionalString(report?.identity?.map_id) === optionalString(packet?.spec?.map_id)
+    && (report?.identity?.local_spec_id != null || packet?.spec?.local_spec_id != null
+      ? campaignIdentitiesMatch(report?.identity, packet?.spec)
+      : optionalString(report?.identity?.map_id) === optionalString(packet?.spec?.map_id))
     && optionalString(report?.identity?.public_route_slug) === optionalString(packet?.campaign?.public_route_slug);
 }
 

package/src/tooling-setup.mjs

@@ -0,0 +1,160 @@
+import { existsSync, lstatSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+
+const PACKAGE = "@nextcommerce/campaigns-os";
+const CONTEXT = ".campaign-runtime/agent-context/CLAUDE.md";
+const IMPORT = `@${CONTEXT}`;
+
+// Setup composes the existing installers after npm has installed the project
+// dependencies. It never chooses a campaign, scaffolds pages, or opens a run.
+export function setupArguments(args, argv) {
+  const values = new Set(["target", "platform"]);
+  const flags = new Set(["dry-run", "json"]);
+  const seen = new Set();
+  const tokens = argv[0] === "campaigns-os" ? argv.slice(1) : argv;
+  for (let i = 2; i < tokens.length; i++) {
+    const token = tokens[i];
+    const key = token.startsWith("--") ? token.slice(2) : "";
+    if ((!values.has(key) && !flags.has(key)) || seen.has(key)) {
+      throw new Error(`tooling setup: unsupported or repeated argument ${JSON.stringify(token)}.`);
+    }
+    seen.add(key);
+    if (values.has(key)) {
+      if (!tokens[i + 1] || tokens[i + 1].startsWith("--")) throw new Error(`tooling setup: --${key} requires a value.`);
+      i++;
+    }
+  }
+  if (typeof args.target !== "string" || !args.target.trim()) throw new Error("tooling setup: select the campaign folder with --target <directory>.");
+  if (args.platform && args.platform !== "claude") throw new Error("tooling setup: this entry supports --platform claude. Other agents can use install-skills and install-agent-context.");
+}
+
+function json(path) {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+function hasContextImport(text) {
+  let fence = null;
+  let found = false;
+  for (const line of text.split(/\r?\n/)) {
+    const marker = line.match(/^ {0,3}(`{3,}|~{3,})(.*)$/);
+    if (fence) {
+      if (marker && marker[1][0] === fence[0] && marker[1].length >= fence.length && !marker[2].trim()) fence = null;
+    } else if (marker) {
+      fence = marker[1];
+    } else if (/^ {0,3}@/.test(line) && line.trim() === IMPORT) {
+      found = true;
+    }
+  }
+  if (!found && fence) throw new Error("tooling setup: close the unterminated code fence in CLAUDE.md before setup can append an active context import; no files were changed.");
+  return found;
+}
+
+function regularDestination(root, path) {
+  const rel = relative(root, path);
+  if (!rel || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    throw new Error(`tooling setup: destination must stay inside the selected project: ${path}.`);
+  }
+  const parts = rel.split(sep);
+  let current = root;
+  for (let i = 0; i < parts.length; i++) {
+    current = join(current, parts[i]);
+    let stat;
+    try { stat = lstatSync(current); } catch (error) {
+      // Every existing ancestor has already been checked. Once a component is
+      // absent, its descendants cannot exist; dangling symlinks still have lstat.
+      if (error.code === "ENOENT") return;
+      throw error;
+    }
+    if (stat.isSymbolicLink() || (i < parts.length - 1 ? !stat.isDirectory() : !stat.isFile())) {
+      throw new Error(`tooling setup: preserve ${current}; expected a regular ${i < parts.length - 1 ? "directory" : "file"}, not a symlink or another file type.`);
+    }
+  }
+}
+
+export function setupTooling(args, { packageRoot, installSkills, installAgentContext, installBrowser }) {
+  const target = realpathSync(resolve(args.target));
+  const pkg = json(join(packageRoot, "package.json"));
+  const manifestPath = join(target, "package.json");
+  const lockPath = join(target, "package-lock.json");
+  if (!existsSync(manifestPath)) {
+    throw new Error(`tooling setup: package.json is missing. For a new project, follow the pinned install in ${join(packageRoot, "docs/local-setup.md")}. For an existing project, restore its manifest and lockfile and run npm ci.`);
+  }
+  if (!existsSync(lockPath)) {
+    throw new Error("tooling setup: package-lock.json is missing. Restore the project's reviewed lockfile, or generate it from its existing dependency pins with npm install, then rerun setup. Do not replace the project's page-kit pin with a new-project example.");
+  }
+  const manifest = json(manifestPath);
+  const pins = [manifest.devDependencies?.[PACKAGE], manifest.dependencies?.[PACKAGE]].filter(Boolean);
+  if (!pins.length || pins.some((pin) => pin !== pkg.version)) {
+    throw new Error(`tooling setup: the project must pin ${PACKAGE} exactly to the running version ${pkg.version}; preserve its current pin or explicitly install the reviewed version first.`);
+  }
+  const installed = join(target, "node_modules", "@nextcommerce", "campaigns-os");
+  if (!existsSync(installed) || realpathSync(installed) !== realpathSync(packageRoot)) {
+    throw new Error("tooling setup: run the selected project's installed copy: cd into that folder and use npx --no-install campaigns-os tooling setup --target . --platform claude.");
+  }
+  const lock = json(lockPath);
+  if (lock.packages?.["node_modules/@nextcommerce/campaigns-os"]?.version !== pkg.version) {
+    throw new Error("tooling setup: the lockfile does not match the project toolkit pin; reconcile the reviewed dependency with npm before setup.");
+  }
+  if (!manifest.dependencies?.["next-campaign-page-kit"] && !manifest.devDependencies?.["next-campaign-page-kit"]) {
+    throw new Error("tooling setup: install next-campaign-page-kit in this project first. No campaign pages have been scaffolded or changed.");
+  }
+  if (!existsSync(join(target, "node_modules", "next-campaign-page-kit", "package.json"))) {
+    throw new Error("tooling setup: page-kit is declared but not installed; run npm ci in the selected project first.");
+  }
+
+  // Preflight every destination before any installer runs. Custom repository
+  // instructions are preserved; only one Claude import line is appended.
+  const instructions = join(target, "CLAUDE.md");
+  regularDestination(target, instructions);
+  regularDestination(target, join(target, ".gitignore"));
+  for (const name of ["CLAUDE.md", "AGENTS.md", "campaigns-os.mdc", "copilot-instructions.md"]) {
+    const dest = join(target, ".campaign-runtime", "agent-context", name);
+    regularDestination(target, dest);
+    const source = { "CLAUDE.md": "agents/claude/CLAUDE.md", "AGENTS.md": "agents/codex/AGENTS.md", "campaigns-os.mdc": "agents/cursor/campaigns-os.mdc", "copilot-instructions.md": "agents/copilot/copilot-instructions.md" }[name];
+    if (existsSync(dest) && readFileSync(dest, "utf8") !== readFileSync(join(packageRoot, source), "utf8")) {
+      throw new Error(`tooling setup: ${dest} differs from this toolkit's context. Preserve and reconcile it before rerunning setup; no files were changed.`);
+    }
+  }
+  const prior = existsSync(instructions) ? readFileSync(instructions, "utf8") : "";
+  const hasImport = hasContextImport(prior);
+  // Do the fallible download before changing the shared skills or project.
+  const browser = args["dry-run"] ? { ok: true, status: "not_run" } : installBrowser({ json: Boolean(args.json) });
+  const skills = browser.ok ? installSkills(null, Boolean(args["dry-run"]), "claude") : null;
+  const context = browser.ok ? installAgentContext(target, Boolean(args["dry-run"])) : null;
+  const contextFailed = context?.gitignore?.action === "skipped";
+  const ready = browser.ok && !contextFailed;
+  if (ready && !args["dry-run"] && !hasImport) {
+    writeFileSync(instructions, `${prior}${prior && !prior.endsWith("\n") ? "\n" : ""}\n${IMPORT}\n`);
+  }
+  const revision = json(join(packageRoot, "skills.json")).bundle_revision;
+  return {
+    ok: ready,
+    status: !browser.ok ? "browser_install_failed" : contextFailed ? "context_install_failed" : args["dry-run"] ? "dry_run" : "restart_required",
+    target_repo: target,
+    skills_revision: revision,
+    skills,
+    context,
+    instructions: { path: instructions, action: !ready ? "not_run" : hasImport ? "unchanged" : "append_import" },
+    browser,
+    next_action: contextFailed
+      ? `Setup could not add the runtime ignore block (${context.gitignore.reason}). Fix .gitignore and rerun setup; skills and context files may already be installed.`
+      : args["dry-run"]
+      ? "Run tooling setup with the same target and without --dry-run to install the browser, skills and agent context."
+      : browser.ok
+      ? `Restart Claude Code in this folder, then use the next-campaigns-os skill with your CampaignSpec and source material. Confirm the loaded bundle with npx --no-install campaigns-os tooling status --platform claude --skills-revision ${revision}.`
+      : "Fix the browser installation error and rerun tooling setup; existing page source and repository instructions are preserved.",
+    note: "Setup prepares tools; it does not scaffold pages, create a spec, select a campaign, log in, or prove that an agent loaded the installed skills.",
+  };
+}
+
+export function setupTextLines(result) {
+  return [
+    `Status: ${result.status.toUpperCase()}`,
+    `Campaign folder: ${result.target_repo}`,
+    `Skills revision: ${result.skills_revision}`,
+    `Browser: ${result.browser.status}`,
+    ...(result.browser.note ? [result.browser.note] : []),
+    result.next_action,
+    result.note,
+  ];
+}