@decocms/blocks-cli 7.0.0

package/scripts/migrate/templates/lib-utils.ts

@@ -0,0 +1,326 @@
+/**
+ * Templates for src/lib/ utility wrappers that bridge signature gaps
+ * between deco-cx/apps (old stack) and @decocms/apps-start (new stack).
+ *
+ * These are written *lazily*: only shims that are actually imported by
+ * the migrated codebase get generated. See `selectImportedLibTemplates`.
+ *
+ * Lazy generation matters because:
+ * - Most sites end up importing zero of these (apps-start exports
+ *   direct equivalents for most VTEX utilities — see migrate#107).
+ * - Eager generation creates dead `src/lib/*.ts` files that every site
+ *   then has to clean up by hand (see baggagio-tanstack#7, ~235 LOC).
+ *
+ * Registry shape: `"src/lib/<name>.ts"` → file contents.
+ */
+export const LIB_TEMPLATES: Record<string, string> = {
+  // Filled in below after the const declarations to keep the registry
+  // and template literals colocated. See trailing assignment.
+};
+
+/**
+ * Given the set of `~/lib/X` imports actually present in the migrated
+ * codebase, return the subset of templates to write.
+ *
+ * `importedSpecifiers` are the `X` parts (without `~/lib/` prefix and
+ * without `.ts` extension), e.g. `"vtex-transform"`, `"http-utils"`.
+ */
+export function selectImportedLibTemplates(
+  importedSpecifiers: Set<string>,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const spec of importedSpecifiers) {
+    const key = `src/lib/${spec}.ts`;
+    if (key in LIB_TEMPLATES) {
+      out[key] = LIB_TEMPLATES[key];
+    }
+  }
+  return out;
+}
+
+// Per the migration tooling policy (D3 — Throwing stubs):
+// generated stubs MUST throw at runtime so the first call surfaces the
+// gap loudly. Silent identity-cast `toProduct` was the bug behind
+// baggagio-tanstack#10 (PDP product data was being dropped on the floor
+// for weeks before anyone noticed).
+//
+// Each thrown message points at the canonical replacement so the fix
+// is mechanical. `deco-post-cleanup --fix` automates the swap.
+const LIB_VTEX_TRANSFORM = `import type { Product } from "@decocms/apps/commerce/types";
+
+const STUB =
+  "[deco-migrate] \`~/lib/vtex-transform.toProduct\` is a generated stub. " +
+  "Replace with: import { toProduct } from '@decocms/apps/vtex/utils/transform' " +
+  "(canonical signature: \`toProduct(product, sku, level, options)\`). " +
+  "Run \`deco-post-cleanup --fix\` or see the deco-to-tanstack-migration skill " +
+  "(post-migration-cleanup § 5).";
+
+export function toProduct(_vtexProduct: any, ..._rest: any[]): Product {
+  throw new Error(STUB);
+}
+`;
+
+const LIB_VTEX_INTELLIGENT_SEARCH = `// Per the migration tooling policy (D3): \`getISCookiesFromBag\` cannot
+// be implemented on TanStack Start because the bag-based lookup
+// mechanism does not exist. Sites must read cookies directly from the
+// request — see the \`vtex-shim-regression\` audit rule for guidance.
+const STUB_GET_IS_COOKIES =
+  "[deco-migrate] \`~/lib/vtex-intelligent-search.getISCookiesFromBag\` is a " +
+  "generated stub. Refactor: extract IS cookies from " +
+  "\`request.headers.get('cookie')\` directly. The bag-based lookup mechanism " +
+  "does not exist on TanStack Start. See the deco-to-tanstack-migration " +
+  "skill (post-migration-cleanup § 5).";
+
+export function getISCookiesFromBag(_req?: any): Record<string, string> {
+  throw new Error(STUB_GET_IS_COOKIES);
+}
+
+export function isFilterParam(key: string): boolean {
+  return key.startsWith("filter.");
+}
+
+export function toPath(facets: { key: string; value: string }[]): string {
+  return facets.map((f) => \`\${f.key}/\${f.value}\`).join("/");
+}
+
+export function withDefaultFacets(
+  facets: { key: string; value: string }[],
+  defaults?: any,
+): { key: string; value: string }[] {
+  if (Array.isArray(defaults)) {
+    return [...defaults, ...facets];
+  }
+  return [...facets];
+}
+
+export function withDefaultParams(
+  params: any,
+  defaults?: Record<string, string>,
+): any {
+  if (params instanceof URLSearchParams) {
+    if (defaults) {
+      for (const [key, value] of Object.entries(defaults)) {
+        if (!params.has(key)) {
+          params.set(key, value);
+        }
+      }
+    }
+    return params;
+  }
+  return { ...params, ...defaults };
+}
+`;
+
+const LIB_VTEX_SEGMENT = `// Per the migration tooling policy (D3): both these stubs throw at
+// runtime to force the call site to be fixed. Silent fallbacks here
+// mean the storefront silently fails to forward VTEX segment data
+// (sales channel, regionId, currency, etc.) and pricing/inventory
+// quietly diverge from what the user should see.
+const STUB_GET_SEGMENT_FROM_BAG =
+  "[deco-migrate] \`~/lib/vtex-segment.getSegmentFromBag\` is a generated " +
+  "stub. Refactor: read cookies via \`request.headers.get('cookie')\` then " +
+  "call \`buildSegmentFromCookies()\` from '@decocms/apps/vtex/utils/segment'. " +
+  "The bag-based lookup mechanism does not exist on TanStack Start.";
+
+const STUB_WITH_SEGMENT_COOKIE =
+  "[deco-migrate] \`~/lib/vtex-segment.withSegmentCookie\` is a generated " +
+  "stub. Replace with: import { withSegmentCookie } from " +
+  "'@decocms/apps/vtex/utils/segment' (canonical signature: " +
+  "\`withSegmentCookie(segment, headers?)\`). Run \`deco-post-cleanup --fix\` " +
+  "or see the deco-to-tanstack-migration skill.";
+
+export function getSegmentFromBag(_req?: any): Record<string, unknown> | null {
+  throw new Error(STUB_GET_SEGMENT_FROM_BAG);
+}
+
+export function withSegmentCookie(..._args: any[]): any {
+  throw new Error(STUB_WITH_SEGMENT_COOKIE);
+}
+`;
+
+const LIB_HTTP_UTILS = `/**
+ * Drop-in replacement for the typed HTTP client from deco-cx/apps.
+ * Supports both simple \`.get(path)\` / \`.post(path, body)\` calls AND
+ * the indexed pattern \`client["GET /api/path"]({params}, {init})\`
+ * used by legacy loaders.
+ */
+export function createHttpClient<_T = any>(options: {
+  base: string;
+  headers?: Record<string, string> | Headers;
+  fetcher?: typeof fetch;
+}) {
+  const base = options.base.replace(/\\/$/, "");
+  const defaultHeaders: Record<string, string> =
+    options.headers instanceof Headers
+      ? Object.fromEntries(options.headers.entries())
+      : (options.headers || {});
+
+  const handler: ProxyHandler<Record<string, unknown>> = {
+    get(_target, prop) {
+      if (prop === "get") {
+        return async <R = any>(path: string, init?: RequestInit): Promise<R> => {
+          const res = await fetch(\`\${base}\${path}\`, {
+            ...init,
+            headers: { ...defaultHeaders, ...(init?.headers as Record<string, string>) },
+          });
+          return res.json();
+        };
+      }
+      if (prop === "post") {
+        return async <R = any>(path: string, body: unknown, init?: RequestInit): Promise<R> => {
+          const res = await fetch(\`\${base}\${path}\`, {
+            method: "POST",
+            ...init,
+            headers: {
+              "Content-Type": "application/json",
+              ...defaultHeaders,
+              ...(init?.headers as Record<string, string>),
+            },
+            body: JSON.stringify(body),
+          });
+          return res.json();
+        };
+      }
+      if (typeof prop === "string" && /^(GET|POST|PUT|PATCH|DELETE)\\s+/.test(prop)) {
+        const spaceIdx = prop.indexOf(" ");
+        const method = prop.slice(0, spaceIdx);
+        let apiPath = prop.slice(spaceIdx + 1);
+
+        return async (params: Record<string, any> = {}, init?: RequestInit) => {
+          const cleanParams = { ...params };
+
+          const starMatch = apiPath.match(/\\*(\\w+)/);
+          if (starMatch) {
+            const paramName = starMatch[1];
+            if (cleanParams[paramName] != null) {
+              apiPath = apiPath.replace(\`*\${paramName}\`, String(cleanParams[paramName]));
+              delete cleanParams[paramName];
+            } else {
+              apiPath = apiPath.replace(/\\/\\*\\w+/, "");
+            }
+          }
+
+          let url = \`\${base}\${apiPath}\`;
+
+          if (method === "GET") {
+            const sp = new URLSearchParams();
+            for (const [k, v] of Object.entries(cleanParams)) {
+              if (v !== undefined && v !== null) sp.set(k, String(v));
+            }
+            const qs = sp.toString();
+            if (qs) url += (url.includes("?") ? "&" : "?") + qs;
+          }
+
+          const fetchInit: RequestInit = {
+            method,
+            ...init,
+            headers: {
+              ...defaultHeaders,
+              ...(init?.headers instanceof Headers
+                ? Object.fromEntries(init.headers.entries())
+                : (init?.headers as Record<string, string>)),
+            },
+            ...(method !== "GET" && Object.keys(cleanParams).length > 0
+              ? { body: JSON.stringify(cleanParams) }
+              : {}),
+          };
+
+          const res = await fetch(url, fetchInit);
+          return { json: () => res.json(), ok: res.ok, status: res.status, headers: res.headers };
+        };
+      }
+      return undefined;
+    },
+  };
+
+  return new Proxy({} as Record<string, unknown>, handler) as any;
+}
+`;
+
+const LIB_VTEX_CLIENT = `export interface VTEXCommerceStable {
+  account: string;
+  environment?: string;
+}
+`;
+
+const LIB_FETCH_UTILS = `export const STALE = {
+  "Cache-Control": "public, max-age=120, stale-while-revalidate=600",
+};
+`;
+
+const LIB_VTEX_FETCH = `export async function fetchSafe(
+  input: string | URL | Request,
+  init?: RequestInit,
+): Promise<Response> {
+  const response = await fetch(input, init);
+  if (!response.ok) {
+    console.error(\`VTEX fetch failed: \${response.status} \${response.statusText}\`);
+  }
+  return response;
+}
+`;
+
+const LIB_VTEX_ID = `export function parseCookie(cookieStr?: string | null): Record<string, string> {
+  if (!cookieStr) return {};
+  return Object.fromEntries(
+    cookieStr.split(";").map((c) => {
+      const [key, ...rest] = c.trim().split("=");
+      return [key, rest.join("=")];
+    }),
+  );
+}
+`;
+
+const LIB_GRAPHQL_UTILS = `export function createGraphqlClient(options: {
+  endpoint: string;
+  headers?: Record<string, string>;
+}) {
+  return {
+    async query<T = any>(query: string, variables?: Record<string, unknown>): Promise<T> {
+      const res = await fetch(options.endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...options.headers,
+        },
+        body: JSON.stringify({ query, variables }),
+      });
+      const json = await res.json();
+      return json.data;
+    },
+  };
+}
+`;
+
+const LIB_FILTER_NAVIGATE = `/**
+ * Converts a VTEX filter URL string (e.g. "?filter.brand=x&filter.price=10:50")
+ * into a clean search string without internal params like \`payload\`.
+ * Returns "" or "?filter.brand=x&..." ready to append to pathname.
+ */
+export function toFilterSearchString(filterUrl: string): string {
+  const str = filterUrl.startsWith("?") ? filterUrl.slice(1) : filterUrl;
+  if (!str) return "";
+
+  const params = new URLSearchParams(str);
+  params.delete("payload");
+
+  const clean = params.toString();
+  return clean ? \`?\${clean}\` : "";
+}
+`;
+
+// Populate the registry now that all template literals are declared.
+// Keys must match the relative path the migration script writes; values
+// are the file contents.
+Object.assign(LIB_TEMPLATES, {
+  "src/lib/vtex-transform.ts": LIB_VTEX_TRANSFORM,
+  "src/lib/vtex-intelligent-search.ts": LIB_VTEX_INTELLIGENT_SEARCH,
+  "src/lib/vtex-segment.ts": LIB_VTEX_SEGMENT,
+  "src/lib/http-utils.ts": LIB_HTTP_UTILS,
+  "src/lib/vtex-client.ts": LIB_VTEX_CLIENT,
+  "src/lib/fetch-utils.ts": LIB_FETCH_UTILS,
+  "src/lib/vtex-fetch.ts": LIB_VTEX_FETCH,
+  "src/lib/vtex-id.ts": LIB_VTEX_ID,
+  "src/lib/graphql-utils.ts": LIB_GRAPHQL_UTILS,
+  "src/lib/filter-navigate.ts": LIB_FILTER_NAVIGATE,
+});

package/scripts/migrate/templates/lockfile-check-yml.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { generateLockfileCheckYml } from "./lockfile-check-yml";
+
+describe("generateLockfileCheckYml", () => {
+  it("emits a valid GitHub Actions workflow with the bun version pinned", () => {
+    const yaml = generateLockfileCheckYml("1.3.5");
+    expect(yaml).toContain("name: lockfile-check");
+    expect(yaml).toContain("on:");
+    expect(yaml).toContain("pull_request:");
+    expect(yaml).toContain("bun-version: 1.3.5");
+    expect(yaml).toContain("bun install --frozen-lockfile");
+  });
+
+  it("strips an accidental `bun@` prefix from the version input", () => {
+    const yaml = generateLockfileCheckYml("bun@1.3.5");
+    expect(yaml).toContain("bun-version: 1.3.5");
+    expect(yaml).not.toMatch(/bun-version:\s*bun@/);
+  });
+
+  it("scopes the trigger to package.json + bun.lock + the workflow itself", () => {
+    const yaml = generateLockfileCheckYml("1.3.5");
+    expect(yaml).toContain('"package.json"');
+    expect(yaml).toContain('"bun.lock"');
+    expect(yaml).toContain('".github/workflows/lockfile-check.yml"');
+  });
+});

package/scripts/migrate/templates/lockfile-check-yml.ts

@@ -0,0 +1,66 @@
+/**
+ * Generates `.github/workflows/lockfile-check.yml`, the PR-time
+ * guardrail that fails any pull request which would have failed
+ * Cloudflare Workers Builds with `lockfile had changes, but lockfile
+ * is frozen`. This catches drift before it reaches main, instead of
+ * only after deploy attempts.
+ *
+ * Lives in the site repo (per-site, not centralised) because per
+ * D6.3 we are NOT scaffolding caller stubs that pull in
+ * `decocms/deco-start@vN` reusable workflows. The check is small
+ * enough that copy-paste-per-site is the right tradeoff.
+ *
+ * Bun version pinning matches the `packageManager` field in the
+ * scaffolded `package.json` (see `templates/package-json.ts`'s
+ * `CANONICAL_BUN_VERSION`). Kept in lockstep manually for now;
+ * future iterations may consolidate both into a shared constant.
+ */
+export function generateLockfileCheckYml(bunVersion: string): string {
+  const v = stripBunPrefix(bunVersion);
+  return `name: lockfile-check
+
+# PR-time guardrail: re-runs the same install Cloudflare Workers Builds
+# runs on deploy (\`bun install --frozen-lockfile\`). Fails the PR if
+# bun.lock would have rejected the install — closes the loop so drift
+# can never reach main, only to be caught by Workers Builds at deploy
+# time.
+#
+# Pairs with:
+#   - "packageManager": "bun@${v}" in package.json
+#   - .gitignore bans on package-lock.json / yarn.lock / pnpm-lock.yaml
+#   - the deco-post-cleanup audit's lockfile-* rules
+#
+# Adjust \`bun-version\` here in lockstep with the package.json
+# \`packageManager\` field.
+
+on:
+  pull_request:
+    paths:
+      - "package.json"
+      - "bun.lock"
+      - ".github/workflows/lockfile-check.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  frozen-install:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: ${v}
+      - name: bun install --frozen-lockfile
+        run: bun install --frozen-lockfile
+`;
+}
+
+/**
+ * Strip an accidental `bun@` prefix from the version string so the
+ * YAML's `bun-version` input (which expects a bare semver) doesn't
+ * receive `bun@1.3.5`.
+ */
+function stripBunPrefix(input: string): string {
+  return input.replace(/^bun@/, "");
+}

package/scripts/migrate/templates/package-json.ts

@@ -0,0 +1,177 @@
+import { execSync } from "node:child_process";
+import type { MigrationContext } from "../types";
+
+/**
+ * Fleet-wide canonical bun version. Bumped here propagates to all newly
+ * migrated sites via the `packageManager` field AND the
+ * `lockfile-check.yml` workflow's `bun-version` input. See
+ * MIGRATION_TOOLING_PLAN.md for the bun-canonical decision.
+ *
+ * Exported because the lockfile-check workflow template reads it
+ * directly to keep both files in lockstep.
+ */
+export const CANONICAL_BUN_VERSION = "1.3.5";
+
+/**
+ * Get the latest published version of an npm package.
+ * Falls back to the provided default if the lookup fails.
+ */
+function getLatestVersion(pkg: string, fallback: string): string {
+  try {
+    const version = execSync(`npm view ${pkg} version`, {
+      encoding: "utf-8",
+      timeout: 10000,
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    return version || fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Extract npm dependencies from deno.json import map.
+ * Entries like `"fuse.js": "npm:fuse.js@7.0.0"` become `"fuse.js": "^7.0.0"`.
+ */
+function extractNpmDeps(importMap: Record<string, string>): Record<string, string> {
+  const deps: Record<string, string> = {};
+  const SKIP_KEYS = new Set([
+    "daisyui", "preact-render-to-string", "simple-git", "fast-json-patch",
+    "postcss", "cssnano", "partytown",
+  ]);
+  for (const [key, value] of Object.entries(importMap)) {
+    // Skip framework deps we handle ourselves
+    if (key.startsWith("preact") || key.startsWith("@preact/")) continue;
+    if (key.startsWith("@deco/")) continue;
+    if (key.startsWith("@biomejs/")) continue;
+    if (key.startsWith("firebase/")) continue;
+    if (SKIP_KEYS.has(key)) continue;
+
+    // npm: protocol — direct npm import
+    if (value.startsWith("npm:")) {
+      const raw = value.slice(4);
+      const atIdx = raw.lastIndexOf("@");
+      if (atIdx <= 0) {
+        deps[raw] = "*";
+      } else {
+        const name = raw.slice(0, atIdx);
+        let version = raw.slice(atIdx + 1);
+        if (/^[~^>=<]/.test(version)) {
+          deps[name] = version;
+        } else {
+          deps[name] = `^${version}`;
+        }
+      }
+      continue;
+    }
+
+    // esm.sh URLs — extract package name and version
+    const esmMatch = value.match(/esm\.sh\/(@?[^@?]+)@([^?/]+)/);
+    if (esmMatch) {
+      const [, name, version] = esmMatch;
+      if (name.startsWith("preact") || name.startsWith("@preact/")) continue;
+      deps[name] = `^${version}`;
+      continue;
+    }
+  }
+  return deps;
+}
+
+export function generatePackageJson(ctx: MigrationContext): string {
+  const extractedDeps = {
+    ...extractNpmDeps(ctx.importMap),
+    ...ctx.discoveredNpmDeps,
+  };
+
+  // Consolidate firebase/* split imports into single package
+  const hasFirebase = Object.keys(ctx.importMap).some((k) => k.startsWith("firebase"));
+  if (hasFirebase && !extractedDeps["firebase"]) {
+    extractedDeps["firebase"] = "^12.10.0";
+  }
+  // Remove wildcard versions
+  for (const [k, v] of Object.entries(extractedDeps)) {
+    if (v === "^*" || v === "*") extractedDeps[k] = "latest";
+  }
+
+  const siteDeps = extractedDeps;
+
+  // Fetch latest versions from npm registry
+  const startVersion = getLatestVersion("@decocms/start", "0.34.0");
+  const appsVersion = getLatestVersion("@decocms/apps", "0.27.0");
+
+  const pkg = {
+    name: ctx.siteName,
+    version: "0.1.0",
+    type: "module",
+    description: `${ctx.siteName} storefront powered by TanStack Start`,
+    scripts: {
+      dev: "vite dev",
+      "dev:clean":
+        "rm -rf node_modules/.vite .wrangler/state .tanstack && vite dev",
+      "generate:blocks":
+        "tsx node_modules/@decocms/start/scripts/generate-blocks.ts",
+      "generate:routes": "tsr generate",
+      "generate:schema": `tsx node_modules/@decocms/start/scripts/generate-schema.ts --site ${ctx.siteName}`,
+      "generate:invoke":
+        "tsx node_modules/@decocms/start/scripts/generate-invoke.ts",
+      "generate:sections":
+        "tsx node_modules/@decocms/start/scripts/generate-sections.ts",
+      "generate:loaders": `tsx node_modules/@decocms/start/scripts/generate-loaders.ts --exclude vtex/loaders,vtex/actions,loaders/vtex-auth-loader,loaders/reviews/productReviews,loaders/product/buyTogether,loaders/search/productListPageCollection,loaders/search/intelligenseSearch,loaders/Layouts/ProductCard`,
+      build:
+        "npm run generate:blocks && npm run generate:sections && npm run generate:loaders && npm run generate:schema && npm run generate:invoke && tsr generate && vite build",
+      preview: "vite preview",
+      // Deploy is owned by Cloudflare Workers Builds (D6.3); the
+      // repo<->worker connection is configured per-worker in the CF
+      // dashboard. Local devs use plain `wrangler` against the
+      // committed wrangler.jsonc.
+      deploy: "wrangler deploy",
+      types: "wrangler types",
+      typecheck: "tsc --noEmit",
+      format: 'prettier --write "src/**/*.{ts,tsx}"',
+      "format:check": 'prettier --check "src/**/*.{ts,tsx}"',
+      knip: "knip",
+      clean:
+        "rm -rf node_modules .cache dist .wrangler/state node_modules/.vite && bun install",
+      "tailwind:lint":
+        "tsx scripts/tailwind-lint.ts",
+      "tailwind:fix":
+        "tsx scripts/tailwind-lint.ts --fix",
+    },
+    author: "deco.cx",
+    license: "MIT",
+    packageManager: `bun@${CANONICAL_BUN_VERSION}`,
+    dependencies: {
+      "@decocms/apps": `^${appsVersion}`,
+      "@decocms/start": `^${startVersion}`,
+      "@tanstack/react-query": "5.90.21",
+      "@tanstack/react-router": "1.166.7",
+      "@tanstack/react-start": "1.166.8",
+      "@tanstack/react-store": "0.9.2",
+      "@tanstack/store": "0.9.2",
+      "colorjs.io": "^0.6.1",
+      react: "^19.2.4",
+      "react-dom": "^19.2.4",
+      ...siteDeps,
+    },
+    devDependencies: {
+      "@cloudflare/vite-plugin": "^1.27.0",
+      "@tailwindcss/vite": "^4.2.1",
+      "@tanstack/router-cli": "1.166.7",
+      "@types/react": "^19.2.14",
+      "@types/react-dom": "^19.2.3",
+      "@vitejs/plugin-react": "^5.1.4",
+      "babel-plugin-react-compiler": "^1.0.0",
+      "daisyui": "^5.5.19",
+      knip: "^5.61.2",
+      prettier: "^3.5.3",
+      tailwindcss: "^4.2.1",
+      "ts-morph": "^27.0.2",
+      tsx: "^4.19.4",
+      typescript: "^5.9.3",
+      vite: "^7.3.1",
+      wrangler: "^4.72.0",
+    },
+  };
+
+  return JSON.stringify(pkg, null, 2) + "\n";
+}