@decocms/blocks-cli 7.0.0

package/scripts/generate-blocks.ts

@@ -0,0 +1,274 @@
+#!/usr/bin/env tsx
+/**
+ * Reads .deco/blocks/*.json and emits:
+ *   1. blocks.gen.json  — compact JSON data (the source of truth)
+ *   2. blocks.gen.ts    — thin TypeScript re-export for editor tooling
+ *
+ * At runtime the Vite plugin (src/vite/plugin.js) intercepts `blocks.gen.ts`
+ * imports and replaces them with `JSON.parse(...)` of the .json file. This
+ * avoids Vite's SSR module runner hanging on large (13MB+) JS object literals
+ * and lets V8 use its fast JSON parser instead of the full JS parser.
+ *
+ * Usage (from site root):
+ *   npx tsx node_modules/@decocms/blocks-cli/scripts/generate-blocks.ts
+ *
+ * Env / CLI:
+ *   --blocks-dir  override input  (default: .deco/blocks)
+ *   --out-file    override output (default: src/server/cms/blocks.gen.ts)
+ *
+ * Programmatic:
+ *   import { generateBlocks } from "@decocms/blocks-cli/generate-blocks";
+ *   await generateBlocks({ blocksDir, outFile });
+ *
+ * The Vite plugin's dev-mode watcher uses the programmatic entry to keep the
+ * generated artifact in sync with `.deco/blocks/` without spawning a child
+ * process per change.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import {
+  blockHasPath,
+  type Candidate,
+  decodeBlockNameWithPasses,
+  mergeCandidates,
+  singleDecodeBlockName,
+} from "./lib/blocks-dedupe";
+
+const TS_STUB = [
+  "// Auto-generated — thin wrapper around blocks.gen.json.",
+  "// The Vite plugin replaces this at load time with JSON.parse(...).",
+  "// Do not edit manually.",
+  "",
+  "export const blocks: Record<string, any> = {};",
+  "",
+].join("\n");
+
+export interface GenerateBlocksOptions {
+  blocksDir: string;
+  outFile: string;
+  /** Suppress the per-run summary log. Defaults to false. */
+  silent?: boolean;
+}
+
+export interface GenerateBlocksResult {
+  count: number;
+  collisions: number;
+  jsonFile: string;
+  outFile: string;
+  /** True when the blocks dir was missing and an empty barrel was emitted. */
+  empty: boolean;
+  /**
+   * The merged decofile map that was written to `jsonFile`. Returned so callers
+   * (the dev Vite plugin) can seed an in-memory cache and apply cheap deltas to
+   * it without re-reading the whole `.deco/blocks` directory on every edit.
+   */
+  blocks: Record<string, unknown>;
+}
+
+export async function generateBlocks(
+  options: GenerateBlocksOptions,
+): Promise<GenerateBlocksResult> {
+  const blocksDir = path.resolve(options.blocksDir);
+  const outFile = path.resolve(options.outFile);
+  const jsonFile = outFile.replace(/\.ts$/, ".json");
+  const silent = options.silent ?? false;
+
+  if (!fs.existsSync(blocksDir)) {
+    if (!silent) {
+      console.warn(`Blocks directory not found: ${blocksDir} — generating empty barrel.`);
+    }
+    fs.mkdirSync(path.dirname(outFile), { recursive: true });
+    fs.writeFileSync(jsonFile, "{}");
+    fs.writeFileSync(outFile, TS_STUB);
+    return { count: 0, collisions: 0, jsonFile, outFile, empty: true, blocks: {} };
+  }
+
+  const files = fs.readdirSync(blocksDir).filter((f) => f.endsWith(".json"));
+
+  // Read each file into a Candidate, then let the dedupe lib pick the winner
+  // per decoded key and report any collisions. See `lib/blocks-dedupe.ts` for
+  // the priority order and the rationale behind it (TL;DR: never use file size,
+  // don't trust mtime alone in CI clones).
+  const candidatesWithKeys: Array<{ candidate: Candidate; key: string }> = [];
+  for (const file of files) {
+    const { name, passes } = decodeBlockNameWithPasses(file);
+    const fp = path.join(blocksDir, file);
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(fs.readFileSync(fp, "utf-8"));
+    } catch (e) {
+      if (!silent) console.warn(`Failed to parse ${file}:`, e);
+      continue;
+    }
+    candidatesWithKeys.push({
+      key: name,
+      candidate: {
+        file,
+        passes,
+        mtimeMs: fs.statSync(fp).mtimeMs,
+        hasPath: blockHasPath(parsed),
+        parsed,
+      },
+    });
+  }
+
+  const { winners, collisions } = mergeCandidates(candidatesWithKeys);
+
+  if (!silent && collisions.length > 0) {
+    console.warn(
+      `Detected ${collisions.length} filename collision(s) in ${path.relative(process.cwd(), blocksDir)}:`,
+    );
+    for (const c of collisions) {
+      const losers = c.files.filter((f) => f !== c.winner);
+      console.warn(`  - ${c.key}`);
+      console.warn(`      winner: ${c.winner}`);
+      for (const l of losers) console.warn(`      ignore: ${l}`);
+    }
+    console.warn("    Cause: multiple writers (manual sync vs deco-sync-bot) producing");
+    console.warn("    different filename encodings for the same logical key. Delete the");
+    console.warn("    stale file(s) listed under 'ignore' to silence this warning.");
+  }
+
+  // Use single-decoded stem of the winning file as the decofile key.
+  // This matches the Deno runtime's `parseBlockId` (one decodeURIComponent)
+  // so that studio's `encodeURIComponent(blockKey)` round-trips back to the
+  // exact filename on disk.
+  const blocks: Record<string, unknown> = {};
+  for (const [_name, c] of Object.entries(winners)) {
+    blocks[singleDecodeBlockName(c.file)] = c.parsed;
+  }
+
+  fs.mkdirSync(path.dirname(outFile), { recursive: true });
+
+  // 1. Compact JSON — the real data (no pretty-printing to save ~40% size)
+  const jsonStr = JSON.stringify(blocks);
+  fs.writeFileSync(jsonFile, jsonStr);
+
+  // 2. Thin TS wrapper — just for TypeScript tooling and as a Vite load target.
+  // Only write if content differs to avoid triggering Vite's file watcher,
+  // which would cascade module invalidation to the route tree and crash
+  // TanStack Router during dev hot-reload.
+  let existingTs: string | undefined;
+  try {
+    existingTs = fs.readFileSync(outFile, "utf-8");
+  } catch {}
+  if (existingTs !== TS_STUB) {
+    fs.writeFileSync(outFile, TS_STUB);
+  }
+
+  if (!silent) {
+    const jsonSizeMB = (Buffer.byteLength(jsonStr) / 1_048_576).toFixed(1);
+    console.log(
+      `Generated ${Object.keys(blocks).length} blocks → ${path.relative(process.cwd(), jsonFile)} (${jsonSizeMB} MB)`,
+    );
+  }
+
+  return {
+    count: Object.keys(blocks).length,
+    collisions: collisions.length,
+    jsonFile,
+    outFile,
+    empty: false,
+    blocks,
+  };
+}
+
+export interface ReadBlockDeltaOptions {
+  blocksDir: string;
+  /**
+   * Changed block files as basenames within `blocksDir` (e.g.
+   * `pages-Home%2520(principal)-287364.json`), each tagged with whether the
+   * event was a delete.
+   */
+  files: Array<{ name: string; isDelete: boolean }>;
+  /** Suppress per-file read warnings. Defaults to false. */
+  silent?: boolean;
+}
+
+/**
+ * Read ONLY the changed block files and return a delta map keyed by decofile
+ * key: `{ [key]: value }` for upserts, `{ [key]: null }` for deletes. The map
+ * is meant to be wrapped as `{ blocks: <delta> }` and POSTed to `/.decofile`,
+ * which applies it over the in-memory snapshot (see `applyDelta` in
+ * `src/admin/decofile.ts`).
+ *
+ * This is the incremental counterpart to `generateBlocks`. `generateBlocks`
+ * re-reads and re-merges the ENTIRE `.deco/blocks` directory and re-stringifies
+ * the whole snapshot — O(whole decofile), tens of MB of synchronous fs + JSON
+ * work that blocks the Node/Vite event loop for seconds on large sites (a CMS
+ * toggle that writes one 1 MB block file would otherwise re-process a 10 MB+
+ * decofile). `readBlockDelta` touches only the files that actually changed, so
+ * the dev watcher's hot path is O(changed files).
+ *
+ * Key derivation matches `generateBlocks` (`singleDecodeBlockName`). The
+ * cross-file collision dedupe that `generateBlocks` runs (see
+ * `lib/blocks-dedupe.ts`) is intentionally skipped here — the just-written
+ * file is treated as current truth ("newest write wins"), which is what a CMS
+ * editor expects. The full restart-time bootstrap regen reconciles any
+ * lingering collision via the dedupe logic.
+ */
+export function readBlockDelta(options: ReadBlockDeltaOptions): Record<string, unknown | null> {
+  const blocksDir = path.resolve(options.blocksDir);
+  const silent = options.silent ?? false;
+  const delta: Record<string, unknown | null> = {};
+
+  for (const { name, isDelete } of options.files) {
+    if (!name.endsWith(".json")) continue;
+    const key = singleDecodeBlockName(name);
+
+    if (isDelete) {
+      delta[key] = null;
+      continue;
+    }
+
+    const fp = path.join(blocksDir, name);
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(fs.readFileSync(fp, "utf-8"));
+    } catch (e) {
+      // File vanished mid-event or is a partial write in progress — skip it.
+      // A later watcher event (or the restart bootstrap) picks up the settled
+      // content, so dropping it here never permanently loses an update.
+      if (!silent) console.warn(`Failed to read changed block ${name}:`, e);
+      continue;
+    }
+    delta[key] = parsed;
+  }
+
+  return delta;
+}
+
+// ---------------------------------------------------------------------------
+// CLI shim — preserved so `npm run generate:blocks` and migration scripts
+// keep working unchanged.
+// ---------------------------------------------------------------------------
+
+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", "src/server/cms/blocks.gen.ts"));
+
+  generateBlocks({ blocksDir, outFile }).catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}

package/scripts/generate-invoke.test.ts

@@ -0,0 +1,195 @@
+/**
+ * Integration test for scripts/generate-invoke.ts.
+ *
+ * The generator scans a `vtex/invoke.ts` file from @decocms/apps and emits a
+ * site-local `src/server/invoke.gen.ts` with top-level `createServerFn`
+ * declarations. The piece we care most about locking is the Set-Cookie
+ * bridge: every handler must call `forwardResponseCookies()` after the
+ * action awaits, so VTEX-set cookies captured by `vtexFetchWithCookies`
+ * reach the browser via TanStack Start's HTTP response. Without this,
+ * `checkout.vtex.com` never reaches the browser, the storefront's
+ * mini-cart and VTEX's server-side orderForm drift apart, and /checkout
+ * loads with an empty cart.
+ *
+ * We exercise the generator end-to-end against a minimal fixture
+ * `invoke.ts` rather than unit-test internal helpers — the failure
+ * mode we want to prevent (a missing `forwardResponseCookies()` call
+ * in the emit string) only shows up in the produced source text.
+ */
+
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+const GENERATOR = path.resolve(__dirname, "generate-invoke.ts");
+
+const FIXTURE_INVOKE_TS = `\
+import { createInvokeFn } from "@decocms/start/sdk/createInvoke";
+import { getOrCreateCart, simulateCart } from "./actions/checkout";
+import { createSession } from "./actions/session";
+import type { OrderForm } from "./types";
+
+export const invoke = {
+	vtex: {
+		actions: {
+			// Direct pass-through wrapper — most common shape.
+			getOrCreateCart: createInvokeFn(
+				(data: { orderFormId?: string }) => getOrCreateCart(data),
+			) as unknown as (ctx: { data: { orderFormId?: string } }) => Promise<OrderForm>,
+
+			simulateCart: createInvokeFn(
+				(data: { postalCode: string }) => simulateCart(data),
+			),
+
+			// Adapting wrapper — payload gets wrapped into the action's
+			// props shape. The generator MUST preserve this wrap or the
+			// action call typechecks against the wrong props type.
+			createSession: createInvokeFn(
+				(data: Record<string, any>) => createSession({ data }),
+			),
+		},
+	},
+} as const;
+`;
+
+// Minimal stubs the generator's import-resolution doesn't *execute* but
+// ts-morph parses these to populate the importMap. We only need names to
+// resolve.
+const FIXTURE_ACTIONS_CHECKOUT_TS = `\
+export async function getOrCreateCart(_data: any): Promise<any> { return null; }
+export async function simulateCart(_data: any): Promise<any> { return null; }
+`;
+const FIXTURE_ACTIONS_SESSION_TS = `\
+export interface CreateSessionProps { data: Record<string, any>; }
+export async function createSession(_props: CreateSessionProps): Promise<any> { return null; }
+`;
+const FIXTURE_TYPES_TS = `export type OrderForm = unknown;\n`;
+
+describe("generate-invoke.ts — output shape", () => {
+  // The fixture is read-only across tests: every assertion runs against
+  // the same generated `invoke.gen.ts`. Running the generator once in
+  // `beforeAll` keeps the test fast (each `npx tsx` spawn is ~3-5s) and
+  // sidesteps the vitest 5s default per-test timeout that this suite was
+  // tipping over once we grew the fixture.
+  let appsDir: string;
+  let siteDir: string;
+  let outFile: string;
+  let generatedOutput: string;
+  let generatorStatus: number | null;
+
+  beforeAll(() => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "gen-invoke-"));
+    appsDir = path.join(tmp, "apps");
+    siteDir = path.join(tmp, "site");
+    fs.mkdirSync(path.join(appsDir, "vtex", "actions"), { recursive: true });
+    fs.mkdirSync(path.join(siteDir, "src", "server"), { recursive: true });
+    fs.writeFileSync(path.join(appsDir, "vtex", "invoke.ts"), FIXTURE_INVOKE_TS);
+    fs.writeFileSync(
+      path.join(appsDir, "vtex", "actions", "checkout.ts"),
+      FIXTURE_ACTIONS_CHECKOUT_TS,
+    );
+    fs.writeFileSync(
+      path.join(appsDir, "vtex", "actions", "session.ts"),
+      FIXTURE_ACTIONS_SESSION_TS,
+    );
+    fs.writeFileSync(path.join(appsDir, "vtex", "types.ts"), FIXTURE_TYPES_TS);
+    outFile = path.join(siteDir, "src", "server", "invoke.gen.ts");
+
+    const result = spawnSync(
+      "npx",
+      ["tsx", GENERATOR, "--apps-dir", appsDir, "--out-file", outFile],
+      { cwd: siteDir, encoding: "utf8" },
+    );
+    generatorStatus = result.status;
+    generatedOutput = fs.readFileSync(outFile, "utf8");
+  }, 30_000);
+
+  afterAll(() => {
+    // Best-effort cleanup; tmp dirs leak otherwise.
+    try {
+      fs.rmSync(path.dirname(appsDir), { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  });
+
+  it("runs to completion against a minimal fixture", () => {
+    // Sanity check — every subsequent assertion is wasted if the
+    // generator process bombed.
+    expect(generatorStatus).toBe(0);
+  });
+
+  it("imports the framework helpers needed for Set-Cookie propagation", () => {
+    // Both imports must be present — without them, forwardResponseCookies
+    // doesn't compile in the site, and the regression we're fixing
+    // resurfaces silently when someone deletes one of them.
+    expect(generatedOutput).toContain('from "@tanstack/react-start/server"');
+    expect(generatedOutput).toMatch(/getResponseHeaders\s*,?\s*\n?\s*setResponseHeader/);
+    expect(generatedOutput).toContain(
+      'import { RequestContext } from "@decocms/blocks/sdk/requestContext"',
+    );
+  });
+
+  it("emits the forwardResponseCookies helper exactly once", () => {
+    const declMatches = generatedOutput.match(/function forwardResponseCookies\(\)/g);
+    expect(declMatches).toHaveLength(1);
+
+    // The helper must read from RequestContext.responseHeaders and call
+    // setResponseHeader. Locking the bridge ends-to-ends.
+    expect(generatedOutput).toContain("RequestContext.current");
+    expect(generatedOutput).toContain("ctx.responseHeaders.getSetCookie");
+    expect(generatedOutput).toContain('setResponseHeader("set-cookie"');
+  });
+
+  it("calls forwardResponseCookies() inside every generated handler", () => {
+    // Each .handler(async ({ data }) ...) block produced by the
+    // generator must contain a `forwardResponseCookies()` call. We
+    // count handlers vs. call sites — excluding the declaration site
+    // (`function forwardResponseCookies()`), which also matches the
+    // bare `forwardResponseCookies()` token.
+    const handlerCount = (generatedOutput.match(/\.handler\(async \(\{ data \}\)/g) ?? []).length;
+    const allOccurrences = (generatedOutput.match(/\bforwardResponseCookies\(\)/g) ?? []).length;
+    const declSites = (generatedOutput.match(/function\s+forwardResponseCookies\(\)/g) ?? [])
+      .length;
+    const callSites = allOccurrences - declSites;
+
+    expect(handlerCount).toBe(3);
+    expect(declSites).toBe(1);
+    expect(callSites).toBe(3);
+  });
+
+  it("calls forwardResponseCookies AFTER the action awaits (so RequestContext is populated)", () => {
+    // The action must complete (await result) before we read the
+    // captured Set-Cookies — otherwise we'd forward an empty set
+    // every time. The expression body after `await` can be any call
+    // shape the wrapper produces (`fn(data)` or `fn({ data })`),
+    // so we match across the whole expression up to the semicolon.
+    const pattern =
+      /const result = await [^;]+;\s+forwardResponseCookies\(\);\s+return (?:unwrapResult\(result\)|result);/g;
+    const orderedCalls = generatedOutput.match(pattern) ?? [];
+    expect(orderedCalls.length).toBe(3);
+  });
+
+  it("preserves adapting wrappers verbatim (does not collapse to actionFn(data))", () => {
+    // Regression for the createSession-shape wrapper: the generator
+    // previously hard-coded `${importedFn}(data)` in every handler,
+    // silently dropping the wrap that wrappers like
+    //   createSession: createInvokeFn((data) => createSession({ data }))
+    // perform to bridge the external invoke shape to the internal
+    // action shape. Sites that regenerated against this hit
+    // `TS2345: Property 'data' is missing in type '{ [x: string]: any; }'`
+    // at the regenerated call site of every adapting wrapper.
+    expect(generatedOutput).toContain("const result = await createSession({ data });");
+    // And the broken shortcut must NOT appear for this action.
+    expect(generatedOutput).not.toMatch(/const result = await createSession\(data\);/);
+
+    // Direct pass-through wrappers are unaffected: their body is
+    // already `actionFn(data)`, so emitting verbatim produces the same
+    // output that the previous shortcut produced. Lock that too — a
+    // future refactor that breaks pass-throughs would be just as bad.
+    expect(generatedOutput).toContain("const result = await getOrCreateCart(data);");
+    expect(generatedOutput).toContain("const result = await simulateCart(data);");
+  });
+});