@dudousxd/nestjs-codegen 0.28.0 → 0.29.0

package/dist/index.d.cts

@@ -378,18 +378,29 @@ declare const DEFAULT_SANDBOX_KIT_OUTPUT = ".genui/sandbox-kit.json";
 interface WriteSandboxKitDocsOptions {
     root: string;
     output: string;
-    entry?: string;
-    include?: string | readonly string[];
-    css?: string | readonly string[];
+    components?: string | readonly string[];
+    styles?: string | readonly string[];
+    wrapper?: string;
+    stylesDocs?: string;
     tsconfig?: string;
 }
+/** The same options as the agent's Vite plugin (`@dudousxd/nestjs-agent/vite`). */
 interface GenuiSandboxKitOptions {
-    /** A module whose exports are the kit (e.g. `src/genui/kit.ts`). */
-    entry?: string;
-    /** A glob (or several) whose files' exports are the kit (e.g. `web/components/ui/*.tsx`). */
-    include?: string | readonly string[];
-    /** Stylesheet glob(s) whose custom properties become the sandbox theme. */
-    css?: string | readonly string[];
+    /**
+     * Modules whose exports are the kit's React components: files, globs, directories or packages
+     * (`web/components/ui`, `src/genui/kit.ts`, `@mui/material`). Default: the first shadcn
+     * `components/ui` dir found.
+     */
+    components?: string | readonly string[];
+    /**
+     * The app's style entry files (plain CSS, Sass, a Tailwind stylesheet…): what the model is told
+     * about the styles (Tailwind tokens, or the CSS class vocabulary) and the theme's variables.
+     */
+    styles?: string | readonly string[];
+    /** A module whose default export wraps the model's App (theme providers). */
+    wrapper?: string;
+    /** Guidance on the styles for the model: a markdown file, or the text itself. */
+    stylesDocs?: string;
     /** The tsconfig the component prop types are read through. */
     tsconfig?: string;
     /**
@@ -408,15 +419,17 @@ interface GenuiSandboxKitOptions {
 }
 /**
  * Writes the generative-UI **sandbox kit docs** — the app's design-system components (shadcn
- * `components/ui` by default) with the props read from their TypeScript types — to
+ * `components/ui` by default) with the props read from their TypeScript types, and what its
+ * `styles` are (Tailwind tokens, or a CSS class vocabulary, and the theme's variables) — to
  * `.genui/sandbox-kit.json`, where the `@dudousxd/nestjs-agent` server reads them.
  *
  * Runs on every generate pass (one-shot CLI, `--watch`, and the Nest module's watcher). The
  * descriptor lives outside `outDir`, so it is written by the generator itself, not through
- * `emitFiles`; the kit files, stylesheets and the descriptor are tracked as inputs, so editing
- * a component regenerates in watch mode and a deleted descriptor is rewritten.
+ * `emitFiles`; the kit files, the stylesheets (and what they import) and the descriptor are
+ * tracked as inputs, so editing a component or a stylesheet regenerates in watch mode and a
+ * deleted descriptor is rewritten.
  *
- * Needs the optional peer `@dudousxd/nestjs-agent-core` (>=0.52.0) unless `generate` is given.
+ * Needs the optional peer `@dudousxd/nestjs-agent-core` (>=0.53.0) unless `generate` is given.
  */
 declare function genuiSandboxKit(options?: GenuiSandboxKitOptions): CodegenExtension;
 
@@ -435,6 +448,6 @@ interface FastDiscoveryOptions {
 }
 declare function discoverContractsFast(opts: FastDiscoveryOptions): Promise<RouteDescriptor[]>;
 
-declare const VERSION = "0.28.0";
+declare const VERSION = "0.29.0";
 
 export { type ChainModuleRendererOptions, CodegenError, type CodegenManifest, ConfigError, DEFAULT_SANDBOX_KIT_OUTPUT, DriftGuardError, type EntryPoint, type FastDiscoveryOptions, type GenuiSandboxKitOptions, type JsonSchema, type MocksEmitOptions, type OpenApiDocument, type OpenApiEmitOptions, type OpenApiInfo, RenderContext, RenderedModule, ResolvedConfig, RouteDescriptor, SchemaModule, SchemaNode, type TsTypeContext, UserConfig, VERSION, ValidationAdapter, type WatchOptions, type Watcher, type WriteSandboxKitDocsOptions, acquireLock, buildMocksFile, buildOpenApiSpec, createChainModuleRenderer, defineConfig, discoverContractsFast, emitApi, emitForms, emitMocks, emitOpenApi, emitRoutes, extractSchemaFromDto, generate, genuiSandboxKit, loadConfig, renderTsType, resolveConfig, schemaModuleToJsonSchema, schemaNodeToJsonSchema, toObjectKey, typeNameFor, watch };

package/dist/index.d.ts

@@ -378,18 +378,29 @@ declare const DEFAULT_SANDBOX_KIT_OUTPUT = ".genui/sandbox-kit.json";
 interface WriteSandboxKitDocsOptions {
     root: string;
     output: string;
-    entry?: string;
-    include?: string | readonly string[];
-    css?: string | readonly string[];
+    components?: string | readonly string[];
+    styles?: string | readonly string[];
+    wrapper?: string;
+    stylesDocs?: string;
     tsconfig?: string;
 }
+/** The same options as the agent's Vite plugin (`@dudousxd/nestjs-agent/vite`). */
 interface GenuiSandboxKitOptions {
-    /** A module whose exports are the kit (e.g. `src/genui/kit.ts`). */
-    entry?: string;
-    /** A glob (or several) whose files' exports are the kit (e.g. `web/components/ui/*.tsx`). */
-    include?: string | readonly string[];
-    /** Stylesheet glob(s) whose custom properties become the sandbox theme. */
-    css?: string | readonly string[];
+    /**
+     * Modules whose exports are the kit's React components: files, globs, directories or packages
+     * (`web/components/ui`, `src/genui/kit.ts`, `@mui/material`). Default: the first shadcn
+     * `components/ui` dir found.
+     */
+    components?: string | readonly string[];
+    /**
+     * The app's style entry files (plain CSS, Sass, a Tailwind stylesheet…): what the model is told
+     * about the styles (Tailwind tokens, or the CSS class vocabulary) and the theme's variables.
+     */
+    styles?: string | readonly string[];
+    /** A module whose default export wraps the model's App (theme providers). */
+    wrapper?: string;
+    /** Guidance on the styles for the model: a markdown file, or the text itself. */
+    stylesDocs?: string;
     /** The tsconfig the component prop types are read through. */
     tsconfig?: string;
     /**
@@ -408,15 +419,17 @@ interface GenuiSandboxKitOptions {
 }
 /**
  * Writes the generative-UI **sandbox kit docs** — the app's design-system components (shadcn
- * `components/ui` by default) with the props read from their TypeScript types — to
+ * `components/ui` by default) with the props read from their TypeScript types, and what its
+ * `styles` are (Tailwind tokens, or a CSS class vocabulary, and the theme's variables) — to
  * `.genui/sandbox-kit.json`, where the `@dudousxd/nestjs-agent` server reads them.
  *
  * Runs on every generate pass (one-shot CLI, `--watch`, and the Nest module's watcher). The
  * descriptor lives outside `outDir`, so it is written by the generator itself, not through
- * `emitFiles`; the kit files, stylesheets and the descriptor are tracked as inputs, so editing
- * a component regenerates in watch mode and a deleted descriptor is rewritten.
+ * `emitFiles`; the kit files, the stylesheets (and what they import) and the descriptor are
+ * tracked as inputs, so editing a component or a stylesheet regenerates in watch mode and a
+ * deleted descriptor is rewritten.
  *
- * Needs the optional peer `@dudousxd/nestjs-agent-core` (>=0.52.0) unless `generate` is given.
+ * Needs the optional peer `@dudousxd/nestjs-agent-core` (>=0.53.0) unless `generate` is given.
  */
 declare function genuiSandboxKit(options?: GenuiSandboxKitOptions): CodegenExtension;
 
@@ -435,6 +448,6 @@ interface FastDiscoveryOptions {
 }
 declare function discoverContractsFast(opts: FastDiscoveryOptions): Promise<RouteDescriptor[]>;
 
-declare const VERSION = "0.28.0";
+declare const VERSION = "0.29.0";
 
 export { type ChainModuleRendererOptions, CodegenError, type CodegenManifest, ConfigError, DEFAULT_SANDBOX_KIT_OUTPUT, DriftGuardError, type EntryPoint, type FastDiscoveryOptions, type GenuiSandboxKitOptions, type JsonSchema, type MocksEmitOptions, type OpenApiDocument, type OpenApiEmitOptions, type OpenApiInfo, RenderContext, RenderedModule, ResolvedConfig, RouteDescriptor, SchemaModule, SchemaNode, type TsTypeContext, UserConfig, VERSION, ValidationAdapter, type WatchOptions, type Watcher, type WriteSandboxKitDocsOptions, acquireLock, buildMocksFile, buildOpenApiSpec, createChainModuleRenderer, defineConfig, discoverContractsFast, emitApi, emitForms, emitMocks, emitOpenApi, emitRoutes, extractSchemaFromDto, generate, genuiSandboxKit, loadConfig, renderTsType, resolveConfig, schemaModuleToJsonSchema, schemaNodeToJsonSchema, toObjectKey, typeNameFor, watch };

package/dist/index.js

@@ -6143,7 +6143,7 @@ function createChainModuleRenderer(opts) {
 }
 
 // src/extension/genui-sandbox-kit.ts
-import { existsSync as existsSync2 } from "fs";
+import { existsSync as existsSync2, statSync } from "fs";
 import { dirname as dirname5, isAbsolute as isAbsolute3, resolve as resolve6 } from "path";
 import fg4 from "fast-glob";
 var GENUI_KIT_MODULE = "@dudousxd/nestjs-agent-core/genui/kit";
@@ -6155,6 +6155,12 @@ var DEFAULT_KIT_DIRS = [
   "app/components/ui",
   "components/ui"
 ];
+var LEGACY_OPTIONS = {
+  entry: "`entry: X` is now `components: X`",
+  include: "`include: G` is now `components: G` (globs, files, directories or packages)",
+  css: "`css: G` is now `styles: G` (the app's style entry files)"
+};
+var MIN_CORE = "0.53.0";
 async function loadKitModule(specifier = GENUI_KIT_MODULE) {
   let mod;
   try {
@@ -6163,19 +6169,24 @@ async function loadKitModule(specifier = GENUI_KIT_MODULE) {
     const code = err.code;
     if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
       throw new CodegenError(
-        `genuiSandboxKit() needs "${GENUI_KIT_MODULE}" \u2014 install @dudousxd/nestjs-agent-core@>=0.52.0, or pass \`generate\` to genuiSandboxKit().`
+        `genuiSandboxKit() needs "${GENUI_KIT_MODULE}" \u2014 install @dudousxd/nestjs-agent-core@>=${MIN_CORE}, or pass \`generate\` to genuiSandboxKit().`
       );
     }
     if (code === "ERR_PACKAGE_PATH_NOT_EXPORTED") {
       throw new CodegenError(
-        `genuiSandboxKit() needs "${GENUI_KIT_MODULE}", which the installed @dudousxd/nestjs-agent-core does not export \u2014 upgrade it to >=0.52.0.`
+        `genuiSandboxKit() needs "${GENUI_KIT_MODULE}", which the installed @dudousxd/nestjs-agent-core does not export \u2014 upgrade it to >=${MIN_CORE}.`
       );
     }
     throw err;
   }
   if (typeof mod.writeSandboxKitDocs !== "function") {
     throw new CodegenError(
-      `"${GENUI_KIT_MODULE}" has no writeSandboxKitDocs export \u2014 upgrade @dudousxd/nestjs-agent-core to >=0.52.0.`
+      `"${GENUI_KIT_MODULE}" has no writeSandboxKitDocs export \u2014 upgrade @dudousxd/nestjs-agent-core to >=${MIN_CORE}.`
+    );
+  }
+  if (typeof mod.resolveStyleEntries !== "function") {
+    throw new CodegenError(
+      `The installed @dudousxd/nestjs-agent-core predates genuiSandboxKit({ components, styles, wrapper }) \u2014 upgrade it to >=${MIN_CORE}.`
     );
   }
   return mod;
@@ -6189,52 +6200,92 @@ function globBase(glob) {
   return base.join("/");
 }
 function resolveKitFilesLocally(root, options) {
-  if (options.entry !== void 0) {
-    const entry = isAbsolute3(options.entry) ? options.entry : resolve6(root, options.entry);
-    return { entry, files: [entry], dirs: [dirname5(entry)] };
-  }
-  const include = options.include ?? DEFAULT_KIT_DIRS.filter((dir) => existsSync2(resolve6(root, dir))).map(
-    (dir) => `${dir}/*.{tsx,jsx,ts,js}`
-  )[0];
-  if (include === void 0) return null;
-  const globs = typeof include === "string" ? [include] : [...include];
-  const files = fg4.sync(globs, { cwd: root, absolute: true, onlyFiles: true }).sort();
-  return { files, dirs: [...new Set(globs.map((glob) => resolve6(root, globBase(glob))))] };
+  const specs = options.components === void 0 ? DEFAULT_KIT_DIRS.filter((dir) => existsSync2(resolve6(root, dir))).slice(0, 1) : typeof options.components === "string" ? [options.components] : [...options.components];
+  const files = [];
+  const dirs = /* @__PURE__ */ new Set();
+  for (const spec of specs) {
+    if (/[*?{]/.test(spec)) {
+      files.push(...fg4.sync(spec, { cwd: root, absolute: true, onlyFiles: true }));
+      dirs.add(resolve6(root, globBase(spec)));
+      continue;
+    }
+    const path = isAbsolute3(spec) ? spec : resolve6(root, spec);
+    if (existsSync2(path) && statSync(path).isDirectory()) {
+      files.push(...fg4.sync("*.{tsx,jsx,ts,js}", { cwd: path, absolute: true, onlyFiles: true }));
+      dirs.add(path);
+    } else if (existsSync2(path)) {
+      files.push(path);
+      dirs.add(dirname5(path));
+    }
+  }
+  if (options.wrapper !== void 0) {
+    const wrapper = isAbsolute3(options.wrapper) ? options.wrapper : resolve6(root, options.wrapper);
+    if (existsSync2(wrapper)) files.push(wrapper);
+  }
+  if (files.length === 0 && dirs.size === 0) return null;
+  return { files: [...new Set(files)].sort(), dirs: [...dirs] };
 }
 function genuiSandboxKit(options = {}) {
+  const legacy = Object.keys(LEGACY_OPTIONS).filter(
+    (key) => options[key] !== void 0
+  );
+  if (legacy.length > 0) {
+    throw new CodegenError(
+      `genuiSandboxKit(): ${legacy.map((key) => `\`${key}\``).join(", ")} ${legacy.length > 1 ? "were" : "was"} removed \u2014 ${legacy.map((key) => LEGACY_OPTIONS[key]).join("; ")}. The options are now the agent's Vite plugin's: components, styles, wrapper, stylesDocs.`
+    );
+  }
   const output = options.output ?? DEFAULT_SANDBOX_KIT_OUTPUT;
   const source = {
-    ...options.entry !== void 0 ? { entry: options.entry } : {},
-    ...options.include !== void 0 ? { include: options.include } : {}
+    ...options.components !== void 0 ? { components: options.components } : {},
+    ...options.wrapper !== void 0 ? { wrapper: options.wrapper } : {}
   };
   const extension = {
     name: "genui-sandbox-kit",
     // Not read by the host: serialized into the config hash, so changing an option
     // invalidates skip-when-unchanged.
-    options: { ...source, css: options.css, tsconfig: options.tsconfig, output },
+    options: {
+      ...source,
+      styles: options.styles,
+      stylesDocs: options.stylesDocs,
+      tsconfig: options.tsconfig,
+      output
+    },
     async emitFiles(ctx) {
       const root = ctx.cwd;
       let generate2 = options.generate;
-      let resolveFiles = resolveKitFilesLocally;
+      let mod;
       if (!generate2) {
-        const mod = await loadKitModule(options.kitModule);
+        mod = await loadKitModule(options.kitModule);
         generate2 = mod.writeSandboxKitDocs;
-        if (typeof mod.resolveSandboxKitFiles === "function") {
-          resolveFiles = mod.resolveSandboxKitFiles;
-        }
       }
-      const kit = resolveFiles(root, source);
+      const resolveFiles = mod?.resolveSandboxKitFiles ?? resolveKitFilesLocally;
+      let kit = null;
+      try {
+        kit = resolveFiles(root, source);
+      } catch {
+        kit = null;
+      }
       if (kit) ctx.trackInput(...kit.files, ...kit.dirs);
-      if (options.css !== void 0) {
-        const css = typeof options.css === "string" ? [options.css] : [...options.css];
-        ctx.trackInput(...fg4.sync(css, { cwd: root, absolute: true, onlyFiles: true }));
+      if (options.styles !== void 0) {
+        const entries = mod?.resolveStyleEntries ? mod.resolveStyleEntries(root, options.styles).files : fg4.sync(typeof options.styles === "string" ? [options.styles] : [...options.styles], {
+          cwd: root,
+          absolute: true,
+          onlyFiles: true
+        });
+        const files = mod?.collectStyleSources ? mod.collectStyleSources(entries).map((source2) => source2.file) : entries;
+        ctx.trackInput(.../* @__PURE__ */ new Set([...entries, ...files]));
+      }
+      if (options.stylesDocs !== void 0 && !options.stylesDocs.includes("\n")) {
+        const guide = isAbsolute3(options.stylesDocs) ? options.stylesDocs : resolve6(root, options.stylesDocs);
+        if (existsSync2(guide)) ctx.trackInput(guide);
       }
       ctx.trackInput(isAbsolute3(output) ? output : resolve6(root, output));
       await generate2({
         root,
         output,
         ...source,
-        ...options.css !== void 0 ? { css: options.css } : {},
+        ...options.styles !== void 0 ? { styles: options.styles } : {},
+        ...options.stylesDocs !== void 0 ? { stylesDocs: options.stylesDocs } : {},
         ...options.tsconfig !== void 0 ? { tsconfig: options.tsconfig } : {}
       });
       return [];
@@ -6244,7 +6295,7 @@ function genuiSandboxKit(options = {}) {
 }
 
 // src/index.ts
-var VERSION = "0.28.0";
+var VERSION = "0.29.0";
 export {
   CodegenError,
   ConfigError,