@decocms/blocks-cli 7.8.0 → 7.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks-cli",
-  "version": "7.8.0",
+  "version": "7.9.0",
   "type": "module",
   "description": "Deco codegen (generate-blocks, generate-schema, generate-invoke) and Fresh-to-TanStack migration tooling",
   "repository": {
@@ -20,6 +20,7 @@
   },
   "exports": {
     "./generate-blocks": "./scripts/generate-blocks.ts",
+    "./generate-blocks-manifest": "./scripts/generate-blocks-manifest.ts",
     "./generate-schema": "./scripts/generate-schema.ts",
     "./generate-invoke": "./scripts/generate-invoke.ts",
     "./migrate": "./scripts/migrate.ts",
@@ -34,7 +35,7 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.8.0",
+    "@decocms/blocks": "7.9.0",
     "ts-morph": "^27.0.0",
     "tsx": "^4.22.5"
   },

package/scripts/generate-blocks-manifest.test.ts

@@ -0,0 +1,191 @@
+/**
+ * Integration test for `generate-blocks-manifest.ts`.
+ *
+ * Drives the programmatic entry against a tmp fixture of hostile-but-real
+ * block filenames (the shapes found in production `.deco/blocks` corpora:
+ * double-encoded `%2520`, single-encoded `%20`, parentheses, encoded slashes
+ * `%2F`, raw UTF-8), then verifies the emitted module the way a site would
+ * consume it: keys verbatim, `tsc` accepts it, and importing it (via a tsx
+ * child process from the fixture dir, resolving the raw-filename JSON import
+ * specifiers against the real files on disk) yields the parsed contents.
+ */
+import * as cp from "node:child_process";
+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 { generateBlocksManifest } from "./generate-blocks-manifest";
+
+const SCRIPT = path.resolve(__dirname, "generate-blocks-manifest.ts");
+
+const HOSTILE_FIXTURE: Record<string, unknown> = {
+  "pages-PDP%2520Box-102215": { path: "/pdp-box", encoded: "double" },
+  "pages-Home%20(principal)-287364": { path: "/", parens: true },
+  "collections%2Fblog%2Fauthors%2Fx": { nested: "encoded-slash" },
+  "pages-Calçados-42": { utf8: "çãé" },
+};
+
+describe("generate-blocks-manifest", () => {
+  let tmpDir: string;
+  let blocksDir: string;
+  let outFile: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "generate-blocks-manifest-"));
+    blocksDir = path.join(tmpDir, ".deco", "blocks");
+    outFile = path.join(tmpDir, ".deco", "blocksManifest.gen.ts");
+    fs.mkdirSync(blocksDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  const writeFixture = (fixture: Record<string, unknown> = HOSTILE_FIXTURE) => {
+    for (const [key, value] of Object.entries(fixture)) {
+      fs.writeFileSync(path.join(blocksDir, `${key}.json`), JSON.stringify(value));
+    }
+  };
+
+  it("emits verbatim keys and raw-filename import specifiers for hostile names", async () => {
+    writeFixture();
+    const result = await generateBlocksManifest({ blocksDir, outFile, silent: true });
+    expect(result.count).toBe(4);
+    expect(result.empty).toBe(false);
+    expect(result.written).toBe(true);
+
+    const emitted = fs.readFileSync(outFile, "utf-8");
+    for (const key of Object.keys(HOSTILE_FIXTURE)) {
+      // Key: filename minus .json, verbatim — no decoding of %2520/%20/%2F.
+      expect(emitted).toContain(`${JSON.stringify(key)}: `);
+      // Specifier: the raw on-disk filename, relative to the emitted module.
+      expect(emitted).toContain(`from ${JSON.stringify(`./blocks/${key}.json`)};`);
+    }
+    // Never URL-decoded anywhere in the module.
+    expect(emitted).not.toContain("pages-PDP%20Box");
+    expect(emitted).not.toContain("pages-Home (principal)");
+    expect(emitted).not.toContain("collections/blog");
+  });
+
+  it("compiles under tsc (module esnext, bundler resolution, resolveJsonModule)", async () => {
+    writeFixture();
+    await generateBlocksManifest({ blocksDir, outFile, silent: true });
+
+    const r = cp.spawnSync(
+      "npx",
+      [
+        "tsc",
+        "--noEmit",
+        "--strict",
+        "--module",
+        "esnext",
+        "--moduleResolution",
+        "bundler",
+        "--target",
+        "es2022",
+        "--resolveJsonModule",
+        "--skipLibCheck",
+        outFile,
+      ],
+      { encoding: "utf8" },
+    );
+    expect(r.stdout + r.stderr).not.toMatch(/error TS/);
+    expect(r.status).toBe(0);
+  }, 30_000);
+
+  it("importing the emitted module (tsx, from the fixture dir) yields the parsed contents", async () => {
+    writeFixture();
+    await generateBlocksManifest({ blocksDir, outFile, silent: true });
+
+    const runner = path.join(tmpDir, ".deco", "runner.ts");
+    fs.writeFileSync(
+      runner,
+      'import blocks from "./blocksManifest.gen";\nconsole.log(JSON.stringify(blocks));\n',
+    );
+    const r = cp.spawnSync("npx", ["tsx", runner], { encoding: "utf8", cwd: tmpDir });
+    expect(r.stderr).toBe("");
+    expect(r.status).toBe(0);
+    expect(JSON.parse(r.stdout)).toEqual(HOSTILE_FIXTURE);
+  }, 30_000);
+
+  it("is idempotent: regeneration over an unchanged block set writes nothing", async () => {
+    writeFixture();
+    const first = await generateBlocksManifest({ blocksDir, outFile, silent: true });
+    expect(first.written).toBe(true);
+    const emittedFirst = fs.readFileSync(outFile, "utf-8");
+
+    const second = await generateBlocksManifest({ blocksDir, outFile, silent: true });
+    expect(second.written).toBe(false);
+    expect(fs.readFileSync(outFile, "utf-8")).toBe(emittedFirst);
+  });
+
+  it("orders imports deterministically regardless of readdir order (sorted filenames)", async () => {
+    writeFixture({ "z-last": { z: 1 }, "a-first": { a: 1 }, "m-mid": { m: 1 } });
+    await generateBlocksManifest({ blocksDir, outFile, silent: true });
+
+    const emitted = fs.readFileSync(outFile, "utf-8");
+    const importOrder = [...emitted.matchAll(/from "\.\/blocks\/([^"]+)\.json";/g)].map(
+      (m) => m[1],
+    );
+    expect(importOrder).toEqual(["a-first", "m-mid", "z-last"]);
+  });
+
+  it("ignores non-json entries and subdirectories (top-level *.json only)", async () => {
+    writeFixture({ real: { ok: true } });
+    fs.writeFileSync(path.join(blocksDir, "notes.txt"), "not a block");
+    fs.mkdirSync(path.join(blocksDir, "nested"));
+    fs.writeFileSync(path.join(blocksDir, "nested", "deep.json"), "{}");
+
+    const result = await generateBlocksManifest({ blocksDir, outFile, silent: true });
+    expect(result.count).toBe(1);
+    const emitted = fs.readFileSync(outFile, "utf-8");
+    expect(emitted).toContain('"real": _b0');
+    expect(emitted).not.toContain("notes.txt");
+    expect(emitted).not.toContain("deep.json");
+  });
+
+  it("emits an empty manifest when the blocks dir is missing", async () => {
+    fs.rmSync(blocksDir, { recursive: true, force: true });
+    const result = await generateBlocksManifest({ blocksDir, outFile, silent: true });
+    expect(result.count).toBe(0);
+    expect(result.empty).toBe(true);
+
+    const emitted = fs.readFileSync(outFile, "utf-8");
+    expect(emitted).toContain("const blocks: Record<string, unknown> = {");
+    expect(emitted).toContain("export default blocks;");
+    expect(emitted).not.toContain("import _b");
+  });
+
+  it("never lets a generated comment contain the block-comment terminator", async () => {
+    // Filenames land ONLY inside JSON.stringify-quoted string literals — a
+    // name containing `*` + `/` must not be able to truncate any comment in
+    // the emitted module (past incident with interpolated doc comments).
+    writeFixture({ "weird-*∕name": { ok: true }, "star*": { s: 1 } });
+    await generateBlocksManifest({ blocksDir, outFile, silent: true });
+
+    const emitted = fs.readFileSync(outFile, "utf-8");
+    const commentLines = emitted.split("\n").filter((l) => l.startsWith("//"));
+    for (const line of commentLines) {
+      expect(line).not.toContain("*/");
+      expect(line).not.toContain("weird");
+    }
+  });
+
+  it("runs as a CLI with --blocks-dir/--out-file overrides", () => {
+    writeFixture({ "cli-block": { via: "cli" } });
+    const cliOut = path.join(tmpDir, "custom", "manifest.gen.ts");
+
+    const r = cp.spawnSync(
+      "npx",
+      ["tsx", SCRIPT, "--blocks-dir", blocksDir, "--out-file", cliOut],
+      { encoding: "utf8", cwd: tmpDir },
+    );
+    expect(r.status).toBe(0);
+    expect(r.stdout).toContain("Generated static-import manifest for 1 blocks");
+
+    const emitted = fs.readFileSync(cliOut, "utf-8");
+    expect(emitted).toContain('"cli-block": _b0');
+    // Specifier is relative to the out file's own directory.
+    expect(emitted).toContain('from "../.deco/blocks/cli-block.json";');
+  }, 30_000);
+});

package/scripts/generate-blocks-manifest.ts

@@ -0,0 +1,195 @@
+#!/usr/bin/env tsx
+/**
+ * Reads .deco/blocks/*.json and emits blocksManifest.gen.ts — a module that
+ * STATICALLY imports every block file and re-exports them as one
+ * `Record<string, unknown>` keyed exactly like
+ * `@decocms/blocks/cms/loadDecofileDirectory`: filename minus the `.json`
+ * extension, verbatim (no URL-decoding, no renaming — the `pages-` filename
+ * prefix on page blocks is load-bearing, see loadDecofileDirectory's doc
+ * comment).
+ *
+ * Why static imports instead of the runtime fs read: a plain
+ * `loadDecofileDirectory(".deco/blocks")` is invisible to the bundler, so in
+ * `next dev` editing a block JSON invalidates nothing (no CMS content
+ * hot-reload) and production deploys need `outputFileTracingIncludes` hacks
+ * to ship the directory. With the manifest, Next's own module graph owns the
+ * files: editing an imported JSON re-evaluates the server module graph
+ * (~120–165ms measured), which also resets module-scope memos like
+ * `createNextSetup`'s bootstrap cache — content edits reload naturally, and
+ * the JSON is bundled into the build output. The trade-off: adding or
+ * removing a block FILE requires re-running this generator (content edits do
+ * not), so wire it into the site's `generate` chain.
+ *
+ * Import specifiers use the RAW on-disk filename. Verified against webpack,
+ * Turbopack, and Vite: specifiers are opaque strings to all three — `%2520`,
+ * `%20`, parentheses, `%C3%A7`, `%2F` etc. pass through verbatim and nothing
+ * URL-decodes, so JSON.stringify-quoting the specifier (and the key) is all
+ * the escaping needed.
+ *
+ * Usage (from site root):
+ *   npx tsx node_modules/@decocms/blocks-cli/scripts/generate-blocks-manifest.ts
+ *
+ * CLI:
+ *   --blocks-dir  override input  (default: .deco/blocks)
+ *   --out-file    override output (default: .deco/blocksManifest.gen.ts)
+ *
+ * Programmatic:
+ *   import { generateBlocksManifest } from "@decocms/blocks-cli/generate-blocks-manifest";
+ *   await generateBlocksManifest({ blocksDir, outFile });
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+// Header of the emitted module. Kept as line comments and deliberately free
+// of interpolated filenames: block filenames can contain almost any
+// character, and a filename containing the sequence `*` + `/` inside a
+// generated /** ... */ block would terminate the comment early and corrupt
+// the module (a past incident). Filenames only ever appear inside
+// JSON.stringify-quoted string literals below.
+const HEADER = [
+  "// Auto-generated by @decocms/blocks-cli/scripts/generate-blocks-manifest.ts — do not edit.",
+  "//",
+  "// Static-import manifest of every JSON decofile in the blocks directory,",
+  "// keyed by filename minus the .json extension, VERBATIM — the same key",
+  "// format @decocms/blocks/cms/loadDecofileDirectory produces (page blocks",
+  "// keep their load-bearing `pages-` filename prefix).",
+  "//",
+  "// Because every block file is a static import, the bundler's module graph",
+  "// owns them: in `next dev`, editing a block JSON re-evaluates the server",
+  "// module graph (CMS content hot-reload), and production builds bundle the",
+  "// content (no outputFileTracingIncludes needed). Adding or removing a",
+  "// block FILE requires re-running the generator; editing content does not.",
+  "//",
+  "// Regenerate:",
+  "//   npx tsx node_modules/@decocms/blocks-cli/scripts/generate-blocks-manifest.ts",
+  "",
+].join("\n");
+
+export interface GenerateBlocksManifestOptions {
+  blocksDir: string;
+  outFile: string;
+  /** Suppress the per-run summary log. Defaults to false. */
+  silent?: boolean;
+}
+
+export interface GenerateBlocksManifestResult {
+  count: number;
+  outFile: string;
+  /** True when the blocks dir was missing and an empty manifest was emitted. */
+  empty: boolean;
+  /**
+   * True when the manifest on disk actually changed. Regeneration is
+   * idempotent: an unchanged block set rewrites nothing, so watchers (and
+   * Next's module graph) are not tickled by no-op runs.
+   */
+  written: boolean;
+}
+
+function renderManifest(blocksDir: string, outFile: string, files: string[]): string {
+  const lines: string[] = [HEADER];
+
+  const sorted = [...files].sort(); // code-unit sort — locale-independent, diff-stable
+
+  for (let i = 0; i < sorted.length; i++) {
+    // Import specifier: the RAW filename, relative to the emitted module.
+    // JSON.stringify provides all necessary escaping — bundlers do not
+    // URL-decode specifiers, so no percent-escaping/normalizing here.
+    let spec = path
+      .relative(path.dirname(outFile), path.join(blocksDir, sorted[i]))
+      .replace(/\\/g, "/");
+    if (!spec.startsWith(".")) spec = `./${spec}`;
+    lines.push(`import _b${i} from ${JSON.stringify(spec)};`);
+  }
+
+  lines.push("");
+  lines.push("const blocks: Record<string, unknown> = {");
+  for (let i = 0; i < sorted.length; i++) {
+    const key = sorted[i].slice(0, -".json".length);
+    lines.push(`  ${JSON.stringify(key)}: _b${i},`);
+  }
+  lines.push("};");
+  lines.push("");
+  lines.push("export default blocks;");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+async function writeIfChanged(outFile: string, content: string): Promise<boolean> {
+  let existing: string | undefined;
+  try {
+    existing = await fs.promises.readFile(outFile, "utf-8");
+  } catch {}
+  if (existing === content) return false;
+  await fs.promises.mkdir(path.dirname(outFile), { recursive: true });
+  await fs.promises.writeFile(outFile, content);
+  return true;
+}
+
+export async function generateBlocksManifest(
+  options: GenerateBlocksManifestOptions,
+): Promise<GenerateBlocksManifestResult> {
+  const blocksDir = path.resolve(options.blocksDir);
+  const outFile = path.resolve(options.outFile);
+  const silent = options.silent ?? false;
+
+  if (!fs.existsSync(blocksDir)) {
+    if (!silent) {
+      console.warn(`Blocks directory not found: ${blocksDir} — generating empty manifest.`);
+    }
+    const written = await writeIfChanged(outFile, renderManifest(blocksDir, outFile, []));
+    return { count: 0, outFile, empty: true, written };
+  }
+
+  // Top-level *.json files only — mirrors loadDecofileDirectory, which
+  // filters `entry.isFile()` and never recurses (nested paths live encoded
+  // in the FILENAME, e.g. `collections%2Fblog%2F....json`).
+  const files = (await fs.promises.readdir(blocksDir, { withFileTypes: true }))
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+    .map((entry) => entry.name);
+
+  const written = await writeIfChanged(outFile, renderManifest(blocksDir, outFile, files));
+
+  if (!silent) {
+    console.log(
+      `Generated static-import manifest for ${files.length} blocks → ` +
+        `${path.relative(process.cwd(), outFile)}${written ? "" : " (unchanged)"}`,
+    );
+  }
+
+  return { count: files.length, outFile, empty: false, written };
+}
+
+// ---------------------------------------------------------------------------
+// CLI shim — same pattern as generate-blocks.ts.
+// ---------------------------------------------------------------------------
+
+function isMainModule(): boolean {
+  // tsx/node ESM: import.meta.url matches process.argv[1] when invoked directly.
+  // Use a forgiving comparison so it works under both `tsx script.ts` and
+  // `node --import tsx script.ts`.
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    const entryUrl = new URL(`file://${path.resolve(entry)}`).href;
+    return import.meta.url === entryUrl;
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
+  const args = process.argv.slice(2);
+  const arg = (name: string, fallback: string): string => {
+    const idx = args.indexOf(`--${name}`);
+    return idx !== -1 && args[idx + 1] ? args[idx + 1] : fallback;
+  };
+
+  const blocksDir = path.resolve(process.cwd(), arg("blocks-dir", ".deco/blocks"));
+  const outFile = path.resolve(process.cwd(), arg("out-file", ".deco/blocksManifest.gen.ts"));
+
+  generateBlocksManifest({ blocksDir, outFile }).catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}