@fluojs/cli 2.0.1 → 3.0.0

package/README.md

@@ -1,8 +1,11 @@
 # @fluojs/cli
 
 <p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
+<!-- fluo-cli-bootstrap-automation-boundary: explicit-platform-express, numeric-literal-single-argument-listen, manual-host-callback-string-env-multiple-listen -->
 
-The canonical CLI for fluo — bootstrap new applications, generate components, export runtime inspection data, and run code transforms.
+The canonical CLI for fluo — bootstrap new applications, generate components and React page types, export runtime inspection data, and run code transforms.
+
+Preparing for the coordinated Node 24 release? Follow the [consumer migration guide](../../docs/getting-started/migrate-node24.md) before upgrading packages.
 
 ## Table of Contents
 
@@ -30,8 +33,11 @@ pnpm dlx @fluojs/cli new my-app
 
 ## Release Contract
 
-- `@fluojs/cli` is a public package in the intended publish surface.
-- `@fluojs/cli` requires Node.js `>=20.0.0`; generated Bun, Deno, and Cloudflare Workers starters may target non-Node runtimes, but the CLI process itself runs on Node.js.
+- `@fluojs/cli` and every generated Node HTTP, mixed, microservice, and React SSR + Fastify project require Node.js `>=24.0.0 <27`. Node builds target `node24` and Node starters use `@types/node@^24.0.0`. Bun and Deno starters retain native engines; the Workers Node engine constrains only local CLI/Wrangler tooling. Apply the [Node.js migration](../../docs/reference/node-support.md) before upgrading.
+- `@fluojs/cli` requires Node.js `>=24.0.0 <27`; generated Bun, Deno, and Cloudflare Workers starters may target non-Node runtimes, but the CLI process itself runs on Node.js. Generated Node HTTP and mixed projects declare Node.js `>=24.0.0 <27` so listener-level RFC `QUERY` reaches framework dispatch; Node versions below 24 and Node 27+ are excluded. Node microservice-only projects retain their independent `>=24.0.0 <27` floor.
+- `inspect` resolves `@fluojs/runtime` only when inspection runs and only from the inspected project's dependency tree. Install a runtime version compatible with your active Node.js version before using `fluo inspect`; other CLI commands remain available across the CLI's full Node.js `>=24.0.0 <27` range.
+- Interactive `new` flows and optional interactive `inspect --mermaid` guidance resolve `@clack/prompts` only when needed. Both interactive and non-interactive commands support the CLI Node.js `>=24.0.0 <27` range.
+- The CLI and generated Node.js starter toolchain use `tsx@^4.23.1`; generated gRPC starters require `@grpc/grpc-js@^1.14.4`. Refresh existing project lockfiles when adopting these patched floors.
 - The supported install paths are the global package (`npm install -g @fluojs/cli`, `pnpm add -g @fluojs/cli`, `bun add -g @fluojs/cli`, or `yarn global add @fluojs/cli`) and the no-install runner (`pnpm dlx @fluojs/cli ...`).
 - The published `fluo` bin is the `./bin/fluo.mjs` wrapper declared in `package.json`; that wrapper loads the dist-built CLI entrypoint at `../dist/cli.js`.
 
@@ -66,22 +72,45 @@ The update check is skipped in CI, non-TTY output, npm-script contexts, rerun-af
 Scaffold a complete starter application in seconds.
 
 ```bash
-fluo new my-app
+fluo new my-app --package-manager pnpm
 cd my-app
 pnpm dev
 ```
 
+This example pins `pnpm`, so every successful scaffold ends with the same completion block:
+
+```text
+Done.
+Next steps:
+  cd ./my-app
+  pnpm dev  # runs fluo dev
+```
+
+In non-interactive output, an install prints `Installing dependencies with pnpm...` and the package-manager output before that block, while `--no-install` prints `Skipping dependency installation.`. In an interactive terminal, the wizard reports the same install state through its status UI (`Dependencies installed` or `Dependency installation skipped`) instead of those non-interactive stdout lines, then prints the common completion block. A completed pnpm install writes `pnpm-lock.yaml`; `--no-install` leaves it absent until you run `pnpm install` in the generated project. If you omit `--package-manager pnpm`, the CLI selects a manager from the current invocation or workspace signals and falls back to pnpm, so both the next-step command and the lockfile become manager-specific; other managers write their own lockfile instead of `pnpm-lock.yaml` when installation runs.
+
 `fluo create` is an alias for `fluo new`. Use `fluo version`, `fluo help <command>`, `fluo doctor`/`fluo info`/`fluo analyze`, `fluo add`, and `fluo upgrade` for version checks, command help, diagnostics, first-party package shortcuts, and upgrade guidance.
 
-Generated Node.js `dev`, `build`, and `start` package scripts delegate to `fluo dev`, `fluo build`, and `fluo start`. The CLI owns the Node-oriented lifecycle command, prepends the project-local `node_modules/.bin` when invoking local toolchain binaries, and defaults `NODE_ENV` to `development` for `dev` and `production` for `build`/`start` when the caller has not set it explicitly. Bun, Deno, and Workers generated `dev` scripts keep the same `fluo dev` abstraction but default to Bun, Deno, or Wrangler native watch loops to reduce Node-supervised dev processes; use `fluo dev --runner fluo` (or `FLUO_DEV_RUNNER=fluo`) when you need the fluo-owned restart boundary for its debounce/hash reporter contract. Their production/deployment scripts are runtime-native: Bun uses `bun build ./src/main.ts --outdir ./dist --target bun` and `bun dist/main.js`, Deno uses `deno compile --allow-env --allow-net --output dist/app src/main.ts` and `./dist/app`, and Workers exposes Wrangler `preview`/`deploy` scripts instead of `start`. By default, `fluo dev` and `fluo start` show app logs only (application stdout/stderr) so the lifecycle output shape is unified where the CLI owns the process boundary. Use `--reporter pretty` when you want concise fluo-branded lifecycle status and `app │`-prefixed application stdout/stderr, and use `--verbose` (or `FLUO_VERBOSE=1`) when you need raw runtime/tooling watcher output for debugging.
+Generated Node.js `dev`, `build`, and `start` package scripts delegate to `fluo dev`, `fluo build`, and `fluo start`. The CLI owns the Node-oriented lifecycle command, prepends the project-local `node_modules/.bin` when invoking local toolchain binaries, and defaults `NODE_ENV` to `development` for `dev` and `production` for `build`/`start` when the caller has not set it explicitly. Bun, Deno, and Workers generated `dev` scripts keep the same `fluo dev` abstraction but default to Bun, Deno, or Wrangler native watch loops to reduce Node-supervised dev processes; use `fluo dev --runner fluo` (or `FLUO_DEV_RUNNER=fluo`) when you need the fluo-owned restart boundary for its debounce/hash reporter contract. Their production/deployment scripts are runtime-native: Bun uses `bun build ./src/main.ts --outdir ./dist --target bun` and `bun dist/main.js`, Deno uses `deno compile --allow-env --allow-net --output dist/app src/main.ts` and `./dist/app`, and Workers exposes Wrangler `preview`/`deploy` scripts instead of `start`. The generated Deno `AppModule` snapshots application-owned environment values with `Deno.env.toObject()`, so its dev and compiled commands retain broad `--allow-env`; signal listeners do not require a separate Deno permission. By default, `fluo dev` and `fluo start` show app logs only (application stdout/stderr) so the lifecycle output shape is unified where the CLI owns the process boundary. Use `--reporter pretty` when you want concise fluo-branded lifecycle status and `app │`-prefixed application stdout/stderr, and use `--verbose` (or `FLUO_VERBOSE=1`) when you need raw runtime/tooling watcher output for debugging.
 
 Generated starters set their `@fluojs/cli` `devDependency` from the generator CLI package version that created the project, so lifecycle scripts such as `pnpm dev`, `pnpm build`, and `pnpm start` keep using the same CLI behavior that scaffolded the starter instead of a stale hard-coded range.
 
-Generated non-Deno starter `vite.config.ts` files import `fluoDecoratorsPlugin()` from `@fluojs/vite`, so decorator transform updates ship through the maintained Vite package instead of being copied inline into every new project.
+In published mode, every other internal `@fluojs/*` dependency and dev dependency uses
+`^<package version>` from that package's release manifest. The CLI build generates
+this metadata after Changesets versioning and ships it in `dist`, so an unpacked
+CLI does not need the monorepo or a registry lookup to scaffold. Versions remain
+independent, including React's `0.x` line; they are not all set to the CLI's major.
+This applies to every HTTP, microservice, mixed, React, Bun, Deno, and Workers
+starter. Internal local-sandbox tarball overrides still take precedence.
+
+Generated non-Deno standard starter `vite.config.ts` files import `fluoDecoratorsPlugin()` from `@fluojs/vite`, while the React SSR + Vite starter applies the same plugin in `vite.server.config.ts`. The React starter keeps decorator-bearing declarations in `src/app.ts` and JSX rendering in `.tsx` modules, so the supported `.ts` transform boundary stays explicit. Decorator transform updates therefore ship through the maintained Vite package instead of being copied inline into every new project.
+
+New non-Deno projects declare Vite `^8.2.2`, Vitest `^4.1.11`, and `@vitest/coverage-v8` `^4.1.11`. Generated ESM Vite configs use `build.rolldownOptions`; Babel handles standard decorators through `fluoDecoratorsPlugin()` before Rolldown/Oxc processes application code, while `vitest.config.ts` retains `fluoBabelDecoratorsPlugin()` from `@fluojs/testing/vitest`. Direct Oxc/esbuild decorator processing is not supported. Node.js `>=24.0.0 <27` and runtime-native starter metadata are unchanged. Existing projects are not rewritten; adopt the [generated toolchain baseline](../../docs/reference/toolchain-contract-matrix.md) explicitly when upgrading.
+
+When upgrading an existing starter, remove the `ignore: ['src/**/*.test.ts']` rule from `babel.config.cjs`. Generated Babel configs no longer exclude test files, so the testing plugin also transforms decorators declared inside tests before Vitest 4 executes them.
 
-Generated non-Deno HTTP starters use a TDD-first Vitest layout: fast greeting unit tests and `greeting.slice.test.ts` stay colocated under `src/greeting/`, app dispatch tests stay in `src/app.test.ts`, and the default e2e-style request-pipeline tests live in `test/app.e2e.test.ts` with `createTestApp({ rootModule })` plus `app.request(...).send()`. The generated `vitest.config.ts` includes both `src/**/*.test.ts` and `test/**/*.test.ts`, while generated package scripts expose `test`, `test:watch`, `test:cov`, and `test:e2e`; existing `src/app.e2e.test.ts` tests can move to `test/app.e2e.test.ts` without changing the request helper.
+Generated standard non-Deno HTTP starters use a TDD-first Vitest layout: fast greeting unit tests and `greeting.slice.test.ts` stay colocated under `src/greeting/`, app dispatch tests stay in `src/app.test.ts`, and the default e2e-style request-pipeline tests live in `test/app.e2e.test.ts` with `createTestApp({ rootModule })` plus `app.request(...).send()`. The React starter instead includes focused streamed SSR, DOM hydration, and production Playwright hydration tests. Its `test:browser` script starts the built Fastify server and fails on missing assets, hydration warnings, or navigation that bypasses the server-owned route.
 
-For generated Node.js application projects, `fluo dev` runs through a fluo-owned restart boundary by default. The runner watches source and common config inputs, debounces atomic-save bursts, hashes file content before restarting, loads `.env` for each Node app child process it spawns, and ignores noisy output/cache paths such as `node_modules`, `dist`, `.git`, `.fluo`, coverage, cache folders, and editor swap files. Pressing Ctrl+S without changing file content should not restart the app. Planned restarts and terminal shutdown first send `SIGTERM` to the current app child, then force-kill it after a bounded grace period so a non-cooperative child cannot hang the restart supervisor indefinitely. On terminal app child exit or crash outside a planned restart, the runner closes watchers, clears the pending restart timer and paths, unregisters its `SIGINT`/`SIGTERM` handlers, and exits with the child terminal code. This is full-process restart-on-watch, not module-level HMR; config watch reloads are a separate in-process config concern, and future HMR work must document which modules can be safely hot-swapped. Use `fluo dev --raw-watch` or `FLUO_DEV_RAW_WATCH=1` when you need the runtime-native Node watcher for debugging. Generated Bun/Deno/Workers projects delegate watch/reload behavior to `bun --watch`, `deno run --watch`, or `wrangler dev` by default; use `fluo dev --runner fluo` or `FLUO_DEV_RUNNER=fluo` when those projects should return to the fluo-owned restart runner, and use `FLUO_DEV_WATCH_IGNORE=path,pattern` to add extra ignored paths for that runner.
+For generated Node.js application projects, `fluo dev` runs through a fluo-owned restart boundary by default. The runner watches source and common config inputs, debounces atomic-save bursts, hashes file content before restarting, loads `.env` for each Node app child process it spawns, and ignores noisy output/cache paths such as `node_modules`, `dist`, `.git`, `.fluo`, coverage, cache folders, and editor swap files. Pressing Ctrl+S without changing file content should not restart the app. Planned restarts and terminal shutdown first send `SIGTERM` to the current app child, then force-kill it after a bounded grace period so a non-cooperative child cannot hang the restart supervisor indefinitely. On terminal app child exit or crash outside a planned restart, the runner closes watchers, clears the pending restart timer and paths, unregisters its `SIGINT`/`SIGTERM` handlers, and exits with the child terminal code. A terminal error from either the primary recursive watcher or a fallback directory watcher, a required source target that is missing or inaccessible before watcher registration, or an unavailable required fallback source watcher after recursive watching is unavailable follows that same cleanup path. This covers total fallback acquisition failure, partial failure after sibling watchers are acquired, and failure for a directory discovered while the fallback watcher is running; the runner terminates the current app child within the existing bound and exits with code `1` instead of leaving the child or sibling watchers running. This is full-process restart-on-watch, not module-level HMR; config watch reloads are a separate in-process config concern, and future HMR work must document which modules can be safely hot-swapped. Use `fluo dev --raw-watch` or `FLUO_DEV_RAW_WATCH=1` when you need the runtime-native Node watcher for debugging. Generated Bun/Deno/Workers projects delegate watch/reload behavior to `bun --watch`, `deno run --watch --allow-env --allow-net src/main.ts`, or `wrangler dev` by default; the Deno command preserves access to every application-owned environment key consumed through `Deno.env.toObject()`. Use `fluo dev --runner fluo` or `FLUO_DEV_RUNNER=fluo` when those projects should return to the fluo-owned restart runner, and use `FLUO_DEV_WATCH_IGNORE=path,pattern` to add extra ignored paths for that runner.
 
 `fluo new` supports Node.js + Fastify, Express, and raw Node.js HTTP application starters on the same Node-oriented install/build flow:
 
@@ -99,6 +128,29 @@ fluo new my-deno-app --shape application --transport http --runtime deno --platf
 fluo new my-worker-app --shape application --transport http --runtime cloudflare-workers --platform cloudflare-workers
 ```
 
+Select the official HTTP-first React SSR + Vite application with the named starter flag:
+
+```bash
+fluo new my-react-app --starter react-vite-ssr
+```
+
+This starter fixes the schema to Node.js + Fastify HTTP. Run `pnpm dev`, open
+`/products/sku-42?preview=true`, and edit `src/page.tsx`; page UI no longer needs to carry Vite assets,
+the document shell, or the server/client route snapshot wiring. The explicit `@Router(...)` /
+`@Path(...)` handler in `src/app.ts` returns that page as one `ReactElement`, so the existing HTTP
+dispatcher remains authoritative.
+
+Generated application wiring stays visible instead of becoming a framework abstraction:
+`src/entry-server.tsx` owns the replaceable `ReactPageRenderer` and `ReactServerEntry` creation,
+`src/react-app.tsx` shares one document and `ReactClientRouterProvider` composition between server and
+client, `src/entry-client.tsx` calls `hydrateRoot(...)`, and `src/main.ts` uses
+`src/load-manifest.ts` to load the generated Vite manifest before `@fluojs/react/vite` parses it.
+Missing build output, incompatible entry selectors, and hydration mismatches identify those exact
+application files and the lifecycle command to rerun. Generated `Link` output remains a real anchor
+and `router.push(...)` performs full-document navigation through the HTTP dispatcher. The starter
+intentionally excludes RSC, Server Functions, file routing, a client route table, SPA document
+swapping, prefetch, and a data cache.
+
 `fluo new` also exposes microservice starter paths. TCP is the default when you omit `--transport`, and the starter matrix includes runnable Redis Streams, NATS, Kafka, RabbitMQ, MQTT, and gRPC variants with transport-specific dependencies, env templates, and entrypoints:
 
 ```bash
@@ -121,7 +173,7 @@ The starter matrix also includes a mixed single-package starter: one Fastify HTT
 fluo new my-mixed-app --shape mixed --transport tcp --runtime node --platform fastify
 ```
 
-When `fluo new` runs in an interactive TTY, the wizard uses the same flags/config model. It asks for the project name, shape-first branch (`application` -> runtime + HTTP platform, `microservice` -> transport), the maintained tooling preset, package-manager choice, whether to install dependencies immediately, and whether to initialize a git repository. Non-interactive flags and programmatic `runNewCommand(...)` calls use the same resolved defaults.
+When `fluo new` runs in an interactive TTY, the wizard uses the same flags/config model. It first offers the standard backend and React SSR + Vite named starters. The standard branch then asks for the shape-first path (`application` -> runtime + HTTP platform, `microservice` -> transport); the React branch uses its fixed Node.js + Fastify HTTP contract. Both continue with the maintained tooling preset, package-manager choice, dependency installation, and git initialization. Non-interactive flags and programmatic `runNewCommand(...)` calls use the same resolved defaults.
 
 By default, `fluo new my-app` writes to `./my-app`. Use `--target-directory <path>` when the project name and destination path should differ, or when automation should write to an explicit directory:
 
@@ -139,13 +191,14 @@ Use `--print-plan` when you want to preview the fully resolved starter without s
 
 ```bash
 fluo new my-app --shape application --runtime node --platform fastify --print-plan
+fluo new my-react-app --starter react-vite-ssr --print-plan
 fluo new my-service --shape microservice --transport tcp --print-plan
 fluo new my-mixed-app --shape mixed --print-plan
 ```
 
-Plan preview mode resolves the same project name, shape, runtime, platform, transport, tooling preset, package manager, install choice, and git choice as a real scaffold. It prints the selected starter recipe and dependency sets, then exits without creating files, installing dependencies, or initializing a git repository.
+Plan preview mode resolves the same named starter, project name, shape, runtime, platform, transport, tooling preset, package manager, install choice, and git choice as a real scaffold. It prints both the selected starter and recipe plus their dependency sets, then exits without creating files, installing dependencies, or initializing a git repository.
 
-For a docs-level table that separates the shipped starter matrix (Node.js Fastify/Express/raw Node.js HTTP, Bun, Deno, Cloudflare Workers, TCP/Redis Streams/NATS/Kafka/RabbitMQ/MQTT/gRPC microservices, plus mixed) from the remaining broader adapter ecosystem, see the [fluo new support matrix](../../docs/reference/fluo-new-support-matrix.md). Package-level integrations such as `@fluojs/redis` remain part of the broader ecosystem, but they are not extra `fluo new --transport` starter flags.
+For a docs-level table that separates the shipped starter matrix (standard Node.js Fastify/Express/raw Node.js HTTP, React SSR + Vite on Node.js + Fastify, Bun, Deno, Cloudflare Workers, TCP/Redis Streams/NATS/Kafka/RabbitMQ/MQTT/gRPC microservices, plus mixed) from the remaining broader adapter ecosystem, see the [fluo new support matrix](../../docs/reference/fluo-new-support-matrix.md). Package-level integrations such as `@fluojs/redis` remain part of the broader ecosystem, but they are not extra `fluo new --transport` starter flags.
 
 ### 2. Generate a feature
 Generate a feature slice; some schematics auto-register in the module, while others are files-only and must be wired manually.
@@ -209,14 +262,14 @@ fluo dev --studio --dry-run
 
 The CLI starts a local Studio sidecar, prints a tokenized URL, keeps restart lifecycle events flowing through the sidecar, and injects an explicit Studio config into the Node app child before the app imports `@fluojs/runtime`. Studio live mode requires the fluo-owned Node restart runner; `fluo dev --studio` rejects `--raw-watch`, `--runner native`, and `FLUO_DEV_RUNNER=native` so lifecycle events cannot be split from the CLI restart boundary. The sidecar serves the packaged `@fluojs/studio/viewer` React app when that optional package is installed. Runtime package source never reads `process.env` directly; it publishes live graph/routes/request/timing/diagnostic events only when CLI-injected Studio config is present.
 
-Security defaults are local-only: the sidecar binds `127.0.0.1`, runtime ingestion and browser state/SSE APIs require generated tokens, CORS is not enabled by default, and request bodies are not captured by default. The sidecar settles ingestion requests with a bounded error completion when a local client closes the socket after sending only a partial request body, so a malformed local client cannot hang sidecar work indefinitely.
+Security defaults are local-only: the sidecar binds `127.0.0.1`, runtime ingestion and browser state/SSE APIs require generated tokens, CORS is not enabled by default, and request bodies are not captured by default. The sidecar settles ingestion requests with a bounded error completion when a local client closes the socket after sending only a partial request body, so a malformed local client cannot hang sidecar work indefinitely. When `StudioSidecar.close()` starts while an authenticated ingestion body is still incomplete, the sidecar closes only its active ingestion sockets, ends tracked SSE responses through the existing close path, and shares one deterministic teardown across repeated or concurrent close calls. Completed ordinary requests are not part of that active-ingestion ownership set, and a client that remains open with a partial body cannot keep CLI shutdown pending indefinitely.
 
 Runtime support for the MVP is explicit:
 
 | Runtime target | `fluo dev --studio` status |
 | --- | --- |
 | Node dev runner | Full support target. |
-| Bun | Not enabled for this MVP; `fluo dev --studio` rejects Bun projects until a dedicated bridge is implemented and verified. |
+| Bun | Not enabled for this MVP; `fluo dev --studio` rejects Bun projects until a dedicated bridge is implemented and verified. Export Studio-compatible static artifacts with `fluo inspect <module-path> --json --output <path>` or `fluo inspect <module-path> --report --output <path>` instead. |
 | Deno | Not enabled for this MVP; `fluo dev --studio` rejects Deno projects until a dedicated bridge is implemented and verified. |
 | Cloudflare Workers | Unsupported for this MVP unless a worker bridge is added and tested. |
 
@@ -238,7 +291,7 @@ FLUO_VERBOSE=1 fluo dev
 fluo build --reporter silent
 ```
 
-Runtime application logs are configured separately through `ApplicationLogger`, for example `createConsoleApplicationLogger({ mode: 'minimal', level: 'warn' })` or `createJsonApplicationLogger()` from `@fluojs/runtime/node`.
+Runtime application logs are configured separately through `ApplicationLogger`, for example `createConsoleApplicationLogger({ mode: 'minimal', level: 'warn' })` or `createJsonApplicationLogger()` from `@fluojs/platform-nodejs`.
 
 Use `fluo add <package>` for first-party package installation shortcuts and `fluo upgrade` for CLI/latest-version and migration guidance:
 
@@ -258,17 +311,28 @@ fluo migrate ./src --json
 # Apply transformations
 fluo migrate ./src --apply
 fluo migrate ./src --apply --json
-fluo migrate ./src --only imports,inject-params
-fluo migrate ./src --skip tests
+fluo migrate ./src --only imports,injectable
+fluo migrate ./src --skip testing
 ```
 
+The canonical `--only` and `--skip` tokens are `imports`, `inject-params`, `scope`, `bootstrap`, `tests`, and `tsconfig`. The legacy `injectable` and `testing` tokens remain accepted aliases for `inject-params` and `tests`.
+
 Use `--json` when CI jobs, dashboards, or migration reports need a stable machine-readable result. Human output remains the default. JSON mode writes only the structured report to stdout on success, while parser errors and invalid flag combinations still write their message to stderr and return exit code `1` without partial JSON output. The report includes `mode` (`dry-run` or `apply`), `dryRun`, `apply`, enabled `transforms`, `scannedFiles`, `changedFiles`, aggregate `warningCount`, and per-file metadata with `filePath`, `changed`, `appliedTransforms`, `warningCount`, and warnings including category labels and source line numbers.
 
 Review every warning before rerunning with `--apply`. Warnings are manual follow-up items rather than permission for an automatic rewrite to be accepted blindly; use the [NestJS migration guide](../../docs/getting-started/migrate-from-nestjs.md) as the post-codemod checklist for each warning category.
 
+Adapter-independent transforms (`imports`, `injectable`, `scope`, `testing`, and `tsconfig`) run without an HTTP adapter. Bootstrap rewrites never infer a platform: without a selected platform, the codemod retains `NestFactory.create(AppModule)` and its `listen(port)` call and emits a required adapter-selection warning. The only automatic bootstrap rewrite requires explicit `--platform express` and exactly one numeric-literal single-argument `app.listen(port)`. Host, callback, string, environment-derived, and multiple-`listen` forms remain untouched with a warning for manual migration. Install `@fluojs/platform-express` and `express` before compiling the migrated application:
+
+```bash
+fluo migrate ./src --apply --platform express
+
+# Leave bootstrap unchanged while applying only adapter-independent transforms
+fluo migrate ./src --apply --only imports,injectable,scope,testing,tsconfig
+```
+
 **Key Transformations:**
 - Rewrites imports from `@nestjs/common` to `@fluojs/core` or `@fluojs/http`.
-- Rewrites bootstrap patterns and folds supported `listen(port)` calls into fluo runtime startup conventions.
+- Rewrites bootstrap patterns only after explicit platform selection and folds supported `listen(port)` calls into fluo runtime startup conventions.
 - Migrates constructor parameter `@Inject(...)` usage into fluo-compatible dependency declarations.
 - Removes `@Injectable()` and maps scopes to `@Scope()`.
 - Migrates test templates toward `@fluojs/testing` helpers where the codemod can do so safely.
@@ -282,7 +346,7 @@ Export your application structure and troubleshoot initialization issues without
 fluo inspect ./src/app.module.ts --mermaid
 
 # Export snapshot for @fluojs/studio
-fluo inspect ./src/app.module.ts --json > snapshot.json
+fluo inspect ./src/app.module.ts --format json > snapshot.json
 
 # Write the same JSON snapshot to a CI artifact path without shell redirection
 fluo inspect ./src/app.module.ts --json --output artifacts/inspect-snapshot.json
@@ -297,7 +361,16 @@ fluo inspect ./src/app.module.ts --report --output artifacts/inspect-report.json
 fluo inspect ./src/app.module.ts --export AdminModule --json
 ```
 
-The runtime produces the inspection snapshot. `fluo inspect` accepts generated TypeScript source modules such as `./src/app.ts` or `./src/app.module.ts` through an explicit TypeScript loader boundary, while existing `.js` and `.mjs` module paths continue to load through native Node.js ESM. The CLI owns inspect orchestration, JSON serialization, report wrapping, and `--output <path>` artifact writes; Studio owns snapshot parsing, filtering, connection inspection, viewer rendering, and Mermaid graph semantics. `fluo inspect` serializes the snapshot as JSON by default when no output mode flag is provided, and `fluo inspect --mermaid` delegates snapshot-to-Mermaid rendering to the optional `@fluojs/studio` contract. `--export <name>` selects the module export to bootstrap and defaults to `AppModule`; `--timing` records bootstrap timing diagnostics next to the JSON snapshot output, including when `--timing` is provided without an explicit `--json` flag, and `--report` wraps the runtime-produced snapshot with a stable summary for CI/support triage. `--timing` cannot be combined with Mermaid output. `--output <path>` writes the selected inspect payload to an explicit artifact path instead of stdout; it does not make the inspected application writable or change module graph state beyond the normal bootstrap/close cycle. Install Studio in the project that runs the command when you need Mermaid output:
+`--format json` is explicitly equivalent to `--json`: either writes exactly one JSON document to stdout while runtime diagnostics go to stderr, and any other `--format` value is rejected.
+
+The runtime produces the inspection snapshot. `fluo inspect` accepts generated TypeScript source modules such as `./src/app.ts` or `./src/app.module.ts` through an explicit TypeScript loader boundary, while existing `.js` and `.mjs` module paths continue to load through native Node.js ESM. The CLI bootstraps an adapterless application so the authoritative HTTP dispatcher descriptors are available, then adds the runtime-owned `routes` projection to JSON, timing envelopes, and report snapshots. The CLI owns inspect orchestration, JSON serialization, report wrapping, and `--output <path>` artifact writes; Studio owns snapshot parsing, filtering, connection inspection, viewer rendering, and Mermaid graph semantics. `fluo inspect` serializes the snapshot as JSON by default when no output mode flag is provided, and `fluo inspect --mermaid` delegates snapshot-to-Mermaid rendering to the optional `@fluojs/studio` contract. `--export <name>` selects the module export to bootstrap and defaults to `AppModule`; `--timing` records bootstrap timing diagnostics next to the JSON snapshot output, including when `--timing` is provided without an explicit `--json` flag, and `--report` wraps the runtime-produced snapshot with a stable summary for CI/support triage. `--timing` cannot be combined with Mermaid output. `--output <path>` writes the selected inspect payload to an explicit artifact path instead of stdout; it does not make the inspected application writable or change module graph state beyond the normal bootstrap/close cycle.
+
+Each `routes[]` entry contains `id`, `kind`, `method`, effective `path`, optional effective `version`,
+parameter names in `params`, and the originating `module`, `controller`, and `handler`. React
+`@Path(...)` handlers use `kind: 'react-page'`; ordinary HTTP handlers use `kind: 'http'`. The
+artifact never contains parameter values, request bodies, cookies, headers, or query values, and the
+route projection does not participate in matching, conflict detection, or dispatch. Install Studio
+in the project that runs the command when you need Mermaid output:
 
 ```bash
 pnpm add -D @fluojs/studio
@@ -305,6 +378,79 @@ pnpm add -D @fluojs/studio
 
 If Studio is missing, CI and other non-interactive runs fail fast with install guidance instead of prompting or running a package manager. Interactive runs may ask whether you want to install Studio, but `fluo inspect` does not run installs unless an explicit install flow is implemented and approved.
 
+### React Page Type Generation
+
+Generate application-owned, path-only React page types and absolute href builders from the
+bootstrap-resolved route catalog:
+
+```bash
+fluo typegen ./src/app.ts --output ./src/generated/react-pages.ts
+fluo typegen ./src/admin.ts --export AdminModule --output ./src/generated/admin-pages.ts
+fluo typegen ./src/app.ts --output ./src/generated/react-pages.ts --check
+fluo typegen ./src/app.ts --output ./src/generated/react-pages.ts --watch
+```
+
+`--export` defaults to `AppModule`. The command loads TypeScript source through the CLI loader,
+bootstraps the application, reads `app.dispatcher.describeRoutes()`, calls
+`createReactPageCatalog(...)` and `generateReactPageTypes(...)`, then closes the application. Output
+paths are resolved from the current working directory. A missing file is reported as `CREATE`, stale
+content as `UPDATE`, and byte-identical content as `UNCHANGED`. Writes publish one complete temporary
+file with an atomic rename, and `UNCHANGED` never rewrites the target.
+
+Default generation evaluates the application and matching tooling namespaces in one short-lived
+child process, waits for that process to exit, and only then checks or publishes the result. Repeated
+watch generations therefore do not retain application module graphs or TypeScript loader resources
+in the watcher process. Programmatic callers that provide
+`TypegenCommandRuntimeOptions.loadReactTypegenModules` intentionally keep generation in the caller
+process; the returned namespaces remain authoritative for TypeScript, `.js`, and `.mjs` inputs.
+
+`--check` performs the same authoritative bootstrap and generation but never writes the target. It
+compares exact bytes and reports one stable status. `UNCHANGED` goes to stdout with exit code `0`;
+`MISSING`, `STALE`, `MALFORMED`, and `UNSUPPORTED_VERSION` go to stderr with exit codes `2`, `3`, `4`,
+and `5`. A current-version target must be one complete canonical generated body: syntax or structural
+corruption is `MALFORMED`, while a complete artifact from an older catalog is `STALE`. Argument,
+bootstrap, generation, filesystem, and other command failures use exit code `1`. The root package
+exports `TYPEGEN_EXIT_CODES` for programmatic callers.
+
+`--watch` is the bounded development integration. The CLI installs the recursive application-module
+watcher before startup generation. It prints `WATCHING <directory>` only after that generation and
+one coalesced rerun for any changes observed while it ran have completed successfully. Filesystem
+bursts after readiness are coalesced for 100 ms, generations are serialized, and events for the
+output or its temporary files are ignored. Each generation evaluates a current application module
+graph, including changed native `.js` and `.mjs` dependencies, before the authoritative bootstrap.
+A regeneration failure prints `ERROR <output>: <message>`, preserves the last valid artifact, and
+waits for a later change. A watcher failure exits with code `1` after cleanup. Every source event
+received while a generation or its owned artifact commit is active invalidates that work; its output
+cannot publish before the coalesced successor completes. `SIGINT` and `SIGTERM` close the watcher,
+remove signal handlers, cancel the active owned generation (a child process or caller-process
+bootstrap), and abort its owned artifact commit before either can publish. Caller-process
+cancellation waits for asynchronous bootstrap and application close to settle before watch exits
+with code `0`; a child that does not exit after `SIGTERM` is force-killed after the bounded grace
+period.
+Files outside the module directory are intentionally outside this watch boundary; run the command
+again or choose a module path at the intended source root instead of expecting source scanning or a
+second route discovery system.
+
+The generated `reactPageRoutes` object keys routes by stable catalog `id`. Its dynamic `href(...)`,
+`link(...)`, `push(...)`, and `replace(...)` methods require all path params and URI-encode each value;
+static methods accept no params. Spread `route.link(params)` into the existing real-anchor `Link`, or
+pass the existing `ReactRouter` to `route.push(router, params)` / `route.replace(router, params)`:
+
+```tsx
+const productRoute = reactPageRoutes['GET /products/:productId ProductRouter show'];
+
+<Link {...productRoute.link({ productId })}>Product</Link>;
+productRoute.push(router, { productId });
+productRoute.replace(router, { productId });
+```
+
+These generated methods resolve to ordinary absolute href strings before the existing HTTP-first
+client APIs run. They do not add a runtime route table, matcher, relative-route model, or SPA
+navigation. Existing `href(...)`, `Link href`, and router string/`URL` calls remain supported.
+Versioned routes fail explicitly because the catalog cannot distinguish URI versioning from header,
+media-type, or custom version strategies. See the
+[@fluojs/react path-only typegen contract](../react/README.md#path-only-page-type-generation).
+
 ## Public API
 
 The package can be used programmatically to trigger CLI actions from within other tools.
@@ -325,10 +471,14 @@ The package can be used programmatically to trigger CLI actions from within othe
 | `GeneratorKind` | Union type of all supported generator types (e.g., `'controller'`, `'service'`). |
 | `ModuleRegistration` | Type describing controller, provider, or middleware module wiring metadata from generator runs. |
 | `inspectUsage()` | Returns the current `fluo inspect` usage text for help surfaces and tests. |
-| `runInspectCommand(argv, options?)` | Programmatic access to inspect orchestration, JSON/report emission, and Studio Mermaid delegation. |
+| `runInspectCommand(argv, options?)` | Programmatic access to inspect orchestration, compiled route JSON/report emission, and Studio Mermaid delegation. |
 | `InspectCommandRuntimeOptions` | Type for `runInspectCommand(...)` and `runCli(...)` inspect runtime overrides such as cwd, streams, prompts, and Studio renderer loading. |
+| `typegenUsage()` | Returns the current `fluo typegen` usage text for help surfaces and tests. |
+| `TYPEGEN_EXIT_CODES` | Stable `SUCCESS`, `ERROR`, `MISSING`, `STALE`, `MALFORMED`, and `UNSUPPORTED_VERSION` process codes used by typegen automation. |
+| `runTypegenCommand(argv, options?)` | Programmatic access to bootstrap-resolved React page generation, non-mutating checks, and bounded watch mode. |
+| `TypegenCommandRuntimeOptions` | Type for `runTypegenCommand(...)` and `runCli(...)` typegen runtime overrides such as cwd, streams, and tooling module loading. Supplying `loadReactTypegenModules` selects caller-process generation with those namespaces; omitting it uses short-lived generation children. |
 
-Programmatic entry points preserve caller process ownership. `runCli(...)`, `runNewCommand(...)`, and `runInspectCommand(...)` return numeric exit codes instead of calling `process.exit(...)`; prompt cancellation resolves as exit code `0` through the command runner, and setup actions such as dependency installation or git initialization only run when the resolved `fluo new` options request them. `runGenerateCommand(...)` returns a structured `GenerateResult`; pass `dryRun: true` to preview generated file and module-wiring actions without writing files. Caller-supplied prompt hooks can throw `CliPromptCancelledError` from the public package entrypoint to express normal cancellation without depending on CLI-internal files.
+Programmatic entry points preserve caller process ownership. `runCli(...)`, `runNewCommand(...)`, `runInspectCommand(...)`, and `runTypegenCommand(...)` return numeric exit codes instead of calling `process.exit(...)`; typegen callers can compare those results with `TYPEGEN_EXIT_CODES`. Prompt cancellation resolves as exit code `0` through the command runner, and setup actions such as dependency installation or git initialization only run when the resolved `fluo new` options request them. `runGenerateCommand(...)` returns a structured `GenerateResult`; pass `dryRun: true` to preview generated file and module-wiring actions without writing files. Caller-supplied prompt hooks can throw `CliPromptCancelledError` from the public package entrypoint to express normal cancellation without depending on CLI-internal files.
 
 ## Related Packages
 
@@ -343,6 +493,7 @@ Programmatic entry points preserve caller process ownership. `runCli(...)`, `run
 - [cli.ts](./src/cli.ts) - Command dispatcher and argument parsing.
 - [commands/new.ts](./src/commands/new.ts) - Project scaffolding implementation.
 - [commands/inspect.ts](./src/commands/inspect.ts) - Runtime inspection export modes and Studio delegation.
+- [commands/typegen.ts](./src/commands/typegen.ts) - React page catalog bootstrap and deterministic path-only artifact writes.
 - [commands/migrate.ts](./src/commands/migrate.ts) - Decorator codemods, JSON reporting, and transform filters.
 - [commands/package-workflow.ts](./src/commands/package-workflow.ts) - `fluo add` and `fluo upgrade` workflows.
 - [commands/scripts.ts](./src/commands/scripts.ts) - `dev`, `build`, and `start` lifecycle command boundaries.

package/dist/cli.d.ts

@@ -1,5 +1,6 @@
-import { type InspectCommandRuntimeOptions } from './commands/inspect.js';
-import { type NewCommandRuntimeOptions } from './commands/new.js';
+import type { InspectCommandRuntimeOptions } from './commands/inspect.js';
+import type { NewCommandRuntimeOptions } from './commands/new.js';
+import type { TypegenCommandRuntimeOptions } from './commands/typegen.js';
 import type { startStudioSidecar } from './studio/sidecar.js';
 import { type CliUpdateCheckRuntimeOptions } from './update-check.js';
 type CliStream = {
@@ -50,8 +51,8 @@ export interface CliRuntimeOptions {
  *
  * @param argv Argument vector to execute. Defaults to the current process arguments without the node/bin prefix.
  * @param runtime Optional runtime overrides shared by the top-level dispatcher and delegated commands.
- * @returns `0` when the command completes successfully, otherwise `1` after writing the error message to `stderr`.
+ * @returns `0` when the command completes successfully, otherwise the delegated command exit code.
  */
-export declare function runCli(argv?: string[], runtime?: CliRuntimeOptions & NewCommandRuntimeOptions & InspectCommandRuntimeOptions): Promise<number>;
+export declare function runCli(argv?: string[], runtime?: CliRuntimeOptions & NewCommandRuntimeOptions & InspectCommandRuntimeOptions & TypegenCommandRuntimeOptions): Promise<number>;
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,4BAA4B,EAAqB,MAAM,uBAAuB,CAAC;AAE7F,OAAO,EAAE,KAAK,wBAAwB,EAAiB,MAAM,mBAAmB,CAAC;AAMjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,OAAO,EAAE,KAAK,4BAA4B,EAA6C,MAAM,mBAAmB,CAAC;AAGjH,KAAK,SAAS,GAAG;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC,CAAC;AAEF,KAAK,iBAAiB,GAAG;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,aAAa,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC;IACrF,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;QAAC,MAAM,CAAC,EAAE,SAAS,CAAC;QAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,SAAS,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACzL,kBAAkB,CAAC,EAAE,OAAO,kBAAkB,CAAC;IAC/C,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,WAAW,CAAC,EAAE,KAAK,GAAG,4BAA4B,CAAC;CACpD;AA4ZD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,MAAM,CAC1B,IAAI,WAAwB,EAC5B,OAAO,GAAE,iBAAiB,GAAG,wBAAwB,GAAG,4BAAiC,GACxF,OAAO,CAAC,MAAM,CAAC,CAuNjB"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AAC1E,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AAG1E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,OAAO,EAAE,KAAK,4BAA4B,EAA6C,MAAM,mBAAmB,CAAC;AAGjH,KAAK,SAAS,GAAG;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC,CAAC;AAEF,KAAK,iBAAiB,GAAG;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,aAAa,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC;IACrF,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;QAAC,MAAM,CAAC,EAAE,SAAS,CAAC;QAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,SAAS,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACzL,kBAAkB,CAAC,EAAE,OAAO,kBAAkB,CAAC;IAC/C,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,WAAW,CAAC,EAAE,KAAK,GAAG,4BAA4B,CAAC;CACpD;AAqaD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,MAAM,CAC1B,IAAI,WAAwB,EAC5B,OAAO,GAAE,iBAAiB,GAAG,wBAAwB,GAAG,4BAA4B,GAAG,4BAAiC,GACvH,OAAO,CAAC,MAAM,CAAC,CA6PjB"}