@fluojs/cli 1.1.0 → 2.0.1

package/README.ko.md

@@ -31,6 +31,7 @@ pnpm dlx @fluojs/cli new my-app
 ## 릴리스 계약
 
 - `@fluojs/cli`는 intended publish surface에 포함되는 공개 패키지입니다.
+- `@fluojs/cli`는 Node.js `>=20.0.0`을 요구합니다. 생성된 Bun, Deno, Cloudflare Workers starter가 비 Node runtime을 대상으로 할 수는 있지만 CLI process 자체는 Node.js에서 실행됩니다.
 - 지원되는 설치 경로는 전역 패키지(`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`에 선언된 `./bin/fluo.mjs` wrapper이며, 이 wrapper가 dist 빌드 CLI 엔트리포인트인 `../dist/cli.js`를 로드합니다.
 
@@ -112,7 +113,7 @@ fluo new my-grpc-service --shape microservice --transport grpc --runtime node --
 
 지원되는 `--shape microservice --transport` 스타터 값은 정확히 `tcp`, `redis-streams`, `nats`, `kafka`, `rabbitmq`, `mqtt`, `grpc`입니다. 유지보수되는 Redis 기반 스타터가 필요하면 `redis-streams`를 사용하고, 더 넓은 Redis 통합 패턴이 필요하면 스캐폴딩 후 `@fluojs/redis`를 수동으로 추가하세요.
 
-NATS/Kafka/RabbitMQ 스타터 계약은 외부 broker와 caller-owned client library 의존성을 숨기지 않고 명시적으로 유지합니다. 생성된 프로젝트는 `src/app.ts`에서 `nats` + `JSONCodec()`, `kafkajs` producer/consumer collaborator, `amqplib` publisher/consumer collaborator를 직접 연결하므로, 기본 fluo 패키지가 그 의존성을 감춘 것처럼 가장하지 않는 runnable starter 계약이 됩니다. 해당 broker client는 생성된 transport wrapper가 Fluo lifecycle에서 listen/send/emit을 시작할 때 lazy하게 생성합니다. 따라서 `fluo inspect`, 테스트, static tooling이 `src/app.ts`를 import하는 것만으로는 broker에 연결하거나 lifecycle이 teardown을 소유하기 전에 외부 리소스를 열지 않습니다.
+NATS/Kafka/RabbitMQ 스타터 계약은 외부 broker와 caller-owned client library 의존성을 숨기지 않고 명시적으로 유지합니다. 생성된 프로젝트는 `src/app.ts`에서 `nats` + `JSONCodec()`, `kafkajs` producer/consumer collaborator, `amqplib` publisher/consumer collaborator를 직접 연결하므로, 기본 fluo 패키지가 그 의존성을 감춘 것처럼 가장하지 않는 runnable starter 계약이 됩니다. 해당 broker client는 생성된 transport wrapper가 Fluo lifecycle에서 listen/send/emit을 시작할 때 lazy하게 생성합니다. 따라서 `fluo inspect`, 테스트, static tooling이 `src/app.ts`를 import하는 것만으로는 broker에 연결하거나 lifecycle이 teardown을 소유하기 전에 외부 리소스를 열지 않습니다. 종료 중 delegated transport shutdown이 실패해도 각 wrapper는 소유한 client 종료를 계속 시도합니다. Kafka 연결이 일부만 성공한 경우에는 획득한 client를 disconnect하고, RabbitMQ channel 생성이 실패한 경우에는 획득한 connection을 닫은 뒤 startup error를 다시 던집니다.
 
 starter 매트릭스에는 mixed single-package starter도 포함됩니다. 하나의 Fastify HTTP 앱과 attached TCP microservice를 같은 생성 프로젝트 안에 함께 배치합니다.
 
@@ -122,6 +123,18 @@ 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를 사용합니다.
 
+기본적으로 `fluo new my-app`은 `./my-app`에 파일을 씁니다. 프로젝트 이름과 대상 경로가 달라야 하거나 자동화에서 명시적인 디렉터리에 써야 하면 `--target-directory <path>`를 사용하세요:
+
+```bash
+fluo new my-app --target-directory ./apps/api
+```
+
+Scaffold는 기본적으로 비어 있지 않은 대상에서 충돌하는 파일을 덮어쓰지 않습니다. 내용이 다른 생성 파일을 의도적으로 덮어쓰려는 경우에만 `--force`를 추가하세요:
+
+```bash
+fluo new my-app --target-directory ./apps/api --force
+```
+
 side effect 없이 완전히 resolved starter를 미리 확인하려면 `--print-plan`을 사용하세요:
 
 ```bash
@@ -196,7 +209,7 @@ fluo dev --studio --dry-run
 
 CLI는 local Studio sidecar를 시작하고, tokenized URL을 출력하며, restart lifecycle event를 sidecar로 계속 전달하고, 앱이 `@fluojs/runtime`을 import하기 전에 명시적인 Studio config를 Node 앱 child에 주입합니다. Studio live mode는 fluo가 소유한 Node restart runner를 요구합니다. 따라서 lifecycle event가 CLI restart boundary와 분리되지 않도록 `fluo dev --studio`는 `--raw-watch`, `--runner native`, `FLUO_DEV_RUNNER=native`를 거부합니다. Optional package인 `@fluojs/studio`가 설치되어 있으면 sidecar는 패키징된 `@fluojs/studio/viewer` React app을 제공합니다. Runtime package source는 `process.env`를 직접 읽지 않으며, CLI가 주입한 Studio config가 있을 때만 live graph/routes/request/timing/diagnostic event를 전송합니다.
 
-보안 기본값은 local-only입니다. Sidecar는 `127.0.0.1`에 bind되고, runtime ingestion 및 browser state/SSE API는 generated token을 요구하며, CORS는 기본적으로 활성화하지 않고, request body는 기본적으로 수집하지 않습니다.
+보안 기본값은 local-only입니다. Sidecar는 `127.0.0.1`에 bind되고, runtime ingestion 및 browser state/SSE API는 generated token을 요구하며, CORS는 기본적으로 활성화하지 않고, request body는 기본적으로 수집하지 않습니다. Local client가 partial request body만 보내고 socket을 닫으면 sidecar는 bounded error completion으로 ingestion 요청을 settle하므로, malformed local client가 sidecar 작업을 무기한 대기시킬 수 없습니다.
 
 MVP runtime support는 명시적으로 제한됩니다.
 
@@ -302,7 +315,7 @@ Studio가 없으면 CI와 non-interactive 실행은 prompt나 package manager
 | `CliRuntimeOptions` | stream, cwd, environment, registry metadata, update-check hook 같은 `runCli(...)` runtime override 타입입니다. |
 | `newUsage()` | help surface와 test에서 사용하는 현재 `fluo new` usage text를 반환합니다. |
 | `runNewCommand(argv, options?)` | 프로젝트 스캐폴딩 로직에 대한 프로그래밍적 접근을 제공합니다. |
-| `NewCommandRuntimeOptions` | prompt, filesystem write, dependency install, git initialization 같은 `runNewCommand(...)` runtime override 타입입니다. |
+| `NewCommandRuntimeOptions` | prompt, filesystem write, dependency install, git initialization 같은 `runNewCommand(...)` runtime override 타입입니다. `runCli(...)`도 `new` 또는 `create`로 dispatch할 때 이 override를 받습니다. Monorepo-local starter dependency override는 내부 sandbox harness 세부사항이며 이 공개 타입의 일부가 아닙니다. |
 | `CliPromptCancelledError` | 호출자가 제공한 prompt hook이 정상 취소를 알리기 위해 throw할 수 있는 안정적인 sentinel입니다. |
 | `runGenerateCommand(kind, name, baseDirectory, options?)` | built-in schematic generator와 module auto-registration planner에 대한 프로그래밍적 접근을 제공합니다. |
 | `GenerateOptions` | 프로그래밍 방식 generator 옵션 타입입니다. |

package/README.md

@@ -31,6 +31,7 @@ pnpm dlx @fluojs/cli new my-app
 ## Release Contract
 
 - `@fluojs/cli` is a public package in the intended publish surface.
+- `@fluojs/cli` requires Node.js `>=20.0.0`; generated Bun, Deno, and Cloudflare Workers starters may target non-Node runtimes, but the CLI process itself runs on Node.js.
 - The supported install paths are the global package (`npm install -g @fluojs/cli`, `pnpm add -g @fluojs/cli`, `bun add -g @fluojs/cli`, or `yarn global add @fluojs/cli`) and the no-install runner (`pnpm dlx @fluojs/cli ...`).
 - The published `fluo` bin is the `./bin/fluo.mjs` wrapper declared in `package.json`; that wrapper loads the dist-built CLI entrypoint at `../dist/cli.js`.
 
@@ -112,7 +113,7 @@ fluo new my-grpc-service --shape microservice --transport grpc --runtime node --
 
 Supported `--shape microservice --transport` starter values are exactly `tcp`, `redis-streams`, `nats`, `kafka`, `rabbitmq`, `mqtt`, and `grpc`. Use `redis-streams` for the maintained Redis-backed starter, or add `@fluojs/redis` manually after scaffolding when you need broader Redis integration patterns.
 
-The NATS/Kafka/RabbitMQ starter contracts stay explicit about external brokers and caller-owned client libraries. Generated projects wire `nats` + `JSONCodec()`, `kafkajs` producer/consumer collaborators, and `amqplib` publisher/consumer collaborators directly in `src/app.ts` so the starter contract is runnable without pretending the base fluo packages hide those dependencies. Those broker clients are created lazily by the generated transport wrapper when the Fluo lifecycle starts listening, sends, or emits; importing `src/app.ts` for `fluo inspect`, tests, or static tooling does not connect to a broker or open external resources before the application lifecycle owns teardown.
+The NATS/Kafka/RabbitMQ starter contracts stay explicit about external brokers and caller-owned client libraries. Generated projects wire `nats` + `JSONCodec()`, `kafkajs` producer/consumer collaborators, and `amqplib` publisher/consumer collaborators directly in `src/app.ts` so the starter contract is runnable without pretending the base fluo packages hide those dependencies. Those broker clients are created lazily by the generated transport wrapper when the Fluo lifecycle starts listening, sends, or emits; importing `src/app.ts` for `fluo inspect`, tests, or static tooling does not connect to a broker or open external resources before the application lifecycle owns teardown. During shutdown, each wrapper still attempts to close its owned clients when delegated transport shutdown fails. Kafka partial connection failures disconnect acquired clients, and RabbitMQ channel creation failures close the acquired connection before the startup error is rethrown.
 
 The starter matrix also includes a mixed single-package starter: one Fastify HTTP app with an attached TCP microservice in the same generated project.
 
@@ -122,6 +123,18 @@ 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.
 
+By default, `fluo new my-app` writes to `./my-app`. Use `--target-directory <path>` when the project name and destination path should differ, or when automation should write to an explicit directory:
+
+```bash
+fluo new my-app --target-directory ./apps/api
+```
+
+Scaffolding refuses to overwrite conflicting files in a non-empty target by default. Add `--force` only when you intentionally want generated files with different contents to be overwritten:
+
+```bash
+fluo new my-app --target-directory ./apps/api --force
+```
+
 Use `--print-plan` when you want to preview the fully resolved starter without side effects:
 
 ```bash
@@ -196,7 +209,7 @@ fluo dev --studio --dry-run
 
 The CLI starts a local Studio sidecar, prints a tokenized URL, keeps restart lifecycle events flowing through the sidecar, and injects an explicit Studio config into the Node app child before the app imports `@fluojs/runtime`. Studio live mode requires the fluo-owned Node restart runner; `fluo dev --studio` rejects `--raw-watch`, `--runner native`, and `FLUO_DEV_RUNNER=native` so lifecycle events cannot be split from the CLI restart boundary. The sidecar serves the packaged `@fluojs/studio/viewer` React app when that optional package is installed. Runtime package source never reads `process.env` directly; it publishes live graph/routes/request/timing/diagnostic events only when CLI-injected Studio config is present.
 
-Security defaults are local-only: the sidecar binds `127.0.0.1`, runtime ingestion and browser state/SSE APIs require generated tokens, CORS is not enabled by default, and request bodies are not captured by default.
+Security defaults are local-only: the sidecar binds `127.0.0.1`, runtime ingestion and browser state/SSE APIs require generated tokens, CORS is not enabled by default, and request bodies are not captured by default. The sidecar settles ingestion requests with a bounded error completion when a local client closes the socket after sending only a partial request body, so a malformed local client cannot hang sidecar work indefinitely.
 
 Runtime support for the MVP is explicit:
 
@@ -302,7 +315,7 @@ The package can be used programmatically to trigger CLI actions from within othe
 | `CliRuntimeOptions` | Type for `runCli(...)` runtime overrides such as streams, cwd, environment, registry metadata, and update-check hooks. |
 | `newUsage()` | Returns the current `fluo new` usage text for help surfaces and tests. |
 | `runNewCommand(argv, options?)` | Programmatic access to the project scaffolding logic. |
-| `NewCommandRuntimeOptions` | Type for `runNewCommand(...)` runtime overrides such as prompts, filesystem writes, dependency installation, and git initialization. |
+| `NewCommandRuntimeOptions` | Type for `runNewCommand(...)` runtime overrides such as prompts, filesystem writes, dependency installation, and git initialization; `runCli(...)` also accepts these overrides when it dispatches `new` or `create`. Monorepo-local starter dependency overrides are internal sandbox harness details, not part of this public type. |
 | `CliPromptCancelledError` | Stable sentinel that caller-supplied prompt hooks can throw to report normal cancellation. |
 | `runGenerateCommand(kind, name, baseDirectory, options?)` | Programmatic access to the built-in schematic generator and module auto-registration planner. |
 | `GenerateOptions` | Type for programmatic generator options. |

package/dist/cli.d.ts.map

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

package/dist/cli.js

@@ -1,17 +1,18 @@
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync } 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 { runInspectCommand } from './commands/inspect.js';
 import { migrateUsage, runMigrateCommand } from './commands/migrate.js';
-import { newUsage, runNewCommand } from './commands/new.js';
+import { 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';
+import { inspectUsage, newUsage } from './usage.js';
 
 /**
  * Runtime dependency overrides for embedding the CLI in tests or higher-level tooling.

package/dist/commands/generate.d.ts

@@ -1,50 +1,2 @@
-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.
- *
- * `generatedFiles` only includes files whose on-disk content changed during the command.
- * `moduleRegistered` reports whether the target schematic participates in automatic module wiring,
- * even when the target module file was already up to date.
- */
-export type GenerateResult = {
-    generatedFiles: string[];
-    moduleRegistered: boolean;
-    modulePath: string | undefined;
-    nextStepHint: string;
-    plannedFiles: GeneratePlanEntry[];
-    wiringBehavior: GeneratorManifestEntry['wiringBehavior'];
-};
-/**
- * Generates one CLI schematic into a source directory and returns structured wiring metadata.
- *
- * The command keeps generation idempotent where possible: unchanged files are not rewritten, and
- * auto-registered schematics reuse an existing module file when it already contains the required import
- * and registration entry.
- *
- * @example
- * ```ts
- * const result = runGenerateCommand('service', 'Post', './src');
- *
- * console.log(result.wiringBehavior);
- * console.log(result.nextStepHint);
- * ```
- *
- * @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, 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.
- */
-export declare function runGenerateCommand(kind: GeneratorKind, name: string, baseDirectory: string, options?: GenerateOptions): GenerateResult;
+export { type GeneratePlanAction, type GeneratePlanEntry, type GenerateResult, runGenerateCommand } from '../generate-command.js';
 //# sourceMappingURL=generate.d.ts.map

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;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;AAyIF;;;;;;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"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/commands/generate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,KAAK,cAAc,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/commands/generate.js

@@ -1,214 +1 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { basename, dirname, join, normalize, relative, resolve, sep } from 'node:path';
-import { findGeneratorDefinition } from '../generators/manifest.js';
-import { ensureModuleImport, generateModuleFiles, registerInModule } from '../generators/module.js';
-import { toKebabCase, toPascalCase, toPlural } from '../generators/utils.js';
-function writeFileIfChanged(filePath, content) {
-  if (existsSync(filePath) && readFileSync(filePath, 'utf8') === content) {
-    return false;
-  }
-  writeFileSync(filePath, content, 'utf8');
-  return true;
-}
-
-/** Describes how one generated artifact would interact with the workspace. */
-
-/** One path-level action reported by generate dry-run previews and structured results. */
-
-function planFileWrite(filePath, content, options) {
-  if (!existsSync(filePath)) {
-    return {
-      action: 'create',
-      path: filePath
-    };
-  }
-  if (!options.force) {
-    return {
-      action: 'skip',
-      path: filePath
-    };
-  }
-  if (readFileSync(filePath, 'utf8') === content) {
-    return {
-      action: 'unchanged',
-      path: filePath
-    };
-  }
-  return {
-    action: 'overwrite',
-    path: filePath
-  };
-}
-function planModuleWrite(modulePath, content) {
-  if (!existsSync(modulePath)) {
-    return {
-      action: 'module-create',
-      path: modulePath
-    };
-  }
-  if (readFileSync(modulePath, 'utf8') === content) {
-    return {
-      action: 'module-unchanged',
-      path: modulePath
-    };
-  }
-  return {
-    action: 'module-update',
-    path: modulePath
-  };
-}
-function createGeneratorOptions(kind, domainDirectory, kebab, options, resolvedBase) {
-  return {
-    ...options,
-    e2eRootModuleImport: options.e2eRootModuleImport ?? (kind === 'e2e' ? resolveE2eRootModuleImport(domainDirectory, resolvedBase) : undefined),
-    hasRepo: options.hasRepo ?? (kind === 'service' ? existsSync(join(domainDirectory, `${kebab}.repo.ts`)) : undefined),
-    hasService: options.hasService ?? (kind === 'controller' ? existsSync(join(domainDirectory, `${kebab}.service.ts`)) : undefined)
-  };
-}
-function toImportSpecifier(path) {
-  const normalized = path.split(sep).join('/');
-  return normalized.startsWith('.') ? normalized : `./${normalized}`;
-}
-function resolveE2eRootModuleImport(domainDirectory, resolvedBase) {
-  return toImportSpecifier(relative(domainDirectory, join(resolvedBase, 'app')));
-}
-function resolveDomainDirectory(kind, resolvedBase, kebab, options) {
-  if (kind === 'e2e') {
-    return basename(resolvedBase) === 'src' ? join(dirname(resolvedBase), 'test') : join(resolvedBase, 'test');
-  }
-  if (kind === 'request-dto' && options.targetFeature !== undefined) {
-    const normalizedFeature = options.targetFeature.trim();
-    const featureKebab = assertValidResourceName(normalizedFeature);
-    const featureDirectory = /^[A-Z]/u.test(normalizedFeature) ? toPlural(featureKebab) : featureKebab;
-    return join(resolvedBase, featureDirectory);
-  }
-  return join(resolvedBase, toPlural(kebab));
-}
-function assertValidResourceName(name) {
-  const kebab = toKebabCase(name);
-  if (name.trim().length === 0) {
-    throw new Error('Invalid resource name: name must not be empty.');
-  }
-  if (kebab !== normalize(kebab) || kebab.includes('/') || kebab.includes('\\') || kebab.includes('..')) {
-    throw new Error(`Invalid resource name "${name}": must not contain path separators or traversal sequences.`);
-  }
-  if (!/^[a-z0-9][a-z0-9-]*$/.test(kebab)) {
-    throw new Error(`Invalid resource name "${name}": use letters, numbers, spaces, underscores, or hyphens only.`);
-  }
-  return kebab;
-}
-function resolveModulePath(domainDirectory, name) {
-  const kebab = toKebabCase(name);
-  return join(domainDirectory, `${kebab}.module.ts`);
-}
-function readOrCreateModuleSource(modulePath, name) {
-  if (existsSync(modulePath)) {
-    return readFileSync(modulePath, 'utf8');
-  }
-  const [moduleFile] = generateModuleFiles(name);
-  if (!moduleFile) {
-    throw new Error(`Unable to generate module file for resource "${name}".`);
-  }
-  return moduleFile.content;
-}
-function buildUpdatedModuleSource(moduleSource, arrayKey, className, importPath) {
-  let source = moduleSource;
-  source = ensureModuleImport(source, className, importPath);
-  source = registerInModule(source, arrayKey, className);
-  return source;
-}
-function prepareModuleUpdate(domainDirectory, normalizedName, kind, classSuffix, arrayKey) {
-  const kebab = toKebabCase(normalizedName);
-  const modulePath = resolveModulePath(domainDirectory, normalizedName);
-  const className = `${toPascalCase(normalizedName)}${classSuffix}`;
-  const importPath = `${kebab}.${kind}`;
-  const moduleSource = readOrCreateModuleSource(modulePath, normalizedName);
-  return {
-    modulePath,
-    source: buildUpdatedModuleSource(moduleSource, arrayKey, className, importPath)
-  };
-}
-
-/**
- * Structured result returned by {@link runGenerateCommand} for tooling-friendly automation.
- *
- * `generatedFiles` only includes files whose on-disk content changed during the command.
- * `moduleRegistered` reports whether the target schematic participates in automatic module wiring,
- * even when the target module file was already up to date.
- */
-
-/**
- * Generates one CLI schematic into a source directory and returns structured wiring metadata.
- *
- * The command keeps generation idempotent where possible: unchanged files are not rewritten, and
- * auto-registered schematics reuse an existing module file when it already contains the required import
- * and registration entry.
- *
- * @example
- * ```ts
- * const result = runGenerateCommand('service', 'Post', './src');
- *
- * console.log(result.wiringBehavior);
- * console.log(result.nextStepHint);
- * ```
- *
- * @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, 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.
- */
-export function runGenerateCommand(kind, name, baseDirectory, options = {}) {
-  const normalizedName = name.trim();
-  const kebab = assertValidResourceName(normalizedName);
-  const generator = findGeneratorDefinition(kind);
-  const resolvedBase = resolve(baseDirectory);
-  const domainDirectory = resolveDomainDirectory(kind, resolvedBase, kebab, options);
-  const generatorOptions = createGeneratorOptions(kind, domainDirectory, kebab, options, resolvedBase);
-  const files = generator.factory(normalizedName, generatorOptions);
-  const moduleRegistration = 'moduleRegistration' in generator ? generator.moduleRegistration : undefined;
-  const moduleUpdate = moduleRegistration ? prepareModuleUpdate(domainDirectory, normalizedName, kind, moduleRegistration.classSuffix, moduleRegistration.arrayKey) : undefined;
-  const plannedFiles = files.map(file => planFileWrite(join(domainDirectory, file.path), file.content, options));
-  const modulePlan = moduleUpdate ? planModuleWrite(moduleUpdate.modulePath, moduleUpdate.source) : undefined;
-  if (options.dryRun) {
-    return {
-      generatedFiles: [],
-      moduleRegistered: moduleUpdate !== undefined,
-      modulePath: moduleUpdate?.modulePath,
-      nextStepHint: generator.nextStepHint,
-      plannedFiles: modulePlan ? [...plannedFiles, modulePlan] : plannedFiles,
-      wiringBehavior: generator.wiringBehavior
-    };
-  }
-  mkdirSync(domainDirectory, {
-    recursive: true
-  });
-  const writtenPaths = files.map(file => {
-    const filePath = join(domainDirectory, file.path);
-    if (!options.force && existsSync(filePath)) {
-      return null;
-    }
-    return writeFileIfChanged(filePath, file.content) ? filePath : null;
-  }).filter(filePath => filePath !== null);
-  let moduleRegistered = false;
-  let resolvedModulePath;
-  if (moduleUpdate && writeFileIfChanged(moduleUpdate.modulePath, moduleUpdate.source)) {
-    moduleRegistered = true;
-    resolvedModulePath = moduleUpdate.modulePath;
-    if (!writtenPaths.includes(moduleUpdate.modulePath)) {
-      writtenPaths.push(moduleUpdate.modulePath);
-    }
-  } else if (moduleUpdate) {
-    moduleRegistered = true;
-    resolvedModulePath = moduleUpdate.modulePath;
-  }
-  return {
-    generatedFiles: writtenPaths,
-    moduleRegistered: moduleRegistered,
-    modulePath: resolvedModulePath,
-    nextStepHint: generator.nextStepHint,
-    plannedFiles: modulePlan ? [...plannedFiles, modulePlan] : plannedFiles,
-    wiringBehavior: generator.wiringBehavior
-  };
-}
+export { runGenerateCommand } from '../generate-command.js';

package/dist/commands/inspect.d.ts

@@ -32,12 +32,6 @@ export interface InspectCommandRuntimeOptions {
     /** Custom stream for standard output. */
     stdout?: CliStream;
 }
-/**
- * Returns the usage information string for the inspect command.
- *
- * @returns Formatted help text including usage and options.
- */
-export declare function inspectUsage(): string;
 /**
  * Executes the inspect command to visualize the application module graph.
  *

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

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

package/dist/commands/inspect.js

@@ -5,66 +5,19 @@ import { pathToFileURL } from 'node:url';
 import * as clack from '@clack/prompts';
 import { FluoFactory, PLATFORM_SHELL } from '@fluojs/runtime';
 import { tsImport } from 'tsx/esm/api';
-import { renderAliasList, renderHelpTable } from '../help.js';
 import { CliPromptCancelledError, isCliPromptCancelledError } from '../prompt-cancel.js';
+import { inspectUsage } from '../usage.js';
 
 /**
  * Runtime options for the inspect command when used programmatically.
  */
 
-const INSPECT_OPTION_HELP = [{
-  aliases: [],
-  description: 'Emit the runtime platform snapshot/diagnostics payload as JSON (default when no output mode is selected).',
-  option: '--json'
-}, {
-  aliases: [],
-  description: 'Emit a Mermaid graph through the optional @fluojs/studio rendering contract.',
-  option: '--mermaid'
-}, {
-  aliases: [],
-  description: 'Include bootstrap timing diagnostics next to JSON inspect output.',
-  option: '--timing'
-}, {
-  aliases: [],
-  description: 'Emit a CI-friendly JSON report with summary, snapshot, diagnostics, and timing.',
-  option: '--report'
-}, {
-  aliases: [],
-  description: 'Write the selected inspect payload to a file instead of stdout.',
-  option: '--output <path>'
-}, {
-  aliases: [],
-  description: 'Select the exported module symbol name (default: AppModule).',
-  option: '--export <name>'
-}, {
-  aliases: ['-h'],
-  description: 'Show help for the inspect command.',
-  option: '--help'
-}];
 const STUDIO_CONTRACT_ENTRYPOINT = '@fluojs/studio/contracts';
 const TYPESCRIPT_MODULE_EXTENSIONS = new Set(['.ts', '.tsx', '.mts', '.cts']);
 const STUDIO_MISSING_MESSAGE = ['Mermaid graph rendering is owned by @fluojs/studio, but @fluojs/studio is not resolvable from this project.', 'Install @fluojs/studio explicitly (for example: pnpm add -D @fluojs/studio) and rerun fluo inspect --mermaid.'].join('\n');
 function isHelpFlag(value) {
   return value === '--help' || value === '-h';
 }
-
-/**
- * Returns the usage information string for the inspect command.
- *
- * @returns Formatted help text including usage and options.
- */
-export function inspectUsage() {
-  return ['Usage: fluo inspect <module-path> [options]', '', 'Options', renderHelpTable(INSPECT_OPTION_HELP, [{
-    header: 'Option',
-    render: entry => entry.option
-  }, {
-    header: 'Aliases',
-    render: entry => renderAliasList(entry.aliases)
-  }, {
-    header: 'Description',
-    render: entry => entry.description
-  }]), '', 'Docs: https://github.com/fluojs/fluo/tree/main/docs/getting-started/quick-start.md'].join('\n');
-}
 function parseInspectArgs(argv) {
   let modulePath;
   let exportName = 'AppModule';

package/dist/commands/new.d.ts

@@ -17,12 +17,6 @@ export interface NewCommandRuntimeOptions extends NewCommandOptions {
     stdout?: CliStream;
     userAgent?: string;
 }
-/**
- * Renders CLI help text for `fluo new`.
- *
- * @returns Stable help output for the scaffolding command.
- */
-export declare function newUsage(): string;
 /**
  * Executes `fluo new` with parsed arguments and scaffold options.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"new.d.ts","sourceRoot":"","sources":["../../src/commands/new.ts"],"names":[],"mappings":"AAOA,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAWnF,OAAO,KAAK,EAAoB,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAE3E,KAAK,SAAS,GAAG;IACf,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC,CAAC;AAuBF;;GAEG;AACH,MAAM,WAAW,wBAAyB,SAAQ,iBAAiB;IACjE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,KAAK,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC5B,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA0UD;;;;GAIG;AACH,wBAAgB,QAAQ,IAAI,MAAM,CA0BjC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,wBAA6B,GAAG,OAAO,CAAC,MAAM,CAAC,CA4G3G"}
+{"version":3,"file":"new.d.ts","sourceRoot":"","sources":["../../src/commands/new.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,iBAAiB,EAA2B,MAAM,kBAAkB,CAAC;AAWnF,OAAO,KAAK,EAAsC,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAI7F,KAAK,SAAS,GAAG;IACf,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC,CAAC;AAiCF;;GAEG;AACH,MAAM,WAAW,wBAAyB,SAAQ,iBAAiB;IACjE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,KAAK,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC5B,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAiPD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,wBAA6B,GAAG,OAAO,CAAC,MAAM,CAAC,CA6G3G"}