@flight-framework/cli 0.2.0 → 0.2.1

package/README.md

@@ -1,544 +1,544 @@
-# @flight-framework/cli
-
-The command-line interface for Flight Framework. Create, develop, build, and deploy full-stack applications with a single tool.
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Creating a Project](#creating-a-project)
-- [Development](#development)
-- [Building for Production](#building-for-production)
-- [Running in Production](#running-in-production)
-- [Generate Commands](#generate-commands)
-- [Configuration](#configuration)
-- [Environment Variables](#environment-variables)
-- [All Commands Reference](#all-commands-reference)
-- [Troubleshooting](#troubleshooting)
-- [License](#license)
-
----
-
-## Installation
-
-### Global Installation (Recommended)
-
-```bash
-npm install -g @flight-framework/cli
-```
-
-After installation, the `flight` command is available globally:
-
-```bash
-flight --version
-flight --help
-```
-
-### Using npx (No Installation)
-
-Run commands without installing:
-
-```bash
-npx @flight-framework/cli create my-app
-npx @flight-framework/cli dev
-```
-
-### Using pnpm or yarn
-
-```bash
-pnpm add -g @flight-framework/cli
-# or
-yarn global add @flight-framework/cli
-```
-
----
-
-## Creating a Project
-
-### Interactive Mode
-
-Run `create` without arguments for the interactive wizard:
-
-```bash
-flight create
-```
-
-The wizard guides you through:
-1. Project name
-2. UI framework selection
-3. TypeScript or JavaScript
-4. Additional features (forms, auth, i18n, etc.)
-
-### Quick Start
-
-Create a project with defaults (React + TypeScript):
-
-```bash
-flight create my-app
-cd my-app
-npm install
-flight dev
-```
-
-### With Options
-
-Specify options to skip prompts:
-
-```bash
-# React with TypeScript (default)
-flight create my-app
-
-# Vue with TypeScript
-flight create my-app --ui vue
-
-# Svelte with JavaScript
-flight create my-app --ui svelte --no-typescript
-
-# Solid with all features
-flight create my-app --ui solid --features forms,auth,i18n
-```
-
-### Available UI Frameworks
-
-| Framework | Option | Description |
-|-----------|--------|-------------|
-| React | `--ui react` | Default. Best ecosystem support |
-| Vue | `--ui vue` | Composition API with SFC support |
-| Svelte | `--ui svelte` | Compiler-based, minimal runtime |
-| Solid | `--ui solid` | Fine-grained reactivity |
-| Preact | `--ui preact` | Lightweight React alternative |
-| Qwik | `--ui qwik` | Resumability-first |
-| Lit | `--ui lit` | Web Components |
-| HTMX | `--ui htmx` | HTML-driven interactivity |
-
-### Create Options
-
-| Option | Description |
-|--------|-------------|
-| `--ui <framework>` | UI framework to use |
-| `--typescript` | Use TypeScript (default) |
-| `--no-typescript` | Use JavaScript |
-| `--features <list>` | Comma-separated features: forms, auth, i18n, db |
-| `--package-manager <pm>` | npm, pnpm, yarn, or bun |
-| `--git` | Initialize git repository (default: true) |
-| `--no-git` | Skip git initialization |
-| `--install` | Install dependencies (default: true) |
-| `--no-install` | Skip dependency installation |
-| `--raw` | Create raw project (100% Web Standards, zero dependencies) |
-| `--empty` | Create empty project (just package.json) |
-| `--minimal` | Create minimal project (single server file) |
-
-### Toolbox Mode (Zero Lock-in)
-
-Start with the minimum and add what you need:
-
-```bash
-# Raw project - 100% Web Standards, ZERO dependencies
-# Works on Bun, Deno, Node 22+, Cloudflare Workers
-flight create my-app --raw
-
-# Empty project - just package.json
-flight create my-app --empty
-
-# Minimal project - single server file with Flight
-flight create my-app --minimal
-
-# Then add packages as needed
-cd my-app
-flight add http
-flight add db
-flight add cache
-```
-
-The `--raw` mode generates code with **zero Flight dependencies**. You can run it on any runtime and add Flight packages later if you want.
-
----
-
-## Adding Packages
-
-Add Flight packages to an existing project:
-
-```bash
-flight add [package]
-```
-
-### Available Packages
-
-| Package | Description |
-|---------|-------------|
-| `http` | HTTP server with routing and middleware |
-| `core` | File-based routing and configuration |
-| `db` | Database abstraction layer |
-| `cache` | Caching with multiple adapters |
-| `auth` | Authentication adapters |
-| `forms` | Type-safe form handling |
-| `i18n` | Internationalization |
-| `seo` | SEO utilities |
-| `image` | Image optimization |
-| `email` | Email sending |
-| `realtime` | WebSocket and real-time features |
-| `helpers` | Optional helper utilities |
-
-### Examples
-
-```bash
-# Add HTTP server
-flight add http
-
-# Add database support
-flight add db
-
-# Add authentication
-flight add auth
-
-# See all packages
-flight add
-```
-
----
-
-## Development
-
-Start the development server with hot module replacement:
-
-```bash
-flight dev
-```
-
-The dev server includes:
-- Hot Module Replacement (HMR)
-- Server-Side Rendering (if enabled)
-- API routes with hot reload
-- TypeScript type checking
-- Error overlay with source maps
-
-### Dev Options
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `-p, --port <number>` | `5173` | Port number |
-| `-h, --host <host>` | `localhost` | Host to bind |
-| `--open` | `false` | Open browser automatically |
-| `--https` | `false` | Enable HTTPS with self-signed cert |
-| `--ssr` | from config | Enable/disable SSR |
-| `--no-ssr` | - | Disable SSR for this session |
-| `--force` | `false` | Force re-optimization of dependencies |
-
-### Examples
-
-```bash
-# Start on port 3000
-flight dev -p 3000
-
-# Bind to all interfaces (for network access)
-flight dev --host 0.0.0.0
-
-# Open browser and enable HTTPS
-flight dev --open --https
-
-# Disable SSR temporarily
-flight dev --no-ssr
-```
-
----
-
-## Building for Production
-
-Build optimized bundles for production:
-
-```bash
-flight build
-```
-
-The build process:
-1. Type checks the project
-2. Bundles client and server code
-3. Optimizes assets (minification, tree-shaking)
-4. Generates static pages (if configured)
-5. Creates deployment artifacts
-
-### Build Options
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `--target <adapter>` | from config | Deployment target |
-| `--analyze` | `false` | Generate bundle analysis |
-| `--sourcemap` | `false` | Include source maps |
-| `--no-minify` | - | Skip minification |
-
-### Deployment Targets
-
-```bash
-# Node.js server (default)
-flight build --target node
-
-# Cloudflare Workers
-flight build --target cloudflare
-
-# Vercel
-flight build --target vercel
-
-# Netlify
-flight build --target netlify
-
-# Static site
-flight build --target static
-
-# Docker
-flight build --target docker
-```
-
-### Build Output
-
-```
-dist/
-  client/           # Browser bundles
-    assets/
-    index.html
-  server/           # Server code
-    index.js
-  static/           # Pre-rendered pages
-```
-
----
-
-## Running in Production
-
-Start the production server:
-
-```bash
-flight start
-```
-
-This runs the optimized build with:
-- Compression enabled
-- Static asset caching
-- Production error handling
-- Health check endpoint at `/_health`
-
-### Start Options
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `-p, --port <number>` | `3000` | Port number |
-| `-h, --host <host>` | `0.0.0.0` | Host to bind |
-| `--cluster` | `false` | Enable cluster mode |
-| `--workers <number>` | CPU cores | Number of workers |
-
-### Examples
-
-```bash
-# Start on port 8080
-flight start -p 8080
-
-# Enable cluster mode for multi-core
-flight start --cluster --workers 4
-```
-
----
-
-## Generate Commands
-
-Scaffold new files with correct structure:
-
-```bash
-flight generate <type> <name>
-# or shorthand
-flight g <type> <name>
-```
-
-### Available Generators
-
-| Type | Alias | Description |
-|------|-------|-------------|
-| `page` | `p` | New page component |
-| `api` | `a` | API route handler |
-| `component` | `c` | UI component |
-| `action` | `act` | Server action |
-| `middleware` | `mw` | Middleware function |
-| `layout` | `l` | Layout component |
-
-### Examples
-
-```bash
-# Generate a page at /dashboard
-flight g page dashboard
-
-# Generate an API route at /api/users
-flight g api users
-
-# Generate a reusable component
-flight g component Button
-
-# Generate a server action
-flight g action submitForm
-
-# Generate middleware
-flight g middleware auth
-```
-
-### Generated Files
-
-```bash
-flight g page dashboard
-# Creates: src/routes/dashboard.page.tsx
-
-flight g api users
-# Creates: src/routes/api/users.get.ts
-#          src/routes/api/users.post.ts
-
-flight g component Button
-# Creates: src/components/Button.tsx
-#          src/components/Button.css
-```
-
----
-
-## Configuration
-
-Flight uses `flight.config.ts` (or `.js`) in the project root:
-
-```typescript
-// flight.config.ts
-import { defineConfig } from '@flight-framework/core';
-
-export default defineConfig({
-  // Server configuration
-  server: {
-    port: 3000,
-    host: 'localhost',
-  },
-
-  // Rendering options
-  render: {
-    defaultMode: 'ssr',        // 'ssr' | 'ssg' | 'spa'
-    streaming: true,
-  },
-
-  // Build options
-  build: {
-    outDir: 'dist',
-    target: 'node',            // Deployment target
-    minify: true,
-    sourcemap: false,
-  },
-
-  // Routes configuration
-  routes: {
-    directory: 'src/routes',
-  },
-});
-```
-
----
-
-## Environment Variables
-
-Flight automatically loads environment variables:
-
-| File | Environment | Priority |
-|------|-------------|---------|
-| `.env` | All | 1 (lowest) |
-| `.env.local` | All | 2 |
-| `.env.development` | Development | 3 |
-| `.env.production` | Production | 3 |
-| `.env.development.local` | Development | 4 (highest) |
-| `.env.production.local` | Production | 4 (highest) |
-
-### Accessing Variables
-
-```typescript
-// Server-side (full access)
-const apiKey = process.env.API_KEY;
-
-// Client-side (only PUBLIC_ prefix)
-const publicUrl = process.env.PUBLIC_API_URL;
-```
-
-Only variables prefixed with `PUBLIC_` are exposed to the browser.
-
----
-
-## All Commands Reference
-
-| Command | Description |
-|---------|-------------|
-| `flight create [name]` | Create new project |
-| `flight dev` | Start development server |
-| `flight build` | Build for production |
-| `flight start` | Start production server |
-| `flight generate <type> <name>` | Generate files |
-| `flight typecheck` | Run TypeScript type checking |
-| `flight lint` | Run ESLint |
-| `flight test` | Run tests |
-| `flight preview` | Preview production build locally |
-| `flight upgrade` | Upgrade Flight packages |
-| `flight info` | Display project information |
-
-### Global Options
-
-Available on all commands:
-
-| Option | Description |
-|--------|-------------|
-| `--help` | Show help |
-| `--version` | Show version |
-| `--config <path>` | Path to config file |
-| `--cwd <path>` | Working directory |
-| `--verbose` | Verbose output |
-| `--quiet` | Minimal output |
-
----
-
-## Troubleshooting
-
-### Port Already in Use
-
-```bash
-# Use a different port
-flight dev -p 3001
-
-# Or kill the process using the port
-npx kill-port 5173
-```
-
-### TypeScript Errors on Start
-
-```bash
-# Force rebuild of type cache
-flight dev --force
-```
-
-### Permission Denied (Global Install)
-
-```bash
-# Fix npm permissions
-npm config set prefix ~/.npm-global
-export PATH=~/.npm-global/bin:$PATH
-
-# Or use npx instead
-npx @flight-framework/cli dev
-```
-
-### Slow Dev Server
-
-Check for large `node_modules` in the routes directory, or try:
-
-```bash
-# Clear Vite cache
-rm -rf node_modules/.vite
-flight dev
-```
-
-### Build Fails with Memory Error
-
-Increase Node.js memory limit:
-
-```bash
-NODE_OPTIONS="--max-old-space-size=8192" flight build
-```
-
----
-
-## License
-
-MIT
+# @flight-framework/cli
+
+The command-line interface for Flight Framework. Create, develop, build, and deploy full-stack applications with a single tool.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Creating a Project](#creating-a-project)
+- [Development](#development)
+- [Building for Production](#building-for-production)
+- [Running in Production](#running-in-production)
+- [Generate Commands](#generate-commands)
+- [Configuration](#configuration)
+- [Environment Variables](#environment-variables)
+- [All Commands Reference](#all-commands-reference)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
+
+---
+
+## Installation
+
+### Global Installation (Recommended)
+
+```bash
+npm install -g @flight-framework/cli
+```
+
+After installation, the `flight` command is available globally:
+
+```bash
+flight --version
+flight --help
+```
+
+### Using npx (No Installation)
+
+Run commands without installing:
+
+```bash
+npx @flight-framework/cli create my-app
+npx @flight-framework/cli dev
+```
+
+### Using pnpm or yarn
+
+```bash
+pnpm add -g @flight-framework/cli
+# or
+yarn global add @flight-framework/cli
+```
+
+---
+
+## Creating a Project
+
+### Interactive Mode
+
+Run `create` without arguments for the interactive wizard:
+
+```bash
+flight create
+```
+
+The wizard guides you through:
+1. Project name
+2. UI framework selection
+3. TypeScript or JavaScript
+4. Additional features (forms, auth, i18n, etc.)
+
+### Quick Start
+
+Create a project with defaults (React + TypeScript):
+
+```bash
+flight create my-app
+cd my-app
+npm install
+flight dev
+```
+
+### With Options
+
+Specify options to skip prompts:
+
+```bash
+# React with TypeScript (default)
+flight create my-app
+
+# Vue with TypeScript
+flight create my-app --ui vue
+
+# Svelte with JavaScript
+flight create my-app --ui svelte --no-typescript
+
+# Solid with all features
+flight create my-app --ui solid --features forms,auth,i18n
+```
+
+### Available UI Frameworks
+
+| Framework | Option | Description |
+|-----------|--------|-------------|
+| React | `--ui react` | Default. Best ecosystem support |
+| Vue | `--ui vue` | Composition API with SFC support |
+| Svelte | `--ui svelte` | Compiler-based, minimal runtime |
+| Solid | `--ui solid` | Fine-grained reactivity |
+| Preact | `--ui preact` | Lightweight React alternative |
+| Qwik | `--ui qwik` | Resumability-first |
+| Lit | `--ui lit` | Web Components |
+| HTMX | `--ui htmx` | HTML-driven interactivity |
+
+### Create Options
+
+| Option | Description |
+|--------|-------------|
+| `--ui <framework>` | UI framework to use |
+| `--typescript` | Use TypeScript (default) |
+| `--no-typescript` | Use JavaScript |
+| `--features <list>` | Comma-separated features: forms, auth, i18n, db |
+| `--package-manager <pm>` | npm, pnpm, yarn, or bun |
+| `--git` | Initialize git repository (default: true) |
+| `--no-git` | Skip git initialization |
+| `--install` | Install dependencies (default: true) |
+| `--no-install` | Skip dependency installation |
+| `--raw` | Create raw project (100% Web Standards, zero dependencies) |
+| `--empty` | Create empty project (just package.json) |
+| `--minimal` | Create minimal project (single server file) |
+
+### Toolbox Mode (Zero Lock-in)
+
+Start with the minimum and add what you need:
+
+```bash
+# Raw project - 100% Web Standards, ZERO dependencies
+# Works on Bun, Deno, Node 22+, Cloudflare Workers
+flight create my-app --raw
+
+# Empty project - just package.json
+flight create my-app --empty
+
+# Minimal project - single server file with Flight
+flight create my-app --minimal
+
+# Then add packages as needed
+cd my-app
+flight add http
+flight add db
+flight add cache
+```
+
+The `--raw` mode generates code with **zero Flight dependencies**. You can run it on any runtime and add Flight packages later if you want.
+
+---
+
+## Adding Packages
+
+Add Flight packages to an existing project:
+
+```bash
+flight add [package]
+```
+
+### Available Packages
+
+| Package | Description |
+|---------|-------------|
+| `http` | HTTP server with routing and middleware |
+| `core` | File-based routing and configuration |
+| `db` | Database abstraction layer |
+| `cache` | Caching with multiple adapters |
+| `auth` | Authentication adapters |
+| `forms` | Type-safe form handling |
+| `i18n` | Internationalization |
+| `seo` | SEO utilities |
+| `image` | Image optimization |
+| `email` | Email sending |
+| `realtime` | WebSocket and real-time features |
+| `helpers` | Optional helper utilities |
+
+### Examples
+
+```bash
+# Add HTTP server
+flight add http
+
+# Add database support
+flight add db
+
+# Add authentication
+flight add auth
+
+# See all packages
+flight add
+```
+
+---
+
+## Development
+
+Start the development server with hot module replacement:
+
+```bash
+flight dev
+```
+
+The dev server includes:
+- Hot Module Replacement (HMR)
+- Server-Side Rendering (if enabled)
+- API routes with hot reload
+- TypeScript type checking
+- Error overlay with source maps
+
+### Dev Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-p, --port <number>` | `5173` | Port number |
+| `-h, --host <host>` | `localhost` | Host to bind |
+| `--open` | `false` | Open browser automatically |
+| `--https` | `false` | Enable HTTPS with self-signed cert |
+| `--ssr` | from config | Enable/disable SSR |
+| `--no-ssr` | - | Disable SSR for this session |
+| `--force` | `false` | Force re-optimization of dependencies |
+
+### Examples
+
+```bash
+# Start on port 3000
+flight dev -p 3000
+
+# Bind to all interfaces (for network access)
+flight dev --host 0.0.0.0
+
+# Open browser and enable HTTPS
+flight dev --open --https
+
+# Disable SSR temporarily
+flight dev --no-ssr
+```
+
+---
+
+## Building for Production
+
+Build optimized bundles for production:
+
+```bash
+flight build
+```
+
+The build process:
+1. Type checks the project
+2. Bundles client and server code
+3. Optimizes assets (minification, tree-shaking)
+4. Generates static pages (if configured)
+5. Creates deployment artifacts
+
+### Build Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--target <adapter>` | from config | Deployment target |
+| `--analyze` | `false` | Generate bundle analysis |
+| `--sourcemap` | `false` | Include source maps |
+| `--no-minify` | - | Skip minification |
+
+### Deployment Targets
+
+```bash
+# Node.js server (default)
+flight build --target node
+
+# Cloudflare Workers
+flight build --target cloudflare
+
+# Vercel
+flight build --target vercel
+
+# Netlify
+flight build --target netlify
+
+# Static site
+flight build --target static
+
+# Docker
+flight build --target docker
+```
+
+### Build Output
+
+```
+dist/
+  client/           # Browser bundles
+    assets/
+    index.html
+  server/           # Server code
+    index.js
+  static/           # Pre-rendered pages
+```
+
+---
+
+## Running in Production
+
+Start the production server:
+
+```bash
+flight start
+```
+
+This runs the optimized build with:
+- Compression enabled
+- Static asset caching
+- Production error handling
+- Health check endpoint at `/_health`
+
+### Start Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-p, --port <number>` | `3000` | Port number |
+| `-h, --host <host>` | `0.0.0.0` | Host to bind |
+| `--cluster` | `false` | Enable cluster mode |
+| `--workers <number>` | CPU cores | Number of workers |
+
+### Examples
+
+```bash
+# Start on port 8080
+flight start -p 8080
+
+# Enable cluster mode for multi-core
+flight start --cluster --workers 4
+```
+
+---
+
+## Generate Commands
+
+Scaffold new files with correct structure:
+
+```bash
+flight generate <type> <name>
+# or shorthand
+flight g <type> <name>
+```
+
+### Available Generators
+
+| Type | Alias | Description |
+|------|-------|-------------|
+| `page` | `p` | New page component |
+| `api` | `a` | API route handler |
+| `component` | `c` | UI component |
+| `action` | `act` | Server action |
+| `middleware` | `mw` | Middleware function |
+| `layout` | `l` | Layout component |
+
+### Examples
+
+```bash
+# Generate a page at /dashboard
+flight g page dashboard
+
+# Generate an API route at /api/users
+flight g api users
+
+# Generate a reusable component
+flight g component Button
+
+# Generate a server action
+flight g action submitForm
+
+# Generate middleware
+flight g middleware auth
+```
+
+### Generated Files
+
+```bash
+flight g page dashboard
+# Creates: src/routes/dashboard.page.tsx
+
+flight g api users
+# Creates: src/routes/api/users.get.ts
+#          src/routes/api/users.post.ts
+
+flight g component Button
+# Creates: src/components/Button.tsx
+#          src/components/Button.css
+```
+
+---
+
+## Configuration
+
+Flight uses `flight.config.ts` (or `.js`) in the project root:
+
+```typescript
+// flight.config.ts
+import { defineConfig } from '@flight-framework/core';
+
+export default defineConfig({
+  // Server configuration
+  server: {
+    port: 3000,
+    host: 'localhost',
+  },
+
+  // Rendering options
+  render: {
+    defaultMode: 'ssr',        // 'ssr' | 'ssg' | 'spa'
+    streaming: true,
+  },
+
+  // Build options
+  build: {
+    outDir: 'dist',
+    target: 'node',            // Deployment target
+    minify: true,
+    sourcemap: false,
+  },
+
+  // Routes configuration
+  routes: {
+    directory: 'src/routes',
+  },
+});
+```
+
+---
+
+## Environment Variables
+
+Flight automatically loads environment variables:
+
+| File | Environment | Priority |
+|------|-------------|---------|
+| `.env` | All | 1 (lowest) |
+| `.env.local` | All | 2 |
+| `.env.development` | Development | 3 |
+| `.env.production` | Production | 3 |
+| `.env.development.local` | Development | 4 (highest) |
+| `.env.production.local` | Production | 4 (highest) |
+
+### Accessing Variables
+
+```typescript
+// Server-side (full access)
+const apiKey = process.env.API_KEY;
+
+// Client-side (only PUBLIC_ prefix)
+const publicUrl = process.env.PUBLIC_API_URL;
+```
+
+Only variables prefixed with `PUBLIC_` are exposed to the browser.
+
+---
+
+## All Commands Reference
+
+| Command | Description |
+|---------|-------------|
+| `flight create [name]` | Create new project |
+| `flight dev` | Start development server |
+| `flight build` | Build for production |
+| `flight start` | Start production server |
+| `flight generate <type> <name>` | Generate files |
+| `flight typecheck` | Run TypeScript type checking |
+| `flight lint` | Run ESLint |
+| `flight test` | Run tests |
+| `flight preview` | Preview production build locally |
+| `flight upgrade` | Upgrade Flight packages |
+| `flight info` | Display project information |
+
+### Global Options
+
+Available on all commands:
+
+| Option | Description |
+|--------|-------------|
+| `--help` | Show help |
+| `--version` | Show version |
+| `--config <path>` | Path to config file |
+| `--cwd <path>` | Working directory |
+| `--verbose` | Verbose output |
+| `--quiet` | Minimal output |
+
+---
+
+## Troubleshooting
+
+### Port Already in Use
+
+```bash
+# Use a different port
+flight dev -p 3001
+
+# Or kill the process using the port
+npx kill-port 5173
+```
+
+### TypeScript Errors on Start
+
+```bash
+# Force rebuild of type cache
+flight dev --force
+```
+
+### Permission Denied (Global Install)
+
+```bash
+# Fix npm permissions
+npm config set prefix ~/.npm-global
+export PATH=~/.npm-global/bin:$PATH
+
+# Or use npx instead
+npx @flight-framework/cli dev
+```
+
+### Slow Dev Server
+
+Check for large `node_modules` in the routes directory, or try:
+
+```bash
+# Clear Vite cache
+rm -rf node_modules/.vite
+flight dev
+```
+
+### Build Fails with Memory Error
+
+Increase Node.js memory limit:
+
+```bash
+NODE_OPTIONS="--max-old-space-size=8192" flight build
+```
+
+---
+
+## License
+
+MIT