@flight-framework/cli 0.0.14 → 0.0.16

package/README.md

@@ -1,77 +1,474 @@
-# @flight-framework/cli
-
-Command-line interface for Flight Framework.
-
-## Installation
-
-```bash
-npm install -g @flight-framework/cli
-```
-
-Or use via npx:
-
-```bash
-npx @flight-framework/cli <command>
-```
-
-## Commands
-
-### create
-
-Create a new Flight project.
-
-```bash
-flight create [project-name]
-```
-
-Options:
-
-| Option | Description |
-|--------|-------------|
-| `--ui <framework>` | UI framework: react, vue, svelte, solid, preact, qwik, lit, htmx |
-| `--typescript` | Use TypeScript (default) |
-| `--no-typescript` | Use JavaScript |
-
-### dev
-
-Start the development server.
-
-```bash
-flight dev
-```
-
-Options:
-
-| Option | Description | Default |
-|--------|-------------|---------|
-| `-p, --port` | Port number | `5173` |
-| `-h, --host` | Host to bind | `localhost` |
-| `--open` | Open browser | `false` |
-| `--ssr` | Enable SSR | From config |
-
-### build
-
-Build for production.
-
-```bash
-flight build
-```
-
-### start
-
-Start the production server.
-
-```bash
-flight start
-```
-
-Options:
-
-| Option | Description | Default |
-|--------|-------------|---------|
-| `-p, --port` | Port number | `3000` |
-| `-h, --host` | Host to bind | `0.0.0.0` |
-
-## 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 |
+
+---
+
+## 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