@decocms/start 2.24.0 → 2.25.0

package/.agents/skills/deco-to-tanstack-migration/references/post-migration-cleanup.md

@@ -430,6 +430,7 @@ logic, wrapped in something else) are skipped automatically.
 | `src/sdk/clx.ts` | `@decocms/start/sdk/clx` | yes | Identical implementation; baggagio's extra `clsx` alias has zero callers. |
 | `src/sdk/useSendEvent.ts` | `@decocms/start/sdk/analytics` | no | Site copy uses `<E extends AnalyticsEvent>` generic; framework export is permissive. Replace 1:1 = type-safety loss. Either widen the framework first or accept the loss. |
 | `src/matchers/location.ts` | `@decocms/start/matchers/builtins` | no | Framework's `registerBuiltinMatchers()` ships a richer location matcher (`request.cf` first, geo cookies fallback, headers fallback) plus 10 sibling matchers. Adopting changes behaviour — verify country-name lookup parity, swap `setup.ts`'s `customMatchers` entry. |
+| `src/sdk/url.ts` | `@decocms/apps/commerce/sdk/url` | no | Site fork carries a positional `removeIdSku?: boolean` flag with hardcoded VTEX-specific keys. Canonical apps export uses `{ stripSearchParams: string[] }` (`@decocms/apps@1.9+`). Rewrite imports + each `relative(url, true)` call site → `relative(url, { stripSearchParams: ["idsku", "skuId"] })`, then delete the file. Auto-fix is gated because the call-site rewrite needs JSX/TS-aware transformation, not pure import rewrite. |
 
 ### Adding a new entry
 

package/MIGRATION_TOOLING_PLAN.md

@@ -1215,9 +1215,76 @@ copy-paste regression on any future site gets caught automatically.
 - **15-B-4** — `Picture` API unification (breaking; needs a
   picking-the-winner pass between casaevideo's and baggagio's
   shapes, plus a codemod for call sites).
-- **15-B-5** — `relative()` SKU-stripping option in
-  `@decocms/apps/commerce/sdk/url`. Apps-side change; sites delete
-  their wrapper.
+
+### Wave 15-B-5 (canonical `relative()` + audit registry entry — apps + deco-start) — 🟡 **IN FLIGHT**
+
+The smallest 15-B slice: extend `commerce/sdk/url.ts → relative()`
+with a generic options bag, then point the audit at the canonical
+so future site forks get caught automatically.
+
+Verified state (2026-05-01 grep against baggagio-tanstack):
+
+- `src/sdk/url.ts` carries a positional 2-arg fork (`relative(link,
+  removeIdSku?: boolean)`) with VTEX-specific keys (`idsku`,
+  `skuId`) hardcoded inside.
+- 9 importers in baggagio. ONE of them — `ProductCard.tsx` — uses
+  the 2-arg form (via prop `removeIdSkuFromUrl`). The other 8 use
+  the 1-arg form, identical to the apps canonical.
+- casaevideo doesn't carry a fork.
+
+So the convergence is one apps-side extension + one audit registry
+entry. The single `ProductCard` call site rewrites by hand or by a
+future codemod (out of scope here).
+
+**Shipped (two PRs):**
+
+39. [`apps-start#36`](https://github.com/decocms/apps-start/pull/36) — `feat(commerce/sdk): extend relative() with stripSearchParams option` ✅ **MERGED** (will release as `@decocms/apps@1.9.x`).
+    - **`commerce/sdk/url.ts`**: backwards-compatible second
+      `RelativeOptions` argument with `stripSearchParams?:
+      string[]` primitive. 1-arg callers (everyone in apps + 8/9
+      of baggagio's call sites) unaffected. The byte-for-byte
+      "://path-style" passthrough is locked in by an explicit
+      backwards-compat test.
+    - **Why generic, not `removeIdSku?: boolean`**: hardcoded VTEX
+      key names belong at call sites, not in a generic commerce
+      helper. `stripSearchParams: string[]` works for any platform.
+      Sites pass `["idsku", "skuId"]` themselves — honest about
+      where the platform knowledge lives.
+    - **`commerce/__tests__/url.test.ts`** (new): 18 tests covering
+      base behaviour (relative/absolute/undefined/empty/malformed
+      via `toString()` thrower), `stripSearchParams` primitive
+      (single, multi, empty, missing, repeated keys, all-stripped
+      → drop trailing `?`), and three explicit backwards-compat
+      assertions.
+    - 290/290 tests pass, typecheck + biome clean.
+
+40. `feat(migrate): add url-relative entry to local-framework-duplicate registry` 🟡 **WAITING ON CI** (deco-start side).
+    - **Registry entry** in `FRAMEWORK_DUPLICATES` for
+      `src/sdk/url.ts` → `@decocms/apps/commerce/sdk/url`. Content
+      signature anchored on the legacy positional `removeIdSku?:
+      boolean` shape so sites that already adopted the canonical
+      options-object aren't flagged.
+    - **`safeToAutoFix: false`** — the call-site rewrite from
+      positional `relative(url, true)` to `relative(url, {
+      stripSearchParams: ["idsku", "skuId"] })` requires JSX/TS-
+      aware transformation, not pure import rewrite. The finding's
+      `fix:` field carries the exact recipe.
+    - **Two new tests**: positive case (legacy fork → flagged with
+      the correct hint), negative case (canonical-shaped local
+      fork that already adopted the options object → NOT flagged,
+      proves the signature-anchoring works).
+    - **Skill doc § 8 table** updated with the 4th entry, including
+      version pin (`@decocms/apps@1.9+`).
+    - 355/355 tests pass, typecheck clean. Smoke against baggagio
+      now fires 3 findings (was 2): clx, useSendEvent, url; smoke
+      against casaevideo unchanged at 1 (location-matcher).
+
+**Process note**: this is the first time we ran the apps-side and
+deco-start-side as a pair of PRs. The order matters — apps-start
+must merge first so the deco-start audit registry can point at
+the released canonical. The skill doc explicitly version-pins the
+canonical (`@decocms/apps@1.9+`) so engineers reading the audit
+output know whether they need to bump apps before adopting.
 
 ### Wave 15+ (htmx cleanup PRs on als + propagation to other sites) — Priority 3 / 4
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "2.24.0",
+  "version": "2.25.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/scripts/migrate/post-cleanup/rules.ts

@@ -1053,6 +1053,31 @@ export const FRAMEWORK_DUPLICATES: FrameworkDuplicate[] = [
     description:
       "src/matchers/location.ts overlaps with @decocms/start/matchers/builtins → registerBuiltinMatchers()",
   },
+  {
+    id: "url-relative",
+    sitePath: "src/sdk/url.ts",
+    canonicalImport: "@decocms/apps/commerce/sdk/url",
+    // Fingerprint: site fork carries a positional `removeIdSku?: boolean`
+    // flag + hardcoded VTEX-specific keys (`idsku`, `skuId`). Canonical
+    // apps export uses an options object — `{ stripSearchParams: string[] }`
+    // — which is generic and platform-agnostic.
+    contentSignature: [
+      /export\s+const\s+relative\s*=/,
+      /removeIdSku\s*\?\s*:\s*boolean/,
+      /['"](idsku|skuId)['"]/,
+    ],
+    safeToAutoFix: false,
+    reason:
+      "rewrite imports to '@decocms/apps/commerce/sdk/url'. " +
+      "Each call site using the boolean form `relative(url, true)` becomes " +
+      "`relative(url, { stripSearchParams: [\"idsku\", \"skuId\"] })`. " +
+      "1-arg calls are unchanged. Then delete src/sdk/url.ts. " +
+      "Auto-fix is gated because the call-site rewrite needs JSX/TS-aware " +
+      "transformation (positional bool → options object), not pure import " +
+      "rewrite.",
+    description:
+      "src/sdk/url.ts overlaps with @decocms/apps/commerce/sdk/url → relative() (extended in @decocms/apps@1.9+)",
+  },
 ];
 
 const ruleLocalFrameworkDuplicate: Rule = {

package/scripts/migrate/post-cleanup/runner.test.ts

@@ -1240,6 +1240,51 @@ describe("rule: local-framework-duplicate", () => {
     expect(r.findings[0].fix).toContain("typed AnalyticsEvent generic");
   });
 
+  it("flags src/sdk/url.ts as warn-only (positional bool → options object call-site rewrite)", () => {
+    const fs = makeFs({
+      "/site/src/sdk/url.ts":
+        "export const relative = (\n" +
+        "  link?: string | undefined,\n" +
+        "  removeIdSku?: boolean,\n" +
+        ") => {\n" +
+        '  const linkUrl = link ? new URL(link, "http://localhost") : undefined;\n' +
+        "  if (linkUrl && removeIdSku) {\n" +
+        '    linkUrl.searchParams.delete("idsku");\n' +
+        '    linkUrl.searchParams.delete("skuId");\n' +
+        "  }\n" +
+        "  return linkUrl ? `${linkUrl.pathname}` : undefined;\n" +
+        "};\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "local-framework-duplicate")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].file).toBe("src/sdk/url.ts");
+    expect(r.findings[0].meta?.id).toBe("url-relative");
+    expect(r.findings[0].meta?.safeToAutoFix).toBe(false);
+    expect(r.findings[0].meta?.canonicalImport).toBe(
+      "@decocms/apps/commerce/sdk/url",
+    );
+    expect(r.findings[0].fix).toContain("stripSearchParams");
+  });
+
+  it("does NOT flag a forked url.ts that no longer carries the removeIdSku flag", () => {
+    // A site that already adopted an options-object-shaped local helper
+    // should not be flagged — the rule's signature is anchored on the
+    // legacy positional-boolean shape.
+    const fs = makeFs({
+      "/site/src/sdk/url.ts":
+        "export const relative = (link?: string, options?: { stripSearchParams?: string[] }) => {\n" +
+        '  if (!link) return undefined;\n' +
+        '  return new URL(link, "https://localhost").pathname;\n' +
+        "};\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "local-framework-duplicate")!;
+    // url-relative entry must NOT fire on the canonical-shaped local fork.
+    const urlFinding = r.findings.find((f) => f.meta?.id === "url-relative");
+    expect(urlFinding).toBeUndefined();
+  });
+
   it("flags src/matchers/location.ts as warn-only (behaviour-superset opportunity)", () => {
     const fs = makeFs({
       "/site/src/matchers/location.ts":