@vertz/cli 0.2.0

package/README.md

@@ -0,0 +1,226 @@
+# @vertz/cli
+
+The `vertz` command. Create, develop, build, and publish 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.
+
+## 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
+
+```bash
+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';
+
+const app = createServer();
+// ... define your routes, modules, services
+```
+
+---
+
+## You want to develop locally
+
+```bash
+vertz dev
+```
+
+That's it. This starts your dev server with hot reload, background type-checking, and compiler diagnostics right in your terminal.
+
+**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
+
+---
+
+## You want to build for production
+
+```bash
+vertz build
+```
+
+Compiles your project, runs validation, and outputs production-ready code.
+
+```bash
+vertz build --strict           # treat warnings as errors
+vertz build --output dist      # custom output directory
+```
+
+---
+
+## You want to check your code without building
+
+```bash
+vertz check
+```
+
+Type-checks and validates 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)
+```
+
+---
+
+## You want to generate code
+
+```bash
+vertz generate module users
+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.
+
+You can also define [custom generators](#custom-generators) in your config.
+
+---
+
+## You want to deploy *(coming soon)*
+
+```bash
+vertz publish
+```
+
+One-command deployment to your configured target. **This command is not yet available** — it's on the roadmap.
+
+---
+
+## You want to see your routes
+
+```bash
+vertz routes                   # table format
+vertz routes --format json     # JSON output
+```
+
+Displays every route your application exposes.
+
+---
+
+## Installation
+
+```bash
+npm install @vertz/cli         # or bun add @vertz/cli
+```
+
+**Requirements:** Node.js 18+ or Bun 1.0+, TypeScript 5.0+
+
+---
+
+## Configuration
+
+Create `vertz.config.ts` in your project root:
+
+```ts
+import type { CLIConfig } from '@vertz/cli';
+
+const config: CLIConfig = {
+  compiler: {
+    sourceDir: 'src',
+    entryFile: 'src/app.ts',
+    outputDir: '.vertz/generated',
+  },
+  dev: {
+    port: 3000,
+    host: 'localhost',
+    typecheck: true,
+  },
+};
+
+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 {}` },
+    ];
+  },
+};
+
+const config: CLIConfig = {
+  generators: { entity },
+};
+
+export default config;
+```
+
+```bash
+vertz generate entity product
+vertz generate entity product --timestamps false
+```
+
+---
+
+## 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.outputDir` | `string` | `'.vertz/generated'` | Generated code output |
+| `dev.port` | `number` | `3000` | Dev server port |
+| `dev.host` | `string` | `'localhost'` | Dev server host |
+| `dev.open` | `boolean` | `false` | Open browser on start |
+| `dev.typecheck` | `boolean` | `true` | Background type-checking |
+
+---
+
+## 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.
+
+---
+
+## Related Packages
+
+- [`@vertz/server`](../server) — Server framework (`createServer`)
+- [`@vertz/compiler`](../compiler) — Vertz compiler
+- [`@vertz/codegen`](../codegen) — Code generation utilities
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,399 @@
+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
+*/
+interface BuildCommandOptions {
+	strict?: boolean;
+	output?: string;
+	target?: "node" | "edge" | "worker";
+	noTypecheck?: boolean;
+	noMinify?: boolean;
+	sourcemap?: boolean;
+	verbose?: boolean;
+}
+/**
+* Run the build command
+* @returns Exit code (0 for success, 1 for failure)
+*/
+declare function buildAction(options?: BuildCommandOptions): Promise<number>;
+import { Compiler, Diagnostic } from "@vertz/compiler";
+interface CheckOptions {
+	compiler: Compiler;
+	format: "text" | "json" | "github";
+}
+interface CheckResult {
+	success: boolean;
+	diagnostics: Diagnostic[];
+	output: string;
+}
+declare function checkAction(options: CheckOptions): Promise<CheckResult>;
+interface CreateOptions {
+	projectName?: string;
+	runtime?: string;
+	example?: boolean;
+}
+declare function createAction(options: CreateOptions): Promise<void>;
+import { VertzConfig } from "@vertz/compiler";
+interface DevConfig {
+	port: number;
+	host: string;
+	open: boolean;
+	typecheck: boolean;
+}
+interface GeneratorArgument {
+	name: string;
+	description: string;
+	required: boolean;
+}
+interface GeneratorOption {
+	name: string;
+	flag: string;
+	description: string;
+	default?: string;
+}
+interface GeneratorContext {
+	name: string;
+	options: Record<string, string>;
+	projectRoot: string;
+	sourceDir: string;
+	config: VertzConfig;
+}
+interface GeneratedFile {
+	path: string;
+	content: string;
+}
+interface GeneratorDefinition {
+	name: string;
+	description: string;
+	arguments: GeneratorArgument[];
+	options?: GeneratorOption[];
+	run(context: GeneratorContext): Promise<GeneratedFile[]>;
+}
+interface CLIConfig extends VertzConfig {
+	dev?: DevConfig;
+	generators?: Record<string, GeneratorDefinition>;
+}
+declare const defaultCLIConfig: CLIConfig;
+type DeployTarget = "fly" | "railway" | "docker";
+declare function detectTarget(projectRoot: string, existsFn: (path: string) => boolean): DeployTarget | null;
+interface DeployOptions {
+	target: DeployTarget;
+	runtime: "bun" | "node";
+	port: number;
+	projectRoot: string;
+	dryRun?: boolean;
+}
+type DeployResult = {
+	success: true;
+	files: GeneratedFile[];
+} | {
+	success: false;
+	files: GeneratedFile[];
+	error: string;
+};
+declare function deployAction(options: DeployOptions): DeployResult;
+import { Command as Command2 } from "commander";
+interface DevCommandOptions {
+	port?: number;
+	host?: string;
+	open?: boolean;
+	typecheck?: boolean;
+	noTypecheck?: boolean;
+	verbose?: boolean;
+}
+/**
+* Run the dev command
+*/
+declare function devAction(options?: DevCommandOptions): Promise<void>;
+/**
+* Register the dev command with a Commander program
+*/
+declare function registerDevCommand(program: Command2): void;
+interface GenerateOptions {
+	type: string;
+	name: string;
+	module?: string;
+	sourceDir: string;
+	dryRun?: boolean;
+}
+type GenerateResult = {
+	success: true;
+	files: GeneratedFile[];
+} | {
+	success: false;
+	files: GeneratedFile[];
+	error: string;
+};
+declare function generateAction(options: GenerateOptions): GenerateResult;
+import { Compiler as Compiler2, HttpMethod } from "@vertz/compiler";
+interface FlatRoute {
+	method: HttpMethod;
+	path: string;
+	fullPath: string;
+	operationId: string;
+	moduleName: string;
+	middleware: string[];
+}
+interface RoutesOptions {
+	compiler: Compiler2;
+	format: "table" | "json";
+	module?: string;
+}
+interface RoutesResult {
+	routes: FlatRoute[];
+	output: string;
+}
+declare function routesAction(options: RoutesOptions): Promise<RoutesResult>;
+import { AppIR } from "@vertz/compiler";
+import { GenerateResult as GenerateResult2 } from "@vertz/codegen";
+/**
+* Pipeline types - Core type definitions
+*/
+/**
+* Pipeline stages that can be executed
+*/
+type PipelineStage = "analyze" | "codegen" | "build-ui" | "db-sync";
+/**
+* File categories for smart dispatch
+*/
+type FileCategory = "domain" | "module" | "schema" | "service" | "route" | "component" | "config" | "other";
+/**
+* A file change event from the watcher
+*/
+interface FileChange {
+	type: "add" | "change" | "remove";
+	path: string;
+	category?: FileCategory;
+}
+/**
+* Watcher interface
+*/
+interface Watcher {
+	on(event: "change", handler: (changes: FileChange[]) => void): void;
+	close(): void;
+	/** @internal — for testing only */
+	_emit(change: FileChange): void;
+}
+/**
+* Configuration for the watcher
+*/
+interface WatcherConfig {
+	/** Directory to watch */
+	dir: string;
+	/** Patterns to ignore */
+	ignorePatterns?: string[];
+	/** Debounce delay in ms */
+	debounceMs?: number;
+	/** Callback when files change */
+	onChange?: (changes: FileChange[]) => void;
+}
+/**
+* Pipeline watcher event handlers
+*/
+interface PipelineWatcherHandlers {
+	analyze: (changes: FileChange[]) => void;
+	codegen: (changes: FileChange[]) => void;
+	"build-ui": (changes: FileChange[]) => void;
+	error: (error: Error) => void;
+}
+/**
+* Watcher that understands file semantics
+*/
+interface PipelineWatcher {
+	on<K extends keyof PipelineWatcherHandlers>(event: K, handler: PipelineWatcherHandlers[K]): void;
+	close(): void;
+}
+/**
+* Configuration for the pipeline orchestrator
+*/
+interface PipelineConfig {
+	/** Source directory */
+	sourceDir: string;
+	/** Output directory for generated files */
+	outputDir: string;
+	/** Whether to enable type checking */
+	typecheck: boolean;
+	/** Whether to auto-sync DB schema in dev mode */
+	autoSyncDb: boolean;
+	/** Whether to open browser on start */
+	open: boolean;
+	/** Port for dev server */
+	port: number;
+	/** Host for dev server */
+	host: string;
+}
+/**
+* Result from running a pipeline stage
+*/
+interface StageResult {
+	stage: PipelineStage;
+	success: boolean;
+	durationMs: number;
+	error?: Error;
+	output?: string;
+}
+/**
+* Complete result from running the pipeline
+*/
+interface PipelineResult {
+	success: boolean;
+	stages: StageResult[];
+	totalDurationMs: number;
+	appIR?: AppIR;
+	generatedFiles?: GenerateResult2;
+}
+/**
+* Pipeline Orchestrator
+*
+* Coordinates the full development pipeline:
+* 1. Analyze (compiler → AppIR)
+* 2. Generate (codegen → types, route map, DB client)
+* 3. Build UI (components → ES modules)
+* 4. Serve (dev server with HMR)
+*/
+declare class PipelineOrchestrator {
+	private config;
+	private compiler;
+	private appIR;
+	private isRunning;
+	private stages;
+	constructor(config?: Partial<PipelineConfig>);
+	/**
+	* Initialize the pipeline - create compiler instance
+	*/
+	initialize(): Promise<void>;
+	/**
+	* Run the full pipeline once
+	*/
+	runFull(): Promise<PipelineResult>;
+	/**
+	* Run specific stages based on file changes
+	*/
+	runStages(stages: PipelineStage[]): Promise<PipelineResult>;
+	/**
+	* Run the analyze stage
+	*/
+	private runAnalyze;
+	/**
+	* Run the codegen stage
+	*/
+	private runCodegen;
+	/**
+	* Run the UI build stage
+	* Note: This currently delegates to Vite. In the future, this will use @vertz/ui-compiler directly.
+	*/
+	private runBuildUI;
+	/**
+	* Run the DB sync stage
+	*/
+	private runDbSync;
+	/**
+	* Get the current AppIR
+	*/
+	getAppIR(): AppIR | null;
+	/**
+	* Check if the pipeline is currently running
+	*/
+	isPipelineRunning(): boolean;
+	/**
+	* Get the latest result for a specific stage
+	*/
+	getStageResult(stage: PipelineStage): StageResult | undefined;
+	/**
+	* Clean up resources
+	*/
+	dispose(): Promise<void>;
+}
+/**
+* Create a new pipeline orchestrator
+*/
+declare function createPipelineOrchestrator(config?: Partial<PipelineConfig>): PipelineOrchestrator;
+/**
+* Categorize a file change based on its path
+*/
+declare function categorizeFileChange(path: string): FileCategory;
+/**
+* Determine which pipeline stages are affected by a file category
+*/
+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;
+}
+declare function Banner({ version }: BannerProps): React.ReactElement;
+import { Diagnostic as Diagnostic2 } from "@vertz/compiler";
+import React2 from "react";
+interface DiagnosticDisplayProps {
+	diagnostic: Diagnostic2;
+}
+declare function DiagnosticDisplay({ diagnostic }: DiagnosticDisplayProps): React2.ReactElement;
+import { Diagnostic as Diagnostic3 } from "@vertz/compiler";
+import React3 from "react";
+interface DiagnosticSummaryProps {
+	diagnostics: readonly Diagnostic3[];
+}
+declare function DiagnosticSummary({ diagnostics }: DiagnosticSummaryProps): React3.ReactElement;
+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;
+declare function findProjectRoot(startDir?: string): string | undefined;
+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 };