@nextcommerce/campaigns-os 1.52.0 → 1.54.0

package/src/sdk-attribute-index.mjs

@@ -1,25 +1,43 @@
 // The Campaign Cart SDK attribute index, vendored for the static SDK markup
 // checks (#303).
 //
-// Source: docs/attribute-index.md in NextCommerceCo/campaign-cart at tag
-// v0.4.38 (the SDK pin every certified starter family ships today), which is
-// generated from the feature manifests. Only the data-next-* names are kept:
-// the checks that read this list ask "does the SDK read this data-next-*
-// attribute at all", and the SDK's other attribute families (data-item-*,
-// data-package-*, plain data-*) are not what an agent kit misspells.
+// Source: the SDK's own source in NextCommerceCo/campaign-cart at tag
+// v0.4.41 (the SDK pin every certified starter family ships today): every
+// data-next-* name the SDK's non-test TypeScript names as a string, plus every
+// `dataset.next*` property it reads or writes, turned back into its
+// attribute. Only the data-next-* names are kept: the checks that read this
+// list ask "does the SDK read this data-next-* attribute at all", and the
+// SDK's other attribute families (data-item-*, data-package-*, plain data-*)
+// are not what an agent kit misspells.
 //
 // This is a hardcoded copy and says so, rather than restating the SDK in
 // prose that then drifts (the partner kit's mistake): the list is regenerated
-// whole from the index at a named tag, never edited by hand.
+// whole from the source at a named tag, never edited by hand.
 //
-//   git -C ../campaign-cart show v0.4.38:docs/attribute-index.md \
-//     | grep -oE '`data-[a-z0-9-]+(\s*/\s*data-[a-z0-9-]+)*`' \
-//     | tr -d '`' | tr '/' '\n' | tr -d ' ' | grep '^data-next-' | sort -u
+//   paths=('src/**/*.ts' ':!src/**/*.test.ts' ':!src/**/tests/**' ':!src/docs/**')
+//   { git -C ../campaign-cart grep -h -oP 'data-next-[a-z0-9]+(?:-[a-z0-9]+)*-?' v0.4.41 -- "${paths[@]}"
+//     git -C ../campaign-cart grep -h -oP 'dataset\.next[A-Z][A-Za-z0-9]*' v0.4.41 -- "${paths[@]}" \
+//       | sed 's/^dataset\.//' | perl -pe 's/([A-Z])/-\L$1/g; s/^/data-/'
+//   } | sort -u
+//
+// Up to v0.4.40 the list came from docs/attribute-index.md, which the SDK
+// generated from its feature manifests. v0.4.41 removed the manifests and the
+// index (campaign-cart 5d81b4eb), and its hand-written attribute docs
+// (docs/sdk-attributes.md, docs/guides/reference/data-attributes.md, each
+// feature's guide/) leave out names the source still reads, such as
+// data-next-package-selector and data-next-remove-item. Run at v0.4.40, the
+// source recipe returns every name the v0.4.40 index listed, plus names the
+// manifests never did (the address block's, data-next-i18n,
+// data-next-bump-section, data-next-button-text, the variant option state).
+// At v0.4.41 it returns every name of the v0.4.38 list this replaces, plus
+// those and data-next-phone-e164 / data-next-phone-country.
 //
 // A name ending in "-" (data-next-class-) is a prefix the SDK reads with any
 // suffix.
 
-export const SDK_ATTRIBUTE_INDEX_VERSION = "0.4.38";
+import { RELEASED_SDK_VERSION_PATTERN } from "../campaign-spec/dist/index.js";
+
+export const SDK_ATTRIBUTE_INDEX_VERSION = "0.4.41";
 
 export const SDK_DATA_NEXT_ATTRIBUTES = Object.freeze([
   "data-next-accordion",
@@ -28,8 +46,15 @@ export const SDK_DATA_NEXT_ATTRIBUTES = Object.freeze([
   "data-next-accordion-trigger",
   "data-next-action",
   "data-next-active",
+  "data-next-address",
+  "data-next-address-api",
+  "data-next-address-field",
+  "data-next-address-lang",
+  "data-next-address-row",
+  "data-next-address-state",
   "data-next-await",
   "data-next-bump",
+  "data-next-bump-section",
   "data-next-bundle-card",
   "data-next-bundle-display",
   "data-next-bundle-id",
@@ -47,6 +72,7 @@ export const SDK_DATA_NEXT_ATTRIBUTES = Object.freeze([
   "data-next-bundle-template-id",
   "data-next-bundle-vouchers",
   "data-next-bundles",
+  "data-next-button-text",
   "data-next-cart-item-id",
   "data-next-cart-items",
   "data-next-cart-selector",
@@ -74,6 +100,7 @@ export const SDK_DATA_NEXT_ATTRIBUTES = Object.freeze([
   "data-next-fallback",
   "data-next-format",
   "data-next-hide",
+  "data-next-i18n",
   "data-next-id",
   "data-next-in-cart",
   "data-next-include-shipping",
@@ -98,6 +125,8 @@ export const SDK_DATA_NEXT_ATTRIBUTES = Object.freeze([
   "data-next-payment-form",
   "data-next-payment-method",
   "data-next-payment-state",
+  "data-next-phone-country",
+  "data-next-phone-e164",
   "data-next-product-sync",
   "data-next-property",
   "data-next-property-container",
@@ -138,6 +167,7 @@ export const SDK_DATA_NEXT_ATTRIBUTES = Object.freeze([
   "data-next-tooltip-offset",
   "data-next-tooltip-placement",
   "data-next-tracking-tag",
+  "data-next-unavailable",
   "data-next-upsell",
   "data-next-upsell-action",
   "data-next-upsell-action-for",
@@ -152,17 +182,21 @@ export const SDK_DATA_NEXT_ATTRIBUTES = Object.freeze([
   "data-next-url",
   "data-next-validate",
   "data-next-variant-code",
+  "data-next-variant-name",
   "data-next-variant-option",
   "data-next-variant-option-template-id",
   "data-next-variant-options",
   "data-next-variant-selector-template-id",
   "data-next-variant-selectors",
+  "data-next-variant-value",
 ]);
 
-// The fixed data-next-checkout-field names, from the same tag. The SDK maps a
-// field to the order by this value, so an unlisted name is a silent no-op: the
-// input renders, the shopper fills it, nothing reaches the order. Sources at
-// v0.4.38: src/features/checkout/README.md ("Standard field names"), the
+// The fixed data-next-checkout-field names. The SDK maps a field to the order
+// by this value, so an unlisted name is a silent no-op: the input renders, the
+// shopper fills it, nothing reaches the order. Taken at v0.4.38 and unchanged
+// through v0.4.41 (the README's "Standard field names" line is the same; the
+// names v0.4.39 and v0.4.41 added are the version-gated aliases below).
+// Sources: src/features/checkout/README.md ("Standard field names"), the
 // checkout-form enhancer and its validation/persistence tables, the hosted
 // payment field slots (cc-number, cvv, cc-month/cc-year and their exp-*
 // spellings), payment-method, and accepts_marketing. Billing fields are the
@@ -188,7 +222,7 @@ export const SDK_CHECKOUT_FIELD_NAMES = Object.freeze([
   "exp-month",
   "exp-year",
   "cvv",
-  // Legacy spellings the README at v0.4.38 still lists.
+  // Legacy spellings the README still lists at v0.4.41.
   "card-number",
   "card-expiry",
   "card-cvv",
@@ -197,6 +231,53 @@ export const SDK_CHECKOUT_FIELD_NAMES = Object.freeze([
 
 export const SDK_CHECKOUT_FIELD_PREFIXES = Object.freeze(["billing-"]);
 
+// Field names a later SDK added, each with the first version that maps it.
+// They are the orders API's own names, which the SDK reads as another
+// spelling of its older one (src/utils/checkout-field-names.ts, SDK_NAME):
+// first_name and last_name from v0.4.39 (v0.4.40 is the same SDK), and
+// phone_number from v0.4.41, whose data-attributes reference ("Field names")
+// makes these the names to write and says fname/lname/phone still work. The
+// older names stay in SDK_CHECKOUT_FIELD_NAMES and are valid on every
+// version. A page whose SDK version is unknown is judged as an earlier SDK:
+// the older name works on every version, so asking for it is always safe,
+// and accepting the newer name there could pass a field that never reaches
+// the order. Kept in step with version_gated_aliases in
+// contracts/campaign-cart-checkout-field-contract.v0.json (a test holds the
+// two equal).
+export const SDK_CHECKOUT_FIELD_NAMES_SINCE = Object.freeze({
+  first_name: Object.freeze({ since: "0.4.39", sdk_name: "fname" }),
+  last_name: Object.freeze({ since: "0.4.39", sdk_name: "lname" }),
+  phone_number: Object.freeze({ since: "0.4.41", sdk_name: "phone" }),
+});
+
+// Whether `version` is an exact released SDK version at or after `since`.
+// "Exact released" is campaign-spec's RELEASED_SDK_VERSION_PATTERN, the one
+// doctor's campaigns.json pin check uses, so doctor and standardize agree.
+// Anything else (null, a range, a prerelease, @latest, a v prefix) is not: a
+// prerelease sorts before its release, so 0.4.39-beta.1 does not carry
+// 0.4.39's names.
+export function sdkVersionAtLeast(version, since) {
+  const have = typeof version === "string" ? RELEASED_SDK_VERSION_PATTERN.exec(version) : null;
+  const need = typeof since === "string" ? RELEASED_SDK_VERSION_PATTERN.exec(since) : null;
+  if (!have || !need) return false;
+  for (let index = 1; index <= 3; index += 1) {
+    const diff = Number(have[index]) - Number(need[index]);
+    if (diff !== 0) return diff > 0;
+  }
+  return true;
+}
+
+// The version-gated entry for a field name, billing- prefix included
+// ("billing-first_name" → first_name's entry), or null.
+export function checkoutFieldNameSince(value) {
+  let name = String(value ?? "");
+  const prefix = SDK_CHECKOUT_FIELD_PREFIXES.find((candidate) => name.startsWith(candidate));
+  if (prefix) name = name.slice(prefix.length);
+  if (!Object.hasOwn(SDK_CHECKOUT_FIELD_NAMES_SINCE, name)) return null;
+  const entry = SDK_CHECKOUT_FIELD_NAMES_SINCE[name];
+  return { name, since: entry.since, sdk_name: `${prefix || ""}${entry.sdk_name}` };
+}
+
 const exact = new Set(SDK_DATA_NEXT_ATTRIBUTES.filter((name) => !name.endsWith("-")));
 const prefixes = SDK_DATA_NEXT_ATTRIBUTES.filter((name) => name.endsWith("-"));
 
@@ -205,15 +286,20 @@ export function isIndexedSdkAttribute(name) {
   return exact.has(value) || prefixes.some((prefix) => value.startsWith(prefix) && value.length > prefix.length);
 }
 
-export function isKnownCheckoutFieldName(value) {
+// Whether the SDK maps `value`. `sdkVersion` is the page's exact SDK
+// version; without one, a version-gated name is not known (see
+// SDK_CHECKOUT_FIELD_NAMES_SINCE).
+export function isKnownCheckoutFieldName(value, sdkVersion = null) {
   const name = String(value ?? "");
-  return SDK_CHECKOUT_FIELD_NAMES.includes(name)
-    || SDK_CHECKOUT_FIELD_PREFIXES.some((prefix) => name.startsWith(prefix) && name.length > prefix.length);
+  if (SDK_CHECKOUT_FIELD_NAMES.includes(name)
+    || SDK_CHECKOUT_FIELD_PREFIXES.some((prefix) => name.startsWith(prefix) && name.length > prefix.length)) return true;
+  const gated = checkoutFieldNameSince(name);
+  return Boolean(gated) && sdkVersionAtLeast(sdkVersion, gated.since);
 }
 
 // The Campaign Cart template placeholders, for the raw cart placeholder check
 // (built_output.cart_placeholders). Generated from the SDK renderers at the
-// same tag as the attribute index above, v0.4.38:
+// v0.4.38 (line numbers are at that tag):
 //
 //   src/features/cart/cart-summary/cart-summary.renderer.ts:46-83 (bare vars)
 //   src/features/cart/cart-summary/cart-summary.line-renderer.ts:150-173,
@@ -278,6 +364,8 @@ export const SDK_TEMPLATE_PLACEHOLDERS = Object.freeze({
 });
 
 // The SDK versions whose renderer files above were verified unchanged from
-// v0.4.38 (git blob ids equal at v0.4.38, v0.4.39 and v0.4.40). A page whose
-// loader pins another version cannot pass the placeholder check.
-export const SDK_TEMPLATE_PLACEHOLDERS_VERIFIED_PINS = Object.freeze(["0.4.38", "0.4.39", "0.4.40"]);
+// v0.4.38 (git blob ids equal at v0.4.38, v0.4.39, v0.4.40 and v0.4.41, for
+// the eight renderer files cited above plus cart-item-list.enhancer.ts and
+// order-item-list.enhancer.ts). A page whose loader pins another version
+// cannot pass the placeholder check.
+export const SDK_TEMPLATE_PLACEHOLDERS_VERIFIED_PINS = Object.freeze(["0.4.38", "0.4.39", "0.4.40", "0.4.41"]);

package/src/sdk-markup.mjs

@@ -22,7 +22,12 @@
 //   WRONG_FIELD_NAME           data-next-checkout-field with a value the SDK
 //                              does not map (firstName, lastName, zip …). The
 //                              input renders, the value never reaches the
-//                              order.
+//                              order. first_name, last_name and phone_number
+//                              are judged against the page's SDK version
+//                              (SDK_CHECKOUT_FIELD_NAMES_SINCE): the page's
+//                              own exact loader pin, else the campaign's
+//                              campaigns.json sdk_version, else unknown, which
+//                              is judged as an earlier SDK.
 //   MISSING_SELECTOR_ID_MATCH  an add-to-cart button whose data-next-selector-id
 //                              names no selector on the page. The button waits
 //                              for a selection that can never arrive.
@@ -64,8 +69,13 @@
 
 import { parse } from "parse5";
 
+// cart-placeholders.mjs imports this module's template constants as well;
+// both sides read the other's bindings only inside functions, so the cycle
+// is safe at load.
+import { readLoaderPin } from "./cart-placeholders.mjs";
 import {
   SDK_ATTRIBUTE_INDEX_VERSION,
+  checkoutFieldNameSince,
   isIndexedSdkAttribute,
   isKnownCheckoutFieldName,
 } from "./sdk-attribute-index.mjs";
@@ -158,10 +168,13 @@ function describe(entry) {
 /**
  * Scan one built page. Returns findings with { code_name, code, severity,
  * page_id, file, message, detail } and the set of unknown data-next-* names.
+ * `sdk_version` is the campaign's SDK pin, used when the page carries no
+ * exact loader pin of its own.
  */
-export function scanPageMarkup({ page_id, file = null, content = "" }) {
+export function scanPageMarkup({ page_id, file = null, content = "", sdk_version = null }) {
   const document = parse(String(content || ""));
   const where = file || page_id;
+  const sdk = resolvePageSdkVersion(document, sdk_version);
   const findings = [];
   const unknown = new Set();
 
@@ -187,10 +200,8 @@ export function scanPageMarkup({ page_id, file = null, content = "" }) {
 
     if (a.has("data-next-checkout-field")) {
       const value = a.get("data-next-checkout-field") ?? "";
-      if (!isKnownCheckoutFieldName(value)) {
-        findings.push(finding("WRONG_FIELD_NAME", page_id, where,
-          `data-next-checkout-field="${value}" on ${where} is not a field name the SDK ${SDK_ATTRIBUTE_INDEX_VERSION} maps (${suggestFieldName(value)}). The input renders and the value never reaches the order.`,
-          { value, suggestion: suggestFieldName(value, true) }));
+      if (!isKnownCheckoutFieldName(value, sdk.version)) {
+        findings.push(wrongFieldName(page_id, where, value, sdk));
       }
     }
 
@@ -291,6 +302,32 @@ export function scanPageMarkup({ page_id, file = null, content = "" }) {
   return { page_id, file, findings, unknown_attributes: [...unknown].sort() };
 }
 
+// The SDK version a page runs: its own exact loader pin, else the campaign
+// pin handed in, else null (unknown).
+function resolvePageSdkVersion(document, campaignVersion) {
+  const page = readLoaderPin(document);
+  if (page) return { version: page, source: "loader" };
+  const campaign = typeof campaignVersion === "string" && campaignVersion.trim() ? campaignVersion.trim() : null;
+  if (campaign) return { version: campaign, source: "campaigns_json" };
+  return { version: null, source: null };
+}
+
+function wrongFieldName(page_id, where, value, sdk) {
+  const gated = checkoutFieldNameSince(value);
+  const versionDetail = { sdk_version: sdk.version, sdk_version_source: sdk.source };
+  if (!gated) {
+    return finding("WRONG_FIELD_NAME", page_id, where,
+      `data-next-checkout-field="${value}" on ${where} is not a field name the SDK ${SDK_ATTRIBUTE_INDEX_VERSION} maps (${suggestFieldName(value)}). The input renders and the value never reaches the order.`,
+      { value, suggestion: suggestFieldName(value, true), ...versionDetail });
+  }
+  const running = sdk.version
+    ? `this page loads SDK ${sdk.version} (${sdk.source === "loader" ? "its loader pin" : "the campaigns.json sdk_version"})`
+    : "this page's SDK version could not be read (no exact loader pin on the page and no sdk_version in campaigns.json), so it is judged as an earlier SDK";
+  return finding("WRONG_FIELD_NAME", page_id, where,
+    `data-next-checkout-field="${value}" on ${where} is a field name the SDK maps only from ${gated.since}, and ${running}. The input renders and the value never reaches the order. Use "${gated.sdk_name}", which every SDK version maps, or pin the SDK to ${gated.since} or later.`,
+    { value, suggestion: gated.sdk_name, since: gated.since, ...versionDetail });
+}
+
 function finding(codeName, page_id, file, message, detail = {}) {
   const { code, severity } = SDK_MARKUP_CODES[codeName];
   return { code_name: codeName, code, severity, page_id, file, message: `${codeName}: ${message}`, detail };
@@ -318,11 +355,13 @@ function suggestFieldName(value, bare = false) {
 /**
  * Evaluate the SDK markup family over built pages.
  *
- * @param {{ subject: object, pages: Array<{ page_id: string, file?: string|null, content: string }> }} input
+ * @param {{ subject: object, pages: Array<{ page_id: string, file?: string|null, content: string }>, sdkVersion?: string|null }} input
+ *   `sdkVersion` is the campaign's SDK pin (campaigns.json sdk_version), the
+ *   fallback for a page with no exact loader pin of its own.
  */
-export function evaluateSdkMarkup({ subject, pages = [] } = {}) {
+export function evaluateSdkMarkup({ subject, pages = [], sdkVersion = null } = {}) {
   const resolvedSubject = subject && typeof subject === "object" ? subject : {};
-  const base = { id: SDK_MARKUP, scope: SDK_MARKUP, waivable: false, subject: resolvedSubject, waiver: null, sdk_attribute_index_version: SDK_ATTRIBUTE_INDEX_VERSION };
+  const base = { id: SDK_MARKUP, scope: SDK_MARKUP, waivable: false, subject: resolvedSubject, waiver: null, sdk_attribute_index_version: SDK_ATTRIBUTE_INDEX_VERSION, campaign_sdk_version: typeof sdkVersion === "string" && sdkVersion.trim() ? sdkVersion.trim() : null };
   const list = Array.isArray(pages) ? pages : [];
 
   if (list.length === 0) {
@@ -333,7 +372,7 @@ export function evaluateSdkMarkup({ subject, pages = [] } = {}) {
   const warned = [];
   const unknown = new Map();
   for (const page of list) {
-    const scan = scanPageMarkup(page);
+    const scan = scanPageMarkup({ ...page, sdk_version: page?.sdk_version ?? sdkVersion });
     for (const item of scan.findings) (item.severity === "error" ? findings : warned).push(item);
     for (const name of scan.unknown_attributes) {
       if (!unknown.has(name)) unknown.set(name, []);

package/src/sdk-repin.mjs

@@ -0,0 +1,282 @@
+// `sdk repin`: rewrite the hardcoded Campaign Cart SDK pins of a static
+// campaign repo (one with no page-kit `_data/campaigns.json`).
+//
+// The references are the ones the campaign-ecosystem scan already finds: every
+// http(s) Campaign Cart URL that points at a loader or dist artifact
+// (loader.js, campaign-cart.css), in HTML and script files, HTML comments
+// masked. Only a semver pin (`@vX.Y.Z` or `@X.Y.Z`) below the target version is
+// rewritten, and only its version segment changes; the leading `v` is kept as
+// written. `@latest`, `@main`, commit refs and prerelease refs are reported and
+// left alone, as is a pin already at or above the target (never a downgrade).
+//
+// Preview is the default and writes nothing. `--apply` writes the files and a
+// change record at .campaign-runtime/sdk-repin.json (schema
+// campaigns-os-sdk-repin/v0) that a Run Record can cite by path and sha256.
+// A repo with `_data/campaigns.json` is refused: page-kit owns that pin.
+
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { isReleasedSdkVersion } from "../campaign-spec/dist/index.js";
+import {
+  campaignCartArtifactReferences,
+  isCampaignCartHtmlFile,
+  listCampaignCartScanFiles,
+  listCampaignCartSourceFiles,
+  loadSdkSupportPolicy,
+} from "./campaign-ecosystem.mjs";
+import { refused } from "./lifecycle.mjs";
+import { compareVersions, relPath, unique } from "./repo-scan.mjs";
+
+export const SDK_REPIN_SCHEMA = "campaigns-os-sdk-repin/v0";
+export const SDK_REPIN_RECORD_REL_PATH = ".campaign-runtime/sdk-repin.json";
+const PAGE_KIT_CAMPAIGNS_SUFFIX = "_data/campaigns.json";
+
+const PACKAGE_VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")).version || null;
+  } catch {
+    return null;
+  }
+})();
+
+/** A --target-sdk value repin accepts: a released x.y.z, with or without a leading v. */
+export const isRepinTargetVersion = (value) => isReleasedSdkVersion(String(value ?? "").trim().replace(/^v/, ""));
+
+/**
+ * Plan the rewrite without touching the target. `targetSdk` is an x.y.z (a
+ * leading v is accepted); when absent the policy's preferred_minimum is the
+ * target, the same policy the ecosystem scan evaluates pins against. A target
+ * that is not a directory, or a target version that is not a released SDK
+ * version, is refused (a tagged refusal: one line, nothing journaled).
+ */
+export function planSdkRepin(options = {}) {
+  return planWithSpans(options).plan;
+}
+
+// The plan plus the internal rewrite spans (file offsets) runSdkRepin needs;
+// the spans never leave this module.
+function planWithSpans({ targetRepo, targetSdk = null, sdkSupportPolicy = null } = {}) {
+  const target = resolve(targetRepo);
+  if (!existsSync(target)) throw refused(`sdk repin: --target ${targetRepo} does not exist.`);
+  if (!statSync(target).isDirectory()) throw refused(`sdk repin: --target ${targetRepo} is not a directory.`);
+  const policy = loadSdkSupportPolicy(sdkSupportPolicy);
+  const explicit = targetSdk !== null && targetSdk !== undefined;
+  const toVersion = explicit ? String(targetSdk).trim().replace(/^v/, "") : policy.preferred_minimum;
+  if (!isReleasedSdkVersion(toVersion)) {
+    throw refused(explicit
+      ? `sdk repin: --target-sdk ${targetSdk} is not a released SDK version (x.y.z).`
+      : `sdk repin: the SDK support policy (${policy.source}) names no usable preferred_minimum; pass --target-sdk <x.y.z>.`);
+  }
+  const base = {
+    schema_version: SDK_REPIN_SCHEMA,
+    target_repo: target,
+    to_version: toVersion,
+    to_version_source: explicit ? "argument" : "policy.preferred_minimum",
+    policy,
+  };
+
+  const pageKitData = findPageKitCampaignData(target);
+  if (pageKitData.length) {
+    return { spans: [], plan: {
+      ...base,
+      ok: false,
+      status: "refused_page_kit",
+      message: `${pageKitData.join(", ")} exists: this is a page-kit repo, whose Campaign Cart pin lives in _data/campaigns.json and is owned by page-kit. Use \`campaigns-os page-kit sync --packet <campaign-runtime.build.json>\` to set it from the CampaignSpec; sdk repin rewrites hardcoded pins in static repos only. Nothing was changed.`,
+      page_kit_data: pageKitData,
+      references: [],
+      rewrites: [],
+      left_alone: { not_semver: [], at_target: [], newer_than_target: [] },
+      files: [],
+    } };
+  }
+
+  const references = [];
+  for (const file of listCampaignCartSourceFiles(target)) {
+    const raw = readText(file);
+    if (raw === null) continue;
+    for (const entry of campaignCartArtifactReferences(raw, { isHtml: isCampaignCartHtmlFile(file) })) {
+      // Masking keeps offsets, so the span is the ref in the raw text; a
+      // mismatch would mean the two disagree, and nothing is rewritten then.
+      if (raw.slice(entry.ref_start, entry.ref_end) !== entry.ref) continue;
+      const artifact = /\.css(?:[?#]|$)/i.test(entry.url) ? "css" : "loader";
+      const action = !entry.version
+        ? "not_semver"
+        : compareVersions(entry.version, toVersion) < 0
+          ? "rewrite"
+          : compareVersions(entry.version, toVersion) === 0 ? "at_target" : "newer_than_target";
+      const newRef = action === "rewrite" ? `${entry.ref.startsWith("v") ? "v" : ""}${toVersion}` : null;
+      const urlRefStart = entry.ref_start - entry.url_start;
+      references.push({
+        path: relPath(target, file),
+        line: entry.line,
+        artifact,
+        url: entry.url,
+        ref: entry.ref,
+        version: entry.version,
+        action,
+        new_ref: newRef,
+        new_url: newRef ? `${entry.url.slice(0, urlRefStart)}${newRef}${entry.url.slice(urlRefStart + entry.ref.length)}` : null,
+        ref_start: entry.ref_start,
+        ref_end: entry.ref_end,
+      });
+    }
+  }
+
+  const rewrites = references.filter((entry) => entry.action === "rewrite");
+  const status = !references.length
+    ? "no_references"
+    : rewrites.length ? "changes" : "nothing_to_change";
+  const spans = rewrites.map(({ path, ref_start, ref_end, ref, new_ref }) => ({ path, ref_start, ref_end, ref, new_ref }));
+  return { spans, plan: {
+    ...base,
+    ok: true,
+    status,
+    message: statusMessage(status, toVersion),
+    references: references.map(publicReference),
+    rewrites: rewrites.map(publicReference),
+    left_alone: {
+      not_semver: references.filter((entry) => entry.action === "not_semver").map(publicReference),
+      at_target: references.filter((entry) => entry.action === "at_target").map(publicReference),
+      newer_than_target: references.filter((entry) => entry.action === "newer_than_target").map(publicReference),
+    },
+    files: unique(rewrites.map((entry) => entry.path)),
+  } };
+}
+
+/**
+ * Plan, and with `apply` write. Returns the plan plus `mode`, `applied`,
+ * `change_record` and (after a write) `verified`, the re-scan confirming no
+ * reference below the target is left.
+ */
+export function runSdkRepin({ targetRepo, targetSdk = null, apply = false, sdkSupportPolicy = null, now = () => new Date() } = {}) {
+  const { plan, spans } = planWithSpans({ targetRepo, targetSdk, sdkSupportPolicy });
+  const result = { ...plan };
+  result.mode = apply ? "apply" : "preview";
+  result.applied = false;
+  result.change_record = { path: SDK_REPIN_RECORD_REL_PATH, written: false, sha256: null, record: null };
+  if (plan.status !== "changes") return result;
+
+  const record = buildChangeRecord(plan, now());
+  result.change_record.record = record;
+  if (!apply) return result;
+
+  const byFile = new Map();
+  for (const span of spans) {
+    if (!byFile.has(span.path)) byFile.set(span.path, []);
+    byFile.get(span.path).push(span);
+  }
+  // Every file is re-read and every span checked BEFORE any file is written,
+  // so a file that changed since the plan aborts the run with nothing written.
+  const updates = [];
+  for (const [path, fileSpans] of byFile) {
+    const file = join(plan.target_repo, path);
+    let text = readFileSync(file, "utf8");
+    // Right to left, so earlier offsets stay valid.
+    for (const span of [...fileSpans].sort((a, b) => b.ref_start - a.ref_start)) {
+      if (text.slice(span.ref_start, span.ref_end) !== span.ref) {
+        throw refused(`sdk repin: ${path} changed between the scan and the write (a pinned reference is no longer where the scan found it); no file was written and no change record was made. Re-run sdk repin to plan against the current files.`);
+      }
+      text = `${text.slice(0, span.ref_start)}${span.new_ref}${text.slice(span.ref_end)}`;
+    }
+    updates.push({ file, text });
+  }
+  for (const { file, text } of updates) writeFileSync(file, text);
+  const recordPath = join(plan.target_repo, SDK_REPIN_RECORD_REL_PATH);
+  mkdirSync(dirname(recordPath), { recursive: true });
+  const body = `${JSON.stringify(record, null, 2)}\n`;
+  writeFileSync(recordPath, body);
+  result.applied = true;
+  result.change_record.written = true;
+  result.change_record.sha256 = createHash("sha256").update(body).digest("hex");
+
+  const after = planSdkRepin({ targetRepo: plan.target_repo, targetSdk: plan.to_version, sdkSupportPolicy });
+  result.verified = after.ok && after.rewrites.length === 0;
+  result.message = `Rewrote ${plan.rewrites.length} reference(s) in ${plan.files.length} file(s) to ${plan.to_version}.`;
+  return result;
+}
+
+// The change record: what moved, with repo-relative paths only, so it can be
+// committed and cited (path + sha256) by a Run Record.
+function buildChangeRecord(plan, generatedAt) {
+  return {
+    schema_version: SDK_REPIN_SCHEMA,
+    generated_at: generatedAt.toISOString(),
+    campaigns_os_version: PACKAGE_VERSION,
+    command: "sdk repin",
+    to_version: plan.to_version,
+    to_version_source: plan.to_version_source,
+    from_versions: unique(plan.rewrites.map((entry) => entry.version)).sort(compareVersions),
+    files_touched: plan.files,
+    reference_count: plan.rewrites.length,
+    rewrites: plan.rewrites.map(({ path, line, artifact, ref, new_ref }) => ({ path, line, artifact, from: ref, to: new_ref })),
+    left_alone: {
+      not_semver: plan.left_alone.not_semver.map(({ path, line, ref }) => ({ path, line, ref })),
+      at_target: plan.left_alone.at_target.length,
+      newer_than_target: plan.left_alone.newer_than_target.map(({ path, line, ref }) => ({ path, line, ref })),
+    },
+  };
+}
+
+export function formatSdkRepinReport(result) {
+  const lines = [];
+  const header = result.mode === "apply" ? "sdk repin: apply" : "sdk repin: preview (nothing written; re-run with --apply to write)";
+  lines.push(header);
+  lines.push(`Target: ${result.target_repo}`);
+  lines.push(`Target SDK: ${result.to_version} (${result.to_version_source === "argument" ? "--target-sdk" : `policy preferred_minimum, ${result.policy.source}`})`);
+  if (result.status === "refused_page_kit") {
+    lines.push(`Refused: ${result.message}`);
+    return lines.join("\n");
+  }
+  if (result.rewrites.length) {
+    lines.push(`${result.applied ? "Rewrote" : "Would rewrite"} ${result.rewrites.length} reference(s) in ${result.files.length} file(s):`);
+    for (const entry of result.rewrites) {
+      lines.push(`  ${entry.path}:${entry.line}  ${entry.url}`);
+      lines.push(`    -> ${entry.new_url}`);
+    }
+  }
+  if (result.left_alone.not_semver.length) {
+    lines.push(`Left alone, not semver-pinned (${result.left_alone.not_semver.length}):`);
+    for (const entry of result.left_alone.not_semver) lines.push(`  ${entry.path}:${entry.line}  @${entry.ref}  ${entry.url}`);
+  }
+  if (result.left_alone.newer_than_target.length) {
+    lines.push(`Left alone, newer than ${result.to_version} (${result.left_alone.newer_than_target.length}):`);
+    for (const entry of result.left_alone.newer_than_target) lines.push(`  ${entry.path}:${entry.line}  @${entry.ref}`);
+  }
+  if (result.left_alone.at_target.length) lines.push(`Already at ${result.to_version}: ${result.left_alone.at_target.length} reference(s).`);
+  if (result.status !== "changes") lines.push(result.message);
+  if (result.change_record.written) {
+    lines.push(`Change record: ${result.change_record.path} (sha256 ${result.change_record.sha256})`);
+    lines.push(`Re-scan: ${result.verified ? "no pinned reference below the target remains" : "references below the target remain; inspect the files"}`);
+  }
+  return lines.join("\n");
+}
+
+function statusMessage(status, toVersion) {
+  if (status === "no_references") return "No Campaign Cart loader or stylesheet reference was found; nothing to change.";
+  if (status === "nothing_to_change") return `No semver-pinned reference is below ${toVersion}; nothing to change.`;
+  return `Semver-pinned references below ${toVersion} can be rewritten.`;
+}
+
+function publicReference({ path, line, artifact, url, ref, version, action, new_ref, new_url }) {
+  return { path, line, artifact, url, ref, version, action, new_ref, new_url };
+}
+
+// `_data/campaigns.json` at the target or under any directory the scan walks
+// (a page-kit project nested in a larger repo is still page-kit's pin).
+function findPageKitCampaignData(target) {
+  return listCampaignCartScanFiles(target)
+    .map((file) => relPath(target, file))
+    .filter((path) => path === PAGE_KIT_CAMPAIGNS_SUFFIX || path.endsWith(`/${PAGE_KIT_CAMPAIGNS_SUFFIX}`))
+    .sort();
+}
+
+function readText(path) {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+}