@fluojs/cli 1.0.0-beta.4 → 1.0.0-beta.6

package/README.ko.md

@@ -7,6 +7,7 @@ fluo 공식 CLI — 새 애플리케이션 부트스트랩, 컴포넌트 생성,
 ## 목차
 
 - [설치](#설치)
+- [버전 확인](#버전-확인)
 - [업데이트 확인](#업데이트-확인)
 - [사용 시점](#사용-시점)
 - [빠른 시작](#빠른-시작)
@@ -33,10 +34,22 @@ pnpm dlx @fluojs/cli new my-app
 - 지원되는 설치 경로는 전역 패키지(`npm install -g @fluojs/cli`, `pnpm add -g @fluojs/cli`, `bun add -g @fluojs/cli`, `yarn global add @fluojs/cli`)와 무설치 실행 경로(`pnpm dlx @fluojs/cli ...`)입니다.
 - 배포되는 `fluo` bin은 `package.json`에 선언된 dist 빌드 CLI 엔트리포인트를 기준으로 동작합니다.
 
+## 버전 확인
+
+Interactive update check를 실행하지 않고 설치된 CLI 버전을 확인합니다:
+
+```bash
+fluo version
+fluo --version
+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 결과를 재사용합니다.
+
 업데이트 확인은 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`을 설정하세요.
 
 ## 사용 시점
@@ -57,6 +70,14 @@ cd my-app
 pnpm dev
 ```
 
+`fluo create`는 `fluo new`의 alias입니다. 버전 확인, 명령 도움말, 진단, first-party package shortcut, upgrade 안내가 필요하면 `fluo version`, `fluo help <command>`, `fluo doctor`/`fluo info`/`fluo analyze`, `fluo add`, `fluo upgrade`를 사용하세요.
+
+생성된 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`)를 사용하세요.
+
+생성된 non-Deno starter의 `vite.config.ts`는 `@fluojs/vite`에서 `fluoDecoratorsPlugin()`을 import합니다. 따라서 decorator transform 업데이트는 각 신규 프로젝트에 inline 복사되는 대신 유지보수되는 Vite 패키지를 통해 전달됩니다.
+
+생성된 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`으로 지정하세요.
+
 `fluo new`는 같은 Node 기반 설치/빌드 흐름 위에서 Node.js + Fastify, Express, raw Node.js HTTP 애플리케이션 스타터를 제공합니다.
 
 ```bash
@@ -85,7 +106,7 @@ fluo new my-mqtt-service --shape microservice --transport mqtt --runtime node --
 fluo new my-grpc-service --shape microservice --transport grpc --runtime node --platform none
 ```
 
-지원되는 `--shape microservice --transport` 스타터 값은 정확히 `tcp`, `redis-streams`, `nats`, `kafka`, `rabbitmq`, `mqtt`, `grpc`입니다. 이전 문서에 있던 `redis` 값은 더 이상 제공되는 스타터 계약에 포함되지 않으며, 유지보수되는 Redis 기반 스타터가 필요하면 `redis-streams`를 사용하고, 더 넓은 Redis 통합 패턴이 필요하면 스캐폴딩 후 `@fluojs/redis`를 수동으로 추가하세요.
+지원되는 `--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 계약이 됩니다.
 
@@ -110,16 +131,23 @@ plan preview 모드는 실제 scaffold와 같은 프로젝트 이름, shape, run
 현재 제공되는 스타터 매트릭스(Node.js Fastify/Express/raw Node.js HTTP, Bun, Deno, Cloudflare Workers, TCP/Redis Streams/NATS/Kafka/RabbitMQ/MQTT/gRPC microservice, 그리고 mixed)와 남아 있는 더 넓은 어댑터 생태계를 문서 수준에서 구분한 표는 [fluo new 지원 매트릭스](../../docs/reference/fluo-new-support-matrix.ko.md)를 확인하세요. `@fluojs/redis` 같은 패키지 수준 통합은 더 넓은 생태계에 남아 있지만, 추가 `fluo new --transport` 스타터 플래그는 아닙니다.
 
 ### 2. 기능 추가
-컨트롤러와 서비스가 포함된 새 리소스를 추가하고, 모듈에 자동으로 연결합니다.
+feature slice를 생성합니다. 일부 schematic은 모듈에 자동 등록되고, 일부는 파일만 생성하므로 직접 wiring해야 합니다.
 
 ```bash
 fluo generate module users
+fluo generate resource users
 fluo generate controller users
 fluo generate service users
 fluo generate request-dto users CreateUser
 fluo generate service users --dry-run
 ```
 
+지원되는 generator kind와 alias는 `controller`/`co`, `guard`/`gu`, `interceptor`/`in`, `middleware`/`mi`, `module`/`mo`, `repo`/`repository`, `request-dto`/`req`, `resource`/`resrc`, `response-dto`/`res`, `service`/`s`입니다.
+
+자동 등록되는 generator는 `controller`, `service`, `repo`, `guard`, `interceptor`, `middleware`입니다. 파일만 생성하는 generator는 `module`, `request-dto`, `response-dto`, `resource`입니다.
+
+`fluo generate resource <name>`는 module, controller, service, repository, request DTO, response DTO, test를 포함하는 완전한 feature slice를 생성합니다. 생성된 resource module은 parent module에 자동으로 연결하지 않으므로, slice를 활성화할 준비가 되었을 때 직접 import하세요.
+
 Request DTO 생성은 feature 디렉터리와 DTO 클래스 이름을 분리해서 받습니다. 따라서 `CreateUser`, `UpdateUser` 같은 여러 입력 계약을 같은 `src/users/` 슬라이스 안에 둘 수 있습니다.
 
 `--dry-run`을 추가하면 실제 실행과 같은 타깃 해석, 기존 파일 건너뛰기 또는 덮어쓰기 판단, 모듈 자동 등록 계획, 파일만 생성하는 wiring 상태, 다음 단계 힌트를 미리 볼 수 있습니다. 이 모드는 디렉터리 생성, 파일 쓰기, 모듈 갱신을 수행하지 않습니다. `--force`는 내용이 달라질 기존 파일의 계획 항목을 `SKIP`에서 `OVERWRITE`로 바꾸며, `--target-directory`는 실제 실행과 동일하게 지정한 소스 디렉터리 기준으로 preview 범위를 제한합니다.
@@ -128,6 +156,52 @@ Generator discovery는 의도적으로 built-in `@fluojs/cli/builtin` collection
 
 ## 주요 패턴
 
+### 진단과 프로젝트 스크립트
+설치된 CLI, npm dist-tag, update-check cache 상태, runtime, project script를 확인해야 할 때는 `doctor`/`info`를 사용합니다:
+
+```bash
+fluo doctor
+fluo info
+fluo analyze
+```
+
+`fluo analyze`는 read-only로 동작하며 더 깊은 `inspect --report`와 `migrate --json` workflow를 안내합니다. 생성된 Node.js 프로젝트에서는 `fluo dev`, `fluo build`, `fluo start`가 환경 기본값 및 project-local toolchain binary와 함께 생성 lifecycle을 직접 실행합니다. 생성된 Bun, Deno, Cloudflare Workers 프로젝트에서는 `fluo dev`가 runtime-owned watch loop를 기본값으로 사용하고, `fluo dev --runner fluo`가 CLI 소유 restart boundary를 복원합니다. production/deployment에는 생성된 package script(`bun dist/main.js`, `./dist/app`, Wrangler `preview`/`deploy`)를 사용합니다. lifecycle 명령은 `--dry-run`으로 미리 확인할 수 있습니다:
+
+```bash
+fluo dev --dry-run
+fluo build --dry-run
+fluo start --dry-run
+```
+
+`fluo dev --dry-run`은 watch boundary도 함께 표시합니다. 생성된 Node 프로젝트는 기본적으로 `Watch mode: fluo-restart`를 보여 주며, Node의 `--raw-watch` 또는 `FLUO_DEV_RAW_WATCH=1`은 `Watch mode: native-watch`를 보여 줍니다. Bun/Deno/Workers 프로젝트는 기본적으로 `Watch mode: runtime-native-watch`를 보여 주며, `--runner fluo` 또는 `FLUO_DEV_RUNNER=fluo`를 사용하면 `Watch mode: fluo-restart`로 fluo 소유 restart runner가 복원됩니다.
+
+CLI process boundary를 조정해야 할 때는 런타임 앱 로깅이 아니라 reporter flag를 사용하세요:
+
+```bash
+# 기본값: child stdout/stderr만 표시, fluo lifecycle UI 없음
+fluo dev
+
+# opt-in pretty lifecycle UI + app │ prefix
+fluo dev --reporter pretty
+
+# 디버깅용 raw 런타임/도구 출력(Watcher 배너, native dev UI 등)
+fluo dev --reporter stream
+fluo dev --verbose
+FLUO_VERBOSE=1 fluo dev
+
+# child stderr와 실패는 보존하면서 wrapper/tool status는 숨김
+fluo build --reporter silent
+```
+
+런타임 애플리케이션 로그는 `ApplicationLogger`로 별도 설정합니다. 예를 들어 `@fluojs/runtime/node`의 `createConsoleApplicationLogger({ mode: 'minimal', level: 'warn' })` 또는 `createJsonApplicationLogger()`를 사용하세요.
+
+first-party package 설치 shortcut에는 `fluo add <package>`를 사용하고, CLI/latest-version 및 migration 안내는 `fluo upgrade`로 확인합니다:
+
+```bash
+fluo add studio --dev --dry-run
+fluo upgrade
+```
+
 ### 데코레이터 코드 변환
 코드베이스를 TC39 표준 데코레이터에 맞게 조정하는 codemod를 실행합니다.
 
@@ -139,13 +213,18 @@ fluo migrate ./src --json
 # 변환 적용
 fluo migrate ./src --apply
 fluo migrate ./src --apply --json
+fluo migrate ./src --only imports,inject-params
+fluo migrate ./src --skip tests
 ```
 
 CI 작업, 대시보드, migration report에서 안정적인 machine-readable 결과가 필요하면 `--json`을 사용하세요. 사람을 위한 출력은 기본값으로 유지됩니다. JSON 모드는 성공 시 stdout에 structured report만 기록하고, parser 오류나 잘못된 flag 조합은 기존처럼 stderr에 메시지를 기록한 뒤 exit code `1`을 반환하며 partial JSON을 출력하지 않습니다. Report에는 `mode`(`dry-run` 또는 `apply`), `dryRun`, `apply`, 활성화된 `transforms`, `scannedFiles`, `changedFiles`, 전체 `warningCount`, 그리고 `filePath`, `changed`, `appliedTransforms`, `warningCount`, category label과 source line number가 포함된 warnings per-file metadata가 포함됩니다.
 
 **주요 변환 사항:**
 - `@nestjs/common` 임포트를 `@fluojs/core` 또는 `@fluojs/http`로 재작성합니다.
+- bootstrap 패턴을 재작성하고 지원되는 `listen(port)` 호출을 fluo runtime startup 규칙으로 접습니다.
+- constructor parameter `@Inject(...)` 사용을 fluo 호환 의존성 선언으로 migration합니다.
 - `@Injectable()`을 제거하고 스코프를 `@Scope()`로 매핑합니다.
+- 안전하게 변환 가능한 test template을 `@fluojs/testing` helper 쪽으로 migration합니다.
 - `tsconfig.json`을 업데이트하여 `experimentalDecorators`를 비활성화하고 `baseUrl` 기반 경로 별칭을 TS6-safe `paths` 엔트리로 재작성합니다.
 
 ### 런타임 검사 (Inspection)
@@ -166,9 +245,12 @@ fluo inspect ./src/app.module.ts --json --timing
 
 # 요약, snapshot, diagnostics, timing을 포함한 support triage report 내보내기
 fluo inspect ./src/app.module.ts --report --output artifacts/inspect-report.json
+
+# 특정 module export 검사; 기본값은 AppModule
+fluo inspect ./src/app.module.ts --export AdminModule --json
 ```
 
-런타임이 inspection snapshot을 생산합니다. `fluo inspect`는 그 snapshot을 JSON으로 직렬화하고, `fluo inspect --mermaid`는 snapshot-to-Mermaid 렌더링을 선택적 `@fluojs/studio` 계약에 위임합니다. `--timing`은 JSON 출력에 bootstrap timing diagnostics를 기록하고, `--report`는 CI/support triage를 위해 런타임이 생산한 snapshot을 안정적인 요약과 함께 감쌉니다. `--output <path>`는 선택한 inspect payload를 stdout 대신 명시적 artifact 경로에 씁니다. 이 동작은 검사 대상 애플리케이션을 writable하게 만들지 않으며, 일반 bootstrap/close cycle 외에 module graph state를 바꾸지 않습니다. Mermaid 출력이 필요하면 명령을 실행하는 프로젝트에 Studio를 설치하세요:
+런타임이 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를 설치하세요:
 
 ```bash
 pnpm add -D @fluojs/studio
@@ -183,9 +265,13 @@ Studio가 없으면 CI와 non-interactive 실행은 prompt나 package manager
 | 익스포트 | 설명 |
 |---|---|
 | `runCli(argv?, options?)` | 모든 CLI 명령을 실행하는 메인 진입점입니다. |
+| `newUsage()` | help surface와 test에서 사용하는 현재 `fluo new` usage text를 반환합니다. |
 | `runNewCommand(argv, options?)` | 프로젝트 스캐폴딩 로직에 대한 프로그래밍적 접근을 제공합니다. |
 | `CliPromptCancelledError` | 호출자가 제공한 prompt hook이 정상 취소를 알리기 위해 throw할 수 있는 안정적인 sentinel입니다. |
+| `GenerateOptions` | 프로그래밍 방식 generator 옵션 타입입니다. |
+| `GeneratedFile` | 생성된 파일 경로, 내용, write status를 설명하는 타입입니다. |
 | `GeneratorKind` | 지원되는 모든 생성기 유형(예: `'controller'`, `'service'`)의 유니온 타입입니다. |
+| `ModuleRegistration` | generator 실행의 module wiring 결과를 설명하는 타입입니다. |
 
 프로그래밍 방식 진입점은 호출자 프로세스의 소유권을 보존합니다. `runCli(...)`와 `runNewCommand(...)`는 `process.exit(...)`를 호출하지 않고 숫자 exit code를 반환하며, prompt 취소는 command runner를 통해 exit code `0`으로 해석됩니다. dependency 설치나 git 초기화 같은 setup 작업은 해석된 `fluo new` 옵션이 요청한 경우에만 실행됩니다. 호출자가 제공한 prompt hook은 공개 패키지 엔트리포인트의 `CliPromptCancelledError`를 throw해 CLI 내부 파일에 의존하지 않고 정상 취소를 표현할 수 있습니다.
 
@@ -194,11 +280,19 @@ Studio가 없으면 CI와 non-interactive 실행은 prompt나 package manager
 - **[@fluojs/runtime](../runtime/README.ko.md)**: 부트스트랩 안전 런타임 검사 중 inspection snapshot을 생산하는 기본 엔진입니다.
 - **[@fluojs/studio](../studio/README.ko.md)**: `inspect --json` 출력을 확인하고 `inspect --mermaid`가 사용하는 canonical renderer를 제공하는 웹 기반 UI입니다.
 - **[@fluojs/testing](../testing/README.ko.md)**: 통합 및 E2E 테스트를 위해 생성된 테스트 템플릿에서 사용됩니다.
+- **[@fluojs/vite](../vite/README.ko.md)**: 생성된 starter의 Vite decorator transform plugin을 제공합니다.
 - **[Canonical Runtime Package Matrix](../../docs/reference/package-surface.ko.md)**: 공식 런타임/패키지 조합을 보여주는 기준 문서입니다.
 
 ## 예제 소스
 
 - [cli.ts](./src/cli.ts) - 명령 디스패처 및 인자 파싱.
 - [commands/new.ts](./src/commands/new.ts) - 프로젝트 스캐폴딩 구현.
+- [commands/inspect.ts](./src/commands/inspect.ts) - 런타임 검사 export mode와 Studio 위임.
+- [commands/migrate.ts](./src/commands/migrate.ts) - decorator codemod, JSON report, transform filter.
+- [commands/package-workflow.ts](./src/commands/package-workflow.ts) - `fluo add`와 `fluo upgrade` workflow.
+- [commands/scripts.ts](./src/commands/scripts.ts) - `dev`, `build`, `start` lifecycle command boundary.
+- [update-check.ts](./src/update-check.ts) - interactive latest-version update check와 opt-out 처리.
+- [new/](./src/new/) - starter matrix 해석, prompt, scaffold 실행.
+- [dev-runner/](./src/dev-runner/) - Node restart-on-watch process boundary.
 - [generators/](./src/generators/) - 템플릿 기반 파일 생성 로직.
 - [transforms/](./src/transforms/) - 코드 변환 구현.

package/README.md

@@ -7,6 +7,7 @@ The canonical CLI for fluo — bootstrap new applications, generate components,
 ## Table of Contents
 
 - [Installation](#installation)
+- [Version Inspection](#version-inspection)
 - [Update Checks](#update-checks)
 - [When to Use](#when-to-use)
 - [Quick Start](#quick-start)
@@ -33,10 +34,22 @@ pnpm dlx @fluojs/cli new my-app
 - 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 backed by the dist-built CLI entrypoint declared in `package.json`.
 
+## Version Inspection
+
+Check the installed CLI version without triggering the interactive update check:
+
+```bash
+fluo version
+fluo --version
+fluo -v
+```
+
 ## Update Checks
 
 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.
+
 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.
 
 ## When to Use
@@ -57,6 +70,14 @@ cd my-app
 pnpm dev
 ```
 
+`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 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.
+
+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.
+
 `fluo new` supports Node.js + Fastify, Express, and raw Node.js HTTP application starters on the same Node-oriented install/build flow:
 
 ```bash
@@ -85,7 +106,7 @@ fluo new my-mqtt-service --shape microservice --transport mqtt --runtime node --
 fluo new my-grpc-service --shape microservice --transport grpc --runtime node --platform none
 ```
 
-Supported `--shape microservice --transport` starter values are exactly `tcp`, `redis-streams`, `nats`, `kafka`, `rabbitmq`, `mqtt`, and `grpc`. Earlier docs mentioned `redis`, but that value is no longer part of the shipped starter contract; use `redis-streams` for the maintained Redis-backed starter, or add `@fluojs/redis` manually after scaffolding when you need broader Redis integration patterns.
+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.
 
@@ -110,16 +131,23 @@ Plan preview mode resolves the same project name, shape, runtime, platform, tran
 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.
 
 ### 2. Generate a feature
-Add a new resource with a controller and service, automatically wired into the module.
+Generate a feature slice; some schematics auto-register in the module, while others are files-only and must be wired manually.
 
 ```bash
 fluo generate module users
+fluo generate resource users
 fluo generate controller users
 fluo generate service users
 fluo generate request-dto users CreateUser
 fluo generate service users --dry-run
 ```
 
+Supported generator kinds and aliases are `controller`/`co`, `guard`/`gu`, `interceptor`/`in`, `middleware`/`mi`, `module`/`mo`, `repo`/`repository`, `request-dto`/`req`, `resource`/`resrc`, `response-dto`/`res`, and `service`/`s`.
+
+Auto-registered generators are `controller`, `service`, `repo`, `guard`, `interceptor`, and `middleware`. Files-only generators are `module`, `request-dto`, `response-dto`, and `resource`.
+
+`fluo generate resource <name>` creates a complete feature slice with a module, controller, service, repository, request DTO, response DTO, and tests. It does not wire the resource module into a parent module automatically; import the generated module when you are ready to activate the slice.
+
 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.
 
 Add `--dry-run` to preview the same target resolution, skipped or overwritten file decisions, module auto-registration plan, files-only wiring status, and next-step hint without creating directories, writing files, or updating modules. `--force` still changes existing-file plan entries from `SKIP` to `OVERWRITE` when content would change, and `--target-directory` scopes the preview to that source directory exactly as it does for a real run.
@@ -128,6 +156,52 @@ Generator discovery is intentionally limited to the built-in `@fluojs/cli/builti
 
 ## Common Patterns
 
+### Diagnostics and project scripts
+Use `doctor`/`info` when you need to debug the installed CLI, npm dist-tags, update-check cache state, runtime, and project scripts:
+
+```bash
+fluo doctor
+fluo info
+fluo analyze
+```
+
+`fluo analyze` stays read-only and points to deeper `inspect --report` and `migrate --json` workflows. For generated Node.js projects, `fluo dev`, `fluo build`, and `fluo start` run the generated lifecycle directly with environment defaults and project-local toolchain binaries. For generated Bun, Deno, and Cloudflare Workers projects, `fluo dev` defaults to the runtime-owned watch loop while `fluo dev --runner fluo` restores the CLI-owned restart boundary; production/deployment scripts are the generated package scripts (`bun dist/main.js`, `./dist/app`, or Wrangler `preview`/`deploy`). Use `--dry-run` to preview lifecycle commands:
+
+```bash
+fluo dev --dry-run
+fluo build --dry-run
+fluo start --dry-run
+```
+
+`fluo dev --dry-run` also reports the watch boundary. Generated Node projects show `Watch mode: fluo-restart` by default, Node `--raw-watch` and `FLUO_DEV_RAW_WATCH=1` show `Watch mode: native-watch`, and Bun/Deno/Workers projects show `Watch mode: runtime-native-watch` by default. Use `--runner fluo` or `FLUO_DEV_RUNNER=fluo` in Bun/Deno/Workers projects to show `Watch mode: fluo-restart` and restore the fluo-owned restart runner.
+
+Use reporter flags when you need to tune the CLI process boundary rather than runtime app logging:
+
+```bash
+# Default: child stdout/stderr only, no fluo lifecycle UI
+fluo dev
+
+# Opt-in pretty lifecycle UI + app │ prefixes
+fluo dev --reporter pretty
+
+# Raw runtime/tooling output for debugging (watcher banners, native dev UI, etc.)
+fluo dev --reporter stream
+fluo dev --verbose
+FLUO_VERBOSE=1 fluo dev
+
+# Suppress wrapper/tool status while keeping child stderr and failures visible
+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`.
+
+Use `fluo add <package>` for first-party package installation shortcuts and `fluo upgrade` for CLI/latest-version and migration guidance:
+
+```bash
+fluo add studio --dev --dry-run
+fluo upgrade
+```
+
 ### Decorator Codemods
 Run codemods to align your codebase with TC39 standard decorators.
 
@@ -139,13 +213,18 @@ 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
 ```
 
 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.
 
 **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.
+- 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.
 - Updates `tsconfig.json` to disable `experimentalDecorators` and rewrites `baseUrl`-backed path aliases to TS6-safe `paths` entries.
 
 ### Runtime Inspection
@@ -166,9 +245,12 @@ fluo inspect ./src/app.module.ts --json --timing
 
 # Emit a support triage report with summary, snapshot, diagnostics, and timing
 fluo inspect ./src/app.module.ts --report --output artifacts/inspect-report.json
+
+# Inspect a named module export; defaults to AppModule
+fluo inspect ./src/app.module.ts --export AdminModule --json
 ```
 
-The runtime produces the inspection snapshot. `fluo inspect` serializes that snapshot as JSON, and `fluo inspect --mermaid` delegates snapshot-to-Mermaid rendering to the optional `@fluojs/studio` contract. `--timing` records bootstrap timing diagnostics for JSON output, and `--report` wraps the runtime-produced snapshot with a stable summary for CI/support triage. `--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` 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:
 
 ```bash
 pnpm add -D @fluojs/studio
@@ -183,9 +265,13 @@ 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. |
+| `newUsage()` | Returns the current `fluo new` usage text for help surfaces and tests. |
 | `runNewCommand(argv, options?)` | Programmatic access to the project scaffolding logic. |
 | `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. |
 | `GeneratorKind` | Union type of all supported generator types (e.g., `'controller'`, `'service'`). |
+| `ModuleRegistration` | Type describing module wiring results from generator runs. |
 
 Programmatic entry points preserve caller process ownership. `runCli(...)` and `runNewCommand(...)` 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. Caller-supplied prompt hooks can throw `CliPromptCancelledError` from the public package entrypoint to express normal cancellation without depending on CLI-internal files.
 
@@ -194,11 +280,19 @@ Programmatic entry points preserve caller process ownership. `runCli(...)` and `
 - **[@fluojs/runtime](../runtime/README.md)**: The underlying engine that produces inspection snapshots during bootstrap-safe runtime inspection.
 - **[@fluojs/studio](../studio/README.md)**: The web-based UI for viewing `inspect --json` exports and the canonical renderer used by `inspect --mermaid`.
 - **[@fluojs/testing](../testing/README.md)**: Used by generated test templates for integration and E2E testing.
+- **[@fluojs/vite](../vite/README.md)**: Provides the generated starter Vite decorator transform plugin.
 - **[Canonical Runtime Package Matrix](../../docs/reference/package-surface.md)**: The source of truth for official runtime/package combinations.
 
 ## Example Sources
 
 - [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/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.
+- [update-check.ts](./src/update-check.ts) - Interactive latest-version update checks and opt-out handling.
+- [new/](./src/new/) - Starter matrix resolution, prompts, and scaffold execution.
+- [dev-runner/](./src/dev-runner/) - Node restart-on-watch process boundary.
 - [generators/](./src/generators/) - Template-based file generation logic.
 - [transforms/](./src/transforms/) - Code transformation implementations.

package/dist/cli.d.ts

@@ -15,6 +15,14 @@ export interface CliRuntimeOptions {
     ci?: boolean;
     cwd?: string;
     env?: NodeJS.ProcessEnv;
+    fetchDistTags?: (packageName: string) => Promise<Record<string, string> | undefined>;
+    spawnCommand?: (command: string, args: string[], options: {
+        cwd: string;
+        env: NodeJS.ProcessEnv;
+        stderr?: CliStream;
+        stdio: 'inherit' | 'pipe';
+        stdout?: CliStream;
+    }) => Promise<number>;
     stderr?: CliStream;
     stdin?: CliReadableStream;
     stdout?: CliStream;

package/dist/cli.d.ts.map

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