@decocms/blocks-migrate 0.0.0-stage → 8.0.0-next.0

package/bin/blocks-migrate.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// The `blocks-migrate` command. Loads the TypeScript sources: Bun runs them
+// as they are; under Node, tsx's loader is registered first (the same way
+// `deco` ships in @decocms/blocks).
+const entry = new URL("../src/main.ts", import.meta.url);
+
+if (typeof globalThis.Bun !== "undefined") {
+  await import(entry.href);
+} else {
+  const { register } = await import("tsx/esm/api");
+  register();
+  await import(entry.href);
+}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@decocms/blocks-migrate",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "8.0.0-next.0",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "description": "One-time migration of a v7 Deco site to the next major: block map with legacy aliases, vendored loaders, content in .deco/blocks, secret re-encryption and an import report",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/decocms/blocks.git",
+    "directory": "packages/blocks-migrate"
+  },
+  "files": [
+    "bin",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "bin": {
+    "blocks-migrate": "./bin/blocks-migrate.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run --root ../.. packages/blocks-migrate/",
+    "typecheck": "tsc --noEmit",
+    "lint:unused": "knip"
+  },
+  "dependencies": {
+    "@decocms/blocks": "8.0.0-next.0",
+    "tsx": "^4.22.5",
+    "typescript": "^5.9.3"
+  },
+  "devDependencies": {
+    "knip": "^5.86.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}

package/src/blockMap.ts

@@ -0,0 +1,344 @@
+/**
+ * The block map (spec: renames-and-migrations › Rename a block type). Saved
+ * content names v7 types by file path, like `site/sections/Product/Shelf.tsx`;
+ * the next major resolves a name only through `.deco/index.ts`. This step
+ * writes that file: one entry per type, under a short name, plus an alias
+ * under every v7 name the content stores, so the content keeps resolving.
+ *
+ * - The site's own modules (`site/…`) are registered from `src/`, every
+ *   section under `src/sections` included, so editors can still add them.
+ * - App loaders and actions the content calls are vendored first (see
+ *   ./vendor.ts) and registered from the copy.
+ * - Built-ins and the legacy names the runtime already maps (`page`,
+ *   `multivariate`, …) need no entry.
+ * - Everything else has no v8 equivalent; it is reported, not registered.
+ *
+ * Sections return render descriptors, `{ component, props }`, and `page`
+ * takes them (see /next/tanstack-start-descriptors): it works in any
+ * framework, and the site's view registry maps each component name to the
+ * section it renders.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { BUILT_IN_BLOCKS, LEGACY_ALIASES } from "@decocms/blocks/cli";
+import type { Report } from "./report";
+import { firstFile, locateAppModule, vendorModule } from "./vendor";
+import { forEachBlock, readContent } from "./walk";
+
+type Kind = "section" | "function";
+
+interface Entry {
+  /** The module that holds the block function (default export). */
+  file: string;
+  kind: Kind;
+  /** The v7 names content stores for it. */
+  legacy: string[];
+  short: string;
+  ident: string;
+}
+
+const ANALYTICS_SECTION = /^website\/sections\/Analytics\//;
+
+/** Where to look for a type without a v8 equivalent. */
+const HINTS: [RegExp, string][] = [
+  [
+    /\/apps\//,
+    "a v7 app block; the next major has no apps: create the platform's client in code with these settings (/next/upstream-clients#call-a-client), then delete the saved block",
+  ],
+  [
+    /^website\/sections\/Rendering\/(Lazy|Deferred|SingleDeferred)\.tsx?$/,
+    "v7's Lazy section wrapper: register a block under this name that returns its `section` (it renders normally), or unwrap it in the content",
+  ],
+  [
+    /\/sections\/Seo\//,
+    "an SEO section: register your platform template's SEO block under this name (/next/renames-and-migrations#rename-a-type-with-an-alias)",
+  ],
+  [
+    ANALYTICS_SECTION,
+    "v7's Analytics section: move its tag IDs into your template's tag-manager block (/next/renames-and-migrations#telemetry-and-analytics)",
+  ],
+  [
+    /\/matchers\//,
+    "a v7 matcher with no built-in: register a matcher block under this name (/next/matchers-and-variants#matchers)",
+  ],
+  [
+    /^website\/functions\/requestToParam/,
+    "reads the request; take route params from matchRoute's `params` instead (/next/api-reference#matchroute-url-items)",
+  ],
+];
+const DEFAULT_HINT =
+  "no v8 equivalent and no installed source to vendor: register a block under this name in .deco/index.ts, or migrate the content";
+
+function hintFor(type: string): string {
+  return HINTS.find(([pattern]) => pattern.test(type))?.[1] ?? DEFAULT_HINT;
+}
+
+function kebab(name: string): string {
+  return name
+    .replace(/\.(tsx?|jsx?)$/, "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+    .replace(/[^A-Za-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase();
+}
+
+const RESERVED_WORDS = new Set(
+  `arguments await break case catch class const continue debugger default delete do else enum eval
+  export extends false finally for function if implements import in instanceof interface let new null
+  package private protected public return static super switch this throw true try typeof var void
+  while with yield`.split(/\s+/),
+);
+
+function camel(name: string): string {
+  const ident = name.replace(/-([a-z0-9])/g, (_, c: string) => c.toUpperCase());
+  if (/^[0-9]/.test(ident)) return `_${ident}`;
+  return RESERVED_WORDS.has(ident) ? `${ident}Block` : ident;
+}
+
+function moduleFile(base: string): string | undefined {
+  return /\.(tsx?)$/.test(base) ? firstFile([base]) : firstFile([`${base}.ts`, `${base}.tsx`]);
+}
+
+function listFiles(dir: string, ext: RegExp): string[] {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir, { recursive: true, withFileTypes: true })
+    .filter((d) => d.isFile() && ext.test(d.name) && !/\.test\.tsx?$/.test(d.name))
+    .map((d) => path.join(d.parentPath, d.name));
+}
+
+const HAS_DEFAULT = /\bexport\s+default\b|\bexport\s*\{[^}]*\bdefault\b/;
+const HAS_LOADER =
+  /\bexport\s+(?:async\s+)?(?:function|const|let)\s+loader\b|\bexport\s*\{[^}]*\bloader\b/;
+
+function posix(p: string): string {
+  return p.split(path.sep).join("/");
+}
+
+function importPath(root: string, file: string): string {
+  const rel = posix(path.relative(path.join(root, ".deco"), file)).replace(/\.tsx?$/, "");
+  return rel.startsWith(".") ? rel : `./${rel}`;
+}
+
+interface BlockMapResult {
+  /** Each vendored module: installed source → its copy in the site. */
+  vendored: Map<string, string>;
+}
+
+/** Write `.deco/index.ts` from the site's content and sources. Keeps an existing block map. */
+export function writeBlockMap(root: string, report: Report): BlockMapResult {
+  const existing = ["index.ts", "index.tsx"].find((f) =>
+    fs.existsSync(path.join(root, ".deco", f)),
+  );
+  if (existing) {
+    report.manual.push({
+      step: "block map",
+      subject: `.deco/${existing}`,
+      message: "already exists, so it was kept; delete it and run again to generate one",
+    });
+    return { vendored: new Map() };
+  }
+
+  const { blocks, files } = readContent(root);
+  const used = new Map<string, Set<string>>();
+  /** v7 Analytics sections' GTM/GA4 IDs, so the report carries them over. */
+  const tagIds = new Map<string, Set<string>>();
+  for (const [entry, block] of Object.entries(blocks)) {
+    forEachBlock(block, (node) => {
+      const type = node.__resolveType;
+      if (!used.has(type)) used.set(type, new Set());
+      used.get(type)!.add(files[entry]);
+      if (!ANALYTICS_SECTION.test(type)) return;
+      for (const field of ["trackingIds", "googleAnalyticsIds"]) {
+        const ids = node[field];
+        if (!Array.isArray(ids)) continue;
+        if (!tagIds.has(type)) tagIds.set(type, new Set());
+        for (const id of ids) if (typeof id === "string" && id) tagIds.get(type)!.add(id);
+      }
+    });
+  }
+  const builtIn = new Set(BUILT_IN_BLOCKS);
+  const types = new Set(
+    [...used.keys()].filter(
+      (t) => !Object.hasOwn(blocks, t) && !builtIn.has(t) && !Object.hasOwn(LEGACY_ALIASES, t),
+    ),
+  );
+  for (const file of listFiles(path.join(root, "src", "sections"), /\.tsx$/)) {
+    const type = `site/${posix(path.relative(path.join(root, "src"), file))}`;
+    if (!types.has(type) && !types.has(type.replace(/\.tsx$/, ""))) types.add(type);
+  }
+
+  const byFile = new Map<string, Entry>();
+  const vendored = new Map<string, string>();
+  const leave = (type: string, hint: string) => {
+    const ids = [...(tagIds.get(type) ?? [])];
+    const message = ids.length > 0 ? `${hint}; its tag IDs: ${ids.join(", ")}` : hint;
+    const where = [...(used.get(type) ?? [])];
+    const usedIn =
+      where.length > 0
+        ? ` (in ${where.slice(0, 3).join(", ")}${where.length > 3 ? ", …" : ""})`
+        : "";
+    report.manual.push({ step: "block map", subject: `${type}${usedIn}`, message });
+  };
+
+  for (const type of [...types].sort()) {
+    const [namespace, group] = type.split("/");
+    const kind: Kind = group === "sections" ? "section" : "function";
+    let file: string | undefined;
+    if (namespace === "site") {
+      const rest = type.slice("site/".length);
+      if (rest.split("/").includes("..")) {
+        leave(
+          type,
+          "not a path inside src/; register a block under this name, or migrate the content",
+        );
+        continue;
+      }
+      if (rest.startsWith("apps/")) {
+        leave(type, hintFor(type));
+        continue;
+      }
+      file = moduleFile(path.join(root, "src", rest));
+      if (!file) {
+        leave(
+          type,
+          `no src/${rest} in the site; register a block under this name, or migrate the content`,
+        );
+        continue;
+      }
+    } else if (group === "loaders" || group === "actions") {
+      const located = locateAppModule(root, type);
+      if (!located) {
+        leave(type, hintFor(type));
+        continue;
+      }
+      const before = vendored.size;
+      file = vendorModule(root, located, vendored, report);
+      const count = vendored.size - before;
+      report.done.push({
+        step: "vendor",
+        subject: type,
+        message: `copied to ${posix(path.relative(root, file))}${count > 1 ? ` with ${count - 1} more files` : ""}; rewrite it over the platform's upstream client (/next/upstream-clients)`,
+      });
+    } else {
+      leave(type, hintFor(type));
+      continue;
+    }
+
+    const source = fs.readFileSync(file, "utf8");
+    if (!HAS_DEFAULT.test(source)) {
+      leave(type, `${posix(path.relative(root, file))} has no default export to register`);
+      continue;
+    }
+    const entry = byFile.get(file);
+    if (entry) {
+      entry.legacy.push(type);
+      continue;
+    }
+    byFile.set(file, { file, kind, legacy: [type], short: "", ident: "" });
+    if (kind === "section" && HAS_LOADER.test(source)) {
+      leave(
+        type,
+        "the section has a loader: its saved props are the loader's input (as in v7), but nothing runs the loader; move that code into the block function or a server function",
+      );
+    }
+    if (group === "actions") {
+      leave(
+        type,
+        "an action: block functions should only read; call it from a server function or route handler instead (/next/renames-and-migrations#loaders-actions-and-invoke)",
+      );
+    }
+  }
+
+  // Short names: the file's name, then its path, then a number; never a
+  // built-in, a saved block's name or a v7 name.
+  const taken = new Set<string>([...builtIn, ...Object.keys(blocks), ...types]);
+  const idents = new Set<string>(["section", "PropsOf"]);
+  const entries = [...byFile.values()];
+  for (const entry of entries) {
+    const type = entry.legacy[0];
+    const segments = type.split("/");
+    const prefix = segments[0] === "site" ? "" : `${segments[0]}-`;
+    const candidates = [
+      prefix + kebab(segments.at(-1)!),
+      prefix + kebab(segments.slice(2).join("-")),
+    ];
+    let short = candidates.find((c) => c && !taken.has(c));
+    for (let n = 2; !short; n++)
+      if (!taken.has(`${candidates[1]}-${n}`)) short = `${candidates[1]}-${n}`;
+    taken.add(short);
+    entry.short = short;
+    let ident = camel(short);
+    for (let n = 2; idents.has(ident); n++) ident = `${camel(short)}${n}`;
+    idents.add(ident);
+    entry.ident = ident;
+  }
+
+  fs.writeFileSync(path.join(root, ".deco", "index.ts"), renderBlockMap(root, entries));
+  const aliases = entries.reduce((n, e) => n + e.legacy.length, 0);
+  report.done.push({
+    step: "block map",
+    subject: ".deco/index.ts",
+    message: `${entries.length} blocks, with ${aliases} aliases under their v7 names`,
+  });
+  if (entries.some((e) => e.kind === "section")) {
+    report.manual.push({
+      step: "block map",
+      subject: ".deco/index.ts",
+      message:
+        "sections return descriptors ({ component, props }): add a view registry that maps each component name to its section (/next/rendering)",
+    });
+  }
+  return { vendored };
+}
+
+function renderBlockMap(root: string, entries: Entry[]): string {
+  const lines = [
+    "// Generated by @decocms/blocks-migrate from a v7 site. It's your code now: edit it freely.",
+    "// Each block has a short name plus an alias under every v7 name saved content stores",
+    "// (see /next/renames-and-migrations).",
+    'import type { Blocks, Route, Seo } from "@decocms/blocks";',
+  ];
+  for (const e of entries.filter((e) => e.kind === "function")) {
+    lines.push(`import ${e.ident} from "${importPath(root, e.file)}";`);
+  }
+  lines.push(
+    "",
+    "/** What a section block returns: the component to render and its props (/next/rendering). */",
+    "export interface BlockDescriptor {",
+    "  component: string;",
+    "  props: unknown;",
+    "}",
+    "",
+    "/** A page with its blocks resolved. */",
+    "export interface ResolvedPage extends Route {",
+    "  seo?: Seo;",
+    "  sections: BlockDescriptor[];",
+    "}",
+    "",
+    "/** A v7 section's saved props: its loader's input when it has one, else its component's props. */",
+    "type PropsOf<M> = M extends { loader: (props: infer P, ...rest: any[]) => unknown }",
+    "  ? P",
+    "  : M extends { default: (props: infer P, ...rest: any[]) => unknown }",
+    "    ? P",
+    "    : Record<string, never>;",
+    "",
+    "const section =",
+    "  <M>(component: string) =>",
+    "  (props: PropsOf<M>): BlockDescriptor => ({ component, props });",
+    "",
+  );
+  for (const e of entries.filter((e) => e.kind === "section")) {
+    lines.push(
+      `const ${e.ident} = section<typeof import("${importPath(root, e.file)}")>(${JSON.stringify(e.short)});`,
+    );
+  }
+  lines.push("", "export default {", "  page: (input: ResolvedPage) => input,");
+  for (const e of entries) {
+    lines.push(`  ${JSON.stringify(e.short)}: ${e.ident},`);
+    for (const legacy of e.legacy) lines.push(`  ${JSON.stringify(legacy)}: ${e.ident},`);
+  }
+  lines.push("} satisfies Blocks;", "");
+  return lines.join("\n");
+}

package/src/content.ts

@@ -0,0 +1,121 @@
+/**
+ * Content: the next major reads saved blocks only from `.deco/blocks`, one
+ * JSON file per entry, named by the protocol's file-name rule
+ * (`@decocms/blocks/protocol/keys`). A v7 site that has them there keeps
+ * them as they are; one that only has a decofile (the `/.decofile` dump, or
+ * the generated `.deco/blocks.gen.json`) gets it split into files. The v7
+ * generated files in `.deco/` go: `deco schema` and `deco content` write
+ * their replacements.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { blockFileName, checkBlockName, serializeBlock } from "@decocms/blocks/protocol/keys";
+import type { Report } from "./report";
+import { isPlainObject, readContent } from "./walk";
+
+/** Generated by the v7 codegen; nothing in the next major reads them. */
+const V7_GENERATED = [
+  "blocks.gen.json",
+  "blocks.gen.ts",
+  "loaders.gen.ts",
+  "sections.gen.ts",
+  "meta.gen.json",
+];
+
+/** Where a v7 site may keep a whole decofile, tried in order. */
+const DECOFILE_CANDIDATES = [".deco/blocks.gen.json", ".decofile.json", ".decofile"];
+
+function hasJsonFiles(dir: string): boolean {
+  try {
+    return fs.readdirSync(dir).some((f) => f.endsWith(".json"));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The entries of a decofile: a map of entry name to block, either at the top
+ * level or under `blocks` (the shape `/.decofile` serves).
+ */
+export function decofileEntries(decofile: unknown): Record<string, Record<string, unknown>> {
+  if (!isPlainObject(decofile)) return {};
+  const values = Object.values(decofile);
+  const flat = values.length > 0 && values.every((v) => isPlainObject(v) && "__resolveType" in v);
+  const map = flat ? decofile : isPlainObject(decofile.blocks) ? decofile.blocks : {};
+  const entries: Record<string, Record<string, unknown>> = {};
+  for (const [name, block] of Object.entries(map)) {
+    if (isPlainObject(block)) entries[name] = block;
+  }
+  return entries;
+}
+
+interface MoveContentOptions {
+  /** A decofile to split into `.deco/blocks`, relative to the root. */
+  decofile?: string;
+}
+
+export function moveContent(root: string, report: Report, options: MoveContentOptions = {}): void {
+  const blocksDir = path.join(root, ".deco", "blocks");
+  const hasContent = hasJsonFiles(blocksDir);
+  if (options.decofile && hasContent) {
+    throw new Error(`--decofile given but .deco/blocks already has content`);
+  }
+  if (!hasContent) {
+    const candidates = options.decofile ? [options.decofile] : DECOFILE_CANDIDATES;
+    const source = candidates.map((c) => path.resolve(root, c)).find((c) => fs.existsSync(c));
+    if (source) {
+      const entries = decofileEntries(JSON.parse(fs.readFileSync(source, "utf8")));
+      fs.mkdirSync(blocksDir, { recursive: true });
+      let written = 0;
+      for (const [name, block] of Object.entries(entries)) {
+        const [invalid] = checkBlockName(name);
+        if (invalid) {
+          report.manual.push({
+            step: "content",
+            subject: name,
+            message: `not a valid entry name (${invalid.message}); save it under another name`,
+          });
+          continue;
+        }
+        fs.writeFileSync(path.join(blocksDir, blockFileName(name)), serializeBlock(block));
+        written++;
+      }
+      report.done.push({
+        step: "content",
+        subject: path.relative(root, source),
+        message: `split into ${written} files in .deco/blocks`,
+      });
+    } else if (options.decofile) {
+      throw new Error(`no decofile at ${options.decofile}`);
+    } else {
+      report.manual.push({
+        step: "content",
+        subject: ".deco/blocks",
+        message:
+          "no saved blocks found; download the live content (GET <site>/.decofile) and pass it with --decofile",
+      });
+    }
+  }
+
+  // Names the file-name rule rejects (v7 saved editor previews like
+  // "Preview site/sections/Hero.tsx"): deco content stops on them.
+  for (const d of readContent(root).diagnostics) {
+    if (d.severity !== "error") continue;
+    report.manual.push({
+      step: "content",
+      subject: `.deco/blocks/${d.file}`,
+      message: `${d.message}, or delete it if nothing references it`,
+    });
+  }
+
+  for (const file of V7_GENERATED) {
+    const full = path.join(root, ".deco", file);
+    if (!fs.existsSync(full)) continue;
+    fs.rmSync(full);
+    report.done.push({
+      step: "content",
+      subject: `.deco/${file}`,
+      message: "removed (v7 generated; deco schema and deco content write the next major's files)",
+    });
+  }
+}

package/src/experiments.ts

@@ -0,0 +1,54 @@
+/**
+ * Experiment IDs (spec: renames-and-migrations › Telemetry and analytics).
+ * v7 keyed A/B results on the saved name of the random matcher a variant's
+ * rule pointed at. The next major keys them on `multivariate`'s `experiment`,
+ * so this step copies that name into it and results carry over.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { LEGACY_ALIASES } from "@decocms/blocks/cli";
+import { serializeBlock } from "@decocms/blocks/protocol/keys";
+import type { Report } from "./report";
+import { forEachBlock, readContent } from "./walk";
+
+const RANDOM_MATCHERS = new Set(["website/matchers/random.ts", "website/matchers/random"]);
+
+function isMultivariate(type: string): boolean {
+  return (
+    type === "multivariate" ||
+    (Object.hasOwn(LEGACY_ALIASES, type) && LEGACY_ALIASES[type] === "multivariate")
+  );
+}
+
+/** Set `experiment` on every `multivariate` whose variant rule is a saved random matcher. */
+export function copyExperimentIds(root: string, report: Report): void {
+  const { blocks, files } = readContent(root);
+  const randoms = new Set(
+    Object.entries(blocks)
+      .filter(([, b]) => RANDOM_MATCHERS.has(b.__resolveType as string))
+      .map(([name]) => name),
+  );
+  if (randoms.size === 0) return;
+
+  for (const [entry, block] of Object.entries(blocks)) {
+    let changed = false;
+    forEachBlock(block, (node) => {
+      if (!isMultivariate(node.__resolveType) || node.experiment !== undefined) return;
+      const variants = Array.isArray(node.variants) ? node.variants : [];
+      const name = variants
+        .map((v) => (v as { rule?: { __resolveType?: unknown } } | null)?.rule?.__resolveType)
+        .find((t): t is string => typeof t === "string" && randoms.has(t));
+      if (!name) return;
+      node.experiment = name;
+      changed = true;
+      report.done.push({
+        step: "content",
+        subject: files[entry],
+        message: `set experiment "${name}" (the random matcher's saved name), so A/B results carry over`,
+      });
+    });
+    if (changed) {
+      fs.writeFileSync(path.join(root, ".deco", "blocks", files[entry]), serializeBlock(block));
+    }
+  }
+}