@nextcommerce/campaigns-os 1.41.2 → 1.43.2

package/src/qa-verdict-discovery.mjs

@@ -1,3 +1,4 @@
+import { resolveCampaignIdentity, localQaIdentifier } from "./spec-source-identity.mjs";
 // QA verdict discovery: the one walk over the local verdicts a campaign has
 // written, with the projections each reader needs.
 //
@@ -28,11 +29,20 @@ function qaVerdictSlug(packet) {
 // the slug as identity. A verdict is this campaign's when its campaign_slug
 // is one of them.
 export function qaVerdictIdentifiers(packet) {
+  if (packet?.spec?.local_spec_id != null) {
+    const identity = resolveCampaignIdentity(packet.spec);
+    return identity?.kind === "local_spec" ? [localQaIdentifier(identity.id)] : [];
+  }
   return [...new Set([optionalString(packet?.spec?.map_id), qaVerdictSlug(packet)].filter(Boolean))];
 }
 
 export function qaVerdictIdentityMatch(verdict, packet) {
   const slug = optionalString(verdict?.campaign_slug);
+  if (packet?.spec?.local_spec_id != null || verdict?.local_spec_id != null) {
+    const identity = resolveCampaignIdentity(packet?.spec);
+    return identity?.kind === "local_spec" && verdict?.local_spec_id === identity.id
+      && slug === localQaIdentifier(identity.id);
+  }
   return Boolean(slug) && qaVerdictIdentifiers(packet).includes(slug);
 }
 
@@ -174,6 +184,7 @@ export function qaVerdictCandidateScore(candidate, packet) {
   const mapId = optionalString(packet?.spec?.map_id);
   const slug = qaVerdictSlug(packet);
   let score = 0;
+  if (packet?.spec?.local_spec_id && qaVerdictIdentityMatch(verdict, packet)) score += 100;
   if (mapId && verdict.campaign_slug === mapId) score += 100;
   if (slug && verdict.campaign_slug === slug) score += 80;
   if (verdict.schema_version === "1.0" || verdict.schema_version === "campaigns-os-qa-verdict/v0") score += 10;

package/src/qa-verdict-publish.mjs

@@ -42,6 +42,7 @@ export const QA_VERDICT_PUBLISH_STATES = Object.freeze(["skipped", "ok", "failed
  * must not claim a credential is travelling in clear.
  */
 export async function publishQaVerdict(verdict, proxyBase, { fetchImpl = globalThis.fetch, remitImpl = remit } = {}) {
+  if (verdict?.local_spec_id != null) return { ...skippedQaVerdictPublish(), reason: "local_spec" };
   let httpStatus = null;
   let response = null;
   let failure = null;

package/src/qa-verdict.mjs

@@ -1,3 +1,4 @@
+import { resolveCampaignIdentity, localQaIdentifier } from "./spec-source-identity.mjs";
 export const QA_SCHEMA_VERSION = "1.0";
 
 export const STATUS = Object.freeze({
@@ -95,6 +96,7 @@ function dispositionWithCommercial(assertions, commercial) {
 export function createVerdict({
   runId,
   mapId,
+  localSpecId = null,
   publicRouteSlug = null,
   campaignRefId = null,
   specVersion,
@@ -126,7 +128,8 @@ export function createVerdict({
     run_id: runId,
     // campaign_slug carries the Map ID for schema back-compat; the true public
     // route slug rides alongside so consumers stop conflating the two.
-    campaign_slug: mapId,
+    campaign_slug: localSpecId ? localQaIdentifier(localSpecId) : mapId,
+    ...(localSpecId ? { local_spec_id: localSpecId } : {}),
     public_route_slug: optionalString(publicRouteSlug),
     campaign_ref_id: campaignRefId,
     spec_version: specVersion,
@@ -208,6 +211,10 @@ export function deriveExceptions(assertions = []) {
 
 export function validateVerdict(verdict) {
   const errors = [];
+  if (verdict?.local_spec_id != null && (!resolveCampaignIdentity({ local_spec_id: verdict.local_spec_id })
+    || verdict.campaign_slug !== localQaIdentifier(verdict.local_spec_id))) {
+    errors.push("Local-spec verdict requires a valid local_spec_id and its local QA identifier.");
+  }
   if (!verdict || typeof verdict !== "object" || Array.isArray(verdict)) {
     return ["verdict: must be an object"];
   }

package/src/readback.mjs

@@ -1187,6 +1187,7 @@ function renderIdentity(views, lines) {
     const spec = packet.spec || {};
     const campaign = packet.campaign || {};
     if (spec.map_id) entries.push(["map_id", spec.map_id, "build packet"]);
+    if (spec.local_spec_id) entries.push(["local_spec_id", spec.local_spec_id, "build packet"]);
     if (campaign.public_route_slug) {
       entries.push(["public_route_slug", campaign.public_route_slug, "build packet"]);
     }
@@ -1194,7 +1195,7 @@ function renderIdentity(views, lines) {
     if (assembly.template_family) entries.push(["template_family", assembly.template_family, "build packet"]);
   } else if (doctor) {
     const derived = doctor.derived || {};
-    for (const field of ["map_id", "public_route_slug", "template_family"]) {
+    for (const field of ["map_id", "local_spec_id", "public_route_slug", "template_family"]) {
       if (derived[field]) entries.push([field, derived[field], "doctor output"]);
     }
   }

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/source-html-intake.mjs

@@ -106,7 +106,7 @@ function declaredScopeSkip(page, { skipEntry = null, buildScope = null, manifest
       id: `dec_page_scope_${page.id}`,
       stage: "prepare_build",
       decision_type: "deterministic_derivation",
-      decision: `recorded CampaignSpec page "${page.id}" as template stock, declared out of source scope (${skipEntry ? "explicit source-html manifest skip entry" : 'CampaignSpec build_scope mode "partial"'}); the build stage materialises the page from ${familyLabel}'s stock page, and intake demands no design source for it`,
+      decision: `recorded CampaignSpec page "${page.id}" as template stock, declared out of source scope (${skipEntry ? "explicit source-html manifest skip entry" : 'CampaignSpec build_scope mode "partial"'}); keep the route unbuilt unless the operator opts in to materialising it from ${familyLabel}'s stock page; intake demands no design source for it`,
       confidence: "high",
       template_stock: true,
       template_family: family,

package/src/source-html-manifest.mjs

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 
@@ -95,10 +96,16 @@ export function readSourceHtmlManifestFile(sourceRoot, { manifestPath = null } =
   return { ...readManifestAt(resolvedPath), explicit: Boolean(explicit) };
 }
 
+// One read: the manifest is parsed from, and hashed over, the same bytes. An
+// edit that lands on disk after the read changes neither, so the sha256 a
+// consumer records always describes what was parsed (#501).
 function readManifestAt(manifestPath) {
   let manifest;
+  let sha256;
   try {
-    manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+    const bytes = readFileSync(manifestPath);
+    sha256 = createHash("sha256").update(bytes).digest("hex");
+    manifest = JSON.parse(bytes.toString("utf8"));
   } catch (error) {
     return {
       manifest: null,
@@ -125,7 +132,7 @@ function readManifestAt(manifestPath) {
   const warnings = (validation.warnings || []).map(
     (entry) => `Source-html manifest at ${manifestPath}: [${entry.code}] ${entry.message}`,
   );
-  return { manifest, path: manifestPath, warning: null, warnings, validation };
+  return { manifest, path: manifestPath, sha256, warning: null, warnings, validation };
 }
 
 function validateManifestPage(entry, index, add, addWarning = () => {}) {

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,7 +1,9 @@
+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";
 import { isPlainObject, normalizeString as optionalString } from "./repo-scan.mjs";
+import { withTargetLockSync } from "./target-lock.mjs";
 import {
   ASSEMBLY_REPORT_STAGE_KEYS,
   NEXT_STAGE_CONTRACTS,
@@ -377,7 +379,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);
 }
 
@@ -422,6 +426,16 @@ export function assemblyReportMatchesPacket(report, packet) {
  * (waivers, evidence merges) pass no `stage`: they require the report to
  * exist and bind its identity themselves.
  *
+ * The read-modify-write runs under the per-target writer lock that
+ * prepare-build holds (src/target-lock.mjs, #501), so a stage producer's edit
+ * never lands between prepare-build's pre-publish evidence re-check and its
+ * publication; inside prepare-build's own critical section it enters
+ * directly. A workspace without `targetRepo` (only possible with an explicit
+ * refreshDoctor and no stale stamp) names no target to lock and runs as is.
+ * `lockBudgetMs` bounds the wait (default: the target lock budget). A caller
+ * whose mutate always returns null (a preview) passes `lock: false`: it
+ * writes nothing, so it takes no lock and creates no lock files.
+ *
  * Returns `{ written, skipped, report, reportPath, doctorOutPath }` where
  * `skipped` is `null`, `"absent"`, `"identity"` or `"unchanged"` and `report`
  * is what is now on disk (the mutated report when written, else the one read,
@@ -432,6 +446,10 @@ export function commitAssemblyReport(workspace, mutate, {
   staleReason = null,
   command = null,
   stage = null,
+  lockBudgetMs,
+  // lock: false skips the target lock entirely; only for callers that write
+  // nothing (the waiver dry-run preview). A real commit must take the lock.
+  lock = true,
 } = {}) {
   const hasRefresh = typeof refreshDoctor === "function";
   const hasStale = typeof staleReason === "string" && staleReason.trim();
@@ -450,6 +468,19 @@ export function commitAssemblyReport(workspace, mutate, {
   if (hasRefresh && !doctorOutPath) throw new TypeError("commitAssemblyReport requires a workspace with doctorOutPath to refresh the doctor sidecar.");
   if (hasStale && !targetRepo) throw new TypeError("commitAssemblyReport requires a workspace with targetRepo to stamp the doctor sidecar stale.");
 
+  const commit = () => commitAssemblyReportUnderLock(workspace, mutate, {
+    refreshDoctor, staleReason, command, stage, hasRefresh, reportPath, doctorOutPath, targetRepo,
+  });
+  if (!targetRepo || lock === false) return commit();
+  return withTargetLockSync(targetRepo, commit, {
+    command: command.trim(),
+    ...(lockBudgetMs === undefined ? {} : { budgetMs: lockBudgetMs }),
+  });
+}
+
+function commitAssemblyReportUnderLock(workspace, mutate, {
+  refreshDoctor, staleReason, command, stage, hasRefresh, reportPath, doctorOutPath, targetRepo,
+}) {
   const outcome = { written: false, skipped: null, report: null, reportPath, doctorOutPath };
   const finish = () => {
     if (hasRefresh) {

package/src/target-lock.mjs

@@ -0,0 +1,54 @@
+// The per-target writer lock (#496, #501). prepare-build holds it from reading
+// its inputs through publishing the packet, context and report; the stage
+// writers (every commitAssemblyReport) hold it for their read-modify-write of
+// the Assembly Report, so no stage evidence lands between prepare-build's
+// pre-publish re-check and its rename. It lives beside the Design Source
+// Package, inside the input directory prepare-build's writes already cover.
+import { existsSync, mkdirSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { DESIGN_SOURCE_PACKAGE_REL_PATH } from "./design-source-package.mjs";
+import { withDirectoryLock, withDirectoryLockSync } from "./directory-lock.mjs";
+
+// Generous: a live holder is doing ordinary local work, and a holder that
+// died is recovered by pid.
+export const TARGET_LOCK_BUDGET_MS = 60000;
+
+export function targetLockPath(targetRepo) {
+  const designSourcePackagePath = resolve(targetRepo, DESIGN_SOURCE_PACKAGE_REL_PATH);
+  return join(dirname(designSourcePackagePath), `.${basename(designSourcePackagePath)}.lock`);
+}
+
+// `command` names the waiting command. The lock does not record which command
+// holds it, only a pid, so the holder is described generically. A lock with
+// no owner record is called out on its own: it is never taken over, and the
+// operator needs to know it will not clear by waiting.
+function unavailable(targetRepo, lockPath, command) {
+  return (error) => {
+    if (error?.code !== "EEXIST") {
+      return new Error(`${command} could not take the target lock at ${lockPath}${error?.code ? ` (${error.code})` : ""}: ${error?.message}`, { cause: error });
+    }
+    if (existsSync(lockPath) && !existsSync(join(lockPath, "owner.json"))) {
+      return new Error(
+        `${command}: the target lock at ${lockPath} has no owner record, so it is never taken over automatically `
+        + "(an older campaigns-os release or an interrupted run left it). "
+        + `Confirm no campaigns-os process is working on ${targetRepo}, then remove that lock directory and retry.`,
+      );
+    }
+    return new Error(
+      `${command}: another campaigns-os command is writing ${targetRepo} (lock ${lockPath}). `
+      + "Retry after it finishes. If a run was interrupted, confirm no campaigns-os process is working on this target before removing that lock directory.",
+    );
+  };
+}
+
+export function withTargetLock(targetRepo, fn, { command = "campaigns-os", budgetMs = TARGET_LOCK_BUDGET_MS } = {}) {
+  const lockPath = targetLockPath(targetRepo);
+  mkdirSync(dirname(lockPath), { recursive: true });
+  return withDirectoryLock(lockPath, fn, { budgetMs, unavailable: unavailable(targetRepo, lockPath, command) });
+}
+
+export function withTargetLockSync(targetRepo, fn, { command = "campaigns-os", budgetMs = TARGET_LOCK_BUDGET_MS } = {}) {
+  const lockPath = targetLockPath(targetRepo);
+  mkdirSync(dirname(lockPath), { recursive: true });
+  return withDirectoryLockSync(lockPath, fn, { budgetMs, unavailable: unavailable(targetRepo, lockPath, command) });
+}

package/src/template-brand-contract.mjs

@@ -327,6 +327,22 @@ export function paymentChromeAssetHashes(chrome, { label = "template brand contr
   return byBasename;
 }
 
+// The starter templates' payment-logos.html partial renders one
+// <img data-payment-logo="<method>"> per method and keeps it `hidden` until the
+// campaign offers that method (server render, then payment-logos.js on
+// next:initialized; payment_flags.show_<method>: true forces it visible). A
+// hidden logo is the template gating the method, not residue, so both the
+// static scan and browser QA drop those tags before matching. A visible one
+// (forced on, or revealed at runtime) stays in and is judged like any chrome.
+const PAYMENT_LOGO_IMG_TAG = /<img\b[^>]*\sdata-payment-logo\s*=[^>]*>/gi;
+// Boolean attribute: present with any value (hidden, hidden="", hidden="true", …) means hidden.
+const HIDDEN_ATTRIBUTE = /\shidden(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'=<>`]+))?(?=[\s/>])/i;
+
+export function withoutHiddenPaymentLogos(html) {
+  const text = typeof html === "string" ? html : "";
+  return text.replace(PAYMENT_LOGO_IMG_TAG, (tag) => (HIDDEN_ATTRIBUTE.test(tag) ? "" : tag));
+}
+
 // Pure, static: the markers in rendered checkout HTML that say a payment method
 // shipped. Three sources, in order of authority: the SDK-owned
 // data-next-payment-method attribute every starter-template payment-methods
@@ -338,7 +354,7 @@ export function paymentChromeAssetHashes(chrome, { label = "template brand contr
 // browser QA, which fetches them to attribute the mark; a static scan cannot
 // tell a paypal strip from a card-only one by its filename.
 export function paymentMethodMarkupMatches(html, method, chrome = null) {
-  const text = typeof html === "string" ? html : "";
+  const text = withoutHiddenPaymentLogos(html);
   const canonical = String(method || "").toLowerCase().replace(/[\s-]+/g, "_");
   if (!canonical) return [];
   const matches = [];

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,
+  ];
+}