@nextcommerce/campaigns-os 1.33.0

package/src/orchestration-stage-contract.mjs

@@ -0,0 +1,81 @@
+export const ASSEMBLY_REPORT_STAGE_KEYS = Object.freeze([
+  "prepare_build",
+  "doctor",
+  "setup",
+  "assembly",
+  "polish",
+  "deploy",
+  "qa",
+]);
+
+export const NEXT_STAGE_CONTRACTS = Object.freeze([
+  Object.freeze({
+    cliStage: "setup",
+    reportKey: "setup",
+  }),
+  Object.freeze({
+    cliStage: "build",
+    reportKey: "assembly",
+  }),
+  Object.freeze({
+    cliStage: "polish",
+    reportKey: "polish",
+  }),
+  Object.freeze({
+    cliStage: "deploy",
+    reportKey: "deploy",
+  }),
+  Object.freeze({
+    cliStage: "qa",
+    reportKey: "qa",
+  }),
+]);
+
+export const NEXT_STAGE_ORDER = Object.freeze(NEXT_STAGE_CONTRACTS.map((contract) => contract.cliStage));
+
+const NEXT_STAGE_BY_CLI_STAGE = new Map(
+  NEXT_STAGE_CONTRACTS.map((contract) => [contract.cliStage, contract])
+);
+
+export function nextStageContractForCliStage(cliStage) {
+  return NEXT_STAGE_BY_CLI_STAGE.get(String(cliStage || "")) || null;
+}
+
+export function reportKeyForCliStage(cliStage) {
+  return nextStageContractForCliStage(cliStage)?.reportKey || null;
+}
+
+/**
+ * Status values that count as terminal under PREFIX matching — so
+ * "completed", "completed_with_warnings", and "completed_partial" all
+ * count as terminal under "completed". This matches how the existing
+ * stages already report sub-statuses (see report.stages.assembly.status
+ * shapes in src/cli.mjs and qa/shared/qa-verdict.js). Shared here so the
+ * `next` picker, the session progress summary and the Assembly Report's own
+ * derived summary (src/stage-ledger.mjs) read one definition of "done".
+ */
+export const STAGE_TERMINAL_STATUS_PREFIXES = Object.freeze(["completed", "skipped"]);
+
+export function stageIsTerminal(status) {
+  const normalized = String(status || "");
+  return STAGE_TERMINAL_STATUS_PREFIXES.some((prefix) => normalized.startsWith(prefix));
+}
+
+export function stageIsBlocked(status) {
+  return String(status || "") === "blocked";
+}
+
+// Owner and skill for each stage the picker can name. The doctor's `next`
+// block and the Assembly Report's `next` block are both projections of the
+// same ladder the `next` command walks, so all three spell a stage, its owner
+// and its skill the same way.
+export const NEXT_STAGE_OWNERS = Object.freeze({
+  "prepare-build": Object.freeze({ owner: "operator", default_skill: "next-campaigns-os" }),
+  "doctor-blocked": Object.freeze({ owner: "operator", default_skill: "next-campaigns-os" }),
+  setup: Object.freeze({ owner: "setup", default_skill: "next-campaigns-os-setup" }),
+  build: Object.freeze({ owner: "build", default_skill: "next-campaigns-build" }),
+  polish: Object.freeze({ owner: "polish", default_skill: "next-campaigns-polish" }),
+  deploy: Object.freeze({ owner: "operator", default_skill: "next-campaigns-os" }),
+  qa: Object.freeze({ owner: "qa", default_skill: "next-campaigns-qa" }),
+  done: Object.freeze({ owner: "qa", default_skill: "next-campaigns-os" }),
+});

package/src/package-install-fixture.mjs

@@ -0,0 +1,33 @@
+// Test fixture: a REAL package install of this checkout, staged under a
+// temporary install root, so a test can run the CLI the way a consumer's
+// `npx campaigns-os …` does (install mode detected from the enclosing
+// node_modules, pinned commit read from the lockfile npm would have written).
+// Shared by the tooling-status and page-kit sync suites; not part of the
+// supported surface.
+import { cpSync, mkdirSync, symlinkSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = resolve(fileURLToPath(new URL("..", import.meta.url)));
+
+export const PIN_SHA = "236d7fc454c877e3c07337237ee9e19303c5cc15";
+
+export function stageRealPackageInstall(installRoot) {
+  const pkgRoot = join(installRoot, "node_modules", "@nextcommerce", "campaigns-os");
+  mkdirSync(pkgRoot, { recursive: true });
+  for (const entry of ["agents", "bin", "src", "campaign-spec", "contracts", "schemas", "skills", "skills.json", "package.json"]) {
+    cpSync(join(ROOT, entry), join(pkgRoot, entry), { recursive: true, dereference: true });
+  }
+  symlinkSync(join(ROOT, "node_modules"), join(pkgRoot, "node_modules"), "dir");
+  writeFileSync(join(installRoot, "node_modules", ".package-lock.json"), JSON.stringify({
+    name: "npx",
+    lockfileVersion: 3,
+    packages: {
+      "node_modules/@nextcommerce/campaigns-os": {
+        version: "0.1.0-alpha.0",
+        resolved: `git+ssh://git@github.com/NextCommerceCo/campaigns-os.git#${PIN_SHA}`,
+      },
+    },
+  }));
+  return pkgRoot;
+}

package/src/page-kit-build-summary.mjs

@@ -0,0 +1,175 @@
+// Page Kit build summary gate: consumes the machine-readable summary that
+// `campaign-build --json` (next-campaign-page-kit >= 0.1.4) emits, so doctor
+// verifies what Page Kit actually built — resolved routes, per-page status,
+// and shape warnings — instead of only inspecting rendered _site HTML.
+//
+// Doctrine: dogfood runs on pre-assembled AI HTML never tripped Page Kit
+// routing surprises (NESTED_NO_PERMALINK, DUPLICATE_OUTPUT) because those
+// pages were hand-tuned to be correct. Real designer-exported source will
+// trip them. The build step must capture the summary as an artifact:
+//
+//   npx campaign-build --json > .campaign-runtime/page-kit-build-summary.json
+//
+// and this module turns that artifact into doctor issues every consumer
+// (next, doctor, qa) shares. A missing artifact is a warning, not a block,
+// so target repos on page-kit < 0.1.4 keep working while the fleet upgrades.
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+export const PAGE_KIT_BUILD_SUMMARY_REL_PATH = ".campaign-runtime/page-kit-build-summary.json";
+export const PAGE_KIT_BUILD_SUMMARY_CAPTURE_COMMAND = `npx campaign-build --json > ${PAGE_KIT_BUILD_SUMMARY_REL_PATH}`;
+export const PAGE_KIT_BUILD_SUMMARY_MIN_PAGE_KIT = "0.1.4";
+
+// Page Kit shape warnings that mean the rendered funnel can silently differ
+// from what the author intended; once assembly is complete these escalate to
+// the same severity as a failed page. Exact-match against the page-kit
+// warning-code contract (lib/engine/build.js in NextCommerceCo/campaign-page-kit);
+// when page-kit adds a funnel-corrupting code, it must be added here explicitly —
+// unknown codes deliberately stay non-blocking warnings.
+const ESCALATED_WARNING_CODES = new Set(["DUPLICATE_OUTPUT", "NO_CAMPAIGN"]);
+
+function safeMtimeMs(path) {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+export function readPageKitBuildSummary(targetRepo) {
+  const path = join(targetRepo, PAGE_KIT_BUILD_SUMMARY_REL_PATH);
+  if (!existsSync(path)) return { path, summary: null, error: null };
+  try {
+    const summary = JSON.parse(readFileSync(path, "utf8"));
+    if (!summary || typeof summary !== "object" || !Array.isArray(summary.pages)) {
+      return { path, summary: null, error: "summary is not an object with a pages[] array" };
+    }
+    return { path, summary, error: null };
+  } catch (error) {
+    return { path, summary: null, error: error.message };
+  }
+}
+
+/**
+ * Evaluate the captured Page Kit build summary for one campaign.
+ *
+ * Pure with respect to doctor state: returns { errors, warnings, ready }
+ * issue lists ({ code, message, detail? } / strings for ready) and lets the
+ * caller route them through its own addIssue so formatting stays uniform.
+ *
+ * Returns empty lists when there is nothing to verify yet (no built _site
+ * for the campaign), mirroring the built_output.* checks' gating.
+ */
+export function evaluatePageKitBuildSummary({
+  targetRepo,
+  publicRouteSlug,
+  activePages = [],
+  assemblyComplete = false,
+  builtPathForPage = null,
+}) {
+  const errors = [];
+  const warnings = [];
+  const ready = [];
+  const result = { errors, warnings, ready };
+
+  if (!targetRepo || !publicRouteSlug) return result;
+  const siteRoot = join(targetRepo, "_site", publicRouteSlug);
+  if (!existsSync(siteRoot)) return result;
+
+  const issueTarget = assemblyComplete ? errors : warnings;
+  const { path, summary, error } = readPageKitBuildSummary(targetRepo);
+
+  if (!summary && !error) {
+    warnings.push({
+      code: "built_output.build_summary_missing",
+      message:
+        `No Page Kit build summary at ${PAGE_KIT_BUILD_SUMMARY_REL_PATH}. ` +
+        `Capture one with \`${PAGE_KIT_BUILD_SUMMARY_CAPTURE_COMMAND}\` (requires next-campaign-page-kit >= ${PAGE_KIT_BUILD_SUMMARY_MIN_PAGE_KIT}) ` +
+        `so doctor can verify resolved routes and Page Kit shape warnings instead of guessing from rendered HTML alone.`,
+      detail: { expected_path: PAGE_KIT_BUILD_SUMMARY_REL_PATH },
+    });
+    return result;
+  }
+
+  if (!summary) {
+    warnings.push({
+      code: "built_output.build_summary_invalid",
+      message: `Page Kit build summary at ${PAGE_KIT_BUILD_SUMMARY_REL_PATH} is unreadable (${error}). Re-capture it with \`${PAGE_KIT_BUILD_SUMMARY_CAPTURE_COMMAND}\`.`,
+      detail: { expected_path: PAGE_KIT_BUILD_SUMMARY_REL_PATH, parse_error: error },
+    });
+    return result;
+  }
+
+  // Staleness: if any built page for this campaign is newer than the summary,
+  // the summary describes an older build and its verdicts cannot be trusted.
+  const summaryMtime = typeof builtPathForPage === "function" ? safeMtimeMs(path) : null;
+  if (summaryMtime !== null) {
+    const staleSources = activePages
+      .map((page) => builtPathForPage(page))
+      .map((builtPath) => (builtPath ? safeMtimeMs(builtPath) : null))
+      .filter((builtMtime) => builtMtime !== null && builtMtime > summaryMtime + 1);
+    if (staleSources.length > 0) {
+      warnings.push({
+        code: "built_output.build_summary_stale",
+        message:
+          `Page Kit build summary predates ${staleSources.length} built page(s); the build ran again without re-capturing. ` +
+          `Re-run \`${PAGE_KIT_BUILD_SUMMARY_CAPTURE_COMMAND}\`.`,
+        detail: { newer_pages: staleSources.length },
+      });
+      return result;
+    }
+  }
+
+  const campaignPages = summary.pages.filter((page) => page && page.campaignSlug === publicRouteSlug);
+  if (campaignPages.length === 0) {
+    warnings.push({
+      code: "built_output.build_summary_no_pages",
+      message:
+        `Page Kit build summary has no pages for campaign slug "${publicRouteSlug}". ` +
+        `The capture may have run against a different campaign or before this campaign's source existed; re-run \`${PAGE_KIT_BUILD_SUMMARY_CAPTURE_COMMAND}\`.`,
+      detail: { slug: publicRouteSlug, summary_slugs: [...new Set(summary.pages.map((p) => p?.campaignSlug).filter(Boolean))] },
+    });
+    return result;
+  }
+
+  let failed = 0;
+  let flagged = 0;
+  for (const page of campaignPages) {
+    const pageWarnings = Array.isArray(page.warnings) ? page.warnings : [];
+    const pageErrors = Array.isArray(page.errors) ? page.errors : [];
+
+    if (page.status === "error" || pageErrors.length > 0) {
+      failed += 1;
+      issueTarget.push({
+        code: "built_output.build_page_error",
+        message:
+          `Page Kit failed to build "${page.inputFile}"${page.url ? ` (${page.url})` : ""}: ` +
+          `${pageErrors.map((e) => e.message || e.code).join("; ") || "status=error"}.`,
+        detail: { input_file: page.inputFile, url: page.url ?? null, errors: pageErrors },
+      });
+      // Fall through: a page that fails to render can still carry shape
+      // warnings (e.g. NESTED_NO_PERMALINK) that must survive the error.
+    }
+
+    for (const warning of pageWarnings) {
+      flagged += 1;
+      const escalated = ESCALATED_WARNING_CODES.has(warning.code);
+      const target = escalated ? issueTarget : warnings;
+      target.push({
+        code: escalated ? "built_output.build_page_warning_escalated" : "built_output.build_page_warning",
+        message:
+          `Page Kit flagged "${page.inputFile}"${page.url ? ` (${page.url})` : ""}: [${warning.code}] ${warning.message}`,
+        detail: { input_file: page.inputFile, url: page.url ?? null, warning_code: warning.code },
+      });
+    }
+  }
+
+  if (failed === 0 && flagged === 0) {
+    ready.push(
+      `Page Kit build summary verified for "${publicRouteSlug}": ${campaignPages.length} page(s) built, no build errors or shape warnings`
+    );
+  }
+
+  return result;
+}

package/src/page-kit-campaign-config.mjs

@@ -0,0 +1,57 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { normalizePublicRouteSlug } from "./route-identity.mjs";
+
+export const PAGE_KIT_CAMPAIGNS_REL_PATH = "_data/campaigns.json";
+
+// Public doctor/next/verdict evidence must never inherit arbitrary merchant
+// configuration from campaigns.json. The raw entry is validation-local; this
+// fixed projection is the only loader metadata safe to retain in artifacts.
+export function projectPageKitCampaignLoad(load) {
+  return {
+    status: typeof load?.status === "string" ? load.status : "target_repo_missing",
+    public_route_slug: normalizePublicRouteSlug(load?.public_route_slug),
+    target_path: typeof load?.target_path === "string" && load.target_path
+      ? load.target_path
+      : PAGE_KIT_CAMPAIGNS_REL_PATH,
+  };
+}
+
+export function loadPageKitCampaignEntry({ targetRepo, publicRouteSlug }) {
+  const public_route_slug = normalizePublicRouteSlug(publicRouteSlug);
+  const base = {
+    public_route_slug,
+    target_path: PAGE_KIT_CAMPAIGNS_REL_PATH,
+    entry: null,
+  };
+
+  if (typeof targetRepo !== "string" || !targetRepo.trim() || !existsSync(targetRepo)) {
+    return { ...base, status: "target_repo_missing" };
+  }
+  try {
+    if (!statSync(targetRepo).isDirectory()) return { ...base, status: "target_repo_missing" };
+  } catch {
+    return { ...base, status: "target_repo_missing" };
+  }
+
+  const campaignsPath = join(targetRepo, PAGE_KIT_CAMPAIGNS_REL_PATH);
+  if (!existsSync(campaignsPath)) return { ...base, status: "file_missing" };
+
+  let campaigns;
+  try {
+    campaigns = JSON.parse(readFileSync(campaignsPath, "utf8"));
+  } catch {
+    return { ...base, status: "invalid_json" };
+  }
+  if (!campaigns || typeof campaigns !== "object" || Array.isArray(campaigns)) {
+    return { ...base, status: "root_not_object" };
+  }
+  if (!Object.hasOwn(campaigns, public_route_slug)) {
+    return { ...base, status: "entry_missing" };
+  }
+  const entry = campaigns[public_route_slug];
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+    return { ...base, status: "entry_not_object" };
+  }
+  return { ...base, status: "ok", entry };
+}