@decocms/start 0.42.2 → 0.42.3

package/.claude/skills/run-migration/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: run-migration
+description: Run the deco-start migration script against a target site workspace. Resets the target to its Fresh/Deno state (origin/main), then runs the local migration script. Use for testing migration on real sites.
+---
+
+# Run Deco Migration
+
+Runs the migration script from the local `@decocms/start` repo against a target site.
+
+## How to use
+
+1. **Identify the target site workspace.** The user will specify which site to migrate. Common targets:
+   - miess-01-tanstack: `/Users/jonasjesus/conductor/workspaces/miess-01-tanstack/istanbul`
+
+2. **Reset the target to Fresh/Deno state:**
+   ```bash
+   cd <target-dir>
+   git checkout origin/main -- .
+   git checkout -- .
+   git clean -fd
+   ```
+   This restores the original Fresh/Deno source code.
+
+3. **Remove old node_modules** (migration generates a new package.json):
+   ```bash
+   rm -rf node_modules package-lock.json
+   ```
+
+4. **Run the migration script from local deco-start:**
+   ```bash
+   cd <target-dir>
+   npx tsx /Users/jonasjesus/conductor/workspaces/deco-start/london/scripts/migrate.ts --verbose
+   ```
+   The script uses `--source .` by default (current directory).
+
+5. **Check the output** for errors and review `MIGRATION_REPORT.md`.
+
+6. **If the user wants to test locally** after migration:
+   ```bash
+   cd <target-dir>
+   # Ensure @decocms/start points to local repo (not npm)
+   npm link /Users/jonasjesus/conductor/workspaces/deco-start/london 2>/dev/null || true
+   npm install
+   npm run dev  # or bun run dev
+   ```
+
+## Important notes
+
+- The migration script is at the repo root: `scripts/migrate.ts`
+- Changes to the script are immediately reflected when running (no build needed, tsx runs TS directly)
+- The target site's `origin/main` branch has the original Fresh/Deno code
+- NEVER push migration results to the target site's remote without explicit user confirmation
+- After running, check for runtime errors and update the migration script if needed

package/package.json

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

package/scripts/migrate/phase-scaffold.ts

@@ -65,6 +65,15 @@ export function scaffold(ctx: MigrationContext): void {
   // Styles
   writeFile(ctx, "src/styles/app.css", generateAppCss(ctx));
 
+  // SDK — signal shim (replaces @preact/signals)
+  writeFile(ctx, "src/sdk/signal.ts", generateSignalShim());
+
+  // SDK — clx (class name joiner, with default export for compat)
+  writeFile(ctx, "src/sdk/clx.ts", generateClxShim());
+
+  // SDK — debounce (replaces Deno std/async/debounce)
+  writeFile(ctx, "src/sdk/debounce.ts", generateDebounceShim());
+
   // Apps
   writeFile(ctx, "src/apps/site.ts", generateSiteApp(ctx));
 
@@ -224,6 +233,112 @@ vite.config.timestamp_*
 `;
 }
 
+function generateClxShim(): string {
+  return `/** Filter out nullable values, join and minify class names */
+export const clx = (...args: (string | null | undefined | false)[]) =>
+  args.filter(Boolean).join(" ").replace(/\\s\\s+/g, " ");
+
+/** Alias for compat — some files import as clsx */
+export const clsx = clx;
+
+export default clx;
+`;
+}
+
+function generateDebounceShim(): string {
+  return `/** Debounce a function call — drop-in replacement for Deno std/async/debounce */
+export function debounce<T extends (...args: any[]) => any>(
+  fn: T,
+  delay = 250,
+): T & { clear(): void } {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const debounced = ((...args: Parameters<T>) => {
+    if (timer !== undefined) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = undefined;
+      fn(...args);
+    }, delay);
+  }) as T & { clear(): void };
+
+  debounced.clear = () => {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+  };
+
+  return debounced;
+}
+
+export default debounce;
+`;
+}
+
+function generateSignalShim(): string {
+  return `import { Store } from "@tanstack/store";
+import { useSyncExternalStore, useMemo, useEffect } from "react";
+
+export interface Signal<T> {
+  readonly store: Store<T>;
+  value: T;
+  peek(): T;
+  subscribe(fn: () => void): () => void;
+}
+
+export function signal<T>(initialValue: T): Signal<T> {
+  const store = new Store<T>(initialValue);
+  return {
+    store,
+    get value() { return store.state; },
+    set value(v: T) { store.setState(() => v); },
+    peek() { return store.state; },
+    subscribe(fn) {
+      // @tanstack/store@0.9.x returns { unsubscribe: Function },
+      // NOT a plain function. React's useSyncExternalStore cleanup
+      // expects a bare function — unwrap it.
+      const sub = store.subscribe(() => fn());
+      return typeof sub === "function" ? sub : sub.unsubscribe;
+    },
+  };
+}
+
+export function useSignal<T>(initialValue: T): Signal<T> {
+  const sig = useMemo(() => signal(initialValue), []);
+  useSyncExternalStore(
+    (cb) => sig.subscribe(cb),
+    () => sig.value,
+    () => sig.value,
+  );
+  return sig;
+}
+
+export function useComputed<T>(fn: () => T): Signal<T> {
+  const sig = useMemo(() => signal(fn()), [fn]);
+  return sig;
+}
+
+export function computed<T>(fn: () => T): Signal<T> {
+  return signal(fn());
+}
+
+export function effect(fn: () => void | (() => void)): () => void {
+  const cleanup = fn();
+  return typeof cleanup === "function" ? cleanup : () => {};
+}
+
+export function batch(fn: () => void): void {
+  fn();
+}
+
+export function useSignalEffect(fn: () => void | (() => void)): void {
+  useEffect(fn);
+}
+
+export type { Signal as ReadonlySignal };
+`;
+}
+
 function generateSiteApp(ctx: MigrationContext): string {
   return `export type Platform =
   | "vtex"

package/scripts/migrate/phase-transform.ts

@@ -119,4 +119,89 @@ export function transform(ctx: MigrationContext): void {
   }
 
   console.log(`  Transformed ${ctx.transformedFiles.length} files`);
+
+  // Post-transform: resolve ~/islands/ imports to actual file locations.
+  // Islands are moved to src/sections/ during migration, but components
+  // import them via ~/islands/X which no longer exists. Scan src/ for
+  // the actual file and rewrite the import.
+  if (!ctx.dryRun) {
+    fixIslandImports(ctx);
+  }
+}
+
+/**
+ * Scan all transformed files for ~/islands/ imports and rewrite them
+ * to the actual path where the file was placed (sections/, components/, etc.).
+ */
+function fixIslandImports(ctx: MigrationContext): void {
+  const srcDir = path.join(ctx.sourceDir, "src");
+  if (!fs.existsSync(srcDir)) return;
+
+  // Build a lookup: filename → relative path from src/
+  const fileLookup = new Map<string, string[]>();
+  function scanDir(dir: string) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (entry.name === "node_modules" || entry.name === ".git") continue;
+        scanDir(path.join(dir, entry.name));
+      } else if (entry.name.endsWith(".tsx") || entry.name.endsWith(".ts")) {
+        const relPath = path.relative(srcDir, path.join(dir, entry.name)).replace(/\\/g, "/");
+        const base = entry.name.replace(/\.tsx?$/, "");
+        if (!fileLookup.has(base)) fileLookup.set(base, []);
+        fileLookup.get(base)!.push(relPath);
+      }
+    }
+  }
+  scanDir(srcDir);
+
+  // Scan all .ts/.tsx files in src/ for ~/islands/ imports
+  const islandImportRe = /from\s+["'](~\/islands\/([^"']+))["']/g;
+  let fixCount = 0;
+
+  function walkAndFix(dir: string) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (entry.name === "node_modules" || entry.name === ".git") continue;
+        walkAndFix(path.join(dir, entry.name));
+      } else if (entry.name.endsWith(".tsx") || entry.name.endsWith(".ts")) {
+        const filePath = path.join(dir, entry.name);
+        let content = fs.readFileSync(filePath, "utf-8");
+        let modified = false;
+
+        content = content.replace(islandImportRe, (match, fullImport, islandPath) => {
+          // islandPath = "Cart/Indicator" or "SliderJS" or "Searchbar"
+          const basename = islandPath.replace(/\.tsx?$/, "").split("/").pop()!;
+
+          // Try to find the file — prefer components/ over sections/
+          const candidates = fileLookup.get(basename) || [];
+          // Exclude islands/ paths themselves and routes/
+          const valid = candidates.filter(
+            (c) => !c.startsWith("islands/") && !c.startsWith("routes/"),
+          );
+
+          if (valid.length === 0) return match; // can't resolve, leave as-is
+
+          // Prefer components/ over sections/
+          const preferred =
+            valid.find((c) => c.startsWith("components/")) ??
+            valid.find((c) => c.startsWith("sections/")) ??
+            valid[0];
+
+          const newPath = "~/" + preferred.replace(/\.tsx?$/, "");
+          modified = true;
+          return match.replace(fullImport, newPath);
+        });
+
+        if (modified) {
+          fs.writeFileSync(filePath, content, "utf-8");
+          fixCount++;
+        }
+      }
+    }
+  }
+
+  walkAndFix(srcDir);
+  if (fixCount > 0) {
+    console.log(`  Fixed ~/islands/ imports in ${fixCount} files`);
+  }
 }

package/scripts/migrate/phase-verify.ts

@@ -261,14 +261,14 @@ const checks: Check[] = [
     },
   },
   {
-    name: "No dead cache/cacheKey/loader exports",
+    name: "No dead cache/cacheKey exports",
     severity: "warning",
     fn: (ctx) => {
       const srcDir = path.join(ctx.sourceDir, "src");
       if (!fs.existsSync(srcDir)) return true;
-      const bad = findFilesWithPattern(srcDir, /^export\s+const\s+(?:cache|cacheKey|loader)\s*=/m);
+      const bad = findFilesWithPattern(srcDir, /^export\s+const\s+(?:cache|cacheKey)\s*=/m);
       if (bad.length > 0) {
-        console.log(`    Dead exports found (old cache/loader system): ${bad.join(", ")}`);
+        console.log(`    Dead exports found (old cache system): ${bad.join(", ")}`);
         return false;
       }
       return true;

package/scripts/migrate/transforms/dead-code.ts

@@ -6,13 +6,57 @@ import type { TransformResult } from "../types.ts";
  *
  * - `export const cache = "stale-while-revalidate"` (old cache system)
  * - `export const cacheKey = ...` (old cache key generation)
- * - `export const loader = (props, req, ctx) => ...` (old section loader pattern)
  * - `crypto.subtle.digestSync(...)` (Deno-only sync API)
  *
+ * NOTE: `export const loader` is kept — it's a server-side function the CMS calls.
  * NOTE: invoke.* calls are NOT migrated — they are RPC calls to the server
  * where the CMS config (API keys, etc.) is available. The runtime.ts invoke
  * proxy handles routing them to /deco/invoke/*.
  */
+/**
+ * Remove an `export const <name> = ...` block using brace-counting
+ * so nested `{}` (for loops, if/else) don't cause premature truncation.
+ */
+function removeExportConstBlock(src: string, name: string): string {
+  const pattern = new RegExp(`^export\\s+const\\s+${name}\\s*=`, "m");
+  const match = pattern.exec(src);
+  if (!match) return src;
+
+  // Find the arrow `=>` first, then the opening `{` of the body.
+  // This avoids matching destructuring braces in parameters like
+  // `export const loader = ({ groups }: Props) => { ... }`
+  let pos = match.index + match[0].length;
+  // Look for `=>`
+  const arrowIdx = src.indexOf("=>", pos);
+  if (arrowIdx === -1) {
+    // No arrow function — try simple brace from current position
+    while (pos < src.length && src[pos] !== "{") pos++;
+  } else {
+    // Start searching for `{` after the arrow
+    pos = arrowIdx + 2;
+    while (pos < src.length && src[pos] !== "{") pos++;
+  }
+  if (pos >= src.length) return src; // no brace body, skip
+
+  // Count braces to find the matching closing brace
+  let depth = 0;
+  const start = match.index;
+  for (; pos < src.length; pos++) {
+    if (src[pos] === "{") depth++;
+    else if (src[pos] === "}") {
+      depth--;
+      if (depth === 0) {
+        // Skip optional semicolon and trailing newline
+        let end = pos + 1;
+        if (end < src.length && src[end] === ";") end++;
+        if (end < src.length && src[end] === "\n") end++;
+        return src.slice(0, start) + src.slice(end);
+      }
+    }
+  }
+  return src; // unbalanced braces, don't touch
+}
+
 export function transformDeadCode(content: string): TransformResult {
   const notes: string[] = [];
   let changed = false;
@@ -28,13 +72,9 @@ export function transformDeadCode(content: string): TransformResult {
     notes.push("Removed dead `export const cache` (old caching system)");
   }
 
-  // Remove old cacheKey export (can be multiline)
+  // Remove old cacheKey export (can be multiline with brace-counting)
   if (/^export\s+const\s+cacheKey\s*=/m.test(result)) {
-    // Try to remove the entire cacheKey function — find matching closing brace/semicolon
-    result = result.replace(
-      /^export\s+const\s+cacheKey\s*=\s*\([^)]*\)\s*(?::\s*\w+\s*)?=>\s*\{[\s\S]*?\n\};\s*\n?/gm,
-      "",
-    );
+    result = removeExportConstBlock(result, "cacheKey");
     // Also handle simpler inline forms
     result = result.replace(
       /^export\s+const\s+cacheKey\s*=[^;]*;\s*\n?/gm,
@@ -44,22 +84,8 @@ export function transformDeadCode(content: string): TransformResult {
     notes.push("Removed dead `export const cacheKey` (old caching system)");
   }
 
-  // Remove old section loader export: export const loader = (props, req, ctx) => { ... };
-  // This is the old pattern where sections had co-located loaders.
-  // In TanStack Start, section loaders are handled differently.
-  if (/^export\s+const\s+loader\s*=\s*\(/m.test(result)) {
-    result = result.replace(
-      /^export\s+const\s+loader\s*=\s*\([^)]*\)\s*(?::\s*[\w<>[\]|&\s]+)?\s*=>\s*\{[\s\S]*?\n\};\s*\n?/gm,
-      "",
-    );
-    // Also handle simpler inline forms
-    result = result.replace(
-      /^export\s+const\s+loader\s*=\s*\([^)]*\)\s*=>[^;]*;\s*\n?/gm,
-      "",
-    );
-    changed = true;
-    notes.push("Removed dead `export const loader` (old section loader — use section loaders in @decocms/start)");
-  }
+  // NOTE: `export const loader` is kept — these are server-side functions
+  // that the CMS calls to modify section props before rendering.
 
   // Replace crypto.subtle.digestSync (Deno-only) with a note
   if (result.includes("digestSync")) {

package/scripts/migrate/transforms/fresh-apis.ts

@@ -143,12 +143,17 @@ export function transformFreshApis(content: string): TransformResult {
     );
   }
 
-  // Remove <Head> wrapper — its children should go into route head() config
-  // This is complex to do with regex, so we flag it
+  // Replace <Head>...</Head> with <>...</>
+  // React 19 auto-hoists <title>, <meta>, <link> tags to document <head>.
   if (result.includes("<Head>") || result.includes("<Head ")) {
-    notes.push(
-      "MANUAL: <Head> component found — move contents to route head() config",
-    );
+    // Handle self-closing <Head ... /> first so it becomes <></> (not just <>)
+    result = result.replace(/<Head\s[^>]*\/>/g, "<></>");
+    result = result.replace(/<Head\s*\/>/g, "<></>");
+    result = result.replace(/<Head>/g, "<>");
+    result = result.replace(/<Head\s[^>]*>/g, "<>");
+    result = result.replace(/<\/Head>/g, "</>");
+    changed = true;
+    notes.push("Replaced <Head> with fragment — React 19 hoists head tags automatically");
   }
 
   // scriptAsDataURI → useScript with dangerouslySetInnerHTML

package/scripts/migrate/transforms/imports.ts

@@ -15,8 +15,8 @@ const IMPORT_RULES: Array<[RegExp, string | null]> = [
   [/^"preact\/jsx-runtime"$/, null],
   [/^"preact\/compat"$/, `"react"`],
   [/^"preact"$/, `"react"`],
-  [/^"@preact\/signals-core"$/, null],
-  [/^"@preact\/signals"$/, null],
+  [/^"@preact\/signals-core"$/, `"~/sdk/signal"`],
+  [/^"@preact\/signals"$/, `"~/sdk/signal"`],
 
   // Deco framework
   [/^"@deco\/deco\/hooks"$/, `"@decocms/start/sdk/useScript"`],
@@ -32,25 +32,41 @@ const IMPORT_RULES: Array<[RegExp, string | null]> = [
   [/^"apps\/website\/components\/Theme\.tsx"$/, `"~/components/ui/Theme"`],
   [/^"apps\/commerce\/types\.ts"$/, `"@decocms/apps/commerce/types"`],
 
-  // Apps — catch-all (things like apps/website/mod.ts, apps/vtex/mod.ts, etc.)
+  // Apps — VTEX (hooks, utils, actions, loaders, types)
+  [/^"apps\/vtex\/hooks\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/vtex/hooks/$1"`],
+  [/^"apps\/vtex\/utils\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/vtex/utils/$1"`],
+  [/^"apps\/vtex\/actions\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/vtex/actions/$1"`],
+  [/^"apps\/vtex\/loaders\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/vtex/loaders/$1"`],
+  [/^"apps\/vtex\/types(?:\.ts)?"$/, `"@decocms/apps/vtex/types"`],
+  // Apps — Shopify (hooks, utils, actions, loaders)
+  [/^"apps\/shopify\/hooks\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/shopify/hooks/$1"`],
+  [/^"apps\/shopify\/utils\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/shopify/utils/$1"`],
+  [/^"apps\/shopify\/actions\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/shopify/actions/$1"`],
+  [/^"apps\/shopify\/loaders\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/shopify/loaders/$1"`],
+  // Apps — commerce (types, SDK, utils)
+  [/^"apps\/commerce\/sdk\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/commerce/sdk/$1"`],
+  [/^"apps\/commerce\/utils\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/commerce/utils/$1"`],
+
+  // Apps — catch-all (things like apps/website/mod.ts, apps/analytics/mod.ts, etc.)
   [/^"apps\/([^"]+)"$/, null], // Remove — site.ts is rewritten
 
   // Deco old CDN imports
   [/^"deco\/([^"]+)"$/, null],
 
-  // Std lib — not needed in Node (Deno std lib)
+  // Std lib — redirect useful utils, remove the rest
+  [/^"std\/async\/debounce(?:\.ts)?"$/, `"~/sdk/debounce"`],
   [/^"std\/([^"]+)"$/, null],
   [/^"@std\/crypto"$/, null], // Use globalThis.crypto instead
 
   // site/sdk/* → framework equivalents (before the catch-all site/ → ~/ rule)
-  [/^"site\/sdk\/clx(?:\.tsx?)?.*"$/, `"@decocms/start/sdk/clx"`],
+  [/^"site\/sdk\/clx(?:\.tsx?)?.*"$/, `"~/sdk/clx"`],
   [/^"site\/sdk\/useId(?:\.tsx?)?.*"$/, `"react"`],
   [/^"site\/sdk\/useOffer(?:\.tsx?)?.*"$/, `"@decocms/apps/commerce/sdk/useOffer"`],
   [/^"site\/sdk\/useVariantPossiblities(?:\.tsx?)?.*"$/, `"@decocms/apps/commerce/sdk/useVariantPossibilities"`],
   [/^"site\/sdk\/usePlatform(?:\.tsx?)?.*"$/, null],
 
   // $store/ → ~/ (common Deno import map alias for project root)
-  [/^"\$store\/sdk\/clx(?:\.tsx?)?.*"$/, `"@decocms/start/sdk/clx"`],
+  [/^"\$store\/sdk\/clx(?:\.tsx?)?.*"$/, `"~/sdk/clx"`],
   [/^"\$store\/sdk\/useId(?:\.tsx?)?.*"$/, `"react"`],
   [/^"\$store\/sdk\/useOffer(?:\.tsx?)?.*"$/, `"@decocms/apps/commerce/sdk/useOffer"`],
   [/^"\$store\/sdk\/useVariantPossiblities(?:\.tsx?)?.*"$/, `"@decocms/apps/commerce/sdk/useVariantPossibilities"`],
@@ -67,8 +83,8 @@ const IMPORT_RULES: Array<[RegExp, string | null]> = [
  * The key is the ending of the import path, the value is the replacement specifier.
  */
 const RELATIVE_SDK_REWRITES: Array<[RegExp, string]> = [
-  // sdk/clx → @decocms/start/sdk/clx
-  [/(?:\.\.\/)*sdk\/clx(?:\.tsx?)?$/, "@decocms/start/sdk/clx"],
+  // sdk/clx → ~/sdk/clx (scaffolded locally with default export)
+  [/(?:\.\.\/)*sdk\/clx(?:\.tsx?)?$/, "~/sdk/clx"],
   // sdk/useId → react (useId is built-in in React 19)
   [/(?:\.\.\/)*sdk\/useId(?:\.tsx?)?$/, "react"],
   // sdk/useOffer → @decocms/apps/commerce/sdk/useOffer
@@ -219,6 +235,25 @@ export function transformImports(content: string): TransformResult {
     notes.push("Split useDevice into separate import from @decocms/start/sdk/useDevice");
   }
 
+  // Rewrite dynamic imports: route through rewriteSpecifier so sdk-specific
+  // rules (e.g. site/sdk/useId → react) are applied consistently.
+  const dynamicImportRe = /\bimport\(\s*(["'])([^"']+)\1\s*\)/g;
+  result = result.replace(dynamicImportRe, (_match, quote, specifier) => {
+    const quoted = `"${specifier}"`;
+    const rewritten = rewriteSpecifier(quoted);
+    if (rewritten === null) {
+      // Rule says remove — leave the dynamic import as-is (caller must fix manually)
+      return _match;
+    }
+    if (rewritten !== quoted) {
+      const newSpecifier = rewritten.slice(1, -1);
+      changed = true;
+      notes.push(`Rewrote dynamic import: ${specifier} → ${newSpecifier}`);
+      return `import(${quote}${newSpecifier}${quote})`;
+    }
+    return _match;
+  });
+
   // Clean up blank lines left by removed imports (collapse multiple to one)
   result = result.replace(/\n{3,}/g, "\n\n");
 

package/src/sdk/clx.ts

@@ -1,3 +1,5 @@
 /** Filter out nullable values, join and minify class names */
 export const clx = (...args: (string | null | undefined | false)[]) =>
   args.filter(Boolean).join(" ").replace(/\s\s+/g, " ");
+
+export default clx;

package/src/sdk/signal.ts

@@ -39,3 +39,4 @@ export function signal<T>(initialValue: T): ReactiveSignal<T> {
     },
   };
 }
+