@fluojs/cli 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fluo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,155 @@
+# @fluojs/cli
+
+<p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
+
+fluo 공식 CLI — 새 애플리케이션 부트스트랩, 컴포넌트 생성, 런타임 그래프 검사, 코드 변환을 지원합니다.
+
+## 목차
+
+- [설치](#설치)
+- [사용 시점](#사용-시점)
+- [빠른 시작](#빠른-시작)
+- [주요 패턴](#주요-패턴)
+- [공개 API](#공개-api)
+- [관련 패키지](#관련-패키지)
+- [예제 소스](#예제-소스)
+
+## 설치
+
+```bash
+pnpm add -g @fluojs/cli
+```
+
+설치 없이 직접 실행하려면:
+
+```bash
+pnpm dlx @fluojs/cli new my-app
+```
+
+## 릴리스 계약
+
+- `@fluojs/cli`는 intended publish surface에 포함되는 공개 패키지입니다.
+- 지원되는 설치 경로는 전역 패키지(`pnpm add -g @fluojs/cli`)와 무설치 실행 경로(`pnpm dlx @fluojs/cli ...`)입니다.
+- 배포되는 `fluo` bin은 `package.json`에 선언된 dist 빌드 CLI 엔트리포인트를 기준으로 동작합니다.
+
+## 사용 시점
+
+- **부트스트랩**: 표준적이고 검증 가능한 구조로 새 프로젝트를 시작할 때.
+- **코드 생성**: 일관된 네이밍 규칙과 자동 연결 기능을 갖춘 모듈, 컨트롤러, 서비스, 레포지토리를 생성할 때.
+- **코드 변환**: 기존 코드베이스를 fluo의 표준 데코레이터 모델에 맞출 때.
+- **검사(Inspection)**: 런타임 의존성 그래프를 시각화하고 플랫폼 수준의 문제를 진단할 때.
+
+## 빠른 시작
+
+### 1. 새 프로젝트 생성
+몇 초 만에 완전한 스타터 애플리케이션을 스캐폴딩합니다.
+
+```bash
+fluo new my-app
+cd my-app
+pnpm dev
+```
+
+`fluo new`는 같은 Node 기반 설치/빌드 흐름 위에서 Node.js + Fastify, Express, raw Node.js HTTP 애플리케이션 스타터를 제공합니다.
+
+```bash
+fluo new my-app --shape application --transport http --runtime node --platform fastify
+fluo new my-express-app --shape application --transport http --runtime node --platform express
+fluo new my-node-app --shape application --transport http --runtime node --platform nodejs
+```
+
+애플리케이션 매트릭스에는 런타임별 entrypoint, scripts, dependency 세트를 갖춘 Bun, Deno, Cloudflare Workers 네이티브 스타터도 포함됩니다.
+
+```bash
+fluo new my-bun-app --shape application --transport http --runtime bun --platform bun
+fluo new my-deno-app --shape application --transport http --runtime deno --platform deno
+fluo new my-worker-app --shape application --transport http --runtime cloudflare-workers --platform cloudflare-workers
+```
+
+`fluo new`는 microservice starter path도 제공합니다. `--transport`를 생략하면 TCP가 기본 경로로 사용되며, starter 매트릭스에는 transport별 dependency, env 템플릿, entrypoint를 갖춘 Redis Streams, NATS, Kafka, RabbitMQ, MQTT, gRPC 변형도 포함됩니다.
+
+```bash
+fluo new my-microservice --shape microservice --transport tcp --runtime node --platform none
+fluo new my-redis-streams-service --shape microservice --transport redis-streams --runtime node --platform none
+fluo new my-nats-service --shape microservice --transport nats --runtime node --platform none
+fluo new my-kafka-service --shape microservice --transport kafka --runtime node --platform none
+fluo new my-rabbitmq-service --shape microservice --transport rabbitmq --runtime node --platform none
+fluo new my-mqtt-service --shape microservice --transport mqtt --runtime node --platform none
+fluo new my-grpc-service --shape microservice --transport grpc --runtime node --platform none
+```
+
+지원되는 `--shape microservice --transport` 스타터 값은 정확히 `tcp`, `redis-streams`, `nats`, `kafka`, `rabbitmq`, `mqtt`, `grpc`입니다. 이전 문서에 있던 `redis` 값은 더 이상 제공되는 스타터 계약에 포함되지 않으며, 유지보수되는 Redis 기반 스타터가 필요하면 `redis-streams`를 사용하고, 더 넓은 Redis 통합 패턴이 필요하면 스캐폴딩 후 `@fluojs/redis`를 수동으로 추가하세요.
+
+NATS/Kafka/RabbitMQ 스타터 계약은 외부 broker와 caller-owned client library 의존성을 숨기지 않고 명시적으로 유지합니다. 생성된 프로젝트는 `src/app.ts`에서 `nats` + `JSONCodec()`, `kafkajs` producer/consumer collaborator, `amqplib` publisher/consumer collaborator를 직접 연결하므로, 기본 fluo 패키지가 그 의존성을 감춘 것처럼 가장하지 않는 runnable starter 계약이 됩니다.
+
+starter 매트릭스에는 mixed single-package starter도 포함됩니다. 하나의 Fastify HTTP 앱과 attached TCP microservice를 같은 생성 프로젝트 안에 함께 배치합니다.
+
+```bash
+fluo new my-mixed-app --shape mixed --transport tcp --runtime node --platform fastify
+```
+
+`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를 사용합니다.
+
+현재 제공되는 스타터 매트릭스(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. 기능 추가
+컨트롤러와 서비스가 포함된 새 리소스를 추가하고, 모듈에 자동으로 연결합니다.
+
+```bash
+fluo generate module users
+fluo generate controller users
+fluo generate service users
+```
+
+## 주요 패턴
+
+### 데코레이터 코드 변환
+코드베이스를 TC39 표준 데코레이터에 맞게 조정하는 codemod를 실행합니다.
+
+```bash
+# 변경 사항 미리보기 (dry-run)
+fluo migrate ./src
+
+# 변환 적용
+fluo migrate ./src --apply
+```
+
+**주요 변환 사항:**
+- `@nestjs/common` 임포트를 `@fluojs/core` 또는 `@fluojs/http`로 재작성합니다.
+- `@Injectable()`을 제거하고 스코프를 `@Scope()`로 매핑합니다.
+- `tsconfig.json`을 업데이트하여 `experimentalDecorators`를 비활성화하고 `baseUrl` 기반 경로 별칭을 TS6-safe `paths` 엔트리로 재작성합니다.
+
+### 런타임 검사 (Inspection)
+애플리케이션 구조를 시각화하고 초기화 문제를 해결합니다.
+
+```bash
+# 의존성 그래프를 Mermaid 형식으로 내보내기
+fluo inspect ./src/app.module.ts --mermaid
+
+# @fluojs/studio용 snapshot 내보내기
+fluo inspect ./src/app.module.ts --json > snapshot.json
+```
+
+## 공개 API
+
+다른 도구 내에서 CLI 동작을 트리거하기 위해 패키지를 프로그래밍 방식으로 사용할 수 있습니다.
+
+| 익스포트 | 설명 |
+|---|---|
+| `runCli(argv?, options?)` | 모든 CLI 명령을 실행하는 메인 진입점입니다. |
+| `runNewCommand(argv, options?)` | 프로젝트 스캐폴딩 로직에 대한 프로그래밍적 접근을 제공합니다. |
+| `GeneratorKind` | 지원되는 모든 생성기 유형(예: `'controller'`, `'service'`)의 유니온 타입입니다. |
+
+## 관련 패키지
+
+- **[@fluojs/runtime](../runtime/README.ko.md)**: 검사 및 부트스트랩에 사용되는 기본 엔진입니다.
+- **[@fluojs/studio](../studio/README.ko.md)**: `inspect --json` 출력을 시각화하기 위한 웹 기반 UI입니다.
+- **[@fluojs/testing](../testing/README.ko.md)**: 통합 및 E2E 테스트를 위해 생성된 테스트 템플릿에서 사용됩니다.
+- **[Canonical Runtime Package Matrix](../../docs/reference/package-surface.ko.md)**: 공식 런타임/패키지 조합을 보여주는 기준 문서입니다.
+
+## 예제 소스
+
+- [cli.ts](./src/cli.ts) - 명령 디스패처 및 인자 파싱.
+- [commands/new.ts](./src/commands/new.ts) - 프로젝트 스캐폴딩 구현.
+- [generators/](./src/generators/) - 템플릿 기반 파일 생성 로직.
+- [transforms/](./src/transforms/) - 코드 변환 구현.

package/README.md

@@ -0,0 +1,155 @@
+# @fluojs/cli
+
+<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.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [When to Use](#when-to-use)
+- [Quick Start](#quick-start)
+- [Common Patterns](#common-patterns)
+- [Public API](#public-api)
+- [Related Packages](#related-packages)
+- [Example Sources](#example-sources)
+
+## Installation
+
+```bash
+pnpm add -g @fluojs/cli
+```
+
+Or run directly without installation:
+
+```bash
+pnpm dlx @fluojs/cli new my-app
+```
+
+## Release Contract
+
+- `@fluojs/cli` is a public package in the intended publish surface.
+- 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`.
+
+## 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.
+
+## Quick Start
+
+### 1. Create a new project
+Scaffold a complete starter application in seconds.
+
+```bash
+fluo new my-app
+cd my-app
+pnpm dev
+```
+
+`fluo new` supports Node.js + Fastify, Express, and raw Node.js HTTP application starters on the same Node-oriented install/build flow:
+
+```bash
+fluo new my-app --shape application --transport http --runtime node --platform fastify
+fluo new my-express-app --shape application --transport http --runtime node --platform express
+fluo new my-node-app --shape application --transport http --runtime node --platform nodejs
+```
+
+The application matrix also includes runtime-native Bun, Deno, and Cloudflare Workers starters with runtime-specific entrypoints, scripts, and dependency sets:
+
+```bash
+fluo new my-bun-app --shape application --transport http --runtime bun --platform bun
+fluo new my-deno-app --shape application --transport http --runtime deno --platform deno
+fluo new my-worker-app --shape application --transport http --runtime cloudflare-workers --platform cloudflare-workers
+```
+
+`fluo new` also exposes microservice starter paths. TCP is the default when you omit `--transport`, and the starter matrix includes runnable Redis Streams, NATS, Kafka, RabbitMQ, MQTT, and gRPC variants with transport-specific dependencies, env templates, and entrypoints:
+
+```bash
+fluo new my-microservice --shape microservice --transport tcp --runtime node --platform none
+fluo new my-redis-streams-service --shape microservice --transport redis-streams --runtime node --platform none
+fluo new my-nats-service --shape microservice --transport nats --runtime node --platform none
+fluo new my-kafka-service --shape microservice --transport kafka --runtime node --platform none
+fluo new my-rabbitmq-service --shape microservice --transport rabbitmq --runtime node --platform none
+fluo new my-mqtt-service --shape microservice --transport mqtt --runtime node --platform none
+fluo new my-grpc-service --shape microservice --transport grpc --runtime node --platform none
+```
+
+Supported `--shape microservice --transport` starter values are exactly `tcp`, `redis-streams`, `nats`, `kafka`, `rabbitmq`, `mqtt`, and `grpc`. Earlier docs mentioned `redis`, but that value is no longer part of the shipped starter contract; use `redis-streams` for the maintained Redis-backed starter, or add `@fluojs/redis` manually after scaffolding when you need broader Redis integration patterns.
+
+The NATS/Kafka/RabbitMQ starter contracts stay explicit about external brokers and caller-owned client libraries. Generated projects wire `nats` + `JSONCodec()`, `kafkajs` producer/consumer collaborators, and `amqplib` publisher/consumer collaborators directly in `src/app.ts` so the starter contract is runnable without pretending the base fluo packages hide those dependencies.
+
+The starter matrix also includes a mixed single-package starter: one Fastify HTTP app with an attached TCP microservice in the same generated project.
+
+```bash
+fluo new my-mixed-app --shape mixed --transport tcp --runtime node --platform fastify
+```
+
+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.
+
+For a docs-level table that separates the shipped starter matrix (Node.js Fastify/Express/raw Node.js HTTP, Bun, Deno, Cloudflare Workers, TCP/Redis Streams/NATS/Kafka/RabbitMQ/MQTT/gRPC microservices, plus mixed) from the remaining broader adapter ecosystem, see the [fluo new support matrix](../../docs/reference/fluo-new-support-matrix.md). Package-level integrations such as `@fluojs/redis` remain part of the broader ecosystem, but they are not extra `fluo new --transport` starter flags.
+
+### 2. Generate a feature
+Add a new resource with a controller and service, automatically wired into the module.
+
+```bash
+fluo generate module users
+fluo generate controller users
+fluo generate service users
+```
+
+## Common Patterns
+
+### Decorator Codemods
+Run codemods to align your codebase with TC39 standard decorators.
+
+```bash
+# Preview changes (dry-run)
+fluo migrate ./src
+
+# Apply transformations
+fluo migrate ./src --apply
+```
+
+**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.
+
+```bash
+# Export dependency graph as Mermaid
+fluo inspect ./src/app.module.ts --mermaid
+
+# Export snapshot for @fluojs/studio
+fluo inspect ./src/app.module.ts --json > snapshot.json
+```
+
+## Public API
+
+The package can be used programmatically to trigger CLI actions from within other tools.
+
+| Export | Description |
+|---|---|
+| `runCli(argv?, options?)` | Main entry point to execute any CLI command. |
+| `runNewCommand(argv, options?)` | Programmatic access to the project scaffolding logic. |
+| `GeneratorKind` | Union type of all supported generator types (e.g., `'controller'`, `'service'`). |
+
+## 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/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.
+
+## Example Sources
+
+- [cli.ts](./src/cli.ts) - Command dispatcher and argument parsing.
+- [commands/new.ts](./src/commands/new.ts) - Project scaffolding implementation.
+- [generators/](./src/generators/) - Template-based file generation logic.
+- [transforms/](./src/transforms/) - Code transformation implementations.

package/bin/fluo.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+const { runCli } = await import('../dist/cli.js');
+
+process.exitCode = await runCli(process.argv.slice(2));

package/dist/cli.d.ts

@@ -0,0 +1,37 @@
+import { type NewCommandRuntimeOptions } from './commands/new.js';
+type CliStream = {
+    write(message: string): unknown;
+};
+/**
+ * Runtime dependency overrides for embedding the CLI in tests or higher-level tooling.
+ */
+export interface CliRuntimeOptions {
+    cwd?: string;
+    stderr?: CliStream;
+    stdout?: CliStream;
+}
+/**
+ * Runs the top-level CLI command dispatcher and returns a process-style exit code.
+ *
+ * This programmatic entry point mirrors the published `fluo` binary while allowing callers to swap
+ * standard streams or the working directory for tests, sandboxes, and editor integrations.
+ *
+ * @example
+ * ```ts
+ * import { runCli } from '@fluojs/cli';
+ *
+ * const output: string[] = [];
+ * const exitCode = await runCli(['generate', 'service', 'Post'], {
+ *   cwd: '/workspace/app',
+ *   stdout: { write: (chunk) => output.push(String(chunk)) },
+ *   stderr: { write: (chunk) => output.push(String(chunk)) },
+ * });
+ * ```
+ *
+ * @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.
+ * @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 {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +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"}

package/dist/cli.js

@@ -0,0 +1,292 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+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 { renderAliasList, renderHelpTable } from './help.js';
+
+/**
+ * Runtime dependency overrides for embedding the CLI in tests or higher-level tooling.
+ */
+
+const GENERATE_KIND_HELP = [...generatorManifest.map(entry => ({
+  aliases: [...entry.aliases],
+  description: entry.description,
+  kind: entry.kind,
+  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 TOP_LEVEL_COMMAND_HELP = [{
+  aliases: ['create'],
+  command: 'new',
+  description: 'Scaffold a new fluo application and install dependencies.'
+}, {
+  aliases: ['g'],
+  command: 'generate',
+  description: 'Generate a schematic inside an existing fluo application.'
+}, {
+  aliases: [],
+  command: 'inspect',
+  description: 'Inspect runtime platform snapshot/diagnostics and emit timing optionally.'
+}, {
+  aliases: [],
+  command: 'migrate',
+  description: 'Run NestJS-to-fluo codemods (dry-run by default).'
+}, {
+  aliases: [],
+  command: 'help',
+  description: 'Show top-level or command-specific help.'
+}];
+function normalizeGeneratorKind(value) {
+  return resolveGeneratorKind(value);
+}
+function isHelpFlag(value) {
+  return value === '--help' || value === '-h';
+}
+function generateUsage() {
+  return ['Usage: fluo generate|g <kind> <name> [options]', '', 'Schematics', renderHelpTable(GENERATE_KIND_HELP, [{
+    header: 'Schematic',
+    render: entry => entry.schematic
+  }, {
+    header: 'Aliases',
+    render: entry => renderAliasList(entry.aliases)
+  }, {
+    header: 'Wiring',
+    render: entry => entry.wiring
+  }, {
+    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, [{
+    header: 'Option',
+    render: entry => entry.option
+  }, {
+    header: 'Aliases',
+    render: entry => renderAliasList(entry.aliases)
+  }, {
+    header: 'Description',
+    render: entry => entry.description
+  }]), '', 'Next steps:', '  Run \'pnpm typecheck\' to verify the generated module wiring.', '  Run \'pnpm test\' to execute the generated test templates.', '', 'Docs: https://github.com/fluojs/fluo/tree/main/docs/getting-started/generator-workflow.md'].join('\n');
+}
+function usage() {
+  return ['Usage: fluo <command> [options]', '', 'Commands', renderHelpTable(TOP_LEVEL_COMMAND_HELP, [{
+    header: 'Command',
+    render: entry => entry.command
+  }, {
+    header: 'Aliases',
+    render: entry => renderAliasList(entry.aliases)
+  }, {
+    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');
+}
+function resolveDefaultTargetDirectory(startDirectory) {
+  const resolvedStartDirectory = resolve(startDirectory);
+  if (existsSync(join(resolvedStartDirectory, 'package.json')) && existsSync(join(resolvedStartDirectory, 'src'))) {
+    return join(resolvedStartDirectory, 'src');
+  }
+  if (existsSync(join(resolvedStartDirectory, 'apps'))) {
+    const appDirectories = readdirSync(join(resolvedStartDirectory, 'apps'), {
+      withFileTypes: true
+    }).filter(entry => entry.isDirectory()).map(entry => join(resolvedStartDirectory, 'apps', entry.name)).filter(directory => existsSync(join(directory, 'package.json')) && existsSync(join(directory, 'src')));
+    if (appDirectories.length === 1) {
+      return join(appDirectories[0], 'src');
+    }
+    if (appDirectories.length > 1) {
+      throw new Error('Multiple app targets were found under apps/. Use --target-directory to choose the app src directory explicitly.');
+    }
+  }
+  return resolvedStartDirectory;
+}
+function parseGenerateArgs(argv) {
+  const [command, rawKind, name, ...optionArgs] = argv;
+  const kind = normalizeGeneratorKind(rawKind);
+  if (!(command === 'g' || command === 'generate')) {
+    throw new Error(usage());
+  }
+  if (!kind || !name) {
+    throw new Error(generateUsage());
+  }
+  if (name.startsWith('-')) {
+    throw new Error(`Invalid resource name "${name}": names cannot start with "-".`);
+  }
+  const parsedOptions = {};
+  let targetDirectory;
+  let seenForce = false;
+  let seenTargetDirectory = false;
+  for (let index = 0; index < optionArgs.length; index += 1) {
+    const option = optionArgs[index];
+    const next = optionArgs[index + 1];
+    if (option === '--target-directory' || option === '-o') {
+      if (seenTargetDirectory) {
+        throw new Error('Duplicate --target-directory option.');
+      }
+      if (!next || next.startsWith('-')) {
+        throw new Error('Expected --target-directory to have a path value.');
+      }
+      targetDirectory = next;
+      seenTargetDirectory = true;
+      index += 1;
+      continue;
+    }
+    if (option === '--force' || option === '-f') {
+      if (seenForce) {
+        throw new Error('Duplicate --force option.');
+      }
+      parsedOptions.force = true;
+      seenForce = true;
+      continue;
+    }
+    throw new Error(`Unknown option: ${option}`);
+  }
+  return {
+    kind,
+    name,
+    options: parsedOptions,
+    targetDirectory
+  };
+}
+function parseCommand(argv) {
+  const [command] = argv;
+  if (command === 'new' || command === 'create') {
+    return {
+      argv: argv.slice(1),
+      command: 'new'
+    };
+  }
+  if (command === 'migrate') {
+    return {
+      argv: argv.slice(1),
+      command: 'migrate'
+    };
+  }
+  if (command === 'inspect') {
+    return {
+      argv: argv.slice(1),
+      command: 'inspect'
+    };
+  }
+  return {
+    argv,
+    command: 'generate',
+    parsed: parseGenerateArgs(argv)
+  };
+}
+
+/**
+ * Runs the top-level CLI command dispatcher and returns a process-style exit code.
+ *
+ * This programmatic entry point mirrors the published `fluo` binary while allowing callers to swap
+ * standard streams or the working directory for tests, sandboxes, and editor integrations.
+ *
+ * @example
+ * ```ts
+ * import { runCli } from '@fluojs/cli';
+ *
+ * const output: string[] = [];
+ * const exitCode = await runCli(['generate', 'service', 'Post'], {
+ *   cwd: '/workspace/app',
+ *   stdout: { write: (chunk) => output.push(String(chunk)) },
+ *   stderr: { write: (chunk) => output.push(String(chunk)) },
+ * });
+ * ```
+ *
+ * @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.
+ * @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;
+  try {
+    if (argv.length === 0) {
+      throw new Error(usage());
+    }
+    if (argv[0] === 'help') {
+      const topic = argv[1];
+      if (topic === 'new' || topic === 'create') {
+        stdout.write(`${newUsage()}\n`);
+        return 0;
+      }
+      if (topic === 'g' || topic === 'generate') {
+        stdout.write(`${generateUsage()}\n`);
+        return 0;
+      }
+      if (topic === 'migrate') {
+        stdout.write(`${migrateUsage()}\n`);
+        return 0;
+      }
+      if (topic === 'inspect') {
+        stdout.write(`${inspectUsage()}\n`);
+        return 0;
+      }
+      stdout.write(`${usage()}\n`);
+      return 0;
+    }
+    if (isHelpFlag(argv[0])) {
+      stdout.write(`${usage()}\n`);
+      return 0;
+    }
+    if ((argv[0] === 'g' || argv[0] === 'generate') && argv.slice(1).some(isHelpFlag)) {
+      stdout.write(`${generateUsage()}\n`);
+      return 0;
+    }
+    if (argv[0] === 'migrate' && argv.slice(1).some(isHelpFlag)) {
+      stdout.write(`${migrateUsage()}\n`);
+      return 0;
+    }
+    if (argv[0] === 'inspect' && argv.slice(1).some(isHelpFlag)) {
+      stdout.write(`${inspectUsage()}\n`);
+      return 0;
+    }
+    const parsedCommand = parseCommand(argv);
+    if (parsedCommand.command === 'new') {
+      return runNewCommand(parsedCommand.argv, runtime);
+    }
+    if (parsedCommand.command === 'migrate') {
+      return runMigrateCommand(parsedCommand.argv, runtime);
+    }
+    if (parsedCommand.command === 'inspect') {
+      return runInspectCommand(parsedCommand.argv, 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`);
+    }
+    stdout.write('\n');
+    if (result.wiringBehavior === 'auto-registered' && result.moduleRegistered) {
+      stdout.write(`Wiring: auto-registered in ${result.modulePath ?? 'module'}\n`);
+    } else if (result.wiringBehavior === 'files-only') {
+      stdout.write('Wiring: files only — manual registration required (see next steps)\n');
+    }
+    stdout.write(`\nNext steps:\n  ${result.nextStepHint}\n`);
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    stderr.write(`${message}\n`);
+    return 1;
+  }
+}
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+  process.exitCode = await runCli(undefined, {
+    userAgent: process.env.npm_config_user_agent
+  });
+}