@dudousxd/nestjs-inertia-codegen 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog — @dudousxd/nestjs-inertia-codegen
+
+## 1.0.0
+
+### Minor Changes
+
+- [`c5878e3`](https://github.com/DavideCarvalho/nestjs-inertia/commit/c5878e3f8827d9e89710df0154ea76996b6db62a) - First public release — Inertia.js v3 adapter for NestJS.
+
+  - Core: InertiaModule.forRoot/forRootAsync/forFeature, @Inertia decorator, Inertia.optional/defer/merge/always markers, CSRF with tokenContext, SSR support, Express + Fastify adapters
+  - Vite: setupInertiaVite + nestInertia plugin, @inertia/@vite/@inertiaHead shell directives
+  - Codegen: nestjs-inertia init (full scaffold + auto-patch), auto-watch in dev, static AST discovery, class-validator DTO support, Route/Path type helpers, @As hierarchical naming
+  - Client: defineContract + @ApplyContract, typed Link for React/Vue/Svelte with context providers, createFetcher, SSR hydration, rich error messages
+  - Testing: expectInertia matchers, assertInertia, InertiaTestingModule, fakes
+
+### Patch Changes
+
+- Updated dependencies [[`c5878e3`](https://github.com/DavideCarvalho/nestjs-inertia/commit/c5878e3f8827d9e89710df0154ea76996b6db62a)]:
+  - @dudousxd/nestjs-inertia@1.0.0
+
+## [Unreleased]
+
+### Removed
+
+- **Heavy probe path deleted** — `discoverRoutes` (fork + tsx + real Nest bootstrap) and the associated `probe.ts` child-process script have been removed. Static AST discovery via ts-morph is now the only route-discovery strategy.
+- `useStaticDiscovery` config field removed from `ContractsConfig` / `ResolvedContractsConfig` — there is no longer an alternative.
+- `tsconfig.probe.json` removed from the package.
+- `NESTJS_INERTIA_CODEGEN_PROBE` environment-variable guard removed from `@dudousxd/nestjs-inertia` core module (the probe child process no longer exists).
+
+## 0.9.0-alpha.0 — 2026-05-22
+
+### Changed
+
+- Version bump to `0.9.0-alpha.0` (Inertia v3 monorepo coordination; no source changes)
+
+## 0.8.0-alpha.0 — 2026-05-22
+
+### Added
+
+- **`RouteParamsMap` emission** — codegen now emits a `RouteParamsMap` mapped type alongside `routes.ts`; `init` augments `InertiaRegistry` with the `routes` property automatically
+- **ts-morph static AST contract discovery** — contract metadata is now extracted via ts-morph's static AST traversal instead of a dynamic child-process bootstrap probe; approximately 20× faster cold start and no side effects from running the NestJS app
+- **Watch covers contracts** — `--watch` mode now monitors controller/contract source files and re-emits `api.ts` on change
+- **`init` augmentation update** — `nestjs-inertia init` now scaffolds `InertiaRegistry` augmentation that includes `routes: RouteParamsMap` for typed `Link` and `route()` usage
+
+### Changed
+
+- Version bump to `0.8.0-alpha.0`
+
+## 0.7.0-alpha.0 — 2026-05-22
+
+### Changed
+
+- Bundled with example app, CI workflows, Changesets, MIT LICENSE, and slim docs.
+
+## [0.6.0-alpha.0] - 2026-05-22
+
+### Added
+
+- **Contract discovery** — `discoverContracts(opts)` reads `CONTRACT_METADATA` via the Nest bootstrap probe to collect all `@ApplyContract`-decorated handler contracts; returns `ContractDescriptor[]` (method, path, name, query/body/response schema shapes)
+- **`api.ts` emission** — `emitApi(contracts, outDir)` writes `.nestjs-inertia/api.ts`: a `createApi(opts?)` factory returning a typed route tree built on `@dudousxd/nestjs-inertia-client`'s `createFetcher`; no file is emitted when no contracts are found
+- `generate(config)` orchestrates contract discovery + `emitApi` alongside existing page/route/index emitters
+
+### Changed
+
+- Version bump to `0.6.0-alpha.0`
+
+## [0.5.0-alpha.0] - 2026-05-22
+
+### Added
+
+- Initial release of `@dudousxd/nestjs-inertia-codegen`
+- **Config layer** — `defineConfig` helper + `loadConfig(cwd)` with tsx ESM loader; `ConfigError` for missing file / invalid export / validation failure
+- **Page discovery** — `discoverPages(opts)` via fast-glob; extracts `ComponentProps` type body by brace-counting; supports `relative-no-ext`, `kebab`, and custom name strategies
+- **Route discovery** — `discoverRoutes(opts)` via child-process Nest bootstrap (tsx probe); returns `RouteDescriptor[]` with method, path, params
+- **Emitters**
+  - `emitPages(pages, outDir)` — writes `pages.d.ts` with `InertiaPages` interface (page name → props type, `unknown` for pages without props)
+  - `emitRoutes(routes, outDir)` — writes `routes.ts` with runtime `route(name, params?)` interpolator, `RouteName` union, `RouteParams<K>` template-literal mapped type
+  - `emitCache(pages, outDir)` — writes `components.json` cache manifest (name, relativePath, mtime)
+  - `emitIndex(outDir)` — writes `index.d.ts` barrel re-exporting pages, shared-props, routes
+- **`generate(config)`** — orchestrates discovery + all emitters in one call
+- **Watch mode** — `watch(config, onChange?)` via chokidar (150 ms debounce); returns `{ close() }`. Lock-file guard (`<outDir>/.watcher.lock`) prevents duplicate watchers in the same directory
+- **CLI** — `nestjs-inertia init` (scaffold config + `.gitignore` patch + `nestjs-inertia.d.ts` augmentation stub, idempotent) and `nestjs-inertia codegen [--watch]` powered by `cac`
+- **Programmatic API** — `loadConfig`, `generate`, `watch`, `defineConfig`, `ConfigError`, `CodegenError` all exported from package root

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Davide Carvalho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,182 @@
+# @dudousxd/nestjs-inertia-codegen
+
+> CLI + programmatic API that scans a NestJS + Inertia.js app and emits typed artifacts under `.nestjs-inertia/`.
+
+[![npm version](https://img.shields.io/npm/v/@dudousxd/nestjs-inertia-codegen)](https://www.npmjs.com/package/@dudousxd/nestjs-inertia-codegen)
+
+## Install
+
+```bash
+pnpm add -D @dudousxd/nestjs-inertia-codegen
+pnpm add -D tsx   # required for loading nestjs-inertia.config.ts
+```
+
+## Quick Start
+
+```bash
+# 1. Scaffold config file + .gitignore patch + nestjs-inertia.d.ts augmentation stub
+pnpm nestjs-inertia init
+
+# 2. Generate typed artifacts (one-shot)
+pnpm nestjs-inertia codegen
+
+# 3. Watch mode — regenerates on every page file change (150ms debounce)
+pnpm nestjs-inertia codegen --watch
+```
+
+After running `codegen`, the `.nestjs-inertia/` directory will contain:
+
+```
+.nestjs-inertia/
+  pages.d.ts          # InertiaPages interface (page name → props type)
+  routes.ts           # route() helper + RouteName union + RouteParams<K>
+  api.ts              # typed client API (emitted when @ApplyContract handlers are found)
+  shared-props.d.ts   # (placeholder, future)
+  index.d.ts          # barrel re-export
+  components.json     # cache manifest (name, relativePath, mtime)
+```
+
+### Contract discovery and `api.ts` emission (v0.6.0+)
+
+When controllers use `@ApplyContract` from `@dudousxd/nestjs-inertia-client`, codegen discovers the attached contract metadata during the route-discovery probe and emits `.nestjs-inertia/api.ts` — a fully-typed client module built on `createFetcher`:
+
+```ts
+// .nestjs-inertia/api.ts (generated)
+import { createFetcher } from '@dudousxd/nestjs-inertia-client';
+import type { FetcherOptions } from '@dudousxd/nestjs-inertia-client';
+
+export function createApi(opts?: FetcherOptions) {
+  const fetcher = createFetcher(opts);
+  return {
+    users: {
+      list: (query?: { page?: number }) => fetcher.get('/users', { query }),
+      create: (body: { name: string; email: string }) => fetcher.post('/users', { body }),
+    },
+  };
+}
+```
+
+No `api.ts` is emitted when no `@ApplyContract` handlers are found.
+
+Add `.nestjs-inertia/` to `.gitignore` (the `init` command does this automatically).
+
+## Config Reference
+
+Create `nestjs-inertia.config.ts` at the repo root (or let `init` scaffold it):
+
+```ts
+import { defineConfig } from '@dudousxd/nestjs-inertia-codegen';
+
+export default defineConfig({
+  pages: {
+    // Glob pattern relative to cwd
+    glob: 'inertia/pages/**/*.{tsx,vue,svelte}',
+    // Named export that holds the per-page props type (default: 'ComponentProps')
+    propsExport: 'ComponentProps',
+    // How to derive the Inertia page name from the file path (default: 'relative-no-ext')
+    // Options: 'relative-no-ext' | 'kebab' | ((relativePath: string) => string)
+    componentNameStrategy: 'relative-no-ext',
+  },
+  contracts: {
+    // Glob for controller files watched in --watch mode (default: 'src/**/*.controller.ts')
+    glob: 'src/**/*.controller.ts',
+    // Debounce delay in ms before re-running route discovery (default: 500)
+    debounceMs: 500,
+  },
+  codegen: {
+    // Output directory for generated artifacts (default: '.nestjs-inertia')
+    outDir: '.nestjs-inertia',
+  },
+  app: {
+    // Entry module for route discovery (optional — routes.ts is skipped if absent)
+    moduleEntry: 'src/app.module.ts',
+    tsconfig: 'tsconfig.json',
+  },
+});
+```
+
+Full spec: [`/docs/superpowers/specs/2026-05-22-nestjs-inertia-plan-c-design.md`](../../docs/superpowers/specs/2026-05-22-nestjs-inertia-plan-c-design.md)
+
+## CLI Reference
+
+```
+nestjs-inertia <command> [options]
+
+Commands:
+  init              Scaffold nestjs-inertia.config.ts, nestjs-inertia.d.ts, and
+                    patch .gitignore. Safe to re-run (idempotent).
+  codegen           One-shot generate: discover pages (+ routes if app.moduleEntry
+                    is set) and write typed artifacts to codegen.outDir.
+  codegen --watch   Watch mode: runs an initial codegen pass, then watches
+                    pages.glob for changes and regenerates on each event
+                    (150 ms debounce). Acquires a lock file to prevent duplicate
+                    watchers in the same outDir.
+
+Options:
+  --help, -h        Show help
+  --version, -v     Show version
+```
+
+> **Watch mode — two watchers:** `--watch` runs two independent file watchers:
+> 1. **Pages watcher** (`pages.glob`, 150 ms debounce) — regenerates `pages.d.ts` on any page file change.
+> 2. **Contracts watcher** (`contracts.glob`, default `src/**/*.controller.ts`, 500 ms debounce) — re-runs static AST route discovery via ts-morph (~100–500 ms) and regenerates `routes.ts` and `api.ts` whenever a controller file changes.
+>
+> Configure the contracts glob and debounce via the `contracts` key in `nestjs-inertia.config.ts`.
+
+## Programmatic API
+
+```ts
+import { defineConfig, loadConfig, generate, watch } from '@dudousxd/nestjs-inertia-codegen';
+import type { UserConfig, ResolvedConfig } from '@dudousxd/nestjs-inertia-codegen';
+
+// --- Config ---
+
+// In nestjs-inertia.config.ts — provides type-checking + IDE completion
+export default defineConfig({
+  pages: { glob: 'inertia/pages/**/*.tsx' },
+});
+
+// Load config from disk (resolves defaults, makes paths absolute)
+const config: ResolvedConfig = await loadConfig(process.cwd());
+
+// --- One-shot generation ---
+await generate(config);
+
+// --- Watch mode ---
+const watcher = await watch(config, () => {
+  console.log('Pages regenerated');
+});
+
+// Shut down cleanly (releases lock file)
+await watcher.close();
+```
+
+### Error classes
+
+```ts
+import { ConfigError, CodegenError } from '@dudousxd/nestjs-inertia-codegen';
+```
+
+- `ConfigError` — config file missing, invalid default export, or validation failure.
+- `CodegenError` — emit or discovery failure.
+
+## Module augmentation
+
+After running `init`, a `nestjs-inertia.d.ts` file is created at the repo root:
+
+```ts
+import '@dudousxd/nestjs-inertia';
+import type { InertiaPages } from './.nestjs-inertia/index.js';
+
+declare module '@dudousxd/nestjs-inertia' {
+  interface InertiaRegistry {
+    pages: InertiaPages;
+  }
+}
+```
+
+This augments `InertiaRegistry` in core so page names and their prop types are available to the typed client (Plan D).
+
+## License
+
+MIT

package/bin/nestjs-inertia.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/cli/main.js').then((m) => m.run(process.argv.slice(2)));