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

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,10 @@ cd my-app
 pnpm dev
 ```
 
+생성된 `dev`, `build`, `start` package script는 각각 `fluo dev`, `fluo build`, `fluo start`로 위임합니다. CLI가 런타임별 lifecycle 명령을 소유하고 local toolchain binary를 실행할 때 project-local `node_modules/.bin`을 앞에 붙이며, 호출자가 명시하지 않은 경우 `dev`는 `NODE_ENV=development`, `build`/`start`는 `NODE_ENV=production`을 기본값으로 사용합니다. `fluo dev`는 TTY-aware lifecycle reporter를 사용합니다. Interactive terminal에서는 간결한 fluo-branded status를 보여주고, CI, non-TTY 출력, `--reporter stream`, `--verbose`, `FLUO_VERBOSE=1`에서는 디버깅과 자동화를 위해 raw child-process passthrough를 유지합니다. Cloudflare Workers의 `start`는 배포하지 않고 Wrangler remote preview를 열며, Cloudflare에 게시하려면 명시적인 deploy 명령을 사용하세요.
+
+Node.js 프로젝트에서 `fluo dev`는 더 이상 곧바로 `node --watch`에 위임하지 않고 fluo가 소유한 restart boundary를 거칩니다. 이 runner는 source와 주요 config 입력을 watch하고, atomic-save event burst를 debounce하며, restart 전에 파일 content hash를 비교하고, spawn하는 각 앱 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이며 true module-level HMR이 아닙니다. Config watch reload는 별도의 in-process config 관심사이고, 향후 HMR 작업은 어떤 모듈을 안전하게 hot-swap할 수 있는지 따로 문서화해야 합니다. 디버깅을 위해 런타임 native Node watcher로 되돌리려면 `fluo dev --raw-watch` 또는 `FLUO_DEV_RAW_WATCH=1`을 사용하고, 추가 ignore 경로는 `FLUO_DEV_WATCH_IGNORE=path,pattern`으로 지정하세요.
+
 `fluo new`는 같은 Node 기반 설치/빌드 흐름 위에서 Node.js + Fastify, Express, raw Node.js HTTP 애플리케이션 스타터를 제공합니다.
 
 ```bash
@@ -114,12 +131,15 @@ plan preview 모드는 실제 scaffold와 같은 프로젝트 이름, shape, run
 
 ```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
 ```
 
+`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 +148,49 @@ 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를 안내합니다. 생성된 프로젝트에서는 `fluo dev`, `fluo build`, `fluo start`가 환경 기본값 및 project-local toolchain binary와 함께 생성 lifecycle을 직접 실행합니다. lifecycle 명령은 `--dry-run`으로 미리 확인할 수 있습니다:
+
+```bash
+fluo dev --dry-run
+fluo build --dry-run
+fluo start --dry-run
+```
+
+`fluo dev --dry-run`은 watch boundary도 함께 표시합니다. Node.js 프로젝트는 기본적으로 `Watch mode: fluo-node-restart`를 보여 주며, `--raw-watch` 또는 `FLUO_DEV_RAW_WATCH=1`을 쓰면 `Watch mode: native-watch`를 보여 줍니다. Bun, Deno, Cloudflare Workers는 계속 각 런타임의 native dev watcher를 사용합니다.
+
+CLI process boundary를 조정해야 할 때는 런타임 앱 로깅이 아니라 reporter flag를 사용하세요:
+
+```bash
+# TTY에서는 pretty status, CI/non-TTY에서는 raw passthrough (기본값)
+fluo dev
+
+# child process log를 디버깅하기 위한 기존 passthrough에 가까운 출력
+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를 실행합니다.
 

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,10 @@ cd my-app
 pnpm dev
 ```
 
+Generated `dev`, `build`, and `start` package scripts delegate to `fluo dev`, `fluo build`, and `fluo start`. The CLI owns the runtime-specific 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. `fluo dev` uses a TTY-aware lifecycle reporter: interactive terminals get concise fluo-branded status while CI, non-TTY output, `--reporter stream`, `--verbose`, and `FLUO_VERBOSE=1` keep raw child-process passthrough available for debugging and automation. Cloudflare Workers `start` opens a remote Wrangler preview instead of deploying; use an explicit deploy command when you intend to publish to Cloudflare.
+
+For Node.js projects, `fluo dev` now runs through a fluo-owned restart boundary instead of delegating directly to `node --watch`. The runner watches source and common config inputs, debounces atomic-save bursts, hashes file content before restarting, loads `.env` for each 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 remains full-process restart-on-watch, not true 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` to restore the runtime-native Node watcher for debugging, and use `FLUO_DEV_WATCH_IGNORE=path,pattern` to add extra ignored paths.
+
 `fluo new` supports Node.js + Fastify, Express, and raw Node.js HTTP application starters on the same Node-oriented install/build flow:
 
 ```bash
@@ -114,12 +131,15 @@ Add a new resource with a controller and service, automatically wired into the m
 
 ```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
 ```
 
+`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 +148,49 @@ 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 projects, `fluo dev`, `fluo build`, and `fluo start` run the generated lifecycle directly with environment defaults and project-local toolchain binaries. 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. Node.js projects show `Watch mode: fluo-node-restart` by default, while `--raw-watch` and `FLUO_DEV_RAW_WATCH=1` show `Watch mode: native-watch`. Bun, Deno, and Cloudflare Workers still use their runtime-native dev watchers.
+
+Use reporter flags when you need to tune the CLI process boundary rather than runtime app logging:
+
+```bash
+# Pretty status in TTY, raw passthrough in CI/non-TTY (default)
+fluo dev
+
+# Current passthrough-like output for debugging child process logs
+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.
 

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;AA+VD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,MAAM,CAC1B,IAAI,WAAwB,EAC5B,OAAO,GAAE,iBAAiB,GAAG,wBAAwB,GAAG,4BAAiC,GACxF,OAAO,CAAC,MAAM,CAAC,CAsNjB"}

package/dist/cli.js

@@ -1,10 +1,14 @@
-import { existsSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { diagnosticsUsage, runAnalyzeCommand, runDoctorCommand, runInfoCommand } from './commands/diagnostics.js';
 import { runGenerateCommand } from './commands/generate.js';
 import { inspectUsage, runInspectCommand } from './commands/inspect.js';
 import { migrateUsage, runMigrateCommand } from './commands/migrate.js';
 import { newUsage, runNewCommand } from './commands/new.js';
+import { addUsage, runAddCommand, runUpgradeCommand, upgradeUsage } from './commands/package-workflow.js';
+import { runScriptCommand, scriptUsage } from './commands/scripts.js';
+import { runNodeRestartRunner } from './dev-runner/node-restart-runner.js';
 import { builtInGeneratorCollection, generatorManifest, generatorOptionSchemas, resolveGeneratorKind } from './generators/manifest.js';
 import { renderAliasList, renderHelpTable } from './help.js';
 import { removeUpdateCheckFlags, runCliUpdateCheck } from './update-check.js';
@@ -33,6 +37,34 @@ const TOP_LEVEL_COMMAND_HELP = [{
   aliases: ['g'],
   command: 'generate',
   description: 'Generate a schematic inside an existing fluo application.'
+}, {
+  aliases: ['info'],
+  command: 'doctor',
+  description: 'Print CLI, registry, update-cache, runtime, and project diagnostics.'
+}, {
+  aliases: [],
+  command: 'analyze',
+  description: 'Summarize project diagnostics and point to deeper inspection flows.'
+}, {
+  aliases: [],
+  command: 'dev',
+  description: 'Run the generated project development lifecycle.'
+}, {
+  aliases: [],
+  command: 'start',
+  description: 'Run the generated project production lifecycle.'
+}, {
+  aliases: [],
+  command: 'build',
+  description: 'Run the generated project build lifecycle.'
+}, {
+  aliases: [],
+  command: 'add',
+  description: 'Install @fluojs packages with the detected package manager.'
+}, {
+  aliases: [],
+  command: 'upgrade',
+  description: 'Report latest CLI state and migration workflow guidance.'
 }, {
   aliases: [],
   command: 'inspect',
@@ -41,17 +73,36 @@ const TOP_LEVEL_COMMAND_HELP = [{
   aliases: [],
   command: 'migrate',
   description: 'Run NestJS-to-fluo codemods (dry-run by default).'
+}, {
+  aliases: ['--version', '-v'],
+  command: 'version',
+  description: 'Print the installed fluo CLI version.'
 }, {
   aliases: [],
   command: 'help',
   description: 'Show top-level or command-specific help.'
 }];
+const NODE_DEV_RUNNER_COMMAND = '__node-dev-runner';
 function normalizeGeneratorKind(value) {
   return resolveGeneratorKind(value);
 }
 function isHelpFlag(value) {
   return value === '--help' || value === '-h';
 }
+function isVersionCommand(value) {
+  return value === 'version' || value === '--version' || value === '-v';
+}
+function isCreationCommand(value) {
+  return value === 'new' || value === 'create';
+}
+function readCliVersion() {
+  const packageJsonPath = fileURLToPath(new URL('../package.json', import.meta.url));
+  const manifest = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+  if (typeof manifest !== 'object' || manifest === null || !('version' in manifest) || typeof manifest.version !== 'string') {
+    throw new Error('Unable to determine the installed fluo CLI version.');
+  }
+  return manifest.version;
+}
 function generateUsage() {
   return ['Usage: fluo generate|g <kind> <name> [options]', '       fluo generate|g request-dto|req <feature> <name> [options]', '', 'Schematics', renderHelpTable(GENERATE_KIND_HELP, [{
     header: 'Schematic',
@@ -173,6 +224,42 @@ function parseGenerateArgs(argv) {
 }
 function parseCommand(argv) {
   const [command] = argv;
+  if (command === 'analyze') {
+    return {
+      argv: argv.slice(1),
+      command: 'analyze'
+    };
+  }
+  if (command === 'add') {
+    return {
+      argv: argv.slice(1),
+      command: 'add'
+    };
+  }
+  if (command === 'doctor') {
+    return {
+      argv: argv.slice(1),
+      command: 'doctor'
+    };
+  }
+  if (command === 'info') {
+    return {
+      argv: argv.slice(1),
+      command: 'info'
+    };
+  }
+  if (command === 'build' || command === 'dev' || command === 'start') {
+    return {
+      argv: argv.slice(1),
+      command
+    };
+  }
+  if (command === 'upgrade') {
+    return {
+      argv: argv.slice(1),
+      command: 'upgrade'
+    };
+  }
   if (command === 'new' || command === 'create') {
     return {
       argv: argv.slice(1),
@@ -225,14 +312,33 @@ export async function runCli(argv = process.argv.slice(2), runtime = {}) {
   const stdout = runtime.stdout ?? process.stdout;
   const stderr = runtime.stderr ?? process.stderr;
   const env = runtime.env ?? process.env;
+  const commandRuntime = {
+    ...runtime,
+    env
+  };
   const updateFlagResult = removeUpdateCheckFlags(argv);
   const commandArgv = updateFlagResult.argv;
   try {
+    if (commandArgv[0] === NODE_DEV_RUNNER_COMMAND) {
+      const separatorIndex = commandArgv.indexOf('--');
+      const appArgs = separatorIndex >= 0 ? commandArgv.slice(separatorIndex + 1) : commandArgv.slice(1);
+      return runNodeRestartRunner({
+        appArgs,
+        env,
+        stderr,
+        stdout
+      });
+    }
+    if (isVersionCommand(commandArgv[0])) {
+      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,
@@ -255,6 +361,26 @@ export async function runCli(argv = process.argv.slice(2), runtime = {}) {
         stdout.write(`${generateUsage()}\n`);
         return 0;
       }
+      if (topic === 'doctor' || topic === 'info') {
+        stdout.write(`${diagnosticsUsage('doctor')}\n`);
+        return 0;
+      }
+      if (topic === 'analyze') {
+        stdout.write(`${diagnosticsUsage('analyze')}\n`);
+        return 0;
+      }
+      if (topic === 'build' || topic === 'dev' || topic === 'start') {
+        stdout.write(`${scriptUsage(topic)}\n`);
+        return 0;
+      }
+      if (topic === 'add') {
+        stdout.write(`${addUsage()}\n`);
+        return 0;
+      }
+      if (topic === 'upgrade') {
+        stdout.write(`${upgradeUsage()}\n`);
+        return 0;
+      }
       if (topic === 'migrate') {
         stdout.write(`${migrateUsage()}\n`);
         return 0;
@@ -274,6 +400,26 @@ export async function runCli(argv = process.argv.slice(2), runtime = {}) {
       stdout.write(`${generateUsage()}\n`);
       return 0;
     }
+    if ((commandArgv[0] === 'doctor' || commandArgv[0] === 'info') && commandArgv.slice(1).some(isHelpFlag)) {
+      stdout.write(`${diagnosticsUsage('doctor')}\n`);
+      return 0;
+    }
+    if (commandArgv[0] === 'analyze' && commandArgv.slice(1).some(isHelpFlag)) {
+      stdout.write(`${diagnosticsUsage('analyze')}\n`);
+      return 0;
+    }
+    if ((commandArgv[0] === 'build' || commandArgv[0] === 'dev' || commandArgv[0] === 'start') && commandArgv.slice(1).some(isHelpFlag)) {
+      stdout.write(`${scriptUsage(commandArgv[0])}\n`);
+      return 0;
+    }
+    if (commandArgv[0] === 'add' && commandArgv.slice(1).some(isHelpFlag)) {
+      stdout.write(`${addUsage()}\n`);
+      return 0;
+    }
+    if (commandArgv[0] === 'upgrade' && commandArgv.slice(1).some(isHelpFlag)) {
+      stdout.write(`${upgradeUsage()}\n`);
+      return 0;
+    }
     if (commandArgv[0] === 'migrate' && commandArgv.slice(1).some(isHelpFlag)) {
       stdout.write(`${migrateUsage()}\n`);
       return 0;
@@ -283,14 +429,35 @@ export async function runCli(argv = process.argv.slice(2), runtime = {}) {
       return 0;
     }
     const parsedCommand = parseCommand(commandArgv);
+    if (parsedCommand.command === 'analyze') {
+      return runAnalyzeCommand(parsedCommand.argv, commandRuntime);
+    }
+    if (parsedCommand.command === 'add') {
+      return runAddCommand(parsedCommand.argv, commandRuntime);
+    }
+    if (parsedCommand.command === 'doctor') {
+      return runDoctorCommand(parsedCommand.argv, commandRuntime);
+    }
+    if (parsedCommand.command === 'info') {
+      return runInfoCommand(parsedCommand.argv, commandRuntime);
+    }
+    if (parsedCommand.command === 'build' || parsedCommand.command === 'dev' || parsedCommand.command === 'start') {
+      return runScriptCommand(parsedCommand.command, parsedCommand.argv, commandRuntime);
+    }
+    if (parsedCommand.command === 'upgrade') {
+      return runUpgradeCommand(parsedCommand.argv, commandRuntime);
+    }
     if (parsedCommand.command === 'new') {
-      return runNewCommand(parsedCommand.argv, runtime);
+      return runNewCommand(parsedCommand.argv, commandRuntime);
     }
     if (parsedCommand.command === 'migrate') {
-      return runMigrateCommand(parsedCommand.argv, runtime);
+      return runMigrateCommand(parsedCommand.argv, commandRuntime);
     }
     if (parsedCommand.command === 'inspect') {
-      return runInspectCommand(parsedCommand.argv, runtime);
+      return runInspectCommand(parsedCommand.argv, commandRuntime);
+    }
+    if (parsedCommand.command !== 'generate') {
+      throw new Error(usage());
     }
     const targetDirectory = resolve(cwd, parsedCommand.parsed.targetDirectory ?? resolveDefaultTargetDirectory(cwd));
     const result = runGenerateCommand(parsedCommand.parsed.kind, parsedCommand.parsed.name, targetDirectory, parsedCommand.parsed.options);

package/dist/commands/diagnostics.d.ts

@@ -0,0 +1,15 @@
+type CliStream = {
+    write(message: string): unknown;
+};
+type DiagnosticRuntimeOptions = {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    fetchDistTags?: (packageName: string) => Promise<Record<string, string> | undefined>;
+    stdout?: CliStream;
+};
+export declare function diagnosticsUsage(command?: 'analyze' | 'doctor' | 'info'): string;
+export declare function runDoctorCommand(argv: string[], runtime?: DiagnosticRuntimeOptions): Promise<number>;
+export declare function runInfoCommand(argv: string[], runtime?: DiagnosticRuntimeOptions): Promise<number>;
+export declare function runAnalyzeCommand(argv: string[], runtime?: DiagnosticRuntimeOptions): Promise<number>;
+export {};
+//# sourceMappingURL=diagnostics.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/commands/diagnostics.ts"],"names":[],"mappings":"AAKA,KAAK,SAAS,GAAG;IACf,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC,CAAC;AAEF,KAAK,wBAAwB,GAAG;IAC9B,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,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB,CAAC;AAuHF,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,SAAS,GAAG,QAAQ,GAAG,MAAiB,GAAG,MAAM,CAoB1F;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,wBAA6B,GAAG,OAAO,CAAC,MAAM,CAAC,CAgC9G;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,wBAA6B,GAAG,OAAO,CAAC,MAAM,CAAC,CAO5G;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,wBAA6B,GAAG,OAAO,CAAC,MAAM,CAAC,CAsB/G"}