@vertz/cli 0.2.0 → 0.2.1

package/README.md

@@ -1,132 +1,154 @@
 # @vertz/cli
 
-The `vertz` command. Create, develop, build, and publish Vertz applications.
+The `vertz` CLI — create, develop, build, and deploy Vertz applications.
 
-> **5-minute rule:** You should understand what this CLI does and how to use it in 5 minutes or less. If not, [open an issue](https://github.com/nicholasgriffintn/vertz/issues) — that's a bug in our docs.
+> **5-minute rule:** You should understand what this CLI does and how to use it in 5 minutes or less. If not, [open an issue](https://github.com/vertz-dev/vertz/issues) — that's a bug in our docs.
 
-## What is this?
-
-`@vertz/cli` is the developer tool for Vertz projects. It's the `vertz` binary you run in your terminal. If you're looking for terminal UI building blocks (spinners, task lists, select menus), that's `@vertz/tui`.
-
----
-
-## You want to start a new project
+## Quick Start
 
 ```bash
+# Create a new project
 npx @vertz/cli create my-app
 cd my-app
-```
-
-This scaffolds a new Vertz app with a working `src/app.ts`, config file, and dev scripts. You'll have a running server in under a minute.
-
-Your entry point will look something like this:
 
-```ts
-import { createServer } from '@vertz/server';
+# Start development
+npx vertz dev
 
-const app = createServer();
-// ... define your routes, modules, services
+# Build for production
+npx vertz build
 ```
 
 ---
 
-## You want to develop locally
+## Installation
 
 ```bash
-vertz dev
+npm install @vertz/cli
+# or
+bun add @vertz/cli
 ```
 
-That's it. This starts your dev server with hot reload, background type-checking, and compiler diagnostics right in your terminal.
+**Requirements:** Node.js 22+ or Bun 1.0+
 
-**Common options:**
-
-```bash
-vertz dev --port 4000          # custom port
-vertz dev --host 0.0.0.0      # expose to network
-vertz dev --no-typecheck       # skip background type-checking
-```
+---
 
-**What happens under the hood:**
-1. Compiles your `src/` directory
-2. Starts your server (default: `localhost:3000`)
-3. Watches for file changes and recompiles automatically
-4. Runs type-checking in the background so errors show inline
+## Commands
 
----
+### `vertz create <name>`
 
-## You want to build for production
+Scaffold a new Vertz project.
 
 ```bash
-vertz build
+vertz create my-app                # Create with Bun (default)
+vertz create my-app --runtime node # Create with Node.js
+vertz create my-app --runtime deno # Create with Deno
+vertz create my-app --example      # Include example health module
+vertz create my-app --no-example   # Exclude example (default)
 ```
 
-Compiles your project, runs validation, and outputs production-ready code.
+### `vertz dev`
+
+Start the development server with hot reload. Runs the full pipeline (analyze → generate → build → serve) and watches for file changes.
 
 ```bash
-vertz build --strict           # treat warnings as errors
-vertz build --output dist      # custom output directory
+vertz dev                          # Start on localhost:3000
+vertz dev --port 4000              # Custom port
+vertz dev --host 0.0.0.0           # Expose to network
+vertz dev --open                   # Open browser on start
+vertz dev --no-typecheck           # Disable background type-checking
+vertz dev -v                       # Verbose output
 ```
 
----
+### `vertz build`
 
-## You want to check your code without building
+Compile your project for production.
 
 ```bash
-vertz check
+vertz build                        # Build for Node.js
+vertz build --target edge          # Build for edge runtime
+vertz build --target worker        # Build for worker runtime
+vertz build --output dist          # Custom output directory
+vertz build --no-typecheck         # Skip type checking
+vertz build --no-minify            # Skip minification
+vertz build --sourcemap            # Generate sourcemaps
+vertz build -v                     # Verbose output
 ```
 
-Type-checks and validates your project without producing output. Useful in CI or as a pre-commit hook.
+### `vertz check`
+
+Type-check and validate your project without producing output. Useful in CI or as a pre-commit hook.
 
 ```bash
-vertz check --strict           # fail on warnings
-vertz check --format json      # machine-readable output (text | json | github)
+vertz check                        # Text output
+vertz check --format json           # JSON output
+vertz check --format github        # GitHub Actions format
 ```
 
----
+### `vertz generate [type] [name]`
 
-## You want to generate code
+Generate code scaffolds. Supports multiple types:
 
 ```bash
+# Generate a new module
 vertz generate module users
+
+# Generate service/router/schema within a module
 vertz generate service user --module users
 vertz generate router api --module users
 vertz generate schema user --module users
-```
 
-Scaffolds modules, services, routers, and schemas. Use `--dry-run` to preview what will be generated.
+# Auto-discover domains and generate all (experimental)
+vertz generate
 
-You can also define [custom generators](#custom-generators) in your config.
+# Preview without writing files
+vertz generate module users --dry-run
+```
 
----
+### `vertz codegen`
 
-## You want to deploy *(coming soon)*
+Generate SDK and CLI clients from your compiled API.
 
 ```bash
-vertz publish
+vertz codegen                      # Generate clients
+vertz codegen --dry-run            # Preview without writing
+vertz codegen --output ./sdk       # Custom output directory
 ```
 
-One-command deployment to your configured target. **This command is not yet available** — it's on the roadmap.
+Requires `codegen` configuration in `vertz.config.ts`:
 
----
+```ts
+const config = {
+  codegen: {
+    output: './src/clients',
+    generators: ['typescript', 'swift', 'kotlin'],
+  },
+};
+```
 
-## You want to see your routes
+### `vertz routes`
+
+Display all routes in your application.
 
 ```bash
-vertz routes                   # table format
-vertz routes --format json     # JSON output
+vertz routes                       # Table format
+vertz routes --format json         # JSON output
 ```
 
-Displays every route your application exposes.
-
----
+### `vertz db migrate`
 
-## Installation
+Smart database migration. Automatically chooses the right Prisma command based on environment.
 
 ```bash
-npm install @vertz/cli         # or bun add @vertz/cli
+vertz db migrate                   # Auto-detect: dev=dev, prod=deploy
+vertz db migrate --status         # Show migration status
+vertz db migrate --create-only    # Create migration file without applying
+vertz db migrate --name my-change # Specify migration name
+vertz db migrate --reset          # Reset database (drop all tables)
+vertz db migrate -v               # Verbose output
 ```
 
-**Requirements:** Node.js 18+ or Bun 1.0+, TypeScript 5.0+
+In development: runs `prisma migrate dev` (applies pending + creates new if schema changed).
+In production: runs `prisma migrate deploy` (applies pending only).
 
 ---
 
@@ -147,60 +169,24 @@ const config: CLIConfig = {
     port: 3000,
     host: 'localhost',
     typecheck: true,
+    open: false,
   },
-};
-
-export default config;
-```
-
-Also supports `.js` and `.mjs`. See [Configuration Reference](#configuration-reference) for all options.
-
----
-
-## Custom Generators
-
-Extend `vertz generate` with your own templates:
-
-```ts
-import type { CLIConfig, GeneratorDefinition } from '@vertz/cli';
-
-const entity: GeneratorDefinition = {
-  name: 'entity',
-  description: 'Generate a domain entity with schema and service',
-  arguments: [{ name: 'name', description: 'Entity name', required: true }],
-  options: [
-    { name: 'timestamps', flag: '--timestamps', description: 'Include timestamp fields', default: 'true' },
-  ],
-  async run({ name, sourceDir }) {
-    return [
-      { path: `${sourceDir}/entities/${name}.schema.ts`, content: `export const ${name}Schema = s.object({});` },
-      { path: `${sourceDir}/entities/${name}.service.ts`, content: `export class ${name}Service {}` },
-    ];
+  codegen: {
+    output: './src/clients',
+    generators: ['typescript'],
   },
 };
 
-const config: CLIConfig = {
-  generators: { entity },
-};
-
 export default config;
 ```
 
-```bash
-vertz generate entity product
-vertz generate entity product --timestamps false
-```
-
----
-
-## Configuration Reference
+### Configuration Reference
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `strict` | `boolean` | `false` | Treat warnings as errors |
-| `forceGenerate` | `boolean` | `false` | Force code generation even if up-to-date |
 | `compiler.sourceDir` | `string` | `'src'` | Source directory |
-| `compiler.entryFile` | `string` | `'src/app.ts'` | Entry file path |
+| `compiler.entryFile` | `string` | `'src/app.ts'` | Entry file |
 | `compiler.outputDir` | `string` | `'.vertz/generated'` | Generated code output |
 | `dev.port` | `number` | `3000` | Dev server port |
 | `dev.host` | `string` | `'localhost'` | Dev server host |
@@ -211,7 +197,14 @@ vertz generate entity product --timestamps false
 
 ## Programmatic API
 
-The CLI exports its internals for custom tooling. See the [Programmatic API docs](./docs/programmatic-api.md) for details on `buildAction`, `generateAction`, `createDevLoop`, `createTaskRunner`, and more.
+Import CLI functions for custom tooling:
+
+```ts
+import { buildAction, devAction, createDevLoop } from '@vertz/cli';
+
+await buildAction({ output: './dist' });
+await devAction({ port: 3000 });
+```
 
 ---
 
@@ -220,6 +213,7 @@ The CLI exports its internals for custom tooling. See the [Programmatic API docs
 - [`@vertz/server`](../server) — Server framework (`createServer`)
 - [`@vertz/compiler`](../compiler) — Vertz compiler
 - [`@vertz/codegen`](../codegen) — Code generation utilities
+- [`@vertz/tui`](../tui) — Terminal UI components
 
 ## License
 

package/dist/index.d.ts

@@ -1,14 +1,8 @@
+import { TaskGroup, TaskHandle, TaskRunner } from "@vertz/tui";
+import { colors, createTaskRunner, Message, SelectList, symbols, Task, TaskList } from "@vertz/tui";
 import { Command } from "commander";
 declare function createCLI(): Command;
-/**
-* Vertz Build Command - Production Build
-*
-* Production build command that orchestrates:
-* 1. Codegen - runs the full pipeline to generate types, routes, OpenAPI
-* 2. Typecheck - runs TypeScript compiler for type checking
-* 3. Bundle - bundles the server for production (esbuild)
-* 4. Manifest - generates build manifest for vertz publish
-*/
+import { Result } from "@vertz/errors";
 interface BuildCommandOptions {
 	strict?: boolean;
 	output?: string;
@@ -20,26 +14,28 @@ interface BuildCommandOptions {
 }
 /**
 * Run the build command
-* @returns Exit code (0 for success, 1 for failure)
 */
-declare function buildAction(options?: BuildCommandOptions): Promise<number>;
+declare function buildAction(options?: BuildCommandOptions): Promise<Result<void, Error>>;
 import { Compiler, Diagnostic } from "@vertz/compiler";
+import { Result as Result2 } from "@vertz/errors";
 interface CheckOptions {
 	compiler: Compiler;
 	format: "text" | "json" | "github";
 }
-interface CheckResult {
-	success: boolean;
+interface CheckData {
 	diagnostics: Diagnostic[];
 	output: string;
+	hasErrors: boolean;
 }
-declare function checkAction(options: CheckOptions): Promise<CheckResult>;
+declare function checkAction(options: CheckOptions): Promise<Result2<CheckData, Error>>;
+import { Result as Result3 } from "@vertz/errors";
 interface CreateOptions {
 	projectName?: string;
 	runtime?: string;
 	example?: boolean;
 }
-declare function createAction(options: CreateOptions): Promise<void>;
+declare function createAction(options: CreateOptions): Promise<Result3<void, Error>>;
+import { Result as Result4 } from "@vertz/errors";
 import { VertzConfig } from "@vertz/compiler";
 interface DevConfig {
 	port: number;
@@ -90,15 +86,10 @@ interface DeployOptions {
 	projectRoot: string;
 	dryRun?: boolean;
 }
-type DeployResult = {
-	success: true;
+declare function deployAction(options: DeployOptions): Result4<{
 	files: GeneratedFile[];
-} | {
-	success: false;
-	files: GeneratedFile[];
-	error: string;
-};
-declare function deployAction(options: DeployOptions): DeployResult;
+}, Error>;
+import { Result as Result5 } from "@vertz/errors";
 import { Command as Command2 } from "commander";
 interface DevCommandOptions {
 	port?: number;
@@ -111,11 +102,12 @@ interface DevCommandOptions {
 /**
 * Run the dev command
 */
-declare function devAction(options?: DevCommandOptions): Promise<void>;
+declare function devAction(options?: DevCommandOptions): Promise<Result5<void, Error>>;
 /**
 * Register the dev command with a Commander program
 */
 declare function registerDevCommand(program: Command2): void;
+import { Result as Result6 } from "@vertz/errors";
 interface GenerateOptions {
 	type: string;
 	name: string;
@@ -123,16 +115,11 @@ interface GenerateOptions {
 	sourceDir: string;
 	dryRun?: boolean;
 }
-type GenerateResult = {
-	success: true;
-	files: GeneratedFile[];
-} | {
-	success: false;
+declare function generateAction(options: GenerateOptions): Result6<{
 	files: GeneratedFile[];
-	error: string;
-};
-declare function generateAction(options: GenerateOptions): GenerateResult;
+}, Error>;
 import { Compiler as Compiler2, HttpMethod } from "@vertz/compiler";
+import { Result as Result7 } from "@vertz/errors";
 interface FlatRoute {
 	method: HttpMethod;
 	path: string;
@@ -146,28 +133,66 @@ interface RoutesOptions {
 	format: "table" | "json";
 	module?: string;
 }
-interface RoutesResult {
+declare function routesAction(options: RoutesOptions): Promise<Result7<{
 	routes: FlatRoute[];
 	output: string;
+}, Error>>;
+import { VertzConfig as VertzConfig2 } from "@vertz/compiler";
+declare function findConfigFile(startDir?: string): string | undefined;
+declare function loadConfig(configPath?: string): Promise<VertzConfig2>;
+import { CompileResult } from "@vertz/compiler";
+interface FileChange {
+	type: "add" | "change" | "remove";
+	path: string;
+}
+interface Watcher {
+	on(event: "change", handler: (changes: FileChange[]) => void): void;
+	close(): void;
+	/** @internal — for testing only */
+	_emit(change: FileChange): void;
 }
-declare function routesAction(options: RoutesOptions): Promise<RoutesResult>;
+declare function createWatcher(_dir: string): Watcher;
+interface DevLoopDeps {
+	compile(): Promise<CompileResult>;
+	startProcess(): void;
+	stopProcess(): Promise<void>;
+	onFileChange(handler: (changes: FileChange[]) => void): void;
+	onCompileSuccess(result: CompileResult): void;
+	onCompileError(result: CompileResult): void;
+}
+interface DevLoop {
+	start(): Promise<void>;
+	stop(): Promise<void>;
+}
+declare function createDevLoop(deps: DevLoopDeps): DevLoop;
+import { ChildProcess } from "node:child_process";
+interface ProcessManager {
+	start(entryPoint: string, env?: Record<string, string>): void;
+	stop(): Promise<void>;
+	restart(entryPoint: string, env?: Record<string, string>): Promise<void>;
+	isRunning(): boolean;
+	onOutput(handler: (data: string) => void): void;
+	onError(handler: (data: string) => void): void;
+}
+type SpawnFn = (entryPoint: string, env?: Record<string, string>) => ChildProcess;
+declare function createProcessManager(spawnFn?: SpawnFn): ProcessManager;
 import { AppIR } from "@vertz/compiler";
-import { GenerateResult as GenerateResult2 } from "@vertz/codegen";
+import { GenerateResult } from "@vertz/codegen";
 /**
 * Pipeline types - Core type definitions
 */
 /**
 * Pipeline stages that can be executed
 */
-type PipelineStage = "analyze" | "codegen" | "build-ui" | "db-sync";
+type PipelineStage = "analyze" | "openapi" | "codegen" | "build-ui" | "db-sync";
 /**
 * File categories for smart dispatch
 */
-type FileCategory = "domain" | "module" | "schema" | "service" | "route" | "component" | "config" | "other";
+type FileCategory = "module" | "schema" | "service" | "route" | "entity" | "component" | "config" | "other";
 /**
 * A file change event from the watcher
 */
-interface FileChange {
+interface FileChange2 {
 	type: "add" | "change" | "remove";
 	path: string;
 	category?: FileCategory;
@@ -175,11 +200,11 @@ interface FileChange {
 /**
 * Watcher interface
 */
-interface Watcher {
-	on(event: "change", handler: (changes: FileChange[]) => void): void;
+interface Watcher2 {
+	on(event: "change", handler: (changes: FileChange2[]) => void): void;
 	close(): void;
 	/** @internal — for testing only */
-	_emit(change: FileChange): void;
+	_emit(change: FileChange2): void;
 }
 /**
 * Configuration for the watcher
@@ -192,15 +217,15 @@ interface WatcherConfig {
 	/** Debounce delay in ms */
 	debounceMs?: number;
 	/** Callback when files change */
-	onChange?: (changes: FileChange[]) => void;
+	onChange?: (changes: FileChange2[]) => void;
 }
 /**
 * Pipeline watcher event handlers
 */
 interface PipelineWatcherHandlers {
-	analyze: (changes: FileChange[]) => void;
-	codegen: (changes: FileChange[]) => void;
-	"build-ui": (changes: FileChange[]) => void;
+	analyze: (changes: FileChange2[]) => void;
+	codegen: (changes: FileChange2[]) => void;
+	"build-ui": (changes: FileChange2[]) => void;
 	error: (error: Error) => void;
 }
 /**
@@ -247,7 +272,7 @@ interface PipelineResult {
 	stages: StageResult[];
 	totalDurationMs: number;
 	appIR?: AppIR;
-	generatedFiles?: GenerateResult2;
+	generatedFiles?: GenerateResult;
 }
 /**
 * Pipeline Orchestrator
@@ -282,6 +307,10 @@ declare class PipelineOrchestrator {
 	*/
 	private runAnalyze;
 	/**
+	* Run the OpenAPI generation stage
+	*/
+	private runOpenAPIGenerate;
+	/**
 	* Run the codegen stage
 	*/
 	private runCodegen;
@@ -327,45 +356,6 @@ declare function getAffectedStages(category: FileCategory): PipelineStage[];
 * Create a pipeline watcher
 */
 declare function createPipelineWatcher(config: WatcherConfig): PipelineWatcher;
-import { VertzConfig as VertzConfig2 } from "@vertz/compiler";
-declare function findConfigFile(startDir?: string): string | undefined;
-declare function loadConfig(configPath?: string): Promise<VertzConfig2>;
-import { CompileResult } from "@vertz/compiler";
-interface FileChange2 {
-	type: "add" | "change" | "remove";
-	path: string;
-}
-interface Watcher2 {
-	on(event: "change", handler: (changes: FileChange2[]) => void): void;
-	close(): void;
-	/** @internal — for testing only */
-	_emit(change: FileChange2): void;
-}
-declare function createWatcher2(_dir: string): Watcher2;
-interface DevLoopDeps {
-	compile(): Promise<CompileResult>;
-	startProcess(): void;
-	stopProcess(): Promise<void>;
-	onFileChange(handler: (changes: FileChange2[]) => void): void;
-	onCompileSuccess(result: CompileResult): void;
-	onCompileError(result: CompileResult): void;
-}
-interface DevLoop {
-	start(): Promise<void>;
-	stop(): Promise<void>;
-}
-declare function createDevLoop(deps: DevLoopDeps): DevLoop;
-import { ChildProcess } from "node:child_process";
-interface ProcessManager {
-	start(entryPoint: string, env?: Record<string, string>): void;
-	stop(): Promise<void>;
-	restart(entryPoint: string, env?: Record<string, string>): Promise<void>;
-	isRunning(): boolean;
-	onOutput(handler: (data: string) => void): void;
-	onError(handler: (data: string) => void): void;
-}
-type SpawnFn = (entryPoint: string, env?: Record<string, string>) => ChildProcess;
-declare function createProcessManager(spawnFn?: SpawnFn): ProcessManager;
 import React from "react";
 interface BannerProps {
 	version: string;
@@ -386,8 +376,6 @@ declare function DiagnosticSummary({ diagnostics }: DiagnosticSummaryProps): Rea
 import { Diagnostic as Diagnostic4 } from "@vertz/compiler";
 declare function formatDiagnostic(diagnostic: Diagnostic4): string;
 declare function formatDiagnosticSummary(diagnostics: readonly Diagnostic4[]): string;
-import { colors, createTaskRunner, Message, SelectList, symbols, Task, TaskList } from "@vertz/tui";
-import { TaskGroup, TaskHandle, TaskRunner } from "@vertz/tui";
 declare function formatDuration(ms: number): string;
 declare function formatFileSize(bytes: number): string;
 declare function formatPath(absolutePath: string, cwd?: string): string;
@@ -396,4 +384,4 @@ declare function isCI(): boolean;
 declare function requireParam(value: string | undefined, name: string): string;
 type Runtime = "bun" | "node";
 declare function detectRuntime(): Runtime;
-export { symbols, routesAction, requireParam, registerDevCommand, loadConfig, isCI, getAffectedStages, generateAction, formatPath, formatFileSize, formatDuration, formatDiagnosticSummary, formatDiagnostic, findProjectRoot, findConfigFile, devAction, detectTarget, detectRuntime, deployAction, defaultCLIConfig, createWatcher2 as createWatcher, createTaskRunner, createProcessManager, createPipelineWatcher, createPipelineOrchestrator, createDevLoop, createCLI, createAction, colors, checkAction, categorizeFileChange, buildAction, Watcher, TaskRunner, TaskList, TaskHandle, TaskGroup, Task, StageResult, SelectList, PipelineWatcher, PipelineStage, PipelineResult, PipelineOrchestrator, PipelineConfig, Message, GeneratorDefinition, GeneratedFile, FileChange, FileCategory, DiagnosticSummary, DiagnosticDisplay, DevConfig, CLIConfig, Banner };
+export { symbols, routesAction, requireParam, registerDevCommand, loadConfig, isCI, getAffectedStages, generateAction, formatPath, formatFileSize, formatDuration, formatDiagnosticSummary, formatDiagnostic, findProjectRoot, findConfigFile, devAction, detectTarget, detectRuntime, deployAction, defaultCLIConfig, createWatcher, createTaskRunner, createProcessManager, createPipelineWatcher, createPipelineOrchestrator, createDevLoop, createCLI, createAction, colors, checkAction, categorizeFileChange, buildAction, Watcher2 as Watcher, TaskRunner, TaskList, TaskHandle, TaskGroup, Task, StageResult, SelectList, PipelineWatcher, PipelineStage, PipelineResult, PipelineOrchestrator, PipelineConfig, Message, GeneratorDefinition, GeneratedFile, FileChange2 as FileChange, FileCategory, DiagnosticSummary, DiagnosticDisplay, DevConfig, CLIConfig, Banner };