@fluojs/cli 1.0.0 → 1.0.2

package/README.ko.md

@@ -48,7 +48,7 @@ fluo -v
 
 `fluo`가 interactive TTY에서 실행되면 로컬 캐시를 사용해 공개 npm `latest` dist-tag의 `@fluojs/cli` 버전을 확인하므로 매 invocation마다 registry를 호출하지 않습니다. 더 새로운 버전이 있으면 CLI가 설치 여부를 묻습니다. 거절하면 현재 설치된 버전으로 기존 명령을 계속 실행하고, 승인하면 현재 설치를 소유한 것으로 보이는 package manager의 전역 업데이트 명령(`npm install -g`, `pnpm add -g`, `bun add -g`, `yarn global add`)을 사용한 뒤 같은 인자로 업데이트된 `fluo` 바이너리를 다시 시작합니다. 설치 도구를 추론할 수 없으면 Node.js 기본 전역 설치 경로를 소유하는 npm 기준으로 `npm install -g @fluojs/cli@<latest>`를 fallback으로 사용합니다.
 
-`fluo new`와 alias인 `fluo create`는 일반 update-check cache가 아직 fresh하더라도 스캐폴딩 전에 interactive 최신 버전 확인을 새로 시도합니다. 이를 통해 첫 프로젝트 생성 경로가 방금 배포된 starter 동작과 더 잘 맞춰지며, `fluo dev`, `fluo build`, `fluo generate`, `fluo inspect` 같은 일상 명령은 기존처럼 일반 TTL이 만료될 때까지 cached latest-version 결과를 재사용합니다.
+`fluo new`와 alias인 `fluo create`는 일반 update-check cache가 아직 fresh하더라도 스캐폴딩 전에 interactive 최신 버전 확인을 새로 시도합니다. 이를 통해 첫 프로젝트 생성 경로가 방금 배포된 starter 동작과 더 잘 맞춰지며, `fluo dev`, `fluo build`, `fluo generate`, `fluo inspect` 같은 일상 명령은 기존처럼 일반 TTL이 만료될 때까지 cached latest-version 결과를 재사용합니다. 순수 help 및 version inspection 경로(`fluo help <command>`, `<command> --help`, `fluo version`, `fluo --version`, `fluo -v`)는 interactive update check를 실행하지 않고 즉시 출력합니다.
 
 업데이트 확인은 CI, non-TTY 출력, npm-script context, 업데이트 후 재실행 context, registry/network 실패, 명시적 opt-out 경로에서는 건너뜁니다. 한 번만 끄려면 `--no-update-check`(또는 compatibility alias `--no-update-notifier`)를 사용하고, 자동화에서 절대 prompt가 뜨면 안 되는 경우에는 `FLUO_NO_UPDATE_CHECK=1`을 설정하세요.
 
@@ -74,11 +74,13 @@ pnpm dev
 
 생성된 Node.js `dev`, `build`, `start` package script는 각각 `fluo dev`, `fluo build`, `fluo start`로 위임합니다. CLI가 Node 지향 lifecycle 명령을 소유하고 local toolchain binary를 실행할 때 project-local `node_modules/.bin`을 앞에 붙이며, 호출자가 명시하지 않은 경우 `dev`는 `NODE_ENV=development`, `build`/`start`는 `NODE_ENV=production`을 기본값으로 사용합니다. Bun, Deno, Workers의 생성된 `dev` script는 같은 `fluo dev` 추상성을 유지하되 Node-supervised dev process를 줄이도록 Bun, Deno, Wrangler의 native watch loop를 기본값으로 사용합니다. fluo가 소유한 restart boundary의 debounce/hash reporter 계약이 필요하면 `fluo dev --runner fluo` 또는 `FLUO_DEV_RUNNER=fluo`를 사용하세요. production/deployment script는 runtime-native입니다. Bun은 `bun build ./src/main.ts --outdir ./dist --target bun`과 `bun dist/main.js`를 사용하고, Deno는 `deno compile --allow-env --allow-net --output dist/app src/main.ts`와 `./dist/app`을 사용하며, Workers는 `start` 대신 Wrangler `preview`/`deploy` script를 노출합니다. 기본적으로 `fluo dev`와 `fluo start`는 CLI가 process boundary를 소유하는 경로에서 앱 로그만(애플리케이션 stdout/stderr) 표시합니다. Interactive terminal에서 fluo lifecycle status와 `app │` prefix가 붙은 애플리케이션 출력이 필요하면 `--reporter pretty`를 사용하고, 런타임/도구 watcher 원본 출력이 필요하면 `--verbose`(또는 `FLUO_VERBOSE=1`)를 사용하세요.
 
+생성된 starter는 프로젝트를 만든 generator CLI package version을 기준으로 `@fluojs/cli` `devDependency`를 설정합니다. 따라서 `pnpm dev`, `pnpm build`, `pnpm start` 같은 lifecycle script는 오래된 hard-coded range가 아니라 starter를 스캐폴딩한 CLI 동작과 같은 기준을 사용합니다.
+
 생성된 non-Deno starter의 `vite.config.ts`는 `@fluojs/vite`에서 `fluoDecoratorsPlugin()`을 import합니다. 따라서 decorator transform 업데이트는 각 신규 프로젝트에 inline 복사되는 대신 유지보수되는 Vite 패키지를 통해 전달됩니다.
 
 생성된 non-Deno HTTP starter는 TDD-first Vitest 레이아웃을 사용합니다. 빠른 greeting unit test와 `greeting.slice.test.ts`는 `src/greeting/` 아래에 colocate하고, 앱 dispatch test는 `src/app.test.ts`에 유지하며, 기본 e2e 스타일 request-pipeline test는 `createTestApp({ rootModule })`와 `app.request(...).send()`를 사용해 `test/app.e2e.test.ts`에 둡니다. 생성된 `vitest.config.ts`는 `src/**/*.test.ts`와 `test/**/*.test.ts`를 모두 포함하고, package script는 `test`, `test:watch`, `test:cov`, `test:e2e`를 노출합니다. 기존 `src/app.e2e.test.ts` 테스트는 request helper를 바꾸지 않고 `test/app.e2e.test.ts`로 이동할 수 있습니다.
 
-생성된 Node.js 애플리케이션 프로젝트에서 `fluo dev`는 기본적으로 fluo가 소유한 restart boundary를 거칩니다. 이 runner는 source와 주요 config 입력을 watch하고, atomic-save event burst를 debounce하며, restart 전에 파일 content hash를 비교하고, spawn하는 각 Node 앱 child process마다 `.env`를 로드하며, `node_modules`, `dist`, `.git`, `.fluo`, coverage, cache 폴더, editor swap file 같은 noisy output/cache 경로를 무시합니다. 파일 내용이 바뀌지 않은 Ctrl+S 저장은 앱을 재시작하지 않아야 합니다. 계획된 restart가 아닌 terminal 앱 child exit 또는 crash가 발생하면 runner는 watcher를 닫고, pending restart timer와 path를 비우며, `SIGINT`/`SIGTERM` handler를 등록 해제하고, child의 terminal code로 종료합니다. 이 동작은 full-process restart-on-watch이며 module-level HMR이 아닙니다. Config watch reload는 별도의 in-process config 관심사이고, 향후 HMR 작업은 어떤 모듈을 안전하게 hot-swap할 수 있는지 따로 문서화해야 합니다. 디버깅에 runtime-native Node watcher가 필요하면 `fluo dev --raw-watch` 또는 `FLUO_DEV_RAW_WATCH=1`을 사용하세요. 생성된 Bun/Deno/Workers 프로젝트는 기본적으로 watch/reload를 `bun --watch`, `deno run --watch`, `wrangler dev`에 위임합니다. 해당 프로젝트에서 fluo 소유 restart runner로 되돌리려면 `fluo dev --runner fluo` 또는 `FLUO_DEV_RUNNER=fluo`를 사용하고, 그 runner에 추가 ignore 경로가 필요하면 `FLUO_DEV_WATCH_IGNORE=path,pattern`으로 지정하세요.
+생성된 Node.js 애플리케이션 프로젝트에서 `fluo dev`는 기본적으로 fluo가 소유한 restart boundary를 거칩니다. 이 runner는 source와 주요 config 입력을 watch하고, atomic-save event burst를 debounce하며, restart 전에 파일 content hash를 비교하고, spawn하는 각 Node 앱 child process마다 `.env`를 로드하며, `node_modules`, `dist`, `.git`, `.fluo`, coverage, cache 폴더, editor swap file 같은 noisy output/cache 경로를 무시합니다. 파일 내용이 바뀌지 않은 Ctrl+S 저장은 앱을 재시작하지 않아야 합니다. 계획된 restart와 terminal shutdown은 현재 앱 child에 먼저 `SIGTERM`을 보내고, 제한된 grace period 뒤에도 종료되지 않으면 force-kill하므로 비협조적인 child가 restart supervisor를 무기한 멈추게 할 수 없습니다. 계획된 restart가 아닌 terminal 앱 child exit 또는 crash가 발생하면 runner는 watcher를 닫고, pending restart timer와 path를 비우며, `SIGINT`/`SIGTERM` handler를 등록 해제하고, child의 terminal code로 종료합니다. 이 동작은 full-process restart-on-watch이며 module-level HMR이 아닙니다. Config watch reload는 별도의 in-process config 관심사이고, 향후 HMR 작업은 어떤 모듈을 안전하게 hot-swap할 수 있는지 따로 문서화해야 합니다. 디버깅에 runtime-native Node watcher가 필요하면 `fluo dev --raw-watch` 또는 `FLUO_DEV_RAW_WATCH=1`을 사용하세요. 생성된 Bun/Deno/Workers 프로젝트는 기본적으로 watch/reload를 `bun --watch`, `deno run --watch`, `wrangler dev`에 위임합니다. 해당 프로젝트에서 fluo 소유 restart runner로 되돌리려면 `fluo dev --runner fluo` 또는 `FLUO_DEV_RUNNER=fluo`를 사용하고, 그 runner에 추가 ignore 경로가 필요하면 `FLUO_DEV_WATCH_IGNORE=path,pattern`으로 지정하세요.
 
 `fluo new`는 같은 Node 기반 설치/빌드 흐름 위에서 Node.js + Fastify, Express, raw Node.js HTTP 애플리케이션 스타터를 제공합니다.
 
@@ -110,7 +112,7 @@ fluo new my-grpc-service --shape microservice --transport grpc --runtime node --
 
 지원되는 `--shape microservice --transport` 스타터 값은 정확히 `tcp`, `redis-streams`, `nats`, `kafka`, `rabbitmq`, `mqtt`, `grpc`입니다. 유지보수되는 Redis 기반 스타터가 필요하면 `redis-streams`를 사용하고, 더 넓은 Redis 통합 패턴이 필요하면 스캐폴딩 후 `@fluojs/redis`를 수동으로 추가하세요.
 
-NATS/Kafka/RabbitMQ 스타터 계약은 외부 broker와 caller-owned client library 의존성을 숨기지 않고 명시적으로 유지합니다. 생성된 프로젝트는 `src/app.ts`에서 `nats` + `JSONCodec()`, `kafkajs` producer/consumer collaborator, `amqplib` publisher/consumer collaborator를 직접 연결하므로, 기본 fluo 패키지가 그 의존성을 감춘 것처럼 가장하지 않는 runnable starter 계약이 됩니다.
+NATS/Kafka/RabbitMQ 스타터 계약은 외부 broker와 caller-owned client library 의존성을 숨기지 않고 명시적으로 유지합니다. 생성된 프로젝트는 `src/app.ts`에서 `nats` + `JSONCodec()`, `kafkajs` producer/consumer collaborator, `amqplib` publisher/consumer collaborator를 직접 연결하므로, 기본 fluo 패키지가 그 의존성을 감춘 것처럼 가장하지 않는 runnable starter 계약이 됩니다. 해당 broker client는 생성된 transport wrapper가 Fluo lifecycle에서 listen/send/emit을 시작할 때 lazy하게 생성합니다. 따라서 `fluo inspect`, 테스트, static tooling이 `src/app.ts`를 import하는 것만으로는 broker에 연결하거나 lifecycle이 teardown을 소유하기 전에 외부 리소스를 열지 않습니다.
 
 starter 매트릭스에는 mixed single-package starter도 포함됩니다. 하나의 Fastify HTTP 앱과 attached TCP microservice를 같은 생성 프로젝트 안에 함께 배치합니다.
 
@@ -153,7 +155,7 @@ fluo generate service users --dry-run
 
 `fluo generate module <name> --with-test`는 작성한 module을 `createTestingModule({ rootModule })`로 컴파일하는 `*.slice.test.ts`를 추가합니다. `fluo generate resource <name>`는 module, controller, service, repository, request DTO, response DTO, test를 포함하는 완전한 feature slice를 생성합니다. `--with-slice-test`를 추가하면 provider override와 service resolution을 보여 주는 resource-level slice test도 포함합니다. 생성된 resource module은 parent module에 자동으로 연결하지 않으므로, slice를 활성화할 준비가 되었을 때 직접 import하세요.
 
-`fluo generate e2e <name>`는 generated starter와 같은 app-level test 영역에 request-pipeline test를 두도록 `createTestApp({ rootModule: AppModule })`을 사용하는 `test/<name>.e2e.test.ts`를 작성합니다. 생성된 unit test는 직접 class 동작 검증에, slice test는 DI wiring과 override 검증에, e2e test는 virtual app을 통과하는 route, guard, interceptor, DTO validation, response writing 검증에 사용하세요.
+`fluo generate e2e <name>`는 generated starter와 같은 app-level test 영역에 request-pipeline test를 두도록 `createTestApp({ rootModule: AppModule })`을 사용하는 `test/<name>.e2e.test.ts`를 작성하고, 기본 starter root module인 `../src/app`에서 `AppModule`을 import합니다. 생성된 unit test는 직접 class 동작 검증에, slice test는 DI wiring과 override 검증에, e2e test는 virtual app을 통과하는 route, guard, interceptor, DTO validation, response writing 검증에 사용하세요.
 
 Request DTO 생성은 feature 디렉터리와 DTO 클래스 이름을 분리해서 받습니다. 따라서 `CreateUser`, `UpdateUser` 같은 여러 입력 계약을 같은 `src/users/` 슬라이스 안에 둘 수 있습니다.
 
@@ -248,7 +250,7 @@ fluo inspect ./src/app.module.ts --json > snapshot.json
 fluo inspect ./src/app.module.ts --json --output artifacts/inspect-snapshot.json
 
 # 런타임이 생산한 snapshot 옆에 bootstrap timing 포함하기
-fluo inspect ./src/app.module.ts --json --timing
+fluo inspect ./src/app.module.ts --timing
 
 # 요약, snapshot, diagnostics, timing을 포함한 support triage report 내보내기
 fluo inspect ./src/app.module.ts --report --output artifacts/inspect-report.json
@@ -257,7 +259,7 @@ fluo inspect ./src/app.module.ts --report --output artifacts/inspect-report.json
 fluo inspect ./src/app.module.ts --export AdminModule --json
 ```
 
-런타임이 inspection snapshot을 생산합니다. `fluo inspect`는 output mode flag가 없을 때 기본적으로 그 snapshot을 JSON으로 직렬화하고, `fluo inspect --mermaid`는 snapshot-to-Mermaid 렌더링을 선택적 `@fluojs/studio` 계약에 위임합니다. `--export <name>`은 bootstrap할 module export를 선택하며 기본값은 `AppModule`입니다. `--timing`은 JSON 출력에 bootstrap timing diagnostics를 기록하고, `--report`는 CI/support triage를 위해 런타임이 생산한 snapshot을 안정적인 요약과 함께 감쌉니다. `--timing`은 Mermaid 출력과 함께 사용할 수 없습니다. `--output <path>`는 선택한 inspect payload를 stdout 대신 명시적 artifact 경로에 씁니다. 이 동작은 검사 대상 애플리케이션을 writable하게 만들지 않으며, 일반 bootstrap/close cycle 외에 module graph state를 바꾸지 않습니다. Mermaid 출력이 필요하면 명령을 실행하는 프로젝트에 Studio를 설치하세요:
+런타임이 inspection snapshot을 생산합니다. `fluo inspect`는 `./src/app.ts` 또는 `./src/app.module.ts` 같은 생성된 TypeScript source module을 명시적 TypeScript loader boundary로 받아들이며, 기존 `.js`와 `.mjs` module path는 계속 Node.js native ESM으로 로드합니다. `fluo inspect`는 output mode flag가 없을 때 기본적으로 그 snapshot을 JSON으로 직렬화하고, `fluo inspect --mermaid`는 snapshot-to-Mermaid 렌더링을 선택적 `@fluojs/studio` 계약에 위임합니다. `--export <name>`은 bootstrap할 module export를 선택하며 기본값은 `AppModule`입니다. `--timing`은 명시적인 `--json` flag 없이 제공된 경우를 포함해 JSON snapshot 출력 옆에 bootstrap timing diagnostics를 기록하고, `--report`는 CI/support triage를 위해 런타임이 생산한 snapshot을 안정적인 요약과 함께 감쌉니다. `--timing`은 Mermaid 출력과 함께 사용할 수 없습니다. `--output <path>`는 선택한 inspect payload를 stdout 대신 명시적 artifact 경로에 씁니다. 이 동작은 검사 대상 애플리케이션을 writable하게 만들지 않으며, 일반 bootstrap/close cycle 외에 module graph state를 바꾸지 않습니다. Mermaid 출력이 필요하면 명령을 실행하는 프로젝트에 Studio를 설치하세요:
 
 ```bash
 pnpm add -D @fluojs/studio
@@ -272,8 +274,10 @@ Studio가 없으면 CI와 non-interactive 실행은 prompt나 package manager
 | 익스포트 | 설명 |
 |---|---|
 | `runCli(argv?, options?)` | 모든 CLI 명령을 실행하는 메인 진입점입니다. |
+| `CliRuntimeOptions` | stream, cwd, environment, registry metadata, update-check hook 같은 `runCli(...)` runtime override 타입입니다. |
 | `newUsage()` | help surface와 test에서 사용하는 현재 `fluo new` usage text를 반환합니다. |
 | `runNewCommand(argv, options?)` | 프로젝트 스캐폴딩 로직에 대한 프로그래밍적 접근을 제공합니다. |
+| `NewCommandRuntimeOptions` | prompt, filesystem write, dependency install, git initialization 같은 `runNewCommand(...)` runtime override 타입입니다. |
 | `CliPromptCancelledError` | 호출자가 제공한 prompt hook이 정상 취소를 알리기 위해 throw할 수 있는 안정적인 sentinel입니다. |
 | `GenerateOptions` | 프로그래밍 방식 generator 옵션 타입입니다. |
 | `GeneratedFile` | 생성된 파일 경로, 내용, write status를 설명하는 타입입니다. |

package/README.md

@@ -48,7 +48,7 @@ fluo -v
 
 When `fluo` runs in an interactive TTY, it checks the public npm `latest` dist-tag for `@fluojs/cli` using a local cache so every invocation does not hit the registry. If a newer version is available, the CLI asks whether to install it. Declining continues the current command with the installed version; accepting updates the global CLI with the package manager that appears to own the current installation (`npm install -g`, `pnpm add -g`, `bun add -g`, or `yarn global add`) and then restarts `fluo` with the same arguments under the updated binary. If the installer cannot be inferred, the CLI falls back to `npm install -g @fluojs/cli@<latest>` because npm owns the default Node.js global installation path.
 
-`fluo new` and its `fluo create` alias attempt a fresh interactive latest-version check before scaffolding, even when the normal update-check cache is still fresh. This keeps first-run project creation aligned with newly published starter behavior, while day-to-day commands such as `fluo dev`, `fluo build`, `fluo generate`, and `fluo inspect` continue to reuse the cached latest-version result until the normal TTL expires.
+`fluo new` and its `fluo create` alias attempt a fresh interactive latest-version check before scaffolding, even when the normal update-check cache is still fresh. This keeps first-run project creation aligned with newly published starter behavior, while day-to-day commands such as `fluo dev`, `fluo build`, `fluo generate`, and `fluo inspect` continue to reuse the cached latest-version result until the normal TTL expires. Pure help and version inspection paths (`fluo help <command>`, `<command> --help`, `fluo version`, `fluo --version`, and `fluo -v`) print immediately without running the interactive update check.
 
 The update check is skipped in CI, non-TTY output, npm-script contexts, rerun-after-update contexts, registry/network failures, and explicit opt-out paths. Use `--no-update-check` (or the compatibility alias `--no-update-notifier`) for one invocation, or set `FLUO_NO_UPDATE_CHECK=1` when automation must never prompt.
 
@@ -74,11 +74,13 @@ pnpm dev
 
 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 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.
 
 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.
 
-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. 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. 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.
 
 `fluo new` supports Node.js + Fastify, Express, and raw Node.js HTTP application starters on the same Node-oriented install/build flow:
 
@@ -110,7 +112,7 @@ fluo new my-grpc-service --shape microservice --transport grpc --runtime node --
 
 Supported `--shape microservice --transport` starter values are exactly `tcp`, `redis-streams`, `nats`, `kafka`, `rabbitmq`, `mqtt`, and `grpc`. Use `redis-streams` for the maintained Redis-backed starter, or add `@fluojs/redis` manually after scaffolding when you need broader Redis integration patterns.
 
-The NATS/Kafka/RabbitMQ starter contracts stay explicit about external brokers and caller-owned client libraries. Generated projects wire `nats` + `JSONCodec()`, `kafkajs` producer/consumer collaborators, and `amqplib` publisher/consumer collaborators directly in `src/app.ts` so the starter contract is runnable without pretending the base fluo packages hide those dependencies.
+The NATS/Kafka/RabbitMQ starter contracts stay explicit about external brokers and caller-owned client libraries. Generated projects wire `nats` + `JSONCodec()`, `kafkajs` producer/consumer collaborators, and `amqplib` publisher/consumer collaborators directly in `src/app.ts` so the starter contract is runnable without pretending the base fluo packages hide those dependencies. Those broker clients are created lazily by the generated transport wrapper when the Fluo lifecycle starts listening, sends, or emits; importing `src/app.ts` for `fluo inspect`, tests, or static tooling does not connect to a broker or open external resources before the application lifecycle owns teardown.
 
 The starter matrix also includes a mixed single-package starter: one Fastify HTTP app with an attached TCP microservice in the same generated project.
 
@@ -153,7 +155,7 @@ Auto-registered generators are `controller`, `service`, `repo`, `guard`, `interc
 
 `fluo generate module <name> --with-test` adds a `*.slice.test.ts` that compiles the authored module with `createTestingModule({ rootModule })`. `fluo generate resource <name>` creates a complete feature slice with a module, controller, service, repository, request DTO, response DTO, and tests; add `--with-slice-test` to include a resource-level slice test that demonstrates provider override and service resolution. It does not wire the resource module into a parent module automatically; import the generated module when you are ready to activate the slice.
 
-`fluo generate e2e <name>` writes `test/<name>.e2e.test.ts` with `createTestApp({ rootModule: AppModule })` so request-pipeline tests live in the same app-level test area as generated starters. Use generated unit tests for direct class behavior, slice tests for DI wiring and overrides, and e2e tests for routes, guards, interceptors, DTO validation, and response writing through the virtual app.
+`fluo generate e2e <name>` writes `test/<name>.e2e.test.ts` with `createTestApp({ rootModule: AppModule })` and imports `AppModule` from the default starter root module at `../src/app`, so request-pipeline tests live in the same app-level test area as generated starters. Use generated unit tests for direct class behavior, slice tests for DI wiring and overrides, and e2e tests for routes, guards, interceptors, DTO validation, and response writing through the virtual app.
 
 Request DTO generation accepts the feature directory separately from the DTO class name, so multiple input contracts such as `CreateUser` and `UpdateUser` can live inside the same `src/users/` slice.
 
@@ -248,7 +250,7 @@ fluo inspect ./src/app.module.ts --json > snapshot.json
 fluo inspect ./src/app.module.ts --json --output artifacts/inspect-snapshot.json
 
 # Include bootstrap timing next to the runtime-produced snapshot
-fluo inspect ./src/app.module.ts --json --timing
+fluo inspect ./src/app.module.ts --timing
 
 # Emit a support triage report with summary, snapshot, diagnostics, and timing
 fluo inspect ./src/app.module.ts --report --output artifacts/inspect-report.json
@@ -257,7 +259,7 @@ 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` serializes that 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 for JSON output, 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:
+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. `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:
 
 ```bash
 pnpm add -D @fluojs/studio
@@ -272,8 +274,10 @@ The package can be used programmatically to trigger CLI actions from within othe
 | Export | Description |
 |---|---|
 | `runCli(argv?, options?)` | Main entry point to execute any CLI command. |
+| `CliRuntimeOptions` | Type for `runCli(...)` runtime overrides such as streams, cwd, environment, registry metadata, and update-check hooks. |
 | `newUsage()` | Returns the current `fluo new` usage text for help surfaces and tests. |
 | `runNewCommand(argv, options?)` | Programmatic access to the project scaffolding logic. |
+| `NewCommandRuntimeOptions` | Type for `runNewCommand(...)` runtime overrides such as prompts, filesystem writes, dependency installation, and git initialization. |
 | `CliPromptCancelledError` | Stable sentinel that caller-supplied prompt hooks can throw to report normal cancellation. |
 | `GenerateOptions` | Type for programmatic generator options. |
 | `GeneratedFile` | Type describing generated file paths, content, and write status. |

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,EAAmC,MAAM,uBAAuB,CAAC;AAE3G,OAAO,EAAE,KAAK,wBAAwB,EAA2B,MAAM,mBAAmB,CAAC;AAO3F,OAAO,EAAE,KAAK,4BAA4B,EAA6C,MAAM,mBAAmB,CAAC;AAEjH,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,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;AAwZD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,MAAM,CAC1B,IAAI,WAAwB,EAC5B,OAAO,GAAE,iBAAiB,GAAG,wBAAwB,GAAG,4BAAiC,GACxF,OAAO,CAAC,MAAM,CAAC,CAqNjB"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,4BAA4B,EAAmC,MAAM,uBAAuB,CAAC;AAE3G,OAAO,EAAE,KAAK,wBAAwB,EAA2B,MAAM,mBAAmB,CAAC;AAO3F,OAAO,EAAE,KAAK,4BAA4B,EAA6C,MAAM,mBAAmB,CAAC;AAEjH,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,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"}

package/dist/cli.js

@@ -125,6 +125,9 @@ function isVersionCommand(value) {
 function isCreationCommand(value) {
   return value === 'new' || value === 'create';
 }
+function isHelpInvocation(argv) {
+  return argv[0] === 'help' || argv.some(isHelpFlag);
+}
 function readCliVersion() {
   const packageJsonPath = fileURLToPath(new URL('../package.json', import.meta.url));
   const manifest = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
@@ -387,20 +390,22 @@ export async function runCli(argv = process.argv.slice(2), runtime = {}) {
       stdout.write(`${readCliVersion()}\n`);
       return 0;
     }
-    const updateCheckOptions = runtime.updateCheck === false ? undefined : runtime.updateCheck;
-    const updateCheckResult = await runCliUpdateCheck(commandArgv, {
-      ...updateCheckOptions,
-      ci: runtime.ci,
-      env,
-      bypassCache: isCreationCommand(commandArgv[0]),
-      interactive: runtime.interactive,
-      skip: updateFlagResult.skipUpdateCheck || runtime.updateCheck === false,
-      stderr,
-      stdin: runtime.stdin,
-      stdout
-    });
-    if (updateCheckResult.action === 'reran') {
-      return updateCheckResult.exitCode;
+    if (!isHelpInvocation(commandArgv)) {
+      const updateCheckOptions = runtime.updateCheck === false ? undefined : runtime.updateCheck;
+      const updateCheckResult = await runCliUpdateCheck(commandArgv, {
+        ...updateCheckOptions,
+        ci: runtime.ci,
+        env,
+        bypassCache: isCreationCommand(commandArgv[0]),
+        interactive: runtime.interactive,
+        skip: updateFlagResult.skipUpdateCheck || runtime.updateCheck === false,
+        stderr,
+        stdin: runtime.stdin,
+        stdout
+      });
+      if (updateCheckResult.action === 'reran') {
+        return updateCheckResult.exitCode;
+      }
     }
     if (commandArgv.length === 0) {
       throw new Error(usage());
@@ -416,7 +421,7 @@ export async function runCli(argv = process.argv.slice(2), runtime = {}) {
         return 0;
       }
       if (topic === 'doctor' || topic === 'info') {
-        stdout.write(`${diagnosticsUsage('doctor')}\n`);
+        stdout.write(`${diagnosticsUsage(topic)}\n`);
         return 0;
       }
       if (topic === 'analyze') {
@@ -455,7 +460,7 @@ export async function runCli(argv = process.argv.slice(2), runtime = {}) {
       return 0;
     }
     if ((commandArgv[0] === 'doctor' || commandArgv[0] === 'info') && commandArgv.slice(1).some(isHelpFlag)) {
-      stdout.write(`${diagnosticsUsage('doctor')}\n`);
+      stdout.write(`${diagnosticsUsage(commandArgv[0])}\n`);
       return 0;
     }
     if (commandArgv[0] === 'analyze' && commandArgv.slice(1).some(isHelpFlag)) {

package/dist/commands/generate.js

@@ -70,7 +70,7 @@ function toImportSpecifier(path) {
   return normalized.startsWith('.') ? normalized : `./${normalized}`;
 }
 function resolveE2eRootModuleImport(domainDirectory, resolvedBase) {
-  return toImportSpecifier(relative(domainDirectory, join(resolvedBase, 'app.module')));
+  return toImportSpecifier(relative(domainDirectory, join(resolvedBase, 'app')));
 }
 function resolveDomainDirectory(kind, resolvedBase, kebab, options) {
   if (kind === 'e2e') {

package/dist/commands/inspect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../src/commands/inspect.ts"],"names":[],"mappings":"AAMA,OAAO,EAML,KAAK,qBAAqB,EAE3B,MAAM,iBAAiB,CAAC;AAKzB,KAAK,SAAS,GAAG;IACf,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,KAAK,CAAC,IAAI,IAAI,CAAC;IACf,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnE,CAAC;AAEF,KAAK,cAAc,GAAG;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,KAAK,qBAAqB,GAAG,CAAC,QAAQ,EAAE,qBAAqB,KAAK,MAAM,CAAC;AAEzE,KAAK,2BAA2B,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC,CAAC;AAE/F;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,yEAAyE;IACzE,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,uDAAuD;IACvD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,yEAAyE;IACzE,yBAAyB,CAAC,EAAE,2BAA2B,CAAC;IACxD,wFAAwF;IACxF,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,sCAAsC;IACtC,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,yCAAyC;IACzC,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAkFD;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAarC;AA+PD;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,4BAAiC,GAAG,OAAO,CAAC,MAAM,CAAC,CA4EnH"}
+{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../src/commands/inspect.ts"],"names":[],"mappings":"AAMA,OAAO,EAOL,KAAK,qBAAqB,EAC3B,MAAM,iBAAiB,CAAC;AAMzB,KAAK,SAAS,GAAG;IACf,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,KAAK,CAAC,IAAI,IAAI,CAAC;IACf,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnE,CAAC;AAEF,KAAK,cAAc,GAAG;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,KAAK,qBAAqB,GAAG,CAAC,QAAQ,EAAE,qBAAqB,KAAK,MAAM,CAAC;AAEzE,KAAK,2BAA2B,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC,CAAC;AAE/F;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,yEAAyE;IACzE,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,uDAAuD;IACvD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,yEAAyE;IACzE,yBAAyB,CAAC,EAAE,2BAA2B,CAAC;IACxD,wFAAwF;IACxF,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,sCAAsC;IACtC,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,yCAAyC;IACzC,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAmFD;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAarC;AA+PD;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,4BAAiC,GAAG,OAAO,CAAC,MAAM,CAAC,CAwDnH"}

package/dist/commands/inspect.js

@@ -1,9 +1,10 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
-import { dirname, resolve } from 'node:path';
+import { dirname, extname, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import * as clack from '@clack/prompts';
 import { FluoFactory, PLATFORM_SHELL } from '@fluojs/runtime';
+import { tsImport } from 'tsx/esm/api';
 import { renderAliasList, renderHelpTable } from '../help.js';
 import { CliPromptCancelledError, isCliPromptCancelledError } from '../prompt-cancel.js';
 
@@ -21,7 +22,7 @@ const INSPECT_OPTION_HELP = [{
   option: '--mermaid'
 }, {
   aliases: [],
-  description: 'Bootstrap the application context and emit versioned timing diagnostics.',
+  description: 'Include bootstrap timing diagnostics next to JSON inspect output.',
   option: '--timing'
 }, {
   aliases: [],
@@ -41,6 +42,7 @@ const INSPECT_OPTION_HELP = [{
   option: '--help'
 }];
 const STUDIO_CONTRACT_ENTRYPOINT = '@fluojs/studio/contracts';
+const TYPESCRIPT_MODULE_EXTENSIONS = new Set(['.ts', '.tsx', '.mts', '.cts']);
 const STUDIO_MISSING_MESSAGE = ['Mermaid graph rendering is owned by @fluojs/studio, but @fluojs/studio is not resolvable from this project.', 'Install @fluojs/studio explicitly (for example: pnpm add -D @fluojs/studio) and rerun fluo inspect --mermaid.'].join('\n');
 function isHelpFlag(value) {
   return value === '--help' || value === '-h';
@@ -121,7 +123,7 @@ function parseInspectArgs(argv) {
   if (!modulePath) {
     throw new Error(inspectUsage());
   }
-  if (!json && !mermaid && !timing && !report) {
+  if (!json && !mermaid && !report) {
     json = true;
   }
   const selectedModes = [json, mermaid, report].filter(Boolean).length;
@@ -147,13 +149,12 @@ function resolveRootModule(exportedValue, exportName) {
   }
   return exportedValue;
 }
-function stringifyTiming(timing) {
-  const value = timing ?? {
-    phases: [],
-    totalMs: 0,
-    version: 1
-  };
-  return JSON.stringify(value, null, 2);
+async function importInspectModule(modulePath) {
+  const moduleUrl = pathToFileURL(modulePath).href;
+  if (TYPESCRIPT_MODULE_EXTENSIONS.has(extname(modulePath))) {
+    return tsImport(moduleUrl, import.meta.url);
+  }
+  return import(moduleUrl);
 }
 function stringifySnapshot(snapshot) {
   return JSON.stringify(snapshot, null, 2);
@@ -283,27 +284,8 @@ export async function runInspectCommand(argv, runtime = {}) {
     }
     const parsed = parseInspectArgs(argv);
     const modulePath = resolve(cwd, parsed.modulePath);
-    const importedModule = await import(pathToFileURL(modulePath).href);
+    const importedModule = await importInspectModule(modulePath);
     const rootModule = resolveRootModule(importedModule[parsed.exportName], parsed.exportName);
-    if (parsed.timing && !parsed.json && !parsed.report) {
-      const context = await FluoFactory.createApplicationContext(rootModule, {
-        diagnostics: {
-          timing: true
-        },
-        logger: {
-          debug() {},
-          error() {},
-          log() {},
-          warn() {}
-        }
-      });
-      try {
-        await emitInspectPayload(stringifyTiming(context.bootstrapTiming), parsed, cwd, stdout);
-      } finally {
-        await context.close();
-      }
-      return 0;
-    }
     const context = await FluoFactory.createApplicationContext(rootModule, {
       diagnostics: parsed.timing || parsed.report ? {
         timing: true

package/dist/dev-runner/node-restart-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node-restart-runner.d.ts","sourceRoot":"","sources":["../../src/dev-runner/node-restart-runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE9D,OAAO,EAA0D,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AAIjG,KAAK,mBAAmB,GAAG;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC,CAAC;AAEF,KAAK,mBAAmB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,KAAK,YAAY,CAAC;AACjJ,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,oBAAoB,GAAG,MAAM,GAAG,MAAM,CAAC;AAE9E,KAAK,aAAa,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE1C,KAAK,mBAAmB,GAAG;IACzB,GAAG,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;IAC1D,IAAI,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;CAC5D,CAAC;AAEF,KAAK,qBAAqB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAE;IAAE,SAAS,EAAE,OAAO,CAAA;CAAE,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,KAAK,IAAI,KAAK,SAAS,CAAC;AAE1O,KAAK,iBAAiB,GAAG;IACvB,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAC9C,mBAAmB,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC;CACvD,CAAC;AAEF,uFAAuF;AACvF,MAAM,MAAM,wBAAwB,GAAG;IACrC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,YAAY,CAAC,EAAE,mBAAmB,CAAC;IACnC,UAAU,CAAC,EAAE,mBAAmB,CAAC;IACjC,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,WAAW,CAAC,EAAE,qBAAqB,CAAC;CACrC,CAAC;AAgGF;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,gBAAgB,EAAE,MAAM,EAAE,cAAc,GAAE,MAAM,EAAoB,GAAG,iBAAiB,CAuB/H;AAqED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CA2J7F"}
+{"version":3,"file":"node-restart-runner.d.ts","sourceRoot":"","sources":["../../src/dev-runner/node-restart-runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE9D,OAAO,EAA0D,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AAIjG,KAAK,mBAAmB,GAAG;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC,CAAC;AAEF,KAAK,mBAAmB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,KAAK,YAAY,CAAC;AACjJ,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,oBAAoB,GAAG,MAAM,GAAG,MAAM,CAAC;AAE9E,KAAK,aAAa,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE1C,KAAK,mBAAmB,GAAG;IACzB,GAAG,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;IAC1D,IAAI,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;CAC5D,CAAC;AAEF,KAAK,qBAAqB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAE;IAAE,SAAS,EAAE,OAAO,CAAA;CAAE,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,KAAK,IAAI,KAAK,SAAS,CAAC;AAE1O,KAAK,iBAAiB,GAAG;IACvB,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAC9C,mBAAmB,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC;CACvD,CAAC;AAEF,uFAAuF;AACvF,MAAM,MAAM,wBAAwB,GAAG;IACrC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,YAAY,CAAC,EAAE,mBAAmB,CAAC;IACnC,UAAU,CAAC,EAAE,mBAAmB,CAAC;IACjC,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,WAAW,CAAC,EAAE,qBAAqB,CAAC;CACrC,CAAC;AA4HF;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,gBAAgB,EAAE,MAAM,EAAE,cAAc,GAAE,MAAM,EAAoB,GAAG,iBAAiB,CAuB/H;AAiFD;;;;;GAKG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4M7F"}

package/dist/dev-runner/node-restart-runner.js

@@ -9,6 +9,7 @@ import { fileURLToPath } from 'node:url';
 /** Options used to configure the fluo-owned Node restart-on-watch process boundary. */
 
 const DEFAULT_DEBOUNCE_MS = 100;
+const DEFAULT_CHILD_SHUTDOWN_TIMEOUT_MS = 5_000;
 const PRETTY_TTY_COLOR_ENV = 'FLUO_DEV_PRETTY_TTY_COLOR';
 const DEFAULT_IGNORES = ['.cache', '.fluo', '.git', '.turbo', 'coverage', 'dist', 'node_modules', '*.swp', '*.swo', '*~', '.#*'];
 const WATCH_FILES = ['.env', 'package.json', 'tsconfig.json', 'tsconfig.build.json'];
@@ -75,6 +76,28 @@ function collectWatchedContentPaths(paths, projectDirectory, ignorePatterns) {
   }
   return collected;
 }
+function collectWatchDirectories(directoryPath, projectDirectory, ignorePatterns, directories) {
+  if (shouldIgnorePath(directoryPath, projectDirectory, ignorePatterns)) {
+    return;
+  }
+  try {
+    const stats = statSync(directoryPath);
+    if (!stats.isDirectory()) {
+      return;
+    }
+    directories.add(directoryPath);
+    for (const entry of readdirSync(directoryPath)) {
+      collectWatchDirectories(join(directoryPath, entry), projectDirectory, ignorePatterns, directories);
+    }
+  } catch (_error) {
+    return;
+  }
+}
+function getFallbackWatchDirectories(directoryPath, projectDirectory, ignorePatterns) {
+  const directories = new Set();
+  collectWatchDirectories(directoryPath, projectDirectory, ignorePatterns, directories);
+  return [...directories];
+}
 
 /**
  * Creates a content-diff gate for fluo-owned dev restarts.
@@ -107,9 +130,20 @@ export function createContentChangeGate(projectDirectory, ignorePatterns = DEFAU
 function getWatchTargets(projectDirectory) {
   return [join(projectDirectory, 'src'), ...WATCH_FILES.map(fileName => join(projectDirectory, fileName))].filter(target => existsSync(target));
 }
-function stopChild(child) {
-  if (child && child.exitCode === null && !child.killed) {
-    child.kill('SIGTERM');
+function stopChild(child, shutdownTimeoutMs = DEFAULT_CHILD_SHUTDOWN_TIMEOUT_MS) {
+  if (child && child.exitCode === null) {
+    const forceKillTimer = setTimeout(() => {
+      if (child.exitCode === null) {
+        child.kill('SIGKILL');
+      }
+    }, shutdownTimeoutMs);
+    forceKillTimer.unref?.();
+    child.once('close', () => {
+      clearTimeout(forceKillTimer);
+    });
+    if (!child.killed) {
+      child.kill('SIGTERM');
+    }
   }
 }
 function getPreserveColorTtyImport() {
@@ -184,7 +218,9 @@ export async function runNodeRestartRunner(options) {
   const watchTarget = options.watchTarget ?? watch;
   const appArgs = options.appArgs ?? [];
   const debounceMs = options.debounceMs ?? Number(env.FLUO_DEV_RELOAD_DEBOUNCE_MS ?? DEFAULT_DEBOUNCE_MS);
-  const gate = createContentChangeGate(projectDirectory, parseIgnorePatterns(env));
+  const childShutdownTimeoutMs = Number(env.FLUO_DEV_CHILD_SHUTDOWN_TIMEOUT_MS ?? DEFAULT_CHILD_SHUTDOWN_TIMEOUT_MS);
+  const ignorePatterns = parseIgnorePatterns(env);
+  const gate = createContentChangeGate(projectDirectory, ignorePatterns);
   const watchTargets = getWatchTargets(projectDirectory);
   let child;
   const pendingRestartPaths = new Set();
@@ -252,7 +288,7 @@ export async function runNodeRestartRunner(options) {
           startChild(resolveExitCode, cleanup);
           gate.commitBaseline(committedRestartPaths);
         });
-        stopChild(previousChild);
+        stopChild(previousChild, childShutdownTimeoutMs);
         return;
       }
       try {
@@ -266,10 +302,26 @@ export async function runNodeRestartRunner(options) {
   return new Promise(resolveExitCode => {
     const watchers = [];
     let cleanedUp = false;
+    let resolved = false;
+    const resolveOnce = code => {
+      if (resolved) {
+        return;
+      }
+      resolved = true;
+      resolveExitCode(code);
+    };
     const stop = () => {
       stopping = true;
       cleanup();
-      stopChild(child);
+      const stoppingChild = child;
+      if (!stoppingChild || stoppingChild.exitCode !== null) {
+        resolveOnce(stoppingChild?.exitCode ?? 0);
+        return;
+      }
+      stoppingChild.once('close', code => {
+        resolveOnce(code ?? 0);
+      });
+      stopChild(child, childShutdownTimeoutMs);
     };
     const cleanup = () => {
       if (cleanedUp) {
@@ -289,6 +341,27 @@ export async function runNodeRestartRunner(options) {
       signalTarget.off('SIGTERM', stop);
     };
     startChild(resolveExitCode, cleanup);
+    const watchedFallbackDirectories = new Set();
+    const watchFallbackDirectory = directoryPath => {
+      if (watchedFallbackDirectories.has(directoryPath) || shouldIgnorePath(directoryPath, projectDirectory, ignorePatterns)) {
+        return;
+      }
+      watchedFallbackDirectories.add(directoryPath);
+      const listener = (_event, filename) => {
+        const fileName = filename ? String(filename) : basename(directoryPath);
+        const changedPath = filename ? join(directoryPath, fileName) : directoryPath;
+        scheduleRestart(changedPath, resolveExitCode, cleanup);
+        for (const nextDirectoryPath of getFallbackWatchDirectories(changedPath, projectDirectory, ignorePatterns)) {
+          watchFallbackDirectory(nextDirectoryPath);
+        }
+      };
+      try {
+        watchers.push(watchTarget(directoryPath, listener));
+      } catch (error) {
+        watchedFallbackDirectories.delete(directoryPath);
+        stderr.write(`[fluo] unable to watch ${directoryPath}: ${error instanceof Error ? error.message : String(error)}\n`);
+      }
+    };
     for (const target of watchTargets) {
       try {
         const stats = statSync(target);
@@ -305,7 +378,9 @@ export async function runNodeRestartRunner(options) {
           if (!stats.isDirectory()) {
             throw error;
           }
-          watchers.push(watchTarget(target, listener));
+          for (const directoryPath of getFallbackWatchDirectories(target, projectDirectory, ignorePatterns)) {
+            watchFallbackDirectory(directoryPath);
+          }
         }
       } catch (error) {
         stderr.write(`[fluo] unable to watch ${target}: ${error instanceof Error ? error.message : String(error)}\n`);

package/dist/fixtures/inspect-app.module.d.ts

@@ -0,0 +1,24 @@
+interface TypeScriptFixtureMetadata {
+    readonly source: 'typescript';
+}
+declare class TypeScriptSharedService {
+    readonly metadata: TypeScriptFixtureMetadata;
+}
+/**
+ * Represents a TypeScript-authored shared module fixture.
+ */
+export declare class TypeScriptSharedModule {
+}
+/**
+ * Represents the default TypeScript-authored app module fixture.
+ */
+export declare class AppModule {
+}
+/**
+ * Represents a named TypeScript-authored module fixture for --export coverage.
+ */
+export declare class AdminModule {
+}
+export declare const inspectFixtureServices: (typeof TypeScriptSharedService)[];
+export {};
+//# sourceMappingURL=inspect-app.module.d.ts.map

package/dist/fixtures/inspect-app.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect-app.module.d.ts","sourceRoot":"","sources":["../../src/fixtures/inspect-app.module.ts"],"names":[],"mappings":"AAAA,UAAU,yBAAyB;IACjC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;CAC/B;AAED,cAAM,uBAAuB;IAC3B,QAAQ,CAAC,QAAQ,EAAE,yBAAyB,CAA4B;CACzE;AAED;;GAEG;AACH,qBAAa,sBAAsB;CAAG;AAEtC;;GAEG;AACH,qBAAa,SAAS;CAAG;AAEzB;;GAEG;AACH,qBAAa,WAAW;CAAG;AAE3B,eAAO,MAAM,sBAAsB,oCAA4B,CAAC"}

package/dist/fixtures/inspect-app.module.js

@@ -0,0 +1,21 @@
+class TypeScriptSharedService {
+  metadata = {
+    source: 'typescript'
+  };
+}
+
+/**
+ * Represents a TypeScript-authored shared module fixture.
+ */
+export class TypeScriptSharedModule {}
+
+/**
+ * Represents the default TypeScript-authored app module fixture.
+ */
+export class AppModule {}
+
+/**
+ * Represents a named TypeScript-authored module fixture for --export coverage.
+ */
+export class AdminModule {}
+export const inspectFixtureServices = [TypeScriptSharedService];

package/dist/generators/e2e.js

@@ -10,7 +10,7 @@ import { toKebabCase } from './utils.js';
  */
 export function generateE2eFiles(name, options = {}) {
   const kebab = toKebabCase(name);
-  const rootModuleImport = options.e2eRootModuleImport ?? '../src/app.module';
+  const rootModuleImport = options.e2eRootModuleImport ?? '../src/app';
   return [{
     content: renderTemplate('e2e.test.ts.ejs', {
       kebab,

package/dist/new/scaffold.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../src/new/scaffold.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,gBAAgB,EAAkB,MAAM,YAAY,CAAC;AA+qEnE;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,gBAAgB,EACzB,aAAa,SAAkB,GAC9B,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,6BAAuB,CAAC"}
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../src/new/scaffold.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,gBAAgB,EAAkB,MAAM,YAAY,CAAC;AAqxEnE;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,gBAAgB,EACzB,aAAa,SAAkB,GAC9B,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,6BAAuB,CAAC"}

package/dist/new/scaffold.js

@@ -28,7 +28,6 @@ const PUBLISHED_RUNTIME_DEPENDENCIES = {
   nats: '^2.29.3'
 };
 const PUBLISHED_INTERNAL_DEPENDENCIES = {
-  '@fluojs/cli': '^1.0.0',
   '@fluojs/config': '^1.0.0',
   '@fluojs/core': '^1.0.0',
   '@fluojs/di': '^1.0.0',
@@ -116,6 +115,9 @@ function writeTextFile(filePath, content) {
   writeFileSync(filePath, content, 'utf8');
 }
 function createDependencySpec(packageName, releaseVersion, packageSpecs) {
+  if (packageName === '@fluojs/cli') {
+    return packageSpecs[packageName] ?? createPublishedInternalDependencySpec(releaseVersion);
+  }
   return packageSpecs[packageName] ?? PUBLISHED_RUNTIME_DEPENDENCIES[packageName] ?? PUBLISHED_INTERNAL_DEPENDENCIES[packageName] ?? createPublishedInternalDependencySpec(releaseVersion);
 }
 function createPublishedInternalDependencySpec(version) {
@@ -448,38 +450,38 @@ function describeMicroserviceStarter(options) {
     case 'nats':
       return {
         configLines: ['- NATS broker: configure `NATS_SERVERS` in `.env` before you start the service', '- Subject contract: keep `NATS_MESSAGE_SUBJECT` and `NATS_EVENT_SUBJECT` aligned with the peer services that share the broker namespace'],
-        entrypointNote: '`src/app.ts` opens one caller-owned `nats` client plus `JSONCodec()` and passes both into `NatsMicroserviceTransport` as the canonical starter bootstrap contract',
+        entrypointNote: '`src/app.ts` keeps the caller-owned `nats` client plus `JSONCodec()` contract explicit, but opens the client lazily from the generated transport wrapper when the Fluo lifecycle starts broker work',
         generatedProjectVerification: 'The generated-project verification path typechecks, builds, and tests the scaffold while asserting the NATS starter keeps the `nats` dependency, `.env` contract, and transport entrypoint wiring intact.',
         packageManagerNote: 'runtime choice stays explicit and independent from the package manager you picked; the generated manifest adds the `nats` client because the NATS starter depends on an external broker plus a caller-owned client/bootstrap pair',
         pattern: 'math.sum',
         readmeTransportLabel: 'nats',
         runtimeDependencyNote: 'runtime dependency set: `@fluojs/microservices` plus `nats` for the broker client and codec that `NatsMicroserviceTransport` expects the caller to supply',
         starterNote: 'the NATS starter keeps TCP as the default microservice path when you omit `--transport`, but this scaffold becomes runnable as soon as `NATS_SERVERS` points at a reachable broker cluster',
-        testNote: '`src/app.test.ts` preserves a broker-free integration template via an in-memory transport, while generated-project verification still checks the NATS entrypoint/build contract and the caller-owned client bootstrap wiring.'
+        testNote: '`src/app.test.ts` preserves a broker-free integration template via an in-memory transport, while generated-project verification still checks the NATS entrypoint/build contract and import-safe lazy client bootstrap wiring.'
       };
     case 'kafka':
       return {
         configLines: ['- Kafka brokers: configure `KAFKA_BROKERS` in `.env` before you start the service', '- Topic/group contract: `KAFKA_CLIENT_ID`, `KAFKA_CONSUMER_GROUP`, `KAFKA_MESSAGE_TOPIC`, `KAFKA_EVENT_TOPIC`, and `KAFKA_RESPONSE_TOPIC` stay explicit so the starter never hides its shared broker topology'],
-        entrypointNote: '`src/app.ts` opens canonical `kafkajs` producer/consumer collaborators and passes them into `KafkaMicroserviceTransport`, keeping the response-topic contract explicit in starter-owned config',
+        entrypointNote: '`src/app.ts` keeps the canonical `kafkajs` producer/consumer collaborator contract explicit, but creates them lazily from the generated transport wrapper when the Fluo lifecycle starts broker work',
         generatedProjectVerification: 'The generated-project verification path typechecks, builds, and tests the scaffold while asserting the Kafka starter keeps the `kafkajs` dependency, `.env` contract, and transport entrypoint wiring intact.',
         packageManagerNote: 'runtime choice stays explicit and independent from the package manager you picked; the generated manifest adds `kafkajs` because the Kafka starter depends on an external broker plus caller-owned producer/consumer collaborators',
         pattern: 'math.sum',
         readmeTransportLabel: 'kafka',
         runtimeDependencyNote: 'runtime dependency set: `@fluojs/microservices` plus `kafkajs` for the generated producer/consumer/bootstrap contract used by `KafkaMicroserviceTransport`',
         starterNote: 'the Kafka starter keeps TCP as the default microservice path when you omit `--transport`, but this scaffold becomes runnable as soon as `KAFKA_BROKERS` points at a reachable broker set',
-        testNote: '`src/app.test.ts` preserves a broker-free integration template via an in-memory transport, while generated-project verification still checks the Kafka entrypoint/build contract and the explicit topic/client bootstrap wiring.'
+        testNote: '`src/app.test.ts` preserves a broker-free integration template via an in-memory transport, while generated-project verification still checks the Kafka entrypoint/build contract and import-safe lazy topic/client bootstrap wiring.'
       };
     case 'rabbitmq':
       return {
         configLines: ['- RabbitMQ broker: configure `RABBITMQ_URL` in `.env` before you start the service', '- Queue contract: `RABBITMQ_MESSAGE_QUEUE`, `RABBITMQ_EVENT_QUEUE`, and `RABBITMQ_RESPONSE_QUEUE` stay explicit so the starter advertises exactly which queues and reply path it owns'],
-        entrypointNote: '`src/app.ts` opens a canonical `amqplib` connection/channel pair and passes caller-owned publisher/consumer collaborators into `RabbitMqMicroserviceTransport`',
+        entrypointNote: '`src/app.ts` keeps the canonical `amqplib` connection/channel pair and caller-owned publisher/consumer collaborator contract explicit, but opens them lazily from the generated transport wrapper when the Fluo lifecycle starts broker work',
         generatedProjectVerification: 'The generated-project verification path typechecks, builds, and tests the scaffold while asserting the RabbitMQ starter keeps the `amqplib` dependency, `.env` contract, and transport entrypoint wiring intact.',
         packageManagerNote: 'runtime choice stays explicit and independent from the package manager you picked; the generated manifest adds `amqplib` because the RabbitMQ starter depends on an external broker plus caller-owned publisher/consumer collaborators',
         pattern: 'math.sum',
         readmeTransportLabel: 'rabbitmq',
         runtimeDependencyNote: 'runtime dependency set: `@fluojs/microservices`, `amqplib`, and `@types/amqplib` for the generated queue client/bootstrap contract used by `RabbitMqMicroserviceTransport`',
         starterNote: 'the RabbitMQ starter keeps TCP as the default microservice path when you omit `--transport`, but this scaffold becomes runnable as soon as `RABBITMQ_URL` points at a reachable broker',
-        testNote: '`src/app.test.ts` preserves a broker-free integration template via an in-memory transport, while generated-project verification still checks the RabbitMQ entrypoint/build contract and the explicit queue/bootstrap wiring.'
+        testNote: '`src/app.test.ts` preserves a broker-free integration template via an in-memory transport, while generated-project verification still checks the RabbitMQ entrypoint/build contract and import-safe lazy queue/bootstrap wiring.'
       };
     default:
       return {
@@ -1025,8 +1027,8 @@ export class AppModule {}
     case 'nats':
       return `import { Module } from '@fluojs/core';
 import { ConfigModule } from '@fluojs/config';
-import { MicroservicesModule, NatsMicroserviceTransport } from '@fluojs/microservices';
-import { JSONCodec, connect } from 'nats';
+import { MicroservicesModule, NatsMicroserviceTransport, type MicroserviceTransport } from '@fluojs/microservices';
+import { JSONCodec, connect, type NatsConnection } from 'nats';
 
 import { MathHandler } from './math/math.handler';
 
@@ -1037,36 +1039,73 @@ const servers = (process.env.NATS_SERVERS ?? 'nats://127.0.0.1:4222')
 const eventSubject = process.env.NATS_EVENT_SUBJECT ?? 'fluo.microservices.events';
 const messageSubject = process.env.NATS_MESSAGE_SUBJECT ?? 'fluo.microservices.messages';
 const codec = JSONCodec();
-const connection = await connect({
-  name: 'fluo-microservice-starter',
-  servers,
-});
-const client = {
-  close() {
-    void connection.close();
-  },
-  publish(subject: string, payload: Uint8Array) {
-    connection.publish(subject, payload);
-  },
-  request(subject: string, payload: Uint8Array, options?: { timeout?: number }) {
-    return connection.request(subject, payload, options);
-  },
-  subscribe(subject: string, handler: (message: { data: Uint8Array; respond(data: Uint8Array): void }) => void) {
-    const subscription = connection.subscribe(subject);
 
-    void (async () => {
-      for await (const message of subscription) {
-        handler(message);
-      }
-    })();
+class LazyNatsTransport implements MicroserviceTransport {
+  private connection: NatsConnection | undefined;
+  private transport: NatsMicroserviceTransport | undefined;
 
-    return {
-      unsubscribe() {
-        subscription.unsubscribe();
+  async close() {
+    await this.transport?.close();
+    await this.connection?.close();
+    this.transport = undefined;
+    this.connection = undefined;
+  }
+
+  async emit(pattern: string, payload: unknown) {
+    await (await this.getTransport()).emit(pattern, payload);
+  }
+
+  async listen(handler: Parameters<MicroserviceTransport['listen']>[0]) {
+    await (await this.getTransport()).listen(handler);
+  }
+
+  async send(pattern: string, payload: unknown, signal?: AbortSignal) {
+    return await (await this.getTransport()).send(pattern, payload, signal);
+  }
+
+  private async getTransport() {
+    if (this.transport) {
+      return this.transport;
+    }
+
+    const connection = await connect({
+      name: 'fluo-microservice-starter',
+      servers,
+    });
+    this.connection = connection;
+    this.transport = new NatsMicroserviceTransport({
+      client: {
+        publish(subject: string, payload: Uint8Array) {
+          connection.publish(subject, payload);
+        },
+        request(subject: string, payload: Uint8Array, options?: { timeout?: number }) {
+          return connection.request(subject, payload, options);
+        },
+        subscribe(subject: string, handler: (message: { data: Uint8Array; respond(data: Uint8Array): void }) => void) {
+          const subscription = connection.subscribe(subject);
+
+          void (async () => {
+            for await (const message of subscription) {
+              handler(message);
+            }
+          })();
+
+          return {
+            unsubscribe() {
+              subscription.unsubscribe();
+            },
+          };
+        },
       },
-    };
-  },
-};
+      codec,
+      eventSubject,
+      messageSubject,
+      requestTimeoutMs: 3_000,
+    });
+
+    return this.transport;
+  }
+}
 
 @Module({
   imports: [
@@ -1075,13 +1114,7 @@ const client = {
       processEnv: process.env,
     }),
     MicroservicesModule.forRoot({
-      transport: new NatsMicroserviceTransport({
-        client,
-        codec,
-        eventSubject,
-        messageSubject,
-        requestTimeoutMs: 3_000,
-      }),
+      transport: new LazyNatsTransport(),
     }),
   ],
   providers: [MathHandler],
@@ -1091,8 +1124,8 @@ export class AppModule {}
     case 'kafka':
       return `import { Module } from '@fluojs/core';
 import { ConfigModule } from '@fluojs/config';
-import { Kafka, logLevel } from 'kafkajs';
-import { KafkaMicroserviceTransport, MicroservicesModule } from '@fluojs/microservices';
+import { Kafka, logLevel, type Consumer, type Producer } from 'kafkajs';
+import { KafkaMicroserviceTransport, MicroservicesModule, type MicroserviceTransport } from '@fluojs/microservices';
 
 import { MathHandler } from './math/math.handler';
 
@@ -1105,61 +1138,105 @@ const consumerGroup = process.env.KAFKA_CONSUMER_GROUP ?? 'fluo-handlers';
 const eventTopic = process.env.KAFKA_EVENT_TOPIC ?? 'fluo.microservices.events';
 const messageTopic = process.env.KAFKA_MESSAGE_TOPIC ?? 'fluo.microservices.messages';
 const responseTopic = process.env.KAFKA_RESPONSE_TOPIC ?? 'fluo.microservices.responses';
-const kafka = new Kafka({
-  brokers,
-  clientId,
-  logLevel: logLevel.NOTHING,
-});
-const producer = kafka.producer();
-const consumer = kafka.consumer({ groupId: consumerGroup });
-await Promise.all([producer.connect(), consumer.connect()]);
-
-const handlers = new Map<string, (message: string) => Promise<void> | void>();
-let consumerRunning = false;
-
-const producerClient = {
-  async publish(topic: string, message: string) {
-    await producer.send({
-      messages: [{ value: message }],
-      topic,
-    });
-  },
-};
 
-const consumerClient = {
-  async subscribe(topic: string, handler: (message: string) => Promise<void> | void) {
-    handlers.set(topic, handler);
-    await consumer.subscribe({ fromBeginning: false, topic });
+class LazyKafkaTransport implements MicroserviceTransport {
+  private consumer: Consumer | undefined;
+  private producer: Producer | undefined;
+  private transport: KafkaMicroserviceTransport | undefined;
+
+  async close() {
+    await this.transport?.close();
+    await Promise.all([
+      this.consumer?.disconnect().catch(() => undefined),
+      this.producer?.disconnect().catch(() => undefined),
+    ]);
+    this.consumer = undefined;
+    this.producer = undefined;
+    this.transport = undefined;
+  }
 
-    if (consumerRunning) {
-      return;
-    }
+  async emit(pattern: string, payload: unknown) {
+    await (await this.getTransport()).emit(pattern, payload);
+  }
 
-    consumerRunning = true;
-    void consumer.run({
-      eachMessage: async ({ topic, message }) => {
-        const value = message.value?.toString();
+  async listen(handler: Parameters<MicroserviceTransport['listen']>[0]) {
+    await (await this.getTransport()).listen(handler);
+  }
 
-        if (!value) {
-          return;
-        }
+  async send(pattern: string, payload: unknown, signal?: AbortSignal) {
+    return await (await this.getTransport()).send(pattern, payload, signal);
+  }
+
+  private async getTransport() {
+    if (this.transport) {
+      return this.transport;
+    }
 
-        await handlers.get(topic)?.(value);
+    const kafka = new Kafka({
+      brokers,
+      clientId,
+      logLevel: logLevel.NOTHING,
+    });
+    const producer = kafka.producer();
+    const consumer = kafka.consumer({ groupId: consumerGroup });
+    await Promise.all([producer.connect(), consumer.connect()]);
+
+    const handlers = new Map<string, (message: string) => Promise<void> | void>();
+    let consumerRunning = false;
+
+    this.producer = producer;
+    this.consumer = consumer;
+    this.transport = new KafkaMicroserviceTransport({
+      consumer: {
+        async subscribe(topic: string, handler: (message: string) => Promise<void> | void) {
+          handlers.set(topic, handler);
+          await consumer.subscribe({ fromBeginning: false, topic });
+
+          if (consumerRunning) {
+            return;
+          }
+
+          consumerRunning = true;
+          void consumer.run({
+            eachMessage: async ({ topic, message }) => {
+              const value = message.value?.toString();
+
+              if (!value) {
+                return;
+              }
+
+              await handlers.get(topic)?.(value);
+            },
+          });
+        },
+        async unsubscribe(topic: string) {
+          handlers.delete(topic);
+
+          if (handlers.size > 0) {
+            return;
+          }
+
+          consumerRunning = false;
+          await consumer.stop();
+        },
+      },
+      eventTopic,
+      messageTopic,
+      producer: {
+        async publish(topic: string, message: string) {
+          await producer.send({
+            messages: [{ value: message }],
+            topic,
+          });
+        },
       },
+      requestTimeoutMs: 3_000,
+      responseTopic,
     });
-  },
-  async unsubscribe(topic: string) {
-    handlers.delete(topic);
-
-    if (handlers.size > 0) {
-      return;
-    }
 
-    consumerRunning = false;
-    await consumer.stop();
-    await Promise.all([consumer.disconnect(), producer.disconnect()]);
-  },
-};
+    return this.transport;
+  }
+}
 
 @Module({
   imports: [
@@ -1168,14 +1245,7 @@ const consumerClient = {
       processEnv: process.env,
     }),
     MicroservicesModule.forRoot({
-      transport: new KafkaMicroserviceTransport({
-        consumer: consumerClient,
-        eventTopic,
-        messageTopic,
-        producer: producerClient,
-        requestTimeoutMs: 3_000,
-        responseTopic,
-      }),
+      transport: new LazyKafkaTransport(),
     }),
   ],
   providers: [MathHandler],
@@ -1187,7 +1257,7 @@ export class AppModule {}
 
 import { Module } from '@fluojs/core';
 import { ConfigModule } from '@fluojs/config';
-import { MicroservicesModule, RabbitMqMicroserviceTransport } from '@fluojs/microservices';
+import { MicroservicesModule, RabbitMqMicroserviceTransport, type MicroserviceTransport } from '@fluojs/microservices';
 
 import { MathHandler } from './math/math.handler';
 
@@ -1195,61 +1265,99 @@ const url = process.env.RABBITMQ_URL ?? 'amqp://127.0.0.1:5672';
 const eventQueue = process.env.RABBITMQ_EVENT_QUEUE ?? 'fluo.microservices.events';
 const messageQueue = process.env.RABBITMQ_MESSAGE_QUEUE ?? 'fluo.microservices.messages';
 const responseQueue = process.env.RABBITMQ_RESPONSE_QUEUE ?? 'fluo.microservices.responses';
-const connection = await connect(url);
-const channel = await connection.createConfirmChannel();
-const consumerTags = new Map<string, string>();
-
-const publisher = {
-  async publish(queue: string, message: string) {
-    await channel.assertQueue(queue, { durable: true });
-    await new Promise<void>((resolve, reject) => {
-      channel.sendToQueue(queue, Buffer.from(message), { persistent: true }, (error) => {
-        if (error) {
-          reject(error);
-          return;
-        }
 
-        resolve();
-      });
-    });
-  },
-};
+class LazyRabbitMqTransport implements MicroserviceTransport {
+  private channel: Awaited<ReturnType<Awaited<ReturnType<typeof connect>>['createConfirmChannel']>> | undefined;
+  private connection: Awaited<ReturnType<typeof connect>> | undefined;
+  private transport: RabbitMqMicroserviceTransport | undefined;
+
+  async close() {
+    await this.transport?.close();
+    await this.channel?.close().catch(() => undefined);
+    await this.connection?.close().catch(() => undefined);
+    this.channel = undefined;
+    this.connection = undefined;
+    this.transport = undefined;
+  }
 
-const consumer = {
-  async cancel(queue: string) {
-    const consumerTag = consumerTags.get(queue);
+  async emit(pattern: string, payload: unknown) {
+    await (await this.getTransport()).emit(pattern, payload);
+  }
 
-    if (!consumerTag) {
-      return;
-    }
+  async listen(handler: Parameters<MicroserviceTransport['listen']>[0]) {
+    await (await this.getTransport()).listen(handler);
+  }
 
-    consumerTags.delete(queue);
-    await channel.cancel(consumerTag);
+  async send(pattern: string, payload: unknown, signal?: AbortSignal) {
+    return await (await this.getTransport()).send(pattern, payload, signal);
+  }
 
-    if (consumerTags.size === 0) {
-      await channel.close();
-      await connection.close();
+  private async getTransport() {
+    if (this.transport) {
+      return this.transport;
     }
-  },
-  async consume(queue: string, handler: (message: string) => Promise<void> | void) {
-    await channel.assertQueue(queue, { durable: true });
-    const result = await channel.consume(queue, (message) => {
-      if (!message) {
-        return;
-      }
-
-      void Promise.resolve(handler(message.content.toString()))
-        .then(() => {
-          channel.ack(message);
-        })
-        .catch(() => {
-          channel.nack(message, false, false);
-        });
+
+    const connection = await connect(url);
+    const channel = await connection.createConfirmChannel();
+    const consumerTags = new Map<string, string>();
+
+    this.connection = connection;
+    this.channel = channel;
+    this.transport = new RabbitMqMicroserviceTransport({
+      consumer: {
+        async cancel(queue: string) {
+          const consumerTag = consumerTags.get(queue);
+
+          if (!consumerTag) {
+            return;
+          }
+
+          consumerTags.delete(queue);
+          await channel.cancel(consumerTag);
+        },
+        async consume(queue: string, handler: (message: string) => Promise<void> | void) {
+          await channel.assertQueue(queue, { durable: true });
+          const result = await channel.consume(queue, (message) => {
+            if (!message) {
+              return;
+            }
+
+            void Promise.resolve(handler(message.content.toString()))
+              .then(() => {
+                channel.ack(message);
+              })
+              .catch(() => {
+                channel.nack(message, false, false);
+              });
+          });
+
+          consumerTags.set(queue, result.consumerTag);
+        },
+      },
+      eventQueue,
+      messageQueue,
+      publisher: {
+        async publish(queue: string, message: string) {
+          await channel.assertQueue(queue, { durable: true });
+          await new Promise<void>((resolve, reject) => {
+            channel.sendToQueue(queue, Buffer.from(message), { persistent: true }, (error) => {
+              if (error) {
+                reject(error);
+                return;
+              }
+
+              resolve();
+            });
+          });
+        },
+      },
+      requestTimeoutMs: 3_000,
+      responseQueue,
     });
 
-    consumerTags.set(queue, result.consumerTag);
-  },
-};
+    return this.transport;
+  }
+}
 
 @Module({
   imports: [
@@ -1258,14 +1366,7 @@ const consumer = {
       processEnv: process.env,
     }),
     MicroservicesModule.forRoot({
-      transport: new RabbitMqMicroserviceTransport({
-        consumer,
-        eventQueue,
-        messageQueue,
-        publisher,
-        requestTimeoutMs: 3_000,
-        responseQueue,
-      }),
+      transport: new LazyRabbitMqTransport(),
     }),
   ],
   providers: [MathHandler],

package/package.json

@@ -9,7 +9,7 @@
     "migration",
     "diagnostics"
   ],
-  "version": "1.0.0",
+  "version": "1.0.2",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -44,10 +44,10 @@
     "ejs": "^3.1.10",
     "tsx": "^4.20.4",
     "typescript": "^6.0.2",
-    "@fluojs/runtime": "^1.0.0"
+    "@fluojs/runtime": "^1.0.1"
   },
   "peerDependencies": {
-    "@fluojs/studio": "^1.0.0"
+    "@fluojs/studio": "^1.0.1"
   },
   "peerDependenciesMeta": {
     "@fluojs/studio": {