@nextcommerce/campaigns-os 1.33.0

package/package.json

@@ -0,0 +1,135 @@
+{
+  "name": "@nextcommerce/campaigns-os",
+  "version": "1.33.0",
+  "description": "Toolkit for agent-assisted NEXT campaign builds.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NextCommerceCo/campaigns-os.git"
+  },
+  "homepage": "https://github.com/NextCommerceCo/campaigns-os#readme",
+  "bugs": {
+    "url": "https://github.com/NextCommerceCo/campaigns-os/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "type": "module",
+  "sideEffects": false,
+  "bin": {
+    "campaigns-os": "./bin/campaigns-os.mjs"
+  },
+  "exports": {
+    "./commercial-journey": {
+      "import": "./src/commercial-journey.mjs",
+      "default": "./src/commercial-journey.mjs"
+    },
+    "./commercial-parity": {
+      "import": "./src/commercial-parity.mjs",
+      "default": "./src/commercial-parity.mjs"
+    },
+    "./campaign-spec": {
+      "types": "./campaign-spec/dist/index.d.ts",
+      "import": "./campaign-spec/dist/index.js",
+      "default": "./campaign-spec/dist/index.js"
+    },
+    "./text-safety": {
+      "import": "./src/text-safety.mjs",
+      "default": "./src/text-safety.mjs"
+    },
+    "./legacy-migration": {
+      "types": "./src/legacy-migration.d.ts",
+      "import": "./src/legacy-migration.mjs",
+      "default": "./src/legacy-migration.mjs"
+    },
+    "./schemas/campaign-spec.v4.schema.json": "./schemas/campaign-spec.v4.schema.json",
+    "./schemas/campaigns-os-legacy-migration-inventory.v0.schema.json": "./schemas/campaigns-os-legacy-migration-inventory.v0.schema.json",
+    "./schemas/campaigns-os-legacy-provisioning-plan.v0.schema.json": "./schemas/campaigns-os-legacy-provisioning-plan.v0.schema.json",
+    "./schemas/campaigns-os-legacy-provisioning-receipt.v0.schema.json": "./schemas/campaigns-os-legacy-provisioning-receipt.v0.schema.json",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "campaigns-os": "node ./bin/campaigns-os.mjs",
+    "skills": "bash ./skills.sh",
+    "qa": "node ./bin/campaigns-os.mjs qa",
+    "qa:install-browser": "npx playwright install chromium",
+    "smoke:polish-capture": "node ./scripts/smoke-polish-capture.mjs --run",
+    "refresh:starter-catalog": "node ./scripts/refresh-starter-template-catalog.mjs",
+    "build:spec": "tsc -p campaign-spec/tsconfig.build.json",
+    "prepare": "npm run build:spec",
+    "check:spec": "node --test \"campaign-spec/test/**/*.test.ts\"",
+    "check": "npm run check:provenance && npm run check:workflows && npm run check:changelog-structure && npm run build:spec && npm run check:tests && npm run check:spec && npm run check:fixtures && npm run check:legacy-migration && npm run check:spec-conformance && npm run check:private-strings && npm run check:template-doctrine && npm run check:slot-manifest && npm run check:skill-versions && npm run check:cart-readiness && npm run check:sidecar-bundle && npm run check:supported-surface && npm run check:release-ledger && npm run check:runtime-recipe && npm run check:orientation-docs && npm run check:runtime-docs && npm run check:pack -- --skip-prepare",
+    "check:tests": "node --test ./src/*.test.mjs ./scripts/refresh-starter-template-catalog.test.mjs ./scripts/check-catalog-provenance.test.mjs ./scripts/check-workflow-contracts.test.mjs ./scripts/check-changelog-structure.test.mjs ./scripts/check-slot-manifest.test.mjs ./scripts/check-skill-versions.test.mjs ./scripts/check-supported-surface.test.mjs ./scripts/check-campaign-spec-conformance.test.mjs ./scripts/check-release-ledger.test.mjs ./scripts/generate-orientation-reference.test.mjs ./scripts/check-runtime-recipe.test.mjs ./scripts/check-fixtures.test.mjs ./scripts/starter-templates-path.test.mjs ./scripts/check-template-doctrine.test.mjs",
+    "check:legacy-migration": "node ./scripts/check-legacy-migration.mjs",
+    "check:fixtures": "node ./scripts/check-fixtures.mjs",
+    "check:spec-conformance": "node ./scripts/check-campaign-spec-conformance.mjs",
+    "check:pack": "node ./scripts/check-pack.mjs",
+    "check:private-strings": "node ./scripts/check-private-strings.mjs",
+    "check:template-doctrine": "node ./scripts/check-template-doctrine.mjs",
+    "check:slot-manifest": "node ./scripts/check-slot-manifest.mjs",
+    "check:cart-readiness": "node ./scripts/check-cart-readiness-contract.mjs",
+    "check:provenance": "node ./scripts/check-catalog-provenance.mjs",
+    "check:workflows": "node ./scripts/check-workflow-contracts.mjs",
+    "check:skill-versions": "node ./scripts/check-skill-versions.mjs",
+    "check:supported-surface": "node ./scripts/check-supported-surface.mjs",
+    "check:release-ledger": "node ./scripts/check-release-ledger.mjs",
+    "check:changelog-structure": "node ./scripts/check-changelog-structure.mjs",
+    "check:orientation-docs": "node ./scripts/generate-orientation-reference.mjs --check",
+    "generate:orientation-docs": "node ./scripts/generate-orientation-reference.mjs --write",
+    "check:runtime-recipe": "node ./scripts/check-runtime-recipe.mjs",
+    "check:runtime-docs": "node ./scripts/generate-runtime-readiness.mjs --check",
+    "generate:runtime-docs": "node ./scripts/generate-runtime-readiness.mjs --write",
+    "check:sidecar-bundle": "node ./bin/campaigns-os.mjs bundle check --packet contracts/fixtures/sidecar-bundle/production-shaped/campaign-runtime.build.json --require-qa --json"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "dependencies": {
+    "acorn": "^8.18.0",
+    "ajv": "^8.20.0",
+    "parse5": "^7.3.0",
+    "yaml": "^2.9.0"
+  },
+  "optionalDependencies": {
+    "playwright": "^1.62.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "files": [
+    "agents",
+    "bin",
+    "campaign-spec",
+    "contracts",
+    "docs/brand-theme-bridge.md",
+    "docs/build-packet.md",
+    "docs/campaign-build-brief.md",
+    "docs/campaign-standardization-report.md",
+    "docs/campaigns-os-build-flow.md",
+    "docs/design-source-package.md",
+    "docs/legacy-migration.md",
+    "docs/migration-sidecar-bundle.md",
+    "docs/orientation-contract-reference.md",
+    "docs/polish-evidence.md",
+    "docs/qa-and-test-orders.md",
+    "docs/release-ledger-authoring-guide.md",
+    "docs/runtime-readiness.md",
+    "docs/supported-surface.md",
+    "docs/versioning.md",
+    "docs/workflow-findings-sidecar.md",
+    "prompts",
+    "schemas",
+    "skills.sh",
+    "skills",
+    "skills.json",
+    "src",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "CONTEXT.md",
+    "compatibility.json",
+    "AGENTS.md",
+    "CHANGELOG.md"
+  ]
+}

package/prompts/first-build.md

@@ -0,0 +1,27 @@
+# First Build Prompt
+
+Please help me build or evaluate a NEXT Campaign from the CampaignSpec, prepared HTML/assets, starter-template contract catalog, and Campaigns OS Build Packet in this repo.
+
+Start by reading:
+
+- `campaign-runtime.build.json`
+- `.campaign-runtime/build-context.json`
+- `.campaign-runtime/assembly-report.json`
+- `contracts/commerce-surface-catalog.json`
+
+Then:
+
+1. Confirm the public route slug and Map ID.
+2. Confirm or challenge the selected template family.
+3. Read `families[family].agentContract`.
+4. Use `sharedFrontmatterVocabulary`.
+5. Replace demo package, shipping, voucher, payment, tracking, footer, and SEO values from CampaignSpec/API.
+6. If source HTML is AI-generated/exported standalone HTML, convert it to page-kit-ready markup first: keep page-owned body markup, strip document wrappers, add YAML frontmatter, move shared CSS/assets into the campaign structure, and use Liquid helpers only for page-kit links/assets/includes.
+7. If intake blocked with `DESIGN_SOURCE_PACKAGE_NOT_READY`, supply desktop and mobile source screenshot proof through `pages[].screenshots[]` in `<source-root>/.campaigns-os/source-html-manifest.json`, then follow the recovery in [Clearing `DESIGN_SOURCE_PACKAGE_NOT_READY`](../docs/design-source-package.md#clearing-design_source_package_not_ready).
+8. Preserve landing/presell source design when it is real source intent.
+9. For checkout/upsell/downsell/receipt, use starter-template commerce surfaces as SDK contract references while preserving required runtime controls.
+10. Copy starter-template families atomically with dependent pages, `_includes/`, `_layouts/`, `assets/css/`, and `assets/js/`; do not copy only checkout/receipt pages.
+11. Run build and SDK/template lint checks.
+12. Record evidence and hand off to polish.
+
+Do not say this is full automated readiness. Build is only one gate before polish, deploy, and QA.

package/prompts/friction-log.md

@@ -0,0 +1,30 @@
+# Friction Log
+
+Use this when filing a developer feedback issue.
+
+## Context
+
+- CampaignSpec path or Map ID:
+- Template family:
+- Source adapter:
+- AI tool:
+- Command run:
+
+## What Happened
+
+Describe the step that was confusing, blocked, or wrong.
+
+## Expected
+
+Describe what the toolkit or prompt should have made obvious.
+
+## Evidence
+
+Paste command output, file paths, screenshots, or assembly-report snippets.
+
+## Severity
+
+- blocker
+- confusing
+- polish
+- idea

package/schemas/campaign-build-brief.v1.schema.json

@@ -0,0 +1,149 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nextcommerce.com/schemas/campaign-build-brief.v1.schema.json",
+  "title": "Campaigns OS Campaign Build Brief v1",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["schema_version"],
+  "properties": {
+    "schema_version": { "const": "campaigns-os-build-brief/v1" },
+    "status": { "enum": ["complete", "needs_answers", "invalid"] },
+    "campaign_intent": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "audience": { "type": ["string", "null"] },
+        "conversion_goal": { "type": ["string", "null"] },
+        "tone": { "type": ["string", "null"] },
+        "compliance": { "type": ["object", "null"], "additionalProperties": true }
+      }
+    },
+    "design_authority": {
+      "type": "object",
+      "description": "Page-id keyed map describing whether each page follows the provided design, selected template, or an adapted source."
+    },
+    "brand": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "commerce_palette_source": { "type": ["string", "null"] },
+        "primary_accent": { "type": ["string", "null"] },
+        "cta_style": { "type": ["string", "null"] },
+        "avoid": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "media": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "sold_variants": { "type": "array", "items": { "type": "string" } },
+        "allow_other_variant_colors": { "type": ["boolean", "null"] },
+        "prefer": { "type": "array", "items": { "type": "string" } },
+        "avoid": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "offer_presentation": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "bundle_cards": { "type": "object", "additionalProperties": true },
+        "post_purchase": { "type": "object", "additionalProperties": true }
+      }
+    },
+    "promo_urgency": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "header_claim_source": { "type": ["string", "null"] },
+        "timer_label": { "type": ["string", "null"] },
+        "show_promo_code_in_timer": { "type": ["boolean", "null"] },
+        "exit_pop": { "type": "object", "additionalProperties": true },
+        "forbid_placeholders": { "type": "boolean" }
+      }
+    },
+    "commerce_surfaces": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "payment_methods_allowed": { "type": "array", "items": { "enum": ["card", "paypal", "apple_pay", "google_pay", "klarna", "afterpay", "sezzle", "shop_pay", "amazon_pay", "venmo", "cash_app"] } },
+        "hidden_payment_methods": { "type": "array", "items": { "enum": ["card", "paypal", "apple_pay", "google_pay", "klarna", "afterpay", "sezzle", "shop_pay", "amazon_pay", "venmo", "cash_app"] } },
+        "order_bump": { "type": "object", "additionalProperties": true },
+        "guarantees": { "type": "object", "additionalProperties": true }
+      }
+    },
+    "canonical_display": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "product_name_source": { "type": ["string", "null"] },
+        "allow_runtime_name_override": { "type": "boolean" },
+        "manual_overrides": { "type": "object", "additionalProperties": true }
+      }
+    },
+    "template_residue_policy": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "block_placeholders": { "type": "boolean" },
+        "block_template_favicon": { "type": "boolean" },
+        "block_demo_payment_methods": { "type": "boolean" },
+        "block_lorem_ipsum": { "type": "boolean" },
+        "block_unapproved_tracking_claims": { "type": "boolean" }
+      }
+    },
+    "qa_policy": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "enforcement": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "status": {
+              "const": "documented_expectation",
+              "description": "Only valid v1 value. Build Brief qa_policy preserves business QA expectations; doctor and QA enforce qa.proof_policy and report.proof_policy."
+            },
+            "enforced_by": { "type": "string" },
+            "note": { "type": "string" }
+          }
+        },
+        "require_desktop_mobile_screenshots": { "type": "boolean" },
+        "require_checkout_flow": { "type": "boolean" },
+        "require_post_purchase_flow": { "type": "boolean" },
+        "fail_on_visible_placeholders": { "type": "boolean" },
+        "compare_live_runtime_data_to_spec": { "type": "boolean" }
+      }
+    },
+    "questions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["id", "priority", "field", "question"],
+        "properties": {
+          "id": { "type": "string" },
+          "priority": { "type": "integer" },
+          "field": { "type": "string" },
+          "question": { "type": "string" },
+          "reason": { "type": "string" },
+          "options": { "type": "array", "items": { "type": "string" } },
+          "blocking": { "type": "boolean" }
+        }
+      }
+    },
+    "gates": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["code", "severity", "message"],
+        "properties": {
+          "code": { "type": "string" },
+          "severity": { "enum": ["blocker", "warning"] },
+          "field": { "type": ["string", "null"] },
+          "message": { "type": "string" }
+        }
+      }
+    }
+  }
+}