@decocms/blocks-cli 7.17.1 → 7.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks-cli",
-  "version": "7.17.1",
+  "version": "7.19.0",
   "type": "module",
   "description": "Deco codegen (generate-blocks, generate-schema, generate-invoke) and Fresh-to-TanStack migration tooling",
   "repository": {
@@ -30,7 +30,7 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.17.1",
+    "@decocms/blocks": "7.19.0",
     "ts-morph": "^27.0.0",
     "tsx": "^4.22.5"
   },

package/scripts/generate-schema.test.ts

@@ -5,9 +5,11 @@ import * as path from "node:path";
 import { Project } from "ts-morph";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import {
+  EITRI_FORMAT_ALIASES,
   WIDGET_TYPE_FORMATS,
   applyWidgetFormat,
   definitionIdForPath,
+  normalizeFormats,
   typeToJsonSchema,
 } from "./generate-schema";
 
@@ -29,6 +31,38 @@ describe("definitionIdForPath", () => {
   });
 });
 
+describe("normalizeFormats (Eitri @format aliases)", () => {
+  it("remaps a known alias in a nested prop schema", () => {
+    const defs = {
+      "abc@Props": {
+        type: "object",
+        properties: {
+          datetime: { type: "string", format: "datetime", title: "Publish date." },
+          post: { type: "string", format: "textarea" },
+        },
+      },
+    };
+    normalizeFormats(defs, EITRI_FORMAT_ALIASES);
+    expect(defs["abc@Props"].properties.datetime.format).toBe("date-time");
+    // textarea is already a valid widget format — left untouched.
+    expect(defs["abc@Props"].properties.post.format).toBe("textarea");
+  });
+
+  it("recurses through arrays and leaves unknown formats alone", () => {
+    const node = {
+      items: [{ format: "datetime" }, { format: "email" }],
+    };
+    normalizeFormats(node, EITRI_FORMAT_ALIASES);
+    expect(node.items[0].format).toBe("date-time");
+    expect(node.items[1].format).toBe("email");
+  });
+
+  it("is a no-op on primitives / null", () => {
+    expect(() => normalizeFormats(null, EITRI_FORMAT_ALIASES)).not.toThrow();
+    expect(() => normalizeFormats("datetime", EITRI_FORMAT_ALIASES)).not.toThrow();
+  });
+});
+
 describe("applyWidgetFormat", () => {
   it("recovers an unresolved widget alias (empty schema) as string + format", () => {
     // When a widget alias like `Color` is imported from a module ts-morph can't

package/scripts/generate-schema.ts

@@ -236,6 +236,35 @@ export const WIDGET_TYPE_FORMATS: Record<string, string> = {
   DateTimeWidget: "date-time",
 };
 
+/**
+ * Eitri authors annotate fields with JSDoc `@format` using Eitri's own vocab
+ * (e.g. `@format datetime`). Map those onto the JSON-Schema `format` values the
+ * Studio widget layer understands. `textarea` already matches, so only the
+ * divergent ones need remapping. Applied only for --platform eitri.
+ */
+export const EITRI_FORMAT_ALIASES: Record<string, string> = {
+  datetime: "date-time",
+};
+
+/**
+ * Recursively remap `format` string values in a JSON-Schema tree using the
+ * given alias map. Mutates in place; only touches `format` fields whose value
+ * is a known alias, so unrelated schema is untouched.
+ */
+export function normalizeFormats(node: unknown, aliases: Record<string, string>): void {
+  if (Array.isArray(node)) {
+    for (const item of node) normalizeFormats(item, aliases);
+    return;
+  }
+  if (node && typeof node === "object") {
+    const obj = node as Record<string, unknown>;
+    if (typeof obj.format === "string" && aliases[obj.format]) {
+      obj.format = aliases[obj.format];
+    }
+    for (const key of Object.keys(obj)) normalizeFormats(obj[key], aliases);
+  }
+}
+
 /**
  * Detect known widget types and set the appropriate format.
  */
@@ -879,7 +908,13 @@ function resolvePropsViaReExport(
   return null;
 }
 
-function findTsxFiles(dir: string): string[] {
+// Default scan extensions. Sections may widen this to also include .jsx/.js
+// on stacks whose sections can be plain JavaScript (e.g. Eitri) — see
+// SECTION_EXTS. Loaders/apps stay TS-only (their input types come from real
+// TypeScript signatures, which JS files cannot express).
+const DEFAULT_EXTS = [".tsx", ".ts"] as const;
+
+function findTsxFiles(dir: string, exts: readonly string[] = DEFAULT_EXTS): string[] {
   const results: string[] = [];
   if (!fs.existsSync(dir)) return results;
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
@@ -887,10 +922,10 @@ function findTsxFiles(dir: string): string[] {
     if (entry.isDirectory()) {
       // The exclusion predicate targets generated/test *files* — a directory
       // named e.g. `foo.gen.ts` is a real path segment and must still be walked.
-      results.push(...findTsxFiles(full));
+      results.push(...findTsxFiles(full, exts));
     } else if (
       !isExcludedCodegenFile(entry.name) &&
-      (entry.name.endsWith(".tsx") || entry.name.endsWith(".ts"))
+      exts.some((e) => entry.name.endsWith(e))
     ) {
       results.push(full);
     }
@@ -1197,6 +1232,11 @@ function generateMeta(): MetaResponse {
   ];
   for (const wrapper of COMMERCE_EXTENSION_WRAPPERS) {
     const matchingLoaders = outputTypeToLoaderKeys.get(wrapper.outputType) ?? [];
+    // A wrapper whose base loader type has no matching loaders in the site is
+    // useless (its `data` picker would only offer Resolvable). Non-commerce
+    // sites (e.g. Eitri) have none, so skip it instead of injecting a phantom
+    // commerce loader into the picker.
+    if (matchingLoaders.length === 0) continue;
     const wrapperDefKey = toBase64(wrapper.key);
     definitions[wrapperDefKey] = {
       title: wrapper.key,
@@ -1238,7 +1278,13 @@ function generateMeta(): MetaResponse {
     process.exit(1);
   }
 
-  const sectionFiles = findTsxFiles(sectionsDir);
+  // Eitri sections can be plain JavaScript (.js/.jsx) as well as TS; other
+  // stacks stay TS-only so a stray .js helper in src/sections isn't mistaken
+  // for a section. A JS file with no extractable Props still registers as a
+  // (prop-less) section rather than being silently skipped.
+  const sectionExts =
+    PLATFORM === "eitri" ? [".tsx", ".ts", ".jsx", ".js"] : DEFAULT_EXTS;
+  const sectionFiles = findTsxFiles(sectionsDir, sectionExts);
   console.log(`Found ${sectionFiles.length} section files`);
   for (const filePath of sectionFiles) {
     getSourceFile(project, filePath, sourceFileCache);
@@ -1419,6 +1465,13 @@ function generateMeta(): MetaResponse {
     }
   }
 
+  // Eitri @format aliases → JSON-Schema formats (e.g. datetime → date-time).
+  // Done as a final pass over the generated definitions so every prop schema,
+  // however deeply nested, is normalized before it reaches Studio.
+  if (PLATFORM === "eitri") {
+    normalizeFormats(definitions, EITRI_FORMAT_ALIASES);
+  }
+
   // Pages, matchers, etc. are injected at runtime by composeMeta() in src/admin/schema.ts.
   // Site-level loaders are generated here (first pass above).
   const emptyAnyOf = { anyOf: [] as any[] };

package/scripts/generate.test.ts

@@ -15,7 +15,7 @@ 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";
-import { parseCliOptions } from "./generate";
+import { buildPlan, parseCliOptions } from "./generate";
 
 const SCRIPT = path.resolve(__dirname, "generate.ts");
 
@@ -213,6 +213,43 @@ describe("parseCliOptions", () => {
     expect(parseCliOptions(["--no-registry"]).registry).toBe(false);
     expect(parseCliOptions([]).registry).toBe(null);
   });
+
+  it("accepts --root and a bare positional path as the effective root", () => {
+    expect(parseCliOptions(["--root", "apps/foo"]).root).toBe("apps/foo");
+    expect(parseCliOptions(["apps/foo"]).root).toBe("apps/foo");
+    expect(parseCliOptions([]).root).toBe(null);
+  });
+
+  it("rejects a second positional but still rejects unknown flags", () => {
+    expect(() => parseCliOptions(["a", "b"])).toThrow(/Unknown option/);
+    expect(() => parseCliOptions(["--wat"])).toThrow(/Unknown option/);
+  });
+});
+
+describe("buildPlan --platform eitri", () => {
+  it("runs only schema + blocks and makes schema self-contained", () => {
+    // makeFixture installs @decocms/tanstack + src/sections + src/loaders, which
+    // would normally enable sections/loaders/invoke; --platform eitri overrides.
+    const dir = makeFixture({ withInvoke: true });
+    try {
+      const plans = buildPlan(dir, parseCliOptions(["--platform", "eitri"]));
+      const byName = Object.fromEntries(plans.map((p) => [p.name, p]));
+
+      expect(byName.schema.enabled).toBe(true);
+      expect(byName.blocks.enabled).toBe(true);
+      for (const name of ["manifest", "sections", "loaders", "invoke"]) {
+        expect(byName[name].enabled).toBe(false);
+        expect(byName[name].disabledReason).toBe("not used by --platform eitri");
+      }
+
+      // schema is asked to bake composeMeta's framework block types in.
+      expect(byName.schema.args).toContain("--compose");
+      const fwIdx = byName.schema.args.indexOf("--framework");
+      expect(byName.schema.args[fwIdx + 1]).toBe("eitri");
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
 });
 
 // ---------------------------------------------------------------------------

package/scripts/generate.ts

@@ -171,6 +171,15 @@ Selection:
   --skip <names>      Comma-separated generators to exclude
   --force             Ignore the cache; run everything selected
   --dry-run           Print what would run / skip / stay disabled, then exit
+  --root <dir>        Effective working directory (also accepted as a bare
+                      positional path). Input dirs + .deco/ output resolve
+                      against it, so a monorepo can target a sub-app folder
+                      without cd. (default: process.cwd())
+
+Platform:
+  --platform <name>   Forwarded to schema. With "eitri": runs ONLY schema +
+                      blocks (skips manifest/sections/loaders/invoke) and makes
+                      the schema self-contained (composeMeta at gen time).
 
 Forwarded to the individual generators:
   --blocks-dir <dir>       blocks + manifest input        (default .deco/blocks)
@@ -220,6 +229,13 @@ export interface CliOptions {
   namespace: string | null;
   platform: string | null;
   skipApps: boolean;
+  /**
+   * Effective working directory. `.deco/` output and input dirs resolve
+   * against this instead of process.cwd(), so a monorepo can target a
+   * sub-app folder without `cd`. Set via `--root <dir>` or a bare positional
+   * path. Relative to process.cwd().
+   */
+  root: string | null;
 }
 
 function parseNames(raw: string, flag: string): GeneratorName[] {
@@ -257,6 +273,7 @@ export function parseCliOptions(argv: string[]): CliOptions {
     namespace: null,
     platform: null,
     skipApps: false,
+    root: null,
   };
 
   const valueOf = (i: number, flag: string): string => {
@@ -335,7 +352,18 @@ export function parseCliOptions(argv: string[]): CliOptions {
       case "--skip-apps":
         opts.skipApps = true;
         break;
+      case "--root":
+        opts.root = valueOf(i, a);
+        i++;
+        break;
       default:
+        // A single bare (non-flag) argument is accepted as the root path, so
+        // `generate ./apps/foo` works like `generate --root ./apps/foo`.
+        // Anything else (or a second positional) is still a hard error.
+        if (!a.startsWith("--") && opts.root === null) {
+          opts.root = a;
+          break;
+        }
         throw new Error(`Unknown option "${a}". Run with --help for usage.`);
     }
   }
@@ -625,6 +653,9 @@ export function buildPlan(cwd: string, opts: CliOptions): GeneratorPlan[] {
         ...(opts.namespace ? ["--namespace", opts.namespace] : []),
         ...(opts.platform ? ["--platform", opts.platform] : []),
         ...(opts.skipApps ? ["--skip-apps"] : []),
+        // Eitri (and any FS-only consumer) needs a self-contained meta.gen.json:
+        // bake composeMeta's framework block types in at generation time.
+        ...(opts.platform === "eitri" ? ["--compose", "--framework", "eitri"] : []),
       ],
       stage: 2,
       ...enabledIf(
@@ -661,6 +692,26 @@ export function buildPlan(cwd: string, opts: CliOptions): GeneratorPlan[] {
     },
   ];
 
+  // --platform eitri: deco only AUTHORS config for Eitri (Eitri renders on its
+  // own mobile runtime), so the only useful artifacts are the self-contained
+  // meta.gen.json (schema) and the bundled decofile snapshot (blocks). The
+  // React-runtime generators (manifest/sections/loaders/invoke) would be dead
+  // weight, and `sections` in particular would otherwise auto-enable because
+  // src/sections exists. Applied before --only/--skip so those still win.
+  if (opts.platform === "eitri") {
+    for (const plan of plans) {
+      if (plan.name === "blocks") {
+        // Emit the snapshot even when .deco/blocks is empty (a fresh Eitri app
+        // has no authored content yet) — generate-blocks writes an empty barrel.
+        plan.enabled = true;
+        plan.disabledReason = undefined;
+      } else if (plan.name !== "schema") {
+        plan.enabled = false;
+        plan.disabledReason = "not used by --platform eitri";
+      }
+    }
+  }
+
   // Apply --only / --skip on top of auto-enablement. --only also FORCES a
   // generator on (explicit intent beats detection) unless its hard inputs
   // are missing in a way that would just crash the child.
@@ -965,6 +1016,19 @@ export async function runGenerate(argv: string[], cwd = process.cwd()): Promise<
     return 0;
   }
 
+  // --root / positional path relocates the effective working directory: every
+  // input dir and the `.deco/` output tree resolve against it (child
+  // generators are spawned with this cwd), so a monorepo can target a sub-app
+  // folder without an explicit `cd`.
+  if (opts.root) {
+    cwd = path.resolve(cwd, opts.root);
+    if (!fs.existsSync(cwd)) {
+      console.error(`[generate] --root path does not exist: ${cwd}`);
+      return 1;
+    }
+    console.log(`[generate] root: ${cwd}`);
+  }
+
   const totalStarted = Date.now();
   const plans = buildPlan(cwd, opts);
   const versions = decoPackageVersions(cwd);