@fluojs/cli 1.0.0-beta.1 → 1.0.0-beta.2

package/README.ko.md

@@ -2,11 +2,12 @@
 
 <p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
 
-fluo 공식 CLI — 새 애플리케이션 부트스트랩, 컴포넌트 생성, 런타임 그래프 검사, 코드 변환을 지원합니다.
+fluo 공식 CLI — 새 애플리케이션 부트스트랩, 컴포넌트 생성, 런타임 검사 데이터 내보내기, 코드 변환을 지원합니다.
 
 ## 목차
 
 - [설치](#설치)
+- [업데이트 확인](#업데이트-확인)
 - [사용 시점](#사용-시점)
 - [빠른 시작](#빠른-시작)
 - [주요 패턴](#주요-패턴)
@@ -32,12 +33,18 @@ pnpm dlx @fluojs/cli new my-app
 - 지원되는 설치 경로는 전역 패키지(`pnpm add -g @fluojs/cli`)와 무설치 실행 경로(`pnpm dlx @fluojs/cli ...`)입니다.
 - 배포되는 `fluo` bin은 `package.json`에 선언된 dist 빌드 CLI 엔트리포인트를 기준으로 동작합니다.
 
+## 업데이트 확인
+
+`fluo`가 interactive TTY에서 실행되면 로컬 캐시를 사용해 공개 npm `latest` dist-tag의 `@fluojs/cli` 버전을 확인하므로 매 invocation마다 registry를 호출하지 않습니다. 더 새로운 버전이 있으면 CLI가 설치 여부를 묻습니다. 거절하면 현재 설치된 버전으로 기존 명령을 계속 실행하고, 승인하면 `pnpm add -g @fluojs/cli@<latest>`를 실행한 뒤 같은 인자로 업데이트된 `fluo` 바이너리를 다시 시작합니다.
+
+업데이트 확인은 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`을 설정하세요.
+
 ## 사용 시점
 
 - **부트스트랩**: 표준적이고 검증 가능한 구조로 새 프로젝트를 시작할 때.
 - **코드 생성**: 일관된 네이밍 규칙과 자동 연결 기능을 갖춘 모듈, 컨트롤러, 서비스, 레포지토리를 생성할 때.
 - **코드 변환**: 기존 코드베이스를 fluo의 표준 데코레이터 모델에 맞출 때.
-- **검사(Inspection)**: 런타임 의존성 그래프를 시각화하고 플랫폼 수준의 문제를 진단할 때.
+- **검사(Inspection)**: 런타임 snapshot 데이터를 내보내고 그래프 보기 또는 렌더링은 Studio 소유 헬퍼에 위임할 때.
 
 ## 빠른 시작
 
@@ -90,6 +97,16 @@ fluo new my-mixed-app --shape mixed --transport tcp --runtime node --platform fa
 
 `fluo new`가 interactive TTY에서 실행되면 wizard는 기존 flags/config 모델을 그대로 사용합니다. wizard는 프로젝트 이름, shape-first 분기(`application` -> runtime + HTTP platform, `microservice` -> transport), 유지보수 가능한 tooling preset, package manager, 즉시 dependency를 설치할지 여부, git 저장소를 초기화할지 여부를 묻습니다. non-interactive 플래그 경로와 프로그래밍 방식의 `runNewCommand(...)` 호출도 동일한 resolved defaults를 사용합니다.
 
+side effect 없이 완전히 resolved starter를 미리 확인하려면 `--print-plan`을 사용하세요:
+
+```bash
+fluo new my-app --shape application --runtime node --platform fastify --print-plan
+fluo new my-service --shape microservice --transport tcp --print-plan
+fluo new my-mixed-app --shape mixed --print-plan
+```
+
+plan preview 모드는 실제 scaffold와 같은 프로젝트 이름, shape, runtime, platform, transport, tooling preset, package manager, install 선택, git 선택을 resolve합니다. 선택된 starter recipe와 dependency 세트를 출력한 뒤 파일 생성, dependency 설치, git 저장소 초기화 없이 종료합니다.
+
 현재 제공되는 스타터 매트릭스(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. 기능 추가
@@ -99,8 +116,16 @@ fluo new my-mixed-app --shape mixed --transport tcp --runtime node --platform fa
 fluo generate module users
 fluo generate controller users
 fluo generate service users
+fluo generate request-dto users CreateUser
+fluo generate service users --dry-run
 ```
 
+Request DTO 생성은 feature 디렉터리와 DTO 클래스 이름을 분리해서 받습니다. 따라서 `CreateUser`, `UpdateUser` 같은 여러 입력 계약을 같은 `src/users/` 슬라이스 안에 둘 수 있습니다.
+
+`--dry-run`을 추가하면 실제 실행과 같은 타깃 해석, 기존 파일 건너뛰기 또는 덮어쓰기 판단, 모듈 자동 등록 계획, 파일만 생성하는 wiring 상태, 다음 단계 힌트를 미리 볼 수 있습니다. 이 모드는 디렉터리 생성, 파일 쓰기, 모듈 갱신을 수행하지 않습니다. `--force`는 내용이 달라질 기존 파일의 계획 항목을 `SKIP`에서 `OVERWRITE`로 바꾸며, `--target-directory`는 실제 실행과 동일하게 지정한 소스 디렉터리 기준으로 preview 범위를 제한합니다.
+
+Generator discovery는 의도적으로 built-in `@fluojs/cli/builtin` collection으로 제한됩니다. 외부 package-owned 또는 app-local generator collection은 보류되어 있습니다. `fluo generate`는 config file을 스캔하거나, 임의 package를 로드하거나, workspace-owned collection code를 실행하지 않습니다. 이 경계는 shipped generator 계약을 보존하면서 generator metadata, option schema, help output, file-write boundary를 결정적이고 테스트 가능하게 유지합니다.
+
 ## 주요 패턴
 
 ### 데코레이터 코드 변환
@@ -109,27 +134,48 @@ fluo generate service users
 ```bash
 # 변경 사항 미리보기 (dry-run)
 fluo migrate ./src
+fluo migrate ./src --json
 
 # 변환 적용
 fluo migrate ./src --apply
+fluo migrate ./src --apply --json
 ```
 
+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`로 재작성합니다.
 - `@Injectable()`을 제거하고 스코프를 `@Scope()`로 매핑합니다.
 - `tsconfig.json`을 업데이트하여 `experimentalDecorators`를 비활성화하고 `baseUrl` 기반 경로 별칭을 TS6-safe `paths` 엔트리로 재작성합니다.
 
 ### 런타임 검사 (Inspection)
-애플리케이션 구조를 시각화하고 초기화 문제를 해결합니다.
+CLI가 그래프 렌더링을 소유하지 않으면서 애플리케이션 구조를 내보내고 초기화 문제를 해결합니다.
 
 ```bash
-# 의존성 그래프를 Mermaid 형식으로 내보내기
+# 선택적 Studio 렌더러를 통해 Mermaid 내보내기
 fluo inspect ./src/app.module.ts --mermaid
 
 # @fluojs/studio용 snapshot 내보내기
 fluo inspect ./src/app.module.ts --json > snapshot.json
+
+# shell redirection 없이 같은 JSON snapshot을 CI artifact 경로에 쓰기
+fluo inspect ./src/app.module.ts --json --output artifacts/inspect-snapshot.json
+
+# 런타임이 생산한 snapshot 옆에 bootstrap timing 포함하기
+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
 ```
 
+런타임이 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를 설치하세요:
+
+```bash
+pnpm add -D @fluojs/studio
+```
+
+Studio가 없으면 CI와 non-interactive 실행은 prompt나 package manager 실행 없이 설치 안내와 함께 빠르게 실패합니다. Interactive 실행에서는 Studio 설치 여부를 물을 수 있지만, 명시적으로 승인되고 구현된 설치 흐름이 없는 한 `fluo inspect`가 package manager install을 실행하지 않습니다.
+
 ## 공개 API
 
 다른 도구 내에서 CLI 동작을 트리거하기 위해 패키지를 프로그래밍 방식으로 사용할 수 있습니다.
@@ -142,8 +188,8 @@ fluo inspect ./src/app.module.ts --json > snapshot.json
 
 ## 관련 패키지
 
-- **[@fluojs/runtime](../runtime/README.ko.md)**: 검사 및 부트스트랩에 사용되는 기본 엔진입니다.
-- **[@fluojs/studio](../studio/README.ko.md)**: `inspect --json` 출력을 시각화하기 위한 웹 기반 UI입니다.
+- **[@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 테스트를 위해 생성된 테스트 템플릿에서 사용됩니다.
 - **[Canonical Runtime Package Matrix](../../docs/reference/package-surface.ko.md)**: 공식 런타임/패키지 조합을 보여주는 기준 문서입니다.
 

package/README.md

@@ -2,11 +2,12 @@
 
 <p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
 
-The canonical CLI for fluo — bootstrap new applications, generate components, inspect runtime graphs, and run code transforms.
+The canonical CLI for fluo — bootstrap new applications, generate components, export runtime inspection data, and run code transforms.
 
 ## Table of Contents
 
 - [Installation](#installation)
+- [Update Checks](#update-checks)
 - [When to Use](#when-to-use)
 - [Quick Start](#quick-start)
 - [Common Patterns](#common-patterns)
@@ -32,12 +33,18 @@ pnpm dlx @fluojs/cli new my-app
 - The supported install paths are the global package (`pnpm add -g @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`.
 
+## 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 runs `pnpm add -g @fluojs/cli@<latest>` and then restarts `fluo` with the same arguments under the updated binary.
+
+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
 
 - **Bootstrapping**: When starting a new project with a standard, verifiable structure.
 - **Generation**: To create modules, controllers, services, and repositories with consistent naming and automatic wiring.
 - **Code transforms**: When aligning an existing codebase with fluo's standard decorator model.
-- **Inspection**: To visualize the runtime dependency graph and diagnose platform-level issues.
+- **Inspection**: To export runtime snapshot data and delegate graph viewing or rendering to Studio-owned helpers.
 
 ## Quick Start
 
@@ -90,6 +97,16 @@ fluo new my-mixed-app --shape mixed --transport tcp --runtime node --platform fa
 
 When `fluo new` runs in an interactive TTY, the wizard uses the same flags/config model. It asks for the project name, shape-first branch (`application` -> runtime + HTTP platform, `microservice` -> transport), the maintained tooling preset, package-manager choice, whether to install dependencies immediately, and whether to initialize a git repository. Non-interactive flags and programmatic `runNewCommand(...)` calls use the same resolved defaults.
 
+Use `--print-plan` when you want to preview the fully resolved starter without side effects:
+
+```bash
+fluo new my-app --shape application --runtime node --platform fastify --print-plan
+fluo new my-service --shape microservice --transport tcp --print-plan
+fluo new my-mixed-app --shape mixed --print-plan
+```
+
+Plan preview mode resolves the same project name, shape, runtime, platform, transport, tooling preset, package manager, install choice, and git choice as a real scaffold. It prints the selected starter recipe and dependency sets, then exits without creating files, installing dependencies, or initializing a git repository.
+
 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
@@ -99,8 +116,16 @@ Add a new resource with a controller and service, automatically wired into the m
 fluo generate module users
 fluo generate controller users
 fluo generate service users
+fluo generate request-dto users CreateUser
+fluo generate service users --dry-run
 ```
 
+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.
+
+Generator discovery is intentionally limited to the built-in `@fluojs/cli/builtin` collection. External package-owned or app-local generator collections are deferred: `fluo generate` does not scan config files, load arbitrary packages, or execute workspace-owned collection code. This keeps generator metadata, option schemas, help output, and file-write boundaries deterministic and testable while preserving the shipped generator contract.
+
 ## Common Patterns
 
 ### Decorator Codemods
@@ -109,27 +134,48 @@ Run codemods to align your codebase with TC39 standard decorators.
 ```bash
 # Preview changes (dry-run)
 fluo migrate ./src
+fluo migrate ./src --json
 
 # Apply transformations
 fluo migrate ./src --apply
+fluo migrate ./src --apply --json
 ```
 
+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`.
 - Removes `@Injectable()` and maps scopes to `@Scope()`.
 - Updates `tsconfig.json` to disable `experimentalDecorators` and rewrites `baseUrl`-backed path aliases to TS6-safe `paths` entries.
 
 ### Runtime Inspection
-Visualize your application structure and troubleshoot initialization issues.
+Export your application structure and troubleshoot initialization issues without making the CLI own graph rendering.
 
 ```bash
-# Export dependency graph as Mermaid
+# Export Mermaid through the optional Studio renderer
 fluo inspect ./src/app.module.ts --mermaid
 
 # Export snapshot for @fluojs/studio
 fluo inspect ./src/app.module.ts --json > snapshot.json
+
+# Write the same JSON snapshot to a CI artifact path without shell redirection
+fluo inspect ./src/app.module.ts --json --output artifacts/inspect-snapshot.json
+
+# Include bootstrap timing next to the runtime-produced snapshot
+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
 ```
 
+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:
+
+```bash
+pnpm add -D @fluojs/studio
+```
+
+If Studio is missing, CI and other non-interactive runs fail fast with install guidance instead of prompting or running a package manager. Interactive runs may ask whether you want to install Studio, but `fluo inspect` does not run installs unless an explicit install flow is implemented and approved.
+
 ## Public API
 
 The package can be used programmatically to trigger CLI actions from within other tools.
@@ -142,8 +188,8 @@ The package can be used programmatically to trigger CLI actions from within othe
 
 ## Related Packages
 
-- **[@fluojs/runtime](../runtime/README.md)**: The underlying engine used for inspection and bootstrap.
-- **[@fluojs/studio](../studio/README.md)**: The web-based UI for visualizing `inspect --json` exports.
+- **[@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.
 - **[Canonical Runtime Package Matrix](../../docs/reference/package-surface.md)**: The source of truth for official runtime/package combinations.
 

package/dist/cli.d.ts

@@ -1,14 +1,24 @@
+import { type InspectCommandRuntimeOptions } from './commands/inspect.js';
 import { type NewCommandRuntimeOptions } from './commands/new.js';
+import { type CliUpdateCheckRuntimeOptions } from './update-check.js';
 type CliStream = {
+    isTTY?: boolean;
     write(message: string): unknown;
 };
+type CliReadableStream = {
+    isTTY?: boolean;
+};
 /**
  * Runtime dependency overrides for embedding the CLI in tests or higher-level tooling.
  */
 export interface CliRuntimeOptions {
+    ci?: boolean;
     cwd?: string;
+    env?: NodeJS.ProcessEnv;
     stderr?: CliStream;
+    stdin?: CliReadableStream;
     stdout?: CliStream;
+    updateCheck?: false | CliUpdateCheckRuntimeOptions;
 }
 /**
  * Runs the top-level CLI command dispatcher and returns a process-style exit code.
@@ -29,9 +39,9 @@ export interface CliRuntimeOptions {
  * ```
  *
  * @param argv Argument vector to execute. Defaults to the current process arguments without the node/bin prefix.
- * @param runtime Optional runtime overrides shared by the top-level dispatcher and the `new` command.
+ * @param runtime Optional runtime overrides shared by the top-level dispatcher and delegated commands.
  * @returns `0` when the command completes successfully, otherwise `1` after writing the error message to `stderr`.
  */
-export declare function runCli(argv?: string[], runtime?: CliRuntimeOptions & NewCommandRuntimeOptions): Promise<number>;
+export declare function runCli(argv?: string[], runtime?: CliRuntimeOptions & NewCommandRuntimeOptions & InspectCommandRuntimeOptions): Promise<number>;
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,KAAK,wBAAwB,EAA2B,MAAM,mBAAmB,CAAC;AAK3F,KAAK,SAAS,GAAG;IACf,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAmPD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,MAAM,CAC1B,IAAI,WAAwB,EAC5B,OAAO,GAAE,iBAAiB,GAAG,wBAA6B,GACzD,OAAO,CAAC,MAAM,CAAC,CAgGjB"}
+{"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"}

package/dist/cli.js

@@ -5,8 +5,9 @@ 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 { generatorManifest, resolveGeneratorKind } from './generators/manifest.js';
+import { builtInGeneratorCollection, generatorManifest, generatorOptionSchemas, resolveGeneratorKind } from './generators/manifest.js';
 import { renderAliasList, renderHelpTable } from './help.js';
+import { removeUpdateCheckFlags, runCliUpdateCheck } from './update-check.js';
 
 /**
  * Runtime dependency overrides for embedding the CLI in tests or higher-level tooling.
@@ -19,19 +20,11 @@ const GENERATE_KIND_HELP = [...generatorManifest.map(entry => ({
   schematic: entry.schematic,
   wiring: entry.wiringBehavior === 'auto-registered' ? 'auto' : 'manual'
 }))];
-const GENERATE_OPTION_HELP = [{
-  aliases: ['-o'],
-  description: 'Write generated files under a specific source directory.',
-  option: '--target-directory <path>'
-}, {
-  aliases: ['-f'],
-  description: 'Overwrite files that already exist.',
-  option: '--force'
-}, {
-  aliases: ['-h'],
-  description: 'Show help for the generate command.',
-  option: '--help'
-}];
+const GENERATE_OPTION_HELP = [...generatorOptionSchemas.map(option => ({
+  aliases: [...option.aliases],
+  description: option.description,
+  option: option.name
+}))];
 const TOP_LEVEL_COMMAND_HELP = [{
   aliases: ['create'],
   command: 'new',
@@ -60,7 +53,7 @@ function isHelpFlag(value) {
   return value === '--help' || value === '-h';
 }
 function generateUsage() {
-  return ['Usage: fluo generate|g <kind> <name> [options]', '', 'Schematics', renderHelpTable(GENERATE_KIND_HELP, [{
+  return ['Usage: fluo generate|g <kind> <name> [options]', '       fluo generate|g request-dto|req <feature> <name> [options]', '', 'Schematics', renderHelpTable(GENERATE_KIND_HELP, [{
     header: 'Schematic',
     render: entry => entry.schematic
   }, {
@@ -72,7 +65,7 @@ function generateUsage() {
   }, {
     header: 'Description',
     render: entry => entry.description
-  }]), '', '  auto   = class is auto-registered in the domain module (created if absent)', '  manual = files only; you must wire the generated class into a module yourself', '', 'Options', renderHelpTable(GENERATE_OPTION_HELP, [{
+  }]), '', '  auto   = class is auto-registered in the domain module (created if absent)', '  manual = files only; you must wire the generated class into a module yourself', '', 'Collections', `  ${builtInGeneratorCollection.id} (${builtInGeneratorCollection.source})`, '  External or app-local generator collections are intentionally deferred; no packages or config files are loaded by generate.', '', 'Options', renderHelpTable(GENERATE_OPTION_HELP, [{
     header: 'Option',
     render: entry => entry.option
   }, {
@@ -93,7 +86,7 @@ function usage() {
   }, {
     header: 'Description',
     render: entry => entry.description
-  }]), '', "Run 'fluo help <command>' for more information on a command.", 'Docs: https://github.com/fluojs/fluo/tree/main/docs/getting-started/quick-start.md'].join('\n');
+  }]), '', 'Options', '  --no-update-check  Skip the interactive CLI update check for this invocation.', '                     Alias: --no-update-notifier.', '', "Run 'fluo help <command>' for more information on a command.", 'Docs: https://github.com/fluojs/fluo/tree/main/docs/getting-started/quick-start.md'].join('\n');
 }
 function resolveDefaultTargetDirectory(startDirectory) {
   const resolvedStartDirectory = resolve(startDirectory);
@@ -114,24 +107,33 @@ function resolveDefaultTargetDirectory(startDirectory) {
   return resolvedStartDirectory;
 }
 function parseGenerateArgs(argv) {
-  const [command, rawKind, name, ...optionArgs] = argv;
+  const [command, rawKind, firstName, ...optionArgs] = argv;
   const kind = normalizeGeneratorKind(rawKind);
   if (!(command === 'g' || command === 'generate')) {
     throw new Error(usage());
   }
-  if (!kind || !name) {
+  if (!kind || !firstName) {
     throw new Error(generateUsage());
   }
-  if (name.startsWith('-')) {
-    throw new Error(`Invalid resource name "${name}": names cannot start with "-".`);
+  if (firstName.startsWith('-')) {
+    throw new Error(`Invalid resource name "${firstName}": names cannot start with "-".`);
   }
   const parsedOptions = {};
+  let name = firstName;
+  let seenRequestDtoName = false;
   let targetDirectory;
   let seenForce = false;
+  let seenDryRun = false;
   let seenTargetDirectory = false;
   for (let index = 0; index < optionArgs.length; index += 1) {
     const option = optionArgs[index];
     const next = optionArgs[index + 1];
+    if (kind === 'request-dto' && !seenRequestDtoName && !option.startsWith('-')) {
+      parsedOptions.targetFeature = firstName;
+      name = option;
+      seenRequestDtoName = true;
+      continue;
+    }
     if (option === '--target-directory' || option === '-o') {
       if (seenTargetDirectory) {
         throw new Error('Duplicate --target-directory option.');
@@ -152,6 +154,14 @@ function parseGenerateArgs(argv) {
       seenForce = true;
       continue;
     }
+    if (option === '--dry-run') {
+      if (seenDryRun) {
+        throw new Error('Duplicate --dry-run option.');
+      }
+      parsedOptions.dryRun = true;
+      seenDryRun = true;
+      continue;
+    }
     throw new Error(`Unknown option: ${option}`);
   }
   return {
@@ -207,19 +217,36 @@ function parseCommand(argv) {
  * ```
  *
  * @param argv Argument vector to execute. Defaults to the current process arguments without the node/bin prefix.
- * @param runtime Optional runtime overrides shared by the top-level dispatcher and the `new` command.
+ * @param runtime Optional runtime overrides shared by the top-level dispatcher and delegated commands.
  * @returns `0` when the command completes successfully, otherwise `1` after writing the error message to `stderr`.
  */
 export async function runCli(argv = process.argv.slice(2), runtime = {}) {
   const cwd = runtime.cwd ? resolve(runtime.cwd) : process.cwd();
   const stdout = runtime.stdout ?? process.stdout;
   const stderr = runtime.stderr ?? process.stderr;
+  const env = runtime.env ?? process.env;
+  const updateFlagResult = removeUpdateCheckFlags(argv);
+  const commandArgv = updateFlagResult.argv;
   try {
-    if (argv.length === 0) {
+    const updateCheckOptions = runtime.updateCheck === false ? undefined : runtime.updateCheck;
+    const updateCheckResult = await runCliUpdateCheck(commandArgv, {
+      ...updateCheckOptions,
+      ci: runtime.ci,
+      env,
+      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());
     }
-    if (argv[0] === 'help') {
-      const topic = argv[1];
+    if (commandArgv[0] === 'help') {
+      const topic = commandArgv[1];
       if (topic === 'new' || topic === 'create') {
         stdout.write(`${newUsage()}\n`);
         return 0;
@@ -239,23 +266,23 @@ export async function runCli(argv = process.argv.slice(2), runtime = {}) {
       stdout.write(`${usage()}\n`);
       return 0;
     }
-    if (isHelpFlag(argv[0])) {
+    if (isHelpFlag(commandArgv[0])) {
       stdout.write(`${usage()}\n`);
       return 0;
     }
-    if ((argv[0] === 'g' || argv[0] === 'generate') && argv.slice(1).some(isHelpFlag)) {
+    if ((commandArgv[0] === 'g' || commandArgv[0] === 'generate') && commandArgv.slice(1).some(isHelpFlag)) {
       stdout.write(`${generateUsage()}\n`);
       return 0;
     }
-    if (argv[0] === 'migrate' && argv.slice(1).some(isHelpFlag)) {
+    if (commandArgv[0] === 'migrate' && commandArgv.slice(1).some(isHelpFlag)) {
       stdout.write(`${migrateUsage()}\n`);
       return 0;
     }
-    if (argv[0] === 'inspect' && argv.slice(1).some(isHelpFlag)) {
+    if (commandArgv[0] === 'inspect' && commandArgv.slice(1).some(isHelpFlag)) {
       stdout.write(`${inspectUsage()}\n`);
       return 0;
     }
-    const parsedCommand = parseCommand(argv);
+    const parsedCommand = parseCommand(commandArgv);
     if (parsedCommand.command === 'new') {
       return runNewCommand(parsedCommand.argv, runtime);
     }
@@ -267,9 +294,17 @@ export async function runCli(argv = process.argv.slice(2), runtime = {}) {
     }
     const targetDirectory = resolve(cwd, parsedCommand.parsed.targetDirectory ?? resolveDefaultTargetDirectory(cwd));
     const result = runGenerateCommand(parsedCommand.parsed.kind, parsedCommand.parsed.name, targetDirectory, parsedCommand.parsed.options);
-    stdout.write(`Generated ${result.generatedFiles.length} file(s):\n`);
-    for (const file of result.generatedFiles) {
-      stdout.write(`  CREATE ${file}\n`);
+    if (parsedCommand.parsed.options.dryRun) {
+      stdout.write('Dry run: no files were written.\n');
+      stdout.write(`Planned ${result.plannedFiles.length} file action(s):\n`);
+      for (const file of result.plannedFiles) {
+        stdout.write(`  ${file.action.toUpperCase()} ${file.path}\n`);
+      }
+    } else {
+      stdout.write(`Generated ${result.generatedFiles.length} file(s):\n`);
+      for (const file of result.generatedFiles) {
+        stdout.write(`  CREATE ${file}\n`);
+      }
     }
     stdout.write('\n');
     if (result.wiringBehavior === 'auto-registered' && result.moduleRegistered) {
@@ -287,6 +322,7 @@ export async function runCli(argv = process.argv.slice(2), runtime = {}) {
 }
 if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
   process.exitCode = await runCli(undefined, {
+    ci: process.env.CI === 'true' || process.env.GITHUB_ACTIONS === 'true',
     userAgent: process.env.npm_config_user_agent
   });
 }

package/dist/commands/generate.d.ts

@@ -1,5 +1,14 @@
 import type { GenerateOptions, GeneratorKind } from '../types.js';
 import type { GeneratorManifestEntry } from '../generators/manifest.js';
+/** Describes how one generated artifact would interact with the workspace. */
+export type GeneratePlanAction = 'create' | 'module-create' | 'module-unchanged' | 'module-update' | 'overwrite' | 'skip' | 'unchanged';
+/** One path-level action reported by generate dry-run previews and structured results. */
+export type GeneratePlanEntry = {
+    /** Planned action for this path. */
+    action: GeneratePlanAction;
+    /** Absolute path affected by the plan entry. */
+    path: string;
+};
 /**
  * Structured result returned by {@link runGenerateCommand} for tooling-friendly automation.
  *
@@ -12,6 +21,7 @@ export type GenerateResult = {
     moduleRegistered: boolean;
     modulePath: string | undefined;
     nextStepHint: string;
+    plannedFiles: GeneratePlanEntry[];
     wiringBehavior: GeneratorManifestEntry['wiringBehavior'];
 };
 /**
@@ -32,7 +42,7 @@ export type GenerateResult = {
  * @param kind Generator kind to execute.
  * @param name Resource name supplied by the caller before normalization.
  * @param baseDirectory Source directory that should receive the generated domain folder.
- * @param options Optional generation flags that control overwrites and sibling-aware templates.
+ * @param options Optional generation flags that control overwrites, request DTO feature placement, and sibling-aware templates.
  * @returns Structured file and wiring metadata for the completed generation run.
  * @throws {Error} When the resource name is invalid, the generator kind is unknown, or the target module source cannot be updated safely.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/commands/generate.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,KAAK,EAAE,sBAAsB,EAAkB,MAAM,2BAA2B,CAAC;AA+FxF;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,sBAAsB,CAAC,gBAAgB,CAAC,CAAC;CAC1D,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,cAAc,CAiD1I"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/commands/generate.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,KAAK,EAAE,sBAAsB,EAAkB,MAAM,2BAA2B,CAAC;AAexF,8EAA8E;AAC9E,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,eAAe,GAAG,kBAAkB,GAAG,eAAe,GAAG,WAAW,GAAG,MAAM,GAAG,WAAW,CAAC;AAExI,0FAA0F;AAC1F,MAAM,MAAM,iBAAiB,GAAG;IAC9B,oCAAoC;IACpC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AA0HF;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,iBAAiB,EAAE,CAAC;IAClC,cAAc,EAAE,sBAAsB,CAAC,gBAAgB,CAAC,CAAC;CAC1D,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,cAAc,CAgE1I"}