@dudousxd/nestjs-codegen 0.27.2 → 0.28.0

package/dist/index.d.cts

@@ -141,7 +141,12 @@ interface WatchOptions {
  *    re-runs static AST route discovery via ts-morph, then re-emits `routes.ts` and (when
  *    contracts are present) `api.ts` + `index.d.ts`.
  *
- * Both watchers share a single lock file in `config.codegen.outDir`. If another live process
+ * 3. **Tracked-inputs watcher** — the files extensions declared via `ctx.trackInput` (recorded
+ *    in the manifest as `extraInputs`), re-synced after every pass. A change re-runs the
+ *    contracts path, so an extension's out-of-glob dependencies (a filter class, a sandbox-kit
+ *    component) regenerate in watch mode too, not only on the next one-shot run.
+ *
+ * All watchers share a single lock file in `config.codegen.outDir`. If another live process
  * already holds the lock, logs a warning and returns a no-op watcher.
  */
 declare function watch(config: ResolvedConfig, onChange?: () => void, options?: WatchOptions): Promise<Watcher>;
@@ -367,6 +372,54 @@ declare function buildMocksFile(routes: RouteDescriptor[], opts?: MocksEmitOptio
 /** Emit `mocks.ts` into `outDir`. */
 declare function emitMocks(routes: RouteDescriptor[], outDir: string, opts?: MocksEmitOptions): Promise<void>;
 
+/** Where the Nest server reads the descriptor from by default (relative to the app root). */
+declare const DEFAULT_SANDBOX_KIT_OUTPUT = ".genui/sandbox-kit.json";
+/** What {@link genuiSandboxKit} passes to `writeSandboxKitDocs`. */
+interface WriteSandboxKitDocsOptions {
+    root: string;
+    output: string;
+    entry?: string;
+    include?: string | readonly string[];
+    css?: string | readonly string[];
+    tsconfig?: string;
+}
+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[];
+    /** The tsconfig the component prop types are read through. */
+    tsconfig?: string;
+    /**
+     * Where the descriptor is written, relative to the app `cwd` (or absolute).
+     * @default '.genui/sandbox-kit.json'
+     */
+    output?: string;
+    /**
+     * The docs writer. Defaults to `writeSandboxKitDocs` from
+     * `@dudousxd/nestjs-agent-core/genui/kit`; inject one to test, or to use another generator.
+     * It is expected to write `output` itself (and only when the contents change).
+     */
+    generate?: (options: WriteSandboxKitDocsOptions) => Promise<unknown>;
+    /** The module the writer is loaded from. Default `@dudousxd/nestjs-agent-core/genui/kit`. */
+    kitModule?: string;
+}
+/**
+ * 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
+ * `.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.
+ *
+ * Needs the optional peer `@dudousxd/nestjs-agent-core` (>=0.52.0) unless `generate` is given.
+ */
+declare function genuiSandboxKit(options?: GenuiSandboxKitOptions): CodegenExtension;
+
 /**
  * Static AST-based contract discovery using ts-morph.
  * Cold start ~100-500 ms.
@@ -382,6 +435,6 @@ interface FastDiscoveryOptions {
 }
 declare function discoverContractsFast(opts: FastDiscoveryOptions): Promise<RouteDescriptor[]>;
 
-declare const VERSION = "0.27.2";
+declare const VERSION = "0.28.0";
 
-export { type ChainModuleRendererOptions, CodegenError, type CodegenManifest, ConfigError, DriftGuardError, type EntryPoint, type FastDiscoveryOptions, 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, acquireLock, buildMocksFile, buildOpenApiSpec, createChainModuleRenderer, defineConfig, discoverContractsFast, emitApi, emitForms, emitMocks, emitOpenApi, emitRoutes, extractSchemaFromDto, generate, loadConfig, renderTsType, resolveConfig, schemaModuleToJsonSchema, schemaNodeToJsonSchema, toObjectKey, typeNameFor, watch };
+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

@@ -141,7 +141,12 @@ interface WatchOptions {
  *    re-runs static AST route discovery via ts-morph, then re-emits `routes.ts` and (when
  *    contracts are present) `api.ts` + `index.d.ts`.
  *
- * Both watchers share a single lock file in `config.codegen.outDir`. If another live process
+ * 3. **Tracked-inputs watcher** — the files extensions declared via `ctx.trackInput` (recorded
+ *    in the manifest as `extraInputs`), re-synced after every pass. A change re-runs the
+ *    contracts path, so an extension's out-of-glob dependencies (a filter class, a sandbox-kit
+ *    component) regenerate in watch mode too, not only on the next one-shot run.
+ *
+ * All watchers share a single lock file in `config.codegen.outDir`. If another live process
  * already holds the lock, logs a warning and returns a no-op watcher.
  */
 declare function watch(config: ResolvedConfig, onChange?: () => void, options?: WatchOptions): Promise<Watcher>;
@@ -367,6 +372,54 @@ declare function buildMocksFile(routes: RouteDescriptor[], opts?: MocksEmitOptio
 /** Emit `mocks.ts` into `outDir`. */
 declare function emitMocks(routes: RouteDescriptor[], outDir: string, opts?: MocksEmitOptions): Promise<void>;
 
+/** Where the Nest server reads the descriptor from by default (relative to the app root). */
+declare const DEFAULT_SANDBOX_KIT_OUTPUT = ".genui/sandbox-kit.json";
+/** What {@link genuiSandboxKit} passes to `writeSandboxKitDocs`. */
+interface WriteSandboxKitDocsOptions {
+    root: string;
+    output: string;
+    entry?: string;
+    include?: string | readonly string[];
+    css?: string | readonly string[];
+    tsconfig?: string;
+}
+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[];
+    /** The tsconfig the component prop types are read through. */
+    tsconfig?: string;
+    /**
+     * Where the descriptor is written, relative to the app `cwd` (or absolute).
+     * @default '.genui/sandbox-kit.json'
+     */
+    output?: string;
+    /**
+     * The docs writer. Defaults to `writeSandboxKitDocs` from
+     * `@dudousxd/nestjs-agent-core/genui/kit`; inject one to test, or to use another generator.
+     * It is expected to write `output` itself (and only when the contents change).
+     */
+    generate?: (options: WriteSandboxKitDocsOptions) => Promise<unknown>;
+    /** The module the writer is loaded from. Default `@dudousxd/nestjs-agent-core/genui/kit`. */
+    kitModule?: string;
+}
+/**
+ * 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
+ * `.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.
+ *
+ * Needs the optional peer `@dudousxd/nestjs-agent-core` (>=0.52.0) unless `generate` is given.
+ */
+declare function genuiSandboxKit(options?: GenuiSandboxKitOptions): CodegenExtension;
+
 /**
  * Static AST-based contract discovery using ts-morph.
  * Cold start ~100-500 ms.
@@ -382,6 +435,6 @@ interface FastDiscoveryOptions {
 }
 declare function discoverContractsFast(opts: FastDiscoveryOptions): Promise<RouteDescriptor[]>;
 
-declare const VERSION = "0.27.2";
+declare const VERSION = "0.28.0";
 
-export { type ChainModuleRendererOptions, CodegenError, type CodegenManifest, ConfigError, DriftGuardError, type EntryPoint, type FastDiscoveryOptions, 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, acquireLock, buildMocksFile, buildOpenApiSpec, createChainModuleRenderer, defineConfig, discoverContractsFast, emitApi, emitForms, emitMocks, emitOpenApi, emitRoutes, extractSchemaFromDto, generate, loadConfig, renderTsType, resolveConfig, schemaModuleToJsonSchema, schemaNodeToJsonSchema, toObjectKey, typeNameFor, watch };
+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

@@ -5655,14 +5655,26 @@ async function computeInputsHash(config, extraInputs = []) {
     hash.update("\n");
   }
   for (const file of extra) {
-    const contents = await readFile2(join13(cwd, file), "utf8").catch(() => null);
     hash.update(`extra:${file}
 `);
-    hash.update(contents ?? "\0missing");
+    hash.update(await readTrackedInput(join13(cwd, file)));
     hash.update("\n");
   }
   return hash.digest("hex");
 }
+async function readTrackedInput(path) {
+  try {
+    return await readFile2(path, "utf8");
+  } catch (err) {
+    if (err.code !== "EISDIR") return "\0missing";
+  }
+  try {
+    const entries = await readdir(path);
+    return `\0dir:${entries.sort().join("\n")}`;
+  } catch {
+    return "\0missing";
+  }
+}
 async function readManifest(outDir) {
   try {
     const raw = await readFile2(join13(outDir, MANIFEST_FILE), "utf8");
@@ -5818,7 +5830,7 @@ async function generate(config, inputRoutes = [], entryPoint = "cli") {
 
 // src/watch/watcher.ts
 import { readFile as readFile4 } from "fs/promises";
-import { join as join16 } from "path";
+import { join as join16, resolve as resolve5 } from "path";
 import chokidar from "chokidar";
 
 // src/watch/lock-file.ts
@@ -5900,11 +5912,36 @@ async function watch(config, onChange, options = {}) {
     }
     return discovery;
   }
+  const trackedWatcher = chokidar.watch([], {
+    ignoreInitial: true,
+    persistent: true,
+    awaitWriteFinish: { stabilityThreshold: 80, pollInterval: 20 }
+  });
+  const trackedPaths = /* @__PURE__ */ new Set();
+  async function syncTrackedInputs() {
+    const manifest = await readManifest(config.codegen.outDir);
+    const fresh = [];
+    for (const path of manifest?.extraInputs ?? []) {
+      const abs = resolve5(config.codegen.cwd, path);
+      if (trackedPaths.has(abs)) continue;
+      trackedPaths.add(abs);
+      fresh.push(abs);
+    }
+    if (fresh.length > 0) trackedWatcher.add(fresh);
+  }
+  async function generateAndTrack(routes) {
+    try {
+      await generate(config, routes, entryPoint);
+    } finally {
+      await syncTrackedInputs().catch(() => {
+      });
+    }
+  }
   async function runInitialPass() {
     try {
       const initialRoutes = (await getDiscovery()).discover();
       lastRoutes = initialRoutes;
-      await generate(config, initialRoutes, entryPoint);
+      await generateAndTrack(initialRoutes);
     } catch (err) {
       if (err instanceof DriftGuardError) {
         console.error(err.message);
@@ -5914,7 +5951,7 @@ async function watch(config, onChange, options = {}) {
         `[nestjs-codegen] Initial route discovery failed, falling back to pages-only: ${err instanceof Error ? err.message : String(err)}`
       );
       try {
-        await generate(config, lastRoutes, entryPoint);
+        await generateAndTrack(lastRoutes);
       } catch {
       }
     }
@@ -5947,7 +5984,7 @@ async function watch(config, onChange, options = {}) {
     pagesDebounceTimer = setTimeout(async () => {
       pagesDebounceTimer = void 0;
       try {
-        await generate(config, lastRoutes, entryPoint);
+        await generateAndTrack(lastRoutes);
       } catch (err) {
         console.error(
           "[nestjs-codegen] Pages generation failed:",
@@ -5979,7 +6016,7 @@ async function watch(config, onChange, options = {}) {
       try {
         const routes = await (await getDiscovery()).rediscover(changed);
         lastRoutes = routes;
-        await generate(config, routes, entryPoint);
+        await generateAndTrack(routes);
       } catch (err) {
         console.error(
           "[nestjs-codegen] Contracts generation failed:",
@@ -6000,6 +6037,9 @@ async function watch(config, onChange, options = {}) {
   formsWatcher.on("add", (p) => scheduleContractsRegenerate(p));
   formsWatcher.on("change", (p) => scheduleContractsRegenerate(p));
   formsWatcher.on("unlink", (p) => scheduleContractsRegenerate(p));
+  trackedWatcher.on("add", (p) => scheduleContractsRegenerate(p));
+  trackedWatcher.on("change", (p) => scheduleContractsRegenerate(p));
+  trackedWatcher.on("unlink", (p) => scheduleContractsRegenerate(p));
   return {
     close: async () => {
       if (pagesDebounceTimer !== void 0) {
@@ -6013,6 +6053,7 @@ async function watch(config, onChange, options = {}) {
       await pagesWatcher.close();
       await contractsWatcher.close();
       await formsWatcher.close();
+      await trackedWatcher.close();
       await lock.release();
     }
   };
@@ -6101,11 +6142,113 @@ function createChainModuleRenderer(opts) {
   };
 }
 
+// src/extension/genui-sandbox-kit.ts
+import { existsSync as existsSync2 } 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";
+var DEFAULT_SANDBOX_KIT_OUTPUT = ".genui/sandbox-kit.json";
+var DEFAULT_KIT_DIRS = [
+  "inertia/components/ui",
+  "resources/js/components/ui",
+  "src/components/ui",
+  "app/components/ui",
+  "components/ui"
+];
+async function loadKitModule(specifier = GENUI_KIT_MODULE) {
+  let mod;
+  try {
+    mod = await import(specifier);
+  } catch (err) {
+    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().`
+      );
+    }
+    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.`
+      );
+    }
+    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.`
+    );
+  }
+  return mod;
+}
+function globBase(glob) {
+  const base = [];
+  for (const part of glob.replace(/\\/g, "/").split("/")) {
+    if (/[*?{[]/.test(part)) break;
+    base.push(part);
+  }
+  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))))] };
+}
+function genuiSandboxKit(options = {}) {
+  const output = options.output ?? DEFAULT_SANDBOX_KIT_OUTPUT;
+  const source = {
+    ...options.entry !== void 0 ? { entry: options.entry } : {},
+    ...options.include !== void 0 ? { include: options.include } : {}
+  };
+  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 },
+    async emitFiles(ctx) {
+      const root = ctx.cwd;
+      let generate2 = options.generate;
+      let resolveFiles = resolveKitFilesLocally;
+      if (!generate2) {
+        const mod = await loadKitModule(options.kitModule);
+        generate2 = mod.writeSandboxKitDocs;
+        if (typeof mod.resolveSandboxKitFiles === "function") {
+          resolveFiles = mod.resolveSandboxKitFiles;
+        }
+      }
+      const kit = resolveFiles(root, source);
+      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 }));
+      }
+      ctx.trackInput(isAbsolute3(output) ? output : resolve6(root, output));
+      await generate2({
+        root,
+        output,
+        ...source,
+        ...options.css !== void 0 ? { css: options.css } : {},
+        ...options.tsconfig !== void 0 ? { tsconfig: options.tsconfig } : {}
+      });
+      return [];
+    }
+  };
+  return extension;
+}
+
 // src/index.ts
-var VERSION = "0.27.2";
+var VERSION = "0.28.0";
 export {
   CodegenError,
   ConfigError,
+  DEFAULT_SANDBOX_KIT_OUTPUT,
   DriftGuardError,
   VERSION,
   acquireLock,
@@ -6121,6 +6264,7 @@ export {
   emitRoutes,
   extractSchemaFromDto,
   generate,
+  genuiSandboxKit,
   loadConfig,
   renderTsType,
   resolveAdapter,