@nextcommerce/campaigns-os 1.33.0

package/campaign-spec/dist/types.js

@@ -0,0 +1,40 @@
+/**
+ * Type surface for the CampaignSpec contract layer.
+ *
+ * The CampaignSpec is the central authoring contract of this repo (see
+ * ../CONTEXT.md). v4.3 is the authoring shape; v4.2 funnels[] is the canonical
+ * internal shape that rules operate on (after normalize()).
+ *
+ * Types here are intentionally permissive on optional fields — the rule
+ * registry catches missing/malformed fields, rather than the type system
+ * refusing to compile against in-progress Map Builder drafts.
+ */
+/**
+ * Optional hint declaring which starter template family the campaign was
+ * authored against. Doctrine: template family is a build-time decision,
+ * not a spec-time decision; this field is a HINT that the build agent
+ * uses as the default when no `--template-family` CLI override is given.
+ *
+ * Pre-Slice 4a, this field already existed as an undocumented convention
+ * read by campaigns-os/src/cli.mjs preferredTemplateFamily(); Slice 4a
+ * blesses it in the schema, adds Map Builder UI to author it, and adds
+ * a validation rule that warns if the value isn't a recognized family.
+ *
+ * Operators / agents always retain veto power via `--template-family`;
+ * the hint never silently locks the build.
+ *
+ * Known families track the certified Campaigns OS commerce-surface catalog.
+ * The AssemblyHintsShape test pins this list to the vendored catalog so a
+ * newly certified family cannot start producing a false unknown-family
+ * warning.
+ */
+export const KNOWN_TEMPLATE_FAMILY_HINTS = [
+    'apollo',
+    'apollo-mv-single-step',
+    'demeter',
+    'olympus',
+    'olympus-mv-single-step',
+    'olympus-mv-two-step',
+    'shop-single-step',
+    'shop-three-step',
+];

package/campaign-spec/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "nc-campaign-spec",
+  "version": "0.1.0",
+  "description": "CampaignSpec contract: normalize, rule registry, fixture corpus. Sits at the centre of Campaigns OS — every other module either authors, validates, projects, or consumes specs through this interface.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "node --test \"test/**/*.test.ts\""
+  }
+}

package/compatibility.json

@@ -0,0 +1,25 @@
+{
+  "package": "@nextcommerce/campaigns-os",
+  "version": "1.33.0",
+  "status": "developer-preview",
+  "contracts": {
+    "campaign_spec": "4.2-4.3",
+    "build_packet": "campaign-runtime-build-packet/v0",
+    "build_context": "campaign-runtime-build-context/v0",
+    "assembly_report": "campaign-runtime-assembly-report/v0",
+    "starter_template_agent_contract": 1,
+    "commerce_surface_catalog": 2
+  },
+  "source_adapters": {
+    "current": ["html_funnel"]
+  },
+  "runtime": {
+    "node": ">=20",
+    "page_kit": "target repo dependency",
+    "campaign_cart_sdk": "0.4.x expected by current fixtures"
+  },
+  "notes": [
+    "This toolkit is an agent-assisted build surface; launch still requires build, polish, deploy, and QA evidence.",
+    "The starter-template catalog snapshot should be refreshed from campaign-cart-starter-templates before toolkit releases."
+  ]
+}

package/contracts/agent-relevant-change-policy.v1.json

@@ -0,0 +1,111 @@
+{
+  "_note": "The SINGLE definition of 'agent-relevant change' for this repository. The changed-path classifier (scripts/orientation-contract.mjs), the two-way release gate (scripts/check-release-ledger.mjs), the generated reference (docs/orientation-contract-reference.md), and every contract test read this file. Do not hand-maintain a second copy anywhere. Authoring rules and worked pass/fail examples: docs/release-ledger-authoring-guide.md.",
+  "schema": "campaigns-os-agent-relevant-change-policy/v1",
+  "policy_version": "1.0.0",
+  "definition": "A change is agent-relevant when it alters something a downstream agent orients on: hashed or named supported-surface paths, CLI commands/subcommands/flags, skills, schemas, package exports, compatibility policy, agent-facing documentation, repository workflows that produce those artifacts, or the generated runtime a consumer must rebuild. This is the union of the release-gate list and the same-surface list in the harness upgrade build plan; neither list alone is normative.",
+  "semantic_classes": {
+    "schema": {
+      "description": "A JSON Schema in schemas/ that a consumer validates artifacts against.",
+      "requires_change_item": true
+    },
+    "hashed_surface": {
+      "description": "A path recorded in contracts/supported-surface.json hashed{}; its bytes are pinned and a change owes a surface_version advance.",
+      "requires_change_item": true
+    },
+    "named_surface": {
+      "description": "A path recorded in contracts/supported-surface.json named[]; content may evolve but the path must keep existing.",
+      "requires_change_item": true
+    },
+    "cli_surface": {
+      "description": "A CLI command, subcommand, or flag reachable from the supported argv surface.",
+      "requires_change_item": true
+    },
+    "skill": {
+      "description": "A versioned skill package or its installer.",
+      "requires_change_item": true
+    },
+    "package_export": {
+      "description": "package.json exports, bin, files, engines, or the dependency/script set a consumer installs.",
+      "requires_change_item": true
+    },
+    "compatibility_policy": {
+      "description": "The published compatibility statement, the supported-surface manifest, or the documents that define surface discipline.",
+      "requires_change_item": true
+    },
+    "documentation": {
+      "description": "Agent-facing documentation of record: the agent entry point, contract references, and authoring guides.",
+      "requires_change_item": true
+    },
+    "workflow": {
+      "description": "A repository workflow or workflow contract that produces or gates a supported artifact.",
+      "requires_change_item": true
+    },
+    "generated_runtime": {
+      "description": "Sources or lockfiles for the generated runtime a consumer must prepare before use.",
+      "requires_change_item": true
+    }
+  },
+  "_evaluation_note": "Evaluation order is fixed and total: self_referential_exemptions -> rules -> derived_from_supported_surface -> ignored -> unclassified (an error). First match wins within each ordered list. match.kind is one of exact | prefix. A rule may carry match_suffix (the path must also end with it) and exclude[] (matches that make the rule NOT apply, so a narrower path falls through to a later rule or to ignored). The derived pass runs BEFORE ignored so that a path newly added to the supported surface can never be swallowed by a broad ignore prefix; that is the fail-closed direction.",
+  "self_referential_exemptions": [
+    { "match": { "kind": "exact", "value": "contracts/release-ledger.json" }, "reason": "The ledger records changes; recording a change in it is not itself a recorded change." },
+    { "match": { "kind": "exact", "value": "CHANGELOG.md" }, "reason": "Changelog sections are linked one-to-one from ledger entries and are enforced by the changelog correspondence gate, not by a separate change item." }
+  ],
+  "rules": [
+    { "match": { "kind": "prefix", "value": "schemas/" }, "match_suffix": ".schema.json", "class": "schema" },
+    { "match": { "kind": "exact", "value": "compatibility.json" }, "class": "compatibility_policy" },
+    { "match": { "kind": "exact", "value": "contracts/supported-surface.json" }, "class": "compatibility_policy" },
+    { "match": { "kind": "exact", "value": "docs/supported-surface.md" }, "class": "compatibility_policy" },
+    { "match": { "kind": "exact", "value": "docs/versioning.md" }, "class": "compatibility_policy" },
+    { "match": { "kind": "exact", "value": "contracts/agent-relevant-change-policy.v1.json" }, "class": "compatibility_policy" },
+    { "match": { "kind": "exact", "value": "contracts/orientation-limits.v1.json" }, "class": "compatibility_policy" },
+    { "match": { "kind": "exact", "value": "contracts/orientation-reason-codes.v1.json" }, "class": "compatibility_policy" },
+    { "match": { "kind": "exact", "value": "bin/campaigns-os.mjs" }, "class": "cli_surface" },
+    { "match": { "kind": "exact", "value": "src/cli.mjs" }, "class": "cli_surface" },
+    { "match": { "kind": "exact", "value": "skills.json" }, "class": "skill" },
+    { "match": { "kind": "exact", "value": "skills.sh" }, "class": "skill" },
+    { "match": { "kind": "prefix", "value": "skills/" }, "class": "skill" },
+    { "match": { "kind": "exact", "value": "package.json" }, "class": "package_export" },
+    { "match": { "kind": "exact", "value": "package-lock.json" }, "class": "generated_runtime" },
+    {
+      "match": { "kind": "prefix", "value": "campaign-spec/" },
+      "exclude": [
+        { "kind": "prefix", "value": "campaign-spec/test/" },
+        { "kind": "prefix", "value": "campaign-spec/fixtures/" },
+        { "kind": "exact", "value": "campaign-spec/README.md" },
+        { "kind": "exact", "value": "campaign-spec/.npmignore" }
+      ],
+      "class": "generated_runtime"
+    },
+    { "match": { "kind": "prefix", "value": ".github/workflows/" }, "class": "workflow" },
+    { "match": { "kind": "exact", "value": "AGENTS.md" }, "class": "documentation" },
+    { "match": { "kind": "exact", "value": "CONTEXT.md" }, "class": "documentation" },
+    { "match": { "kind": "exact", "value": "docs/orientation-contract-reference.md" }, "class": "documentation" },
+    { "match": { "kind": "exact", "value": "docs/release-ledger-authoring-guide.md" }, "class": "documentation" }
+  ],
+  "_ignored_note": "Explicitly NOT agent-relevant. Every ignore carries a reason so 'no agent impact' is an asserted classification, not an omission. A changed path that matches no exemption, rule, derived surface entry, or ignore is an error (unclassified_path) — the classifier fails closed.",
+  "ignored": [
+    { "match": { "kind": "prefix", "value": "contracts/fixtures/" }, "reason": "Test fixtures. Consumer-facing fixtures reach the supported surface through contracts/supported-surface.json named[], which the derived pass classifies first." },
+    { "match": { "kind": "prefix", "value": "fixtures/" }, "reason": "Test fixtures." },
+    { "match": { "kind": "prefix", "value": "scripts/" }, "reason": "Repository checkers. Explicitly unsupported implementation (docs/supported-surface.md)." },
+    { "match": { "kind": "prefix", "value": "src/" }, "reason": "Implementation. Explicitly unsupported except through declared package exports, which package.json changes classify." },
+    { "match": { "kind": "prefix", "value": "campaign-spec/" }, "reason": "Tests, fixtures, and packaging metadata for the generated runtime. The runtime sources a consumer must rebuild are classified by the generated_runtime rule first; only that rule's exclusions reach here." },
+    { "match": { "kind": "prefix", "value": "examples/" }, "reason": "Illustrative, regenerated at will (docs/supported-surface.md)." },
+    { "match": { "kind": "prefix", "value": "prompts/" }, "reason": "Illustrative, regenerated at will (docs/supported-surface.md)." },
+    { "match": { "kind": "prefix", "value": "agents/" }, "reason": "Illustrative, regenerated at will (docs/supported-surface.md)." },
+    { "match": { "kind": "prefix", "value": "docs/adr/" }, "reason": "Architecture decision records: rationale, not a consumed contract." },
+    { "match": { "kind": "prefix", "value": "docs/" }, "reason": "Documentation that is not on the named supported surface and not an agent document of record. Named docs are classified by the derived pass first." },
+    { "match": { "kind": "exact", "value": "README.md" }, "reason": "Repository front page; the agent entry point is AGENTS.md." },
+    { "match": { "kind": "prefix", "value": "contracts/" }, "reason": "Internal build/QA contract data. Supported contract files are classified by explicit rules or the derived pass first." },
+    { "match": { "kind": "prefix", "value": ".github/" }, "reason": "Repository metadata other than workflows, which an explicit rule classifies first." },
+    { "match": { "kind": "exact", "value": ".gitignore" }, "reason": "Repository metadata." },
+    { "match": { "kind": "exact", "value": "LICENSE" }, "reason": "Licence text (Apache-2.0); governs use, not agent behaviour." },
+    { "match": { "kind": "exact", "value": "NOTICE" }, "reason": "Apache-2.0 attribution notice; governs use, not agent behaviour." },
+    { "match": { "kind": "prefix", "value": "." }, "reason": "Dotfile repository metadata." }
+  ],
+  "derived_from_supported_surface": {
+    "manifest": "contracts/supported-surface.json",
+    "hashed_class": "hashed_surface",
+    "named_class": "named_surface",
+    "_note": "Every path in hashed{} and named[] is agent-relevant by construction. Deriving this instead of copying the list is what keeps a newly declared surface entry from being born unclassified."
+  }
+}

package/contracts/brand-theme-source-defaults.figma-sections-export.v0.json

@@ -0,0 +1,32 @@
+{
+  "schema_version": "brand-theme-source-defaults/v0",
+  "producer": "figma-sections-export",
+  "producer_version": "v0",
+  "description": "Known scaffold defaults emitted by figma-sections-export new-section.sh. Matching these values is evidence of uncustomized source tokens, not brand truth.",
+  "core_tokens": [
+    "--brand-primary",
+    "--brand-secondary",
+    "--brand-accent",
+    "--surface-bg",
+    "--surface-card",
+    "--text-primary",
+    "--text-secondary",
+    "--text-inverse",
+    "--border-default"
+  ],
+  "tokens": {
+    "--brand-primary": "#0f75ff",
+    "--brand-secondary": "#edf2ff",
+    "--brand-accent": "#22c55e",
+    "--surface-bg": "#ffffff",
+    "--surface-card": "#f8faff",
+    "--surface-alt": "#f1f5ff",
+    "--text-primary": "#020b1e",
+    "--text-secondary": "#4a5568",
+    "--text-inverse": "#ffffff",
+    "--border-default": "#e2e8f0",
+    "--state-success": "#22c55e",
+    "--state-warning": "#f59e0b",
+    "--state-error": "#ef4444"
+  }
+}

package/contracts/brand-theme-target-tokens.next-core.v0.json

@@ -0,0 +1,65 @@
+{
+  "schema_version": "brand-theme-target-tokens/v0",
+  "target": "next-core",
+  "target_version": "v0",
+  "description": "Shared root custom-property target surface for Campaigns OS brand-theme.css generation. V0 generation must emit only these :root variables.",
+  "tokens": [
+    "--brand--color--primary",
+    "--brand--color--primary-dark",
+    "--brand--color--primary-light",
+    "--brand--color--primary-lighter",
+    "--brand--color--cta-primary",
+    "--brand--color--accent",
+    "--brand--color--secondary",
+    "--brand--color--background",
+    "--brand--color--surface",
+    "--brand--color--foreground",
+    "--brand--color--text-primary",
+    "--brand--color--text-secondary",
+    "--brand--color--text-inverse",
+    "--brand--color--border",
+    "--brand--color--primary-foreground",
+    "--brand--color--accent-foreground",
+    "--brand--color--cta-foreground",
+    "--brand--color--rating-star",
+    "--component--color--outline",
+    "--system-colors--success",
+    "--system-colors--destructive"
+  ],
+  "source_mappings": {
+    "--brand-primary": ["--brand--color--primary"],
+    "--brand-accent": ["--brand--color--accent"],
+    "--brand-secondary": ["--brand--color--secondary"],
+    "--surface-bg": ["--brand--color--background"],
+    "--surface-card": ["--brand--color--surface"],
+    "--text-primary": ["--brand--color--text-primary", "--brand--color--foreground"],
+    "--text-secondary": ["--brand--color--text-secondary"],
+    "--border-default": ["--brand--color--border", "--component--color--outline"],
+    "--rating-star": ["--brand--color--rating-star"],
+    "--state-success": ["--system-colors--success"],
+    "--ui-success": ["--system-colors--success"],
+    "--state-error": ["--system-colors--destructive"],
+    "--ui-danger": ["--system-colors--destructive"],
+    "--brand-cta": ["--brand--color--cta-primary"],
+    "--cta-primary": ["--brand--color--cta-primary"],
+    "--button-primary-bg": ["--brand--color--cta-primary"]
+  },
+  "derived_mappings": {
+    "--brand-primary": {
+      "--brand--color--primary-dark": { "method": "mix-black", "amount": 0.18 },
+      "--brand--color--primary-light": { "method": "mix-white", "amount": 0.2 },
+      "--brand--color--primary-lighter": { "method": "mix-white", "amount": 0.86 }
+    }
+  },
+  "foreground_derivations": {
+    "description": "Foreground/on-color tokens are derived from the luminance of the background they sit on, never copied blindly from a source --text-inverse token (which defaults to white and renders illegible on a light brand, e.g. white-on-yellow CTAs). Each foreground target picks the first paired background that was mapped and emits the readable choice from foreground_choices. next-core .button/.submit-button render their label with --brand--color--text-inverse, so text-inverse pairs with the CTA background first.",
+    "foreground_choices": { "dark": "#0a0a0a", "light": "#ffffff" },
+    "min_contrast_ratio": 4.5,
+    "derivations": {
+      "--brand--color--cta-foreground": ["--brand--color--cta-primary"],
+      "--brand--color--text-inverse": ["--brand--color--cta-primary", "--brand--color--primary"],
+      "--brand--color--primary-foreground": ["--brand--color--primary"],
+      "--brand--color--accent-foreground": ["--brand--color--accent"]
+    }
+  }
+}

package/contracts/campaign-cart-checkout-field-contract.v0.json

@@ -0,0 +1,45 @@
+{
+  "schema_version": "campaign-cart-checkout-field-contract/v0",
+  "provenance": {
+    "source": "NextCommerceCo/campaign-cart v0.4.36 docs/guides/reference/data-attributes.md and src/features/checkout/checkout-form/expiration-fields.ts",
+    "sdk_version": "0.4.36",
+    "captured_at": "2026-08-18"
+  },
+  "binding_attributes": ["data-next-checkout-field", "os-checkout-field"],
+  "canonical_fields": [
+    "email",
+    "phone",
+    "fname",
+    "lname",
+    "address1",
+    "address2",
+    "city",
+    "province",
+    "postal",
+    "country",
+    "cc-number",
+    "exp-month",
+    "exp-year",
+    "cvv",
+    "cc-name",
+    "coupon",
+    "payment-method",
+    "accepts_marketing"
+  ],
+  "accepted_aliases": {
+    "cc-month": "exp-month",
+    "cc-year": "exp-year"
+  },
+  "prefixes": ["billing-"],
+  "stale_aliases": {
+    "state": "province",
+    "region": "province",
+    "postal_code": "postal",
+    "zip": "postal",
+    "postcode": "postal",
+    "town": "city",
+    "first_name": "fname",
+    "last_name": "lname",
+    "street": "address1"
+  }
+}

package/contracts/campaign-cart-sdk-support-policy.v0.json

@@ -0,0 +1,11 @@
+{
+  "schema_version": "campaign-cart-sdk-support-policy/v0",
+  "provenance": {
+    "source": "NextCommerceCo/campaign-cart release tags",
+    "latest_known_release": "0.4.36",
+    "captured_at": "2026-08-18"
+  },
+  "source": "contracts/campaign-cart-sdk-support-policy.v0.json",
+  "minimum_supported": "0.4.20",
+  "preferred_minimum": "0.4.30"
+}