@decocms/blocks-cli 7.21.1 → 7.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks-cli",
-  "version": "7.21.1",
+  "version": "7.22.0",
   "type": "module",
   "description": "Deco codegen (generate-blocks, generate-schema, generate-invoke) and Fresh-to-TanStack migration tooling",
   "repository": {
@@ -16,7 +16,8 @@
     "deco-cf-observability": "./scripts/migrate-to-cf-observability.ts",
     "deco-audit-observability": "./scripts/audit-observability-config.ts",
     "deco-migrate-blocks-to-kv": "./scripts/migrate-blocks-to-kv.ts",
-    "deco-sync-blocks-to-kv": "./scripts/sync-blocks-to-kv.ts"
+    "deco-sync-blocks-to-kv": "./scripts/sync-blocks-to-kv.ts",
+    "deco-upgrade-6-to-7": "./scripts/upgrade-6-to-7.ts"
   },
   "//exports": "Deliberately narrow. ./generate is the ONE public module entry (unified orchestrator); ./generate-blocks stays only because @decocms/tanstack's vite plugin tsImports it (readBlockDelta + programmatic generateBlocks) — each surviving entry must name its consumer here. The other scripts remain shipped FILES (the orchestrator spawns them; sites' existing `tsx node_modules/@decocms/blocks-cli/scripts/generate-*.ts` invocations keep working) but are internal implementation details of ./generate, not module subpaths. CLIs are exposed via bin, not exports.",
   "exports": {
@@ -30,7 +31,7 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.21.1",
+    "@decocms/blocks": "7.22.0",
     "ts-morph": "^27.0.0",
     "tsx": "^4.22.5"
   },

package/scripts/lib/upgrade-6-to-7.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, it } from "vitest";
+import { upgradeFileToV7 } from "./upgrade-6-to-7";
+
+describe("upgradeFileToV7 (#367) — simple 1:1 specifier rewrites", () => {
+  it("rewrites @decocms/start/vite", () => {
+    const r = upgradeFileToV7(`import { decoVitePlugin } from "@decocms/start/vite";`);
+    expect(r.changed).toBe(true);
+    expect(r.content).toBe(`import { decoVitePlugin } from "@decocms/tanstack/vite";`);
+  });
+
+  it("rewrites @decocms/start/sdk/cookiePassthrough", () => {
+    const r = upgradeFileToV7(
+      `import { getRequestCookieHeader } from "@decocms/start/sdk/cookiePassthrough";`,
+    );
+    expect(r.content).toBe(
+      `import { getRequestCookieHeader } from "@decocms/tanstack/sdk/cookiePassthrough";`,
+    );
+  });
+
+  it("rewrites @decocms/start/sdk/workerEntry and sdk/router to @decocms/tanstack root", () => {
+    const r = upgradeFileToV7(
+      [
+        `import { createDecoWorkerEntry } from "@decocms/start/sdk/workerEntry";`,
+        `import { createDecoRouter } from "@decocms/start/sdk/router";`,
+      ].join("\n"),
+    );
+    expect(r.content).toBe(
+      [
+        `import { createDecoWorkerEntry } from "@decocms/tanstack";`,
+        `import { createDecoRouter } from "@decocms/tanstack";`,
+      ].join("\n"),
+    );
+  });
+
+  it("rewrites generic @decocms/start/sdk/* to @decocms/blocks/sdk/*", () => {
+    const r = upgradeFileToV7(
+      [
+        `import { useScript } from "@decocms/start/sdk/useScript";`,
+        `import { useDevice } from "@decocms/start/sdk/useDevice";`,
+        `import { clx } from "@decocms/start/sdk/clx";`,
+      ].join("\n"),
+    );
+    expect(r.content).toBe(
+      [
+        `import { useScript } from "@decocms/blocks/sdk/useScript";`,
+        `import { useDevice } from "@decocms/blocks/sdk/useDevice";`,
+        `import { clx } from "@decocms/blocks/sdk/clx";`,
+      ].join("\n"),
+    );
+  });
+
+  it("rewrites @decocms/start/cms, /setup, /types/widgets, /admin", () => {
+    const r = upgradeFileToV7(
+      [
+        `import { resolveDecoPage } from "@decocms/start/cms";`,
+        `import { createSiteSetup } from "@decocms/start/setup";`,
+        `import type { ImageWidget } from "@decocms/start/types/widgets";`,
+        `import { handleMeta } from "@decocms/start/admin";`,
+      ].join("\n"),
+    );
+    expect(r.content).toContain(`from "@decocms/blocks/cms"`);
+    expect(r.content).toContain(`from "@decocms/blocks/setup"`);
+    expect(r.content).toContain(`from "@decocms/blocks/types/widgets"`);
+    expect(r.content).toContain(`from "@decocms/blocks-admin"`);
+  });
+
+  it("rewrites @decocms/apps/commerce/components/Image to @decocms/blocks/hooks", () => {
+    const r = upgradeFileToV7(`import { Image } from "@decocms/apps/commerce/components/Image";`);
+    expect(r.content).toBe(`import { Image } from "@decocms/blocks/hooks";`);
+  });
+
+  it("rewrites @decocms/apps/commerce/* to @decocms/apps-commerce/*", () => {
+    const r = upgradeFileToV7(`import type { Product } from "@decocms/apps/commerce/types";`);
+    expect(r.content).toBe(`import type { Product } from "@decocms/apps-commerce/types";`);
+  });
+
+  it("rewrites @decocms/apps/vtex/* to @decocms/apps-vtex/*", () => {
+    const r = upgradeFileToV7(`import { getUser } from "@decocms/apps/vtex/loaders/user";`);
+    expect(r.content).toBe(`import { getUser } from "@decocms/apps-vtex/loaders/user";`);
+  });
+
+  it("is a no-op for a file already on the 7.x split packages", () => {
+    const src = `import { createDecoWorkerEntry } from "@decocms/tanstack";\nimport { resolveDecoPage } from "@decocms/blocks/cms";\n`;
+    const r = upgradeFileToV7(src);
+    expect(r.changed).toBe(false);
+    expect(r.content).toBe(src);
+    expect(r.notes).toEqual([]);
+  });
+});
+
+describe("upgradeFileToV7 (#367) — @decocms/start/routes fan-out", () => {
+  it("moves cmsRouteConfig/cmsHomeRouteConfig to @decocms/tanstack root", () => {
+    const r = upgradeFileToV7(
+      `import { cmsRouteConfig, cmsHomeRouteConfig } from "@decocms/start/routes";`,
+    );
+    expect(r.content).toBe(
+      `import { cmsRouteConfig, cmsHomeRouteConfig } from "@decocms/tanstack";`,
+    );
+  });
+
+  it("splits deferredSectionLoader into its own subpath import", () => {
+    const r = upgradeFileToV7(
+      `import { cmsRouteConfig, deferredSectionLoader } from "@decocms/start/routes";`,
+    );
+    expect(r.content).toContain(`import { cmsRouteConfig } from "@decocms/tanstack";`);
+    expect(r.content).toContain(
+      `import { deferredSectionLoader } from "@decocms/tanstack/sdk/deferredSectionLoader";`,
+    );
+  });
+
+  it("renames decoMetaRoute/decoRenderRoute/decoInvokeRoute to their *RouteConfig factory names and flags a MANUAL call-site note", () => {
+    const src = [
+      `import { decoMetaRoute, decoRenderRoute, decoInvokeRoute } from "@decocms/start/routes";`,
+      `export const Route = createFileRoute("/deco/meta")({ ...decoMetaRoute });`,
+    ].join("\n");
+    const r = upgradeFileToV7(src);
+    expect(r.content).toContain(
+      `import { decoMetaRouteConfig, decoRenderRouteConfig, decoInvokeRouteConfig } from "@decocms/tanstack";`,
+    );
+    expect(r.content).toContain("...decoMetaRouteConfig }");
+    expect(r.notes.some((n) => n.includes("decoMetaRoute") && n.includes("factory"))).toBe(true);
+  });
+});
+
+describe("upgradeFileToV7 (#367) — @decocms/start/hooks fan-out", () => {
+  it("moves DecoPageRenderer/DecoRootLayout/PreviewProviders to @decocms/tanstack root", () => {
+    const r = upgradeFileToV7(
+      `import { DecoPageRenderer, DecoRootLayout, PreviewProviders } from "@decocms/start/hooks";`,
+    );
+    expect(r.content).toBe(
+      `import { DecoPageRenderer, DecoRootLayout, PreviewProviders } from "@decocms/tanstack";`,
+    );
+  });
+
+  it("renames RenderSection to SectionRenderer at the import and every usage", () => {
+    const src = [
+      `import { RenderSection } from "@decocms/start/hooks";`,
+      `export const x = <RenderSection section={s} />;`,
+    ].join("\n");
+    const r = upgradeFileToV7(src);
+    expect(r.content).toContain(`import { SectionRenderer } from "@decocms/tanstack";`);
+    expect(r.content).toContain("<SectionRenderer section={s} />");
+    expect(r.content).not.toContain("RenderSection");
+  });
+});

package/scripts/lib/upgrade-6-to-7.ts

@@ -0,0 +1,157 @@
+/**
+ * Codemod: upgrade a site off the frozen pre-split `@decocms/start@6.30.0` /
+ * `@decocms/apps@5.4.0` packages onto the current 7.x split
+ * (`@decocms/tanstack` + `@decocms/blocks` + `@decocms/blocks-admin` +
+ * `@decocms/apps-*`). See #367 — this is a DIFFERENT migration than
+ * Fresh→TanStack (`deco-migrate`): the site is already on TanStack, it's
+ * only the package dependency that needs to move.
+ *
+ * Mapping derived by hand against a real production site
+ * (montecarlo-tanstack) — see the issue for the full worked table. Symbol
+ * renames and relocations mean a pure specifier-string rewrite is not
+ * enough for every case; those are called out below.
+ */
+
+export interface UpgradeResult {
+  content: string;
+  changed: boolean;
+  notes: string[];
+}
+
+/** Straightforward 1:1 specifier rewrites — no symbol splitting needed. */
+const SIMPLE_SPECIFIER_MAP: Array<{ re: RegExp; to: string }> = [
+  { re: /@decocms\/start\/vite\b/g, to: "@decocms/tanstack/vite" },
+  { re: /@decocms\/start\/sdk\/cookiePassthrough\b/g, to: "@decocms/tanstack/sdk/cookiePassthrough" },
+  { re: /@decocms\/start\/sdk\/workerEntry\b/g, to: "@decocms/tanstack" },
+  { re: /@decocms\/start\/sdk\/router\b/g, to: "@decocms/tanstack" },
+  { re: /@decocms\/start\/cms\b/g, to: "@decocms/blocks/cms" },
+  { re: /@decocms\/start\/setup\b/g, to: "@decocms/blocks/setup" },
+  { re: /@decocms\/start\/types\/widgets\b/g, to: "@decocms/blocks/types/widgets" },
+  { re: /@decocms\/start\/admin\b/g, to: "@decocms/blocks-admin" },
+  { re: /@decocms\/apps\/commerce\/components\/Image\b/g, to: "@decocms/blocks/hooks" },
+  { re: /@decocms\/apps\/commerce\//g, to: "@decocms/apps-commerce/" },
+  { re: /@decocms\/apps\/vtex\//g, to: "@decocms/apps-vtex/" },
+];
+
+/**
+ * `@decocms/start/sdk/*` (useScript, useDevice, clx, signal, ...) → the
+ * matching `@decocms/blocks/sdk/*` subpath. Runs AFTER the more specific
+ * sdk/workerEntry, sdk/router, sdk/cookiePassthrough rewrites above so
+ * those aren't double-handled by this catch-all.
+ */
+const GENERIC_SDK_RE = /@decocms\/start\/sdk\/([\w-]+)/g;
+
+/** Named-import line: `import { A, B as C } from "spec";` (captures the clause + spec). */
+const NAMED_IMPORT_RE = /import\s+\{([^}]*)\}\s+from\s+["']([^"']+)["'];?/g;
+
+/** Symbols from `@decocms/start/routes` that move to `@decocms/tanstack/sdk/deferredSectionLoader`. */
+const DEFERRED_LOADER_SYMBOL = "deferredSectionLoader";
+
+/** Symbols renamed on the way from `@decocms/start/{routes,hooks}` to `@decocms/tanstack`. */
+const ROUTE_FACTORY_RENAMES: Record<string, string> = {
+  decoMetaRoute: "decoMetaRouteConfig",
+  decoRenderRoute: "decoRenderRouteConfig",
+  decoInvokeRoute: "decoInvokeRouteConfig",
+};
+const HOOKS_RENAMES: Record<string, string> = {
+  RenderSection: "SectionRenderer",
+};
+
+function splitNamedClause(clause: string): string[] {
+  return clause
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/** Handles the `@decocms/start/routes` and `@decocms/start/hooks` imports, which
+ * fan out to `@decocms/tanstack` (root) plus, for routes, a dedicated subpath
+ * for `deferredSectionLoader`. Symbol renames are applied to both the import
+ * clause and every usage in the file. */
+function rewriteRoutesAndHooksImports(
+  content: string,
+  notes: string[],
+): { content: string; changed: boolean } {
+  let changed = false;
+  // Collected here during the import-line pass, applied to the WHOLE file
+  // afterward — must not mutate `content`/the replace target mid-scan.
+  const pendingRenames: Array<{ from: string; to: string }> = [];
+
+  let result = content.replace(NAMED_IMPORT_RE, (line, clauseRaw: string, spec: string) => {
+    if (spec !== "@decocms/start/routes" && spec !== "@decocms/start/hooks") return line;
+
+    const isRoutes = spec === "@decocms/start/routes";
+    const renames = isRoutes ? ROUTE_FACTORY_RENAMES : HOOKS_RENAMES;
+    const names = splitNamedClause(clauseRaw);
+
+    const deferred: string[] = [];
+    const rootImports: string[] = [];
+
+    for (const name of names) {
+      if (isRoutes && name === DEFERRED_LOADER_SYMBOL) {
+        deferred.push(name);
+        continue;
+      }
+      const rename = renames[name];
+      if (rename) {
+        pendingRenames.push({ from: name, to: rename });
+        rootImports.push(rename);
+        if (isRoutes) {
+          notes.push(
+            `MANUAL: \`${name}\` is now the factory \`${rename}()\` in @decocms/tanstack — ` +
+              `add the call at every usage site (e.g. \`...${rename}()\` instead of \`...${rename}\`).`,
+          );
+        }
+        continue;
+      }
+      rootImports.push(name);
+    }
+
+    changed = true;
+    const lines: string[] = [];
+    if (rootImports.length > 0) {
+      lines.push(`import { ${rootImports.join(", ")} } from "@decocms/tanstack";`);
+    }
+    if (deferred.length > 0) {
+      lines.push(`import { ${deferred.join(", ")} } from "@decocms/tanstack/sdk/deferredSectionLoader";`);
+    }
+    return lines.join("\n");
+  });
+
+  for (const { from, to } of pendingRenames) {
+    result = result.replace(new RegExp(`\\b${from}\\b`, "g"), to);
+  }
+
+  return { content: result, changed };
+}
+
+/**
+ * Upgrade a single file's source from `@decocms/start` / `@decocms/apps`
+ * (pre-7.x-split) specifiers to the current split packages. Pure and
+ * side-effect-free — the CLI wrapper handles file I/O and package.json.
+ */
+export function upgradeFileToV7(content: string): UpgradeResult {
+  const notes: string[] = [];
+  let result = content;
+  let changed = false;
+
+  if (result.includes("@decocms/start/routes") || result.includes("@decocms/start/hooks")) {
+    const r = rewriteRoutesAndHooksImports(result, notes);
+    result = r.content;
+    changed = changed || r.changed;
+  }
+
+  for (const { re, to } of SIMPLE_SPECIFIER_MAP) {
+    const before = result;
+    result = result.replace(re, to);
+    if (result !== before) changed = true;
+  }
+
+  {
+    const before = result;
+    result = result.replace(GENERIC_SDK_RE, "@decocms/blocks/sdk/$1");
+    if (result !== before) changed = true;
+  }
+
+  return { content: result, changed, notes };
+}

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

@@ -0,0 +1,134 @@
+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";
+
+/**
+ * #367: blocks-cli must never leave the frozen pre-7.x-split package
+ * specifiers (@decocms/start@6.30.0, @decocms/apps@5.4.0) in a migrated
+ * site's src/ — including via a transform hand-off marker (jsx.ts emits
+ * `@decocms/start/hooks` as a same-run marker that phase-cleanup.ts is
+ * supposed to resolve to `@decocms/blocks/hooks`) that leaks past cleanup
+ * if the pipeline order ever changes.
+ */
+
+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 legacySpecifierCheck = checks.find(
+  (c) => c.name === "No frozen pre-split package specifiers in src/ (@decocms/start, @decocms/apps/*)",
+);
+if (!legacySpecifierCheck) {
+  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 = legacySpecifierCheck!.fn(ctx);
+    return { ok, output: lines.join("\n") };
+  } finally {
+    spy.mockRestore();
+  }
+}
+
+describe("verify check: 'No frozen pre-split package specifiers in src/' (#367)", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), "verify-legacy-specifiers-"));
+    fs.mkdirSync(path.join(tmp, "src", "hooks"), { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("passes when src/ only imports from the current split packages", () => {
+    fs.writeFileSync(
+      path.join(tmp, "src", "hooks", "useUser.ts"),
+      `import { SectionRenderer } from "@decocms/blocks/hooks";\n` +
+        `import { invoke } from "@decocms/blocks/sdk/invoke";\n` +
+        `export const x = 1;\n`,
+    );
+    const { ok, output } = runCheck(makeCtx(tmp));
+    expect(ok).toBe(true);
+    expect(output).toBe("");
+  });
+
+  it("fails when a `@decocms/start/hooks` hand-off marker leaked past cleanup", () => {
+    fs.writeFileSync(
+      path.join(tmp, "src", "hooks", "useUser.ts"),
+      `import { SectionRenderer } from "@decocms/start/hooks";\nexport const x = 1;\n`,
+    );
+    const { ok, output } = runCheck(makeCtx(tmp));
+    expect(ok).toBe(false);
+    expect(output).toContain("@decocms/start");
+  });
+
+  it("fails on a bare `@decocms/start` import (no subpath)", () => {
+    fs.writeFileSync(
+      path.join(tmp, "src", "hooks", "setup.ts"),
+      `import "@decocms/start";\nexport const x = 1;\n`,
+    );
+    const { ok } = runCheck(makeCtx(tmp));
+    expect(ok).toBe(false);
+  });
+
+  it("fails on a `@decocms/apps/vtex/...` monolith subpath import", () => {
+    fs.writeFileSync(
+      path.join(tmp, "src", "hooks", "old.ts"),
+      `import { getUser } from "@decocms/apps/vtex/loaders/user";\nexport const x = 1;\n`,
+    );
+    const { ok, output } = runCheck(makeCtx(tmp));
+    expect(ok).toBe(false);
+    expect(output).toContain("@decocms/apps/");
+  });
+
+  it("does not flag the current @decocms/apps-vtex split package", () => {
+    fs.writeFileSync(
+      path.join(tmp, "src", "hooks", "useUser.ts"),
+      `import { getUser } from "@decocms/apps-vtex/loaders/user";\nexport const x = 1;\n`,
+    );
+    const { ok } = runCheck(makeCtx(tmp));
+    expect(ok).toBe(true);
+  });
+
+  it("ignores commented-out references", () => {
+    fs.writeFileSync(
+      path.join(tmp, "src", "hooks", "Docs.ts"),
+      `// import { x } from "@decocms/start/hooks"\nexport const x = 1;\n`,
+    );
+    const { ok } = runCheck(makeCtx(tmp));
+    expect(ok).toBe(true);
+  });
+});

package/scripts/migrate/phase-verify.ts

@@ -410,6 +410,30 @@ export const checks: Check[] = [
       return true;
     },
   },
+  {
+    // Fleet-wide regression guard, complementing the scaffolder-only check
+    // in templates/no-legacy-packages.test.ts (#367): the frozen
+    // pre-7.x-split packages (@decocms/start@6.30.0, @decocms/apps@5.4.0)
+    // must never appear in a migrated site's src/, even via a transform
+    // hand-off marker that leaked past cleanup (see jsx.ts's
+    // `@decocms/start/hooks` same-run hand-off to phase-cleanup.ts).
+    name: "No frozen pre-split package specifiers in src/ (@decocms/start, @decocms/apps/*)",
+    severity: "error",
+    fn: (ctx) => {
+      const srcDir = path.join(ctx.sourceDir, "src");
+      if (!fs.existsSync(srcDir)) return true;
+      const bad = [
+        ...findFilesWithPattern(srcDir, /(?:from|import)\s+["']@decocms\/start(?:\/|["'])/),
+        ...findFilesWithPattern(srcDir, /from\s+["']@decocms\/apps\//),
+      ];
+      const unique = [...new Set(bad)];
+      if (unique.length > 0) {
+        console.log(`    Still references frozen @decocms/start or @decocms/apps/* specifiers: ${unique.join(", ")}`);
+        return false;
+      }
+      return true;
+    },
+  },
   {
     name: "Setup infrastructure is complete",
     severity: "error",