@decocms/start 6.4.3 → 6.4.5

package/package.json

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

package/scripts/migrate/phase-analyze.test.ts

@@ -0,0 +1,63 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { extractPlatform } from "./phase-analyze";
+
+// `extractPlatform` runs four strategies in order:
+//   1. deno.json imports referencing apps/{platform}/
+//   2. apps/{platform}.ts file existence
+//   3. apps/site.ts loose string match against platform name + "platform"
+//   4. .deco/blocks filenames hinting at platform
+// Strategy 3 is the false-positive trap that ate Magento sites before #211:
+// helsinki/granadobr's apps/site.ts imports `apps/vtex/mod.ts` for the color
+// palette, so the content matches `"vtex"` even though the real platform is
+// declared via `apps/magento.ts`. The fix adds "magento" to the platforms
+// list so Strategy 2 fires first and short-circuits before Strategy 3 can
+// over-match.
+
+describe("extractPlatform", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), "extract-platform-"));
+    fs.mkdirSync(path.join(tmp, "apps"), { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("detects magento from apps/magento.ts (granadobr/helsinki shape)", () => {
+    fs.writeFileSync(path.join(tmp, "apps", "magento.ts"), "export default {};\n");
+    // Also write a site.ts that imports vtex for color palettes — this is
+    // what tripped Strategy 3 before #211.
+    fs.writeFileSync(
+      path.join(tmp, "apps", "site.ts"),
+      `import { color as vtex } from "apps/vtex/mod.ts";\n` +
+        `export interface State { platform: string }\n`,
+    );
+    expect(extractPlatform(tmp)).toBe("magento");
+  });
+
+  it("detects vtex from apps/vtex.ts", () => {
+    fs.writeFileSync(path.join(tmp, "apps", "vtex.ts"), "export default { account: \"foo\" };\n");
+    expect(extractPlatform(tmp)).toBe("vtex");
+  });
+
+  it("falls back to custom when no platform signal exists", () => {
+    fs.writeFileSync(path.join(tmp, "apps", "site.ts"), "export default {};\n");
+    expect(extractPlatform(tmp)).toBe("custom");
+  });
+
+  it("prefers magento over vtex when both an apps/magento.ts AND a vtex string match exist", () => {
+    // Reproduce the exact granadobr trap: apps/magento.ts is the real signal,
+    // but apps/site.ts loosely contains "vtex" + "platform".
+    fs.writeFileSync(path.join(tmp, "apps", "magento.ts"), "export default {};\n");
+    fs.writeFileSync(
+      path.join(tmp, "apps", "site.ts"),
+      `import "apps/vtex/mod.ts";\nexport interface State { platform: string }\n`,
+    );
+    expect(extractPlatform(tmp)).toBe("magento");
+  });
+});

package/scripts/migrate/phase-analyze.ts

@@ -467,8 +467,21 @@ function extractVtexAccount(sourceDir: string): string | null {
   return null;
 }
 
-function extractPlatform(sourceDir: string): Platform {
-  const platforms: Platform[] = ["vtex", "shopify", "wake", "vnda", "linx", "nuvemshop"];
+export function extractPlatform(sourceDir: string): Platform {
+  // Strategy 2 (apps/{p}.ts existence) is the most reliable signal, but it
+  // only matches when the platform name appears here — so a site whose only
+  // app file is `apps/magento.ts` previously fell through to Strategy 3
+  // and got mis-detected as "vtex" because site.ts imports
+  // `apps/vtex/mod.ts` for color palettes. See #211.
+  const platforms: Platform[] = [
+    "vtex",
+    "shopify",
+    "wake",
+    "vnda",
+    "linx",
+    "nuvemshop",
+    "magento",
+  ];
 
   // Strategy 1: Check deno.json imports for platform-specific app imports
   const denoPath = path.join(sourceDir, "deno.json");

package/scripts/migrate/phase-verify.test.ts

@@ -0,0 +1,127 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { checks } from "./phase-verify";
+import type { MigrationContext } from "./types";
+
+/**
+ * The "No relative imports to deleted SDK files" check used to flag any
+ * relative import to `sdk/{clx,useId,useOffer,useVariantPossiblities,
+ * usePlatform}`. But `useOffer` and `useVariantPossiblities` are KEPT as
+ * site files (see RELATIVE_SDK_REWRITES in transforms/imports.ts) — so
+ * every site that legitimately imports them via a relative path was
+ * failing verify with a misleading error. See #212.
+ *
+ * Pull the specific check out of the registered array and exercise it on
+ * a fixture tree, so we don't have to satisfy the other 24 checks that
+ * `verify()` runs at once.
+ */
+
+function makeCtx(sourceDir: string): MigrationContext {
+  return {
+    sourceDir,
+    siteName: "test-site",
+    platform: "custom",
+    vtexAccount: null,
+    gtmId: null,
+    importMap: {},
+    discoveredNpmDeps: {},
+    themeColors: {},
+    fontFamily: null,
+    files: [],
+    sectionMetas: [],
+    islandClassifications: [],
+    islandWrapperTargets: new Map(),
+    loaderInventory: [],
+    scaffoldedFiles: [],
+    transformedFiles: [],
+    deletedFiles: [],
+    movedFiles: [],
+    manualReviewItems: [],
+    frameworkFindings: [],
+    dryRun: false,
+    verbose: false,
+  };
+}
+
+const sdkCheck = checks.find(
+  (c) => c.name === "No relative imports to deleted SDK files",
+);
+if (!sdkCheck) {
+  throw new Error("verify check not found — name changed?");
+}
+
+function runCheck(ctx: MigrationContext): { ok: boolean; output: string } {
+  const lines: string[] = [];
+  const spy = vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => {
+    lines.push(args.map((a) => String(a)).join(" "));
+  });
+  try {
+    const ok = sdkCheck!.fn(ctx);
+    return { ok, output: lines.join("\n") };
+  } finally {
+    spy.mockRestore();
+  }
+}
+
+describe("verify check: 'No relative imports to deleted SDK files'", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), "verify-sdk-"));
+    fs.mkdirSync(path.join(tmp, "src", "components"), { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("passes when src/ imports useOffer/useVariantPossiblities relatively (kept files, #212)", () => {
+    fs.writeFileSync(
+      path.join(tmp, "src", "components", "ProductCard.tsx"),
+      `import { useOffer } from "../../sdk/useOffer";\n` +
+        `import { useVariantPossibilities } from "../../sdk/useVariantPossiblities";\n` +
+        `export const x = 1;\n`,
+    );
+    const { ok, output } = runCheck(makeCtx(tmp));
+    expect(ok).toBe(true);
+    expect(output).toBe("");
+  });
+
+  it("fails when src/ imports clx/useId/usePlatform relatively (truly deleted)", () => {
+    fs.writeFileSync(
+      path.join(tmp, "src", "components", "Bad.tsx"),
+      `import { clx } from "../../sdk/clx";\n` +
+        `import { useId } from "../../sdk/useId";\n` +
+        `import { usePlatform } from "../../sdk/usePlatform";\n` +
+        `export const x = 1;\n`,
+    );
+    const { ok, output } = runCheck(makeCtx(tmp));
+    expect(ok).toBe(false);
+    // The improved error reports each offending line, not just the file.
+    expect(output).toMatch(/components\/Bad\.tsx:.*sdk\/clx/);
+    expect(output).toMatch(/components\/Bad\.tsx:.*sdk\/useId/);
+    expect(output).toMatch(/components\/Bad\.tsx:.*sdk\/usePlatform/);
+  });
+
+  it("ignores commented-out references to deleted SDK files", () => {
+    fs.writeFileSync(
+      path.join(tmp, "src", "components", "Docs.tsx"),
+      `// import { clx } from "../../sdk/clx"\n` +
+        `// from "../../sdk/useId"\n` +
+        `export const x = 1;\n`,
+    );
+    const { ok } = runCheck(makeCtx(tmp));
+    expect(ok).toBe(true);
+  });
+
+  it("matches both .ts-suffixed and unsuffixed import paths", () => {
+    fs.writeFileSync(
+      path.join(tmp, "src", "components", "WithExt.tsx"),
+      `import { clx } from "../../sdk/clx.ts";\nexport const x = 1;\n`,
+    );
+    const { ok } = runCheck(makeCtx(tmp));
+    expect(ok).toBe(false);
+  });
+});

package/scripts/migrate/phase-verify.ts

@@ -59,7 +59,7 @@ const MUST_NOT_EXIST = [
   "routes/_middleware.ts",
 ];
 
-const checks: Check[] = [
+export const checks: Check[] = [
   {
     name: "All scaffolded files exist",
     severity: "error",
@@ -233,15 +233,24 @@ const checks: Check[] = [
     },
   },
   {
+    // Only flag imports to files that phase-cleanup actually deletes:
+    // `sdk/clx.ts`, `sdk/useId.ts`, `sdk/usePlatform.tsx`. Earlier versions
+    // also matched `useOffer` and `useVariantPossiblities`, which are
+    // explicitly KEPT as site files (RELATIVE_SDK_REWRITES in
+    // transforms/imports.ts skips them on purpose because sites customize
+    // them). That false positive made every Magento/custom-SDK migration
+    // fail verify even when the imports were valid. See #212.
     name: "No relative imports to deleted SDK files",
     severity: "error",
     fn: (ctx) => {
       const srcDir = path.join(ctx.sourceDir, "src");
       if (!fs.existsSync(srcDir)) return true;
-      // Only match relative imports (../ or ./) to deleted SDK files, not @decocms/* package imports
-      const bad = findFilesWithPattern(srcDir, /from\s+["'](?:\.\.?\/)[^"']*\/sdk\/(?:clx|useId|useOffer|useVariantPossiblities|usePlatform)["']/);
+      const pattern = /from\s+["'](?:\.\.?\/)[^"']*\/sdk\/(?:clx|useId|usePlatform)(?:\.tsx?)?["']/;
+      const bad = findMatchesWithPattern(srcDir, pattern);
       if (bad.length > 0) {
-        console.log(`    Still has relative imports to deleted SDK files: ${bad.join(", ")}`);
+        for (const { file, line } of bad) {
+          console.log(`    ${file}: ${line.trim()}`);
+        }
         return false;
       }
       return true;
@@ -493,6 +502,37 @@ function findFilesWithPattern(
   return results;
 }
 
+/**
+ * Like {@link findFilesWithPattern} but returns each offending line alongside
+ * its file, so the verify output can show *what* matched — not just *where*.
+ * Skips comment-only lines so a doc reference doesn't trigger a false fail.
+ */
+function findMatchesWithPattern(
+  dir: string,
+  pattern: RegExp,
+  results: Array<{ file: string; line: string }> = [],
+  baseDir?: string,
+): Array<{ file: string; line: string }> {
+  const root = baseDir ?? dir;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "server") continue;
+      findMatchesWithPattern(fullPath, pattern, results, root);
+    } else if (entry.name.endsWith(".ts") || entry.name.endsWith(".tsx")) {
+      const content = fs.readFileSync(fullPath, "utf-8");
+      const rel = path.relative(root, fullPath);
+      for (const line of content.split("\n")) {
+        const trimmed = line.trimStart();
+        if (trimmed.startsWith("//") || trimmed.startsWith("*")) continue;
+        if (pattern.test(line)) results.push({ file: rel, line });
+      }
+    }
+  }
+  return results;
+}
+
 export function verify(ctx: MigrationContext): boolean {
   logPhase("Verify (Smoke Test)");
 

package/scripts/migrate/types.ts

@@ -5,6 +5,7 @@ export type Platform =
   | "wake"
   | "linx"
   | "nuvemshop"
+  | "magento"
   | "custom";
 
 export interface FileRecord {

package/src/cms/loader.test.ts

@@ -139,6 +139,26 @@ describe("findPageByPath specificity", () => {
     expect(match?.blockKey).toBe("pages-bf");
   });
 
+  it("prefers the home page over an optional-group splat catch-all", () => {
+    // Regression: /{granado/}?* matches "/" and was out-ranking the home
+    // because the `{granado` segment counted as a param. The home block
+    // is a literal-only `/` path and must always win.
+    setBlocks({
+      "pages-home": {
+        name: "Home",
+        path: "/",
+        sections: [],
+      },
+      "pages-pdp-plp": {
+        name: "PDP & PLP",
+        path: "/{granado/}?*",
+        sections: [],
+      },
+    });
+    const match = findPageByPath("/");
+    expect(match?.blockKey).toBe("pages-home");
+  });
+
   it("falls back to the splat page for unknown URLs", () => {
     const match = findPageByPath("/perfumaria");
     expect(match?.blockKey).toBe("pages-pdp-plp");

package/src/cms/loader.ts

@@ -128,28 +128,39 @@ export function withBlocksOverride<T>(override: Record<string, unknown>, fn: ()
 }
 
 // Higher key wins. Compared lexicographically:
-//   [literalSegments, paramSegments, hasNoSplat]
-// So `/foo/bar` > `/foo/:x` > `/foo/*` > `/*`, and `/my-account/*` > `/*`.
+//   [hasNoWildcard, literalSegments, paramSegments]
 //
-// URLPattern syntax (`{group}?`, `:slug([\w-]+)`, trailing `*`) is supported:
-// any segment containing `{`, `}`, or `?` counts as a param, and a segment
-// containing `*` flips the splat bit. This keeps optional-group patterns
-// (e.g. `/{granado/}?*`) from out-ranking real literal pages.
+// `hasNoWildcard` is the top key so a literal-only path always beats any
+// pattern that contains `*` or `{group}?` — including the empty-parts case
+// `/` (literals=0) vs the catch-all `/{prefix/}?*` (literals=0, params=1).
+// Without this, the URLPattern fix (#213/#214) inadvertently lets a
+// `/{group/}?*` catch-all out-rank an exact `/` home page because the
+// `{group` segment counted as a param. See deco-sites/granadobr-tanstack
+// where `/` was being routed to the granado PDP/PLP block's NotFound
+// fallback.
+//
+// Order produced:
+//   /foo/bar (no wildcard, literals=2) > /foo/:x (no wildcard, lit=1, param=1)
+//   /foo (no wildcard) > /{granado/}?*  (has wildcard) > /*
 function pathSpecificityKey(path: string): [number, number, number] {
   const parts = path.split("/").filter(Boolean);
   let literals = 0;
   let params = 0;
-  let hasSplat = false;
+  let hasWildcard = false;
   for (const part of parts) {
-    if (part.includes("*")) hasSplat = true;
-    else if (
-      part.startsWith(":") ||
-      part.startsWith("$") ||
-      /[{}?]/.test(part)
-    ) params++;
-    else literals++;
+    // A wildcard is any `*`, optional group `{...}?`, or any segment
+    // bearing `?` — these all make the pattern match strictly more URLs
+    // than a plain literal/`:param`/`:slug([\w-]+)` segment, so they
+    // are demoted to "least specific" together regardless of count.
+    if (part.includes("*") || /[{}?]/.test(part)) {
+      hasWildcard = true;
+    } else if (part.startsWith(":") || part.startsWith("$")) {
+      params++;
+    } else {
+      literals++;
+    }
   }
-  return [literals, params, hasSplat ? 0 : 1];
+  return [hasWildcard ? 0 : 1, literals, params];
 }
 
 export function getAllPages(): Array<{ key: string; page: DecoPage }> {