@rip-lang/server 1.2.11 → 1.3.0

package/README.md

@@ -2,32 +2,34 @@
 
 # Rip Server - @rip-lang/server
 
-> **A production-grade application server with multi-worker processes, hot reload, HTTPS, and mDNS — written entirely in Rip**
+> **A full-stack web framework and production server — routing, middleware, multi-worker processes, hot reload, HTTPS, and mDNS — written entirely in Rip**
 
-Rip Server is a self-contained application server that turns any
-[@rip-lang/api](https://github.com/shreeve/rip-lang/tree/main/packages/api)
-app into a production-ready service. It handles multi-worker process management,
+Rip Server is a unified web framework and application server. It provides
+Sinatra-style routing, built-in validators, file serving, and middleware
+composition for defining your API, plus multi-worker process management,
 rolling restarts, automatic TLS certificates, mDNS service discovery, and
-request load balancing — all in a single 1,200-line file with zero external
+request load balancing for running it in production — all with zero external
 dependencies.
 
 ## Features
 
 - **Multi-worker architecture** — Automatic worker spawning based on CPU cores
-- **Hot module reloading** — File-watch based reloading with `-w` flag
+- **Hot module reloading** — Watches `*.rip` files by default, rolling restarts on change
 - **Rolling restarts** — Zero-downtime deployments
 - **Automatic HTTPS** — TLS with mkcert or self-signed certificates
 - **mDNS discovery** — `.local` hostname advertisement
 - **Request queue** — Built-in request buffering and load balancing
 - **Built-in dashboard** — Server status UI at `rip.local`
-- **Powered by @rip-lang/api** — Runs any Rip API app
+- **Unified package** — Web framework + production server in one
 
 | File | Lines | Role |
 |------|-------|------|
-| `server.rip` | ~1,210 | Complete server: CLI, workers, load balancing, TLS, mDNS |
+| `api.rip` | ~662 | Core framework: routing, validation, `read()`, `session`, `@send`, server |
+| `middleware.rip` | ~559 | Built-in middleware: cors, logger, sessions, compression, security, serve |
+| `server.rip` | ~1,210 | Process manager: CLI, workers, load balancing, TLS, mDNS |
 | `server.html` | ~420 | Built-in dashboard UI |
 
-> **See Also**: For the API framework, see [@rip-lang/api](../api/README.md). For the DuckDB server, see [@rip-lang/db](../db/README.md).
+> **See Also**: For the DuckDB server, see [@rip-lang/db](../db/README.md).
 
 ## Quick Start
 
@@ -37,27 +39,24 @@ dependencies.
 # Local (per-project)
 bun add @rip-lang/server
 
-# Global (use rip-server from anywhere)
+# Global
 bun add -g rip-lang @rip-lang/server
 ```
 
 ### Running Your App
 
 ```bash
-# From your app directory (uses ./index.rip by default)
-rip-server
-
-# With file watching (recommended for development)
-rip-server -w
+# From your app directory (uses ./index.rip, watches *.rip)
+rip serve
 
 # Name your app (for mDNS: myapp.local)
-rip-server myapp
+rip serve myapp
 
 # Explicit entry file
-rip-server ./app.rip
+rip serve ./app.rip
 
 # HTTP only mode
-rip-server http
+rip serve http
 ```
 
 ### Example App
@@ -65,7 +64,7 @@ rip-server http
 Create `index.rip`:
 
 ```coffee
-import { get, read, start } from '@rip-lang/api'
+import { get, read, start } from '@rip-lang/server'
 
 get '/', ->
   'Hello from Rip Server!'
@@ -83,7 +82,7 @@ start()
 Run it:
 
 ```bash
-rip-server -w
+rip serve
 ```
 
 Test it:
@@ -102,22 +101,677 @@ curl http://localhost/status
 # {"status":"healthy","app":"myapp","workers":5,"ports":{"https":443}}
 ```
 
+## The `read()` Function
+
+A validation and parsing powerhouse that eliminates 90% of API boilerplate.
+
+### Basic Patterns
+
+```coffee
+# Required field (throws if missing)
+email = read 'email', 'email!'
+
+# Optional field (returns null if missing)
+phone = read 'phone', 'phone'
+
+# With default value
+role = read 'role', ['admin', 'user'], 'user'
+
+# Get entire payload
+data = read()
+```
+
+### Range Validation
+
+The `[min, max]` syntax works for both numbers and string lengths:
+
+```coffee
+# Numbers: value range
+age = read 'age', 'int', [18, 120]        # Between 18 and 120
+priority = read 'priority', 'int', [1, 10]  # 1-10 range
+
+# Strings: length range
+username = read 'username', 'string', [3, 20]  # 3-20 characters
+bio = read 'bio', 'string', [0, 500]           # Up to 500 chars
+
+# Named parameters
+views = read 'views', 'int', min: 0             # Non-negative integer
+discount = read 'discount', 'float', max: 100   # Up to 100
+```
+
+### Enumeration Validation
+
+```coffee
+# Must be one of these values
+role = read 'role', ['admin', 'user', 'guest']
+status = read 'status', ['pending', 'active', 'closed']
+```
+
+### Regex Validation
+
+```coffee
+# Custom pattern matching
+code = read 'code', /^[A-Z]{3,6}$/
+```
+
+## Built-in Validators
+
+`@rip-lang/server` includes 37 validators for every common API need:
+
+### Numbers & Money
+```coffee
+id = read 'user_id', 'id!'       # Positive integer (1+)
+count = read 'count', 'whole'    # Non-negative integer (0+)
+price = read 'price', 'float'   # Decimal number
+cost = read 'cost', 'money'     # Banker's rounding to cents
+```
+
+### Text Processing
+```coffee
+title = read 'title', 'string'   # Collapses whitespace
+bio = read 'bio', 'text'         # Light cleanup
+name = read 'name', 'name'       # Trims and normalizes
+```
+
+### Contact Information
+```coffee
+email = read 'email', 'email'        # Valid email format
+phone = read 'phone', 'phone'        # US phone → (555) 123-4567
+address = read 'address', 'address'  # Trimmed address
+```
+
+### Geographic Data
+```coffee
+state = read 'state', 'state'      # Two-letter → uppercase
+zip = read 'zip', 'zip'            # 5-digit zip
+zipplus4 = read 'zip', 'zipplus4'  # 12345-6789 format
+```
+
+### Identity & Security
+```coffee
+ssn = read 'ssn', 'ssn'                # SSN → digits only
+sex = read 'gender', 'sex'             # m/f/o
+username = read 'username', 'username' # 3-20 chars, lowercase
+```
+
+### Web & Technical
+```coffee
+url = read 'website', 'url'      # Valid URL
+ip = read 'ip_address', 'ip'     # IPv4 address
+mac = read 'mac', 'mac'          # MAC address
+color = read 'color', 'color'    # Hex color → #abc123
+uuid = read 'user_id', 'uuid'    # UUID format
+semver = read 'version', 'semver' # Semantic version
+```
+
+### Time & Date
+```coffee
+date = read 'date', 'date'        # YYYY-MM-DD
+time = read 'time', 'time'        # HH:MM or HH:MM:SS (24-hour)
+time12 = read 'time', 'time12'    # 12-hour with am/pm
+```
+
+### Boolean & Collections
+```coffee
+active = read 'active', 'truthy'    # true/t/1/yes/y/on → true
+inactive = read 'off', 'falsy'      # false/f/0/no/n/off → true
+flag = read 'flag', 'bool'          # Either → boolean
+tags = read 'tags', 'array'         # Must be array
+config = read 'config', 'hash'      # Must be object
+settings = read 'data', 'json'      # Parse JSON string
+ids = read 'ids', 'ids'             # "1,2,3" → [1, 2, 3]
+slug = read 'slug', 'slug'          # URL-safe slug
+```
+
+### Custom Validators
+
+```coffee
+import { registerValidator, read } from '@rip-lang/server'
+
+registerValidator 'postalCode', (v) ->
+  if v =~ /^[A-Z]\d[A-Z] \d[A-Z]\d$/i
+    _[0].toUpperCase()
+  else
+    null
+
+# Now use it
+code = read 'postal', 'postalCode!'
+```
+
+## Routing
+
+### HTTP Methods
+
+```coffee
+import { get, post, put, patch, del, all } from '@rip-lang/server'
+
+get    '/users'     -> listUsers!
+post   '/users'     -> createUser!
+get    '/users/:id' -> getUser!
+put    '/users/:id' -> updateUser!
+patch  '/users/:id' -> patchUser!
+del    '/users/:id' -> deleteUser!
+all    '/health'    -> 'ok'  # All methods
+```
+
+### Path Parameters
+
+```coffee
+# Basic parameters
+get '/users/:id' ->
+  id = read 'id', 'id!'
+  { id }
+
+# Multiple parameters
+get '/users/:userId/posts/:postId' ->
+  userId = read 'userId', 'id!'
+  postId = read 'postId', 'id!'
+  { userId, postId }
+
+# Custom patterns
+get '/files/:name{[a-z]+\\.txt}' ->
+  name = read 'name'
+  { file: name }
+
+# Wildcards
+get '/static/*', (env) ->
+  { path: env.req.path }
+```
+
+### Route Grouping
+
+```coffee
+import { prefix } from '@rip-lang/server'
+
+prefix '/api/v1' ->
+  get '/users' -> listUsers!
+  get '/posts' -> listPosts!
+
+prefix '/api/v2' ->
+  get '/users' -> listUsersV2!
+```
+
+## Middleware
+
+### Built-in Middleware
+
+Import from `@rip-lang/server/middleware`:
+
+```coffee
+import { use } from '@rip-lang/server'
+import { cors, logger, compress, sessions, secureHeaders, timeout, bodyLimit } from '@rip-lang/server/middleware'
+
+# Logging
+use logger()
+use logger format: 'tiny'                # Minimal output
+use logger format: 'dev'                 # Colorized (default)
+use logger skip: (c) -> c.req.path is '/health'
+
+# CORS
+use cors()                               # Allow all origins
+use cors origin: 'https://myapp.com'     # Specific origin
+use cors origin: ['https://a.com', 'https://b.com']
+use cors credentials: true, maxAge: 86400
+
+# Compression (gzip/deflate)
+use compress()
+use compress threshold: 1024             # Min bytes to compress
+
+# Security headers
+use secureHeaders()
+use secureHeaders hsts: true, contentSecurityPolicy: "default-src 'self'"
+
+# Request limits
+use timeout ms: 30000                    # 30 second timeout
+use bodyLimit maxSize: 1024 * 1024       # 1MB max body
+```
+
+### Middleware Options
+
+| Middleware | Options |
+|------------|---------|
+| `logger()` | `format`, `skip`, `stream` |
+| `cors()` | `origin`, `methods`, `headers`, `credentials`, `maxAge`, `exposeHeaders`, `preflight` |
+| `compress()` | `threshold`, `encodings` |
+| `sessions()` | `secret`, `name`, `maxAge`, `secure`, `httpOnly`, `sameSite` |
+| `secureHeaders()` | `hsts`, `hstsMaxAge`, `contentSecurityPolicy`, `frameOptions`, `referrerPolicy` |
+| `timeout()` | `ms`, `message`, `status` |
+| `bodyLimit()` | `maxSize`, `message` |
+
+### Session Usage
+
+```coffee
+import { get, use, before, session } from '@rip-lang/server'
+import { sessions } from '@rip-lang/server/middleware'
+
+# Sessions parses cookies directly from request headers
+use sessions secret: process.env.SESSION_SECRET
+
+before ->
+  session.views ?= 0
+  session.views += 1
+
+get '/profile' ->
+  { userId: session.userId, views: session.views }
+
+get '/login' ->
+  session.userId = 123
+  { loggedIn: true }
+
+get '/logout' ->
+  delete session.userId
+  { loggedOut: true }
+```
+
+The `session` import works anywhere via AsyncLocalStorage — no `@` needed, works in helpers and nested callbacks.
+
+**Security note:** Without `secret`, sessions use plain base64 (dev only). With `secret`, sessions are HMAC-SHA256 signed (tamper-proof). Always set `secret` in production.
+
+### CORS with Preflight
+
+```coffee
+import { use } from '@rip-lang/server'
+import { cors } from '@rip-lang/server/middleware'
+
+# Handle OPTIONS early (before routes are matched)
+use cors origin: 'https://myapp.com', preflight: true
+```
+
+### Custom Middleware
+
+```coffee
+# Authentication middleware
+use (c, next) ->
+  token = @req.header 'Authorization'
+  unless token
+    return @json { error: 'Unauthorized' }, 401
+  @user = validateToken!(token)
+  await next()
+
+# Timing middleware
+use (c, next) ->
+  start = Date.now()
+  await next()
+  @header 'X-Response-Time', "#{Date.now() - start}ms"
+```
+
+### Request Lifecycle Filters
+
+Three filters run at different stages: `raw` → `before` → handler → `after`
+
+```coffee
+import { raw, before, after, get } from '@rip-lang/server'
+
+# Runs first — modify raw request before body parsing
+raw (req) ->
+  if req.headers.get('X-Raw-SQL') is 'true'
+    req.headers.set 'content-type', 'text/plain'
+
+skipPaths = ['/favicon.ico', '/ping', '/health']
+
+# Runs before handler (after body parsing)
+before ->
+  @start = Date.now()
+  @silent = @req.path in skipPaths
+  unless @req.header 'Authorization'
+    return @json { error: 'Unauthorized' }, 401
+
+# Runs after handler
+after ->
+  return if @silent
+  console.log "#{@req.method} #{@req.path} - #{Date.now() - @start}ms"
+```
+
+**Note:** `raw` receives the native `Request` object (before parsing). `before` and `after` use `@` to access the context.
+
+**How `@` works:** Handlers are called with `this` bound to the context, so `@foo` is `this.foo`. This gives you Sinatra-like magic access to:
+- `@req` — Request object
+- `@json()`, `@text()`, `@html()`, `@redirect()`, `@send()` — Response helpers
+- `@header()` — Response header modifier
+- `@anything` — Custom per-request state
+
+**Imports that work anywhere** (via AsyncLocalStorage or Proxy):
+- `read` — Validated request parameters
+- `session` — Session data (if middleware enabled)
+- `env` — `process.env` shortcut (e.g., `env.DATABASE_URL`)
+
+## Context Object
+
+Use `@` to access the context directly — no parameter needed:
+
+### Response Helpers
+
+```coffee
+get '/demo' ->
+  # JSON response
+  @json { data: 'value' }
+  @json { data: 'value' }, 201  # With status
+  @json { data: 'value' }, 200, { 'X-Custom': 'header' }
+
+  # Text response
+  @text 'Hello'
+  @text 'Created', 201
+
+  # HTML response
+  @html '<h1>Hello</h1>'
+
+  # Redirect
+  @redirect '/new-location'
+  @redirect '/new-location', 301  # Permanent
+
+  # Raw body
+  @body data, 200, { 'Content-Type': 'application/octet-stream' }
+
+  # File serving (auto-detected MIME type via Bun.file)
+  @send 'public/style.css'                    # text/css
+  @send 'data/export.json', 'application/json' # explicit type
+```
+
+### Request Helpers
+
+```coffee
+get '/info' ->
+  # Path and query parameters — use read() for validation!
+  id = read 'id', 'id!'
+  q  = read 'q'
+
+  # Headers
+  auth = @req.header 'Authorization'
+  allHeaders = @req.header()
+
+  # Body (async)
+  json = @req.json!
+  text = @req.text!
+  form = @req.formData!
+  parsed = @req.parseBody!
+
+  # Raw request
+  @req.raw     # Native Request object
+  @req.method  # 'GET', 'POST', etc.
+  @req.url     # Full URL
+  @req.path    # Path only
+```
+
+### Request-Scoped State
+
+```coffee
+# Store data for later middleware/handlers
+use (c, next) ->
+  @user = { id: 1, name: 'Alice' }
+  @startTime = Date.now()
+  await next()
+
+get '/profile' ->
+  @json @user
+```
+
+## File Serving
+
+### `@send(path, type?)`
+
+Serve a file with auto-detected MIME type. Uses `Bun.file()` internally for
+efficient streaming — the file is never buffered in memory.
+
+```coffee
+# Auto-detected content type (30+ extensions supported)
+get '/css/*', -> @send "css/#{@req.path.slice(5)}"
+
+# Explicit content type
+get '/files/*', -> @send "uploads/#{@req.path.slice(7)}", 'application/octet-stream'
+
+# SPA fallback — serve index.html for all unmatched routes
+notFound -> @send 'index.html', 'text/html; charset=UTF-8'
+```
+
+### `mimeType(path)`
+
+Exported utility that returns the MIME type for a file path:
+
+```coffee
+import { mimeType } from '@rip-lang/server'
+
+mimeType 'style.css'    # 'text/css; charset=UTF-8'
+mimeType 'app.js'       # 'application/javascript'
+mimeType 'photo.png'    # 'image/png'
+mimeType 'data.xyz'     # 'application/octet-stream'
+```
+
+## Error Handling
+
+### Custom Error Handler
+
+```coffee
+import { onError } from '@rip-lang/server'
+
+onError (err, c) ->
+  console.error 'Error:', err
+  c.json { error: err.message }, err.status or 500
+```
+
+### Custom 404 Handler
+
+```coffee
+import { notFound } from '@rip-lang/server'
+
+notFound (c) ->
+  c.json { error: 'Not found', path: c.req.path }, 404
+```
+
+## Server Options
+
+### Basic Server
+
+```coffee
+import { start } from '@rip-lang/server'
+
+start port: 3000
+start port: 3000, host: '0.0.0.0'
+```
+
+### Handler Only (for custom servers)
+
+```coffee
+import { startHandler } from '@rip-lang/server'
+
+export default startHandler()
+```
+
+### App Pattern
+
+```coffee
+import { App, get, post } from '@rip-lang/server'
+
+export default App ->
+  get '/', -> 'Hello'
+  post '/echo', -> read()
+```
+
+## Context Utilities
+
+### ctx()
+
+Get the current request context from anywhere (via AsyncLocalStorage):
+
+```coffee
+import { ctx } from '@rip-lang/server'
+
+logRequest = ->
+  c = ctx()
+  console.log "#{c.req.method} #{c.req.path}" if c
+
+get '/demo' ->
+  logRequest()
+  { ok: true }
+```
+
+### resetGlobals()
+
+Reset all global state (routes, middleware, filters). Useful for testing:
+
+```coffee
+import { resetGlobals, get, start } from '@rip-lang/server'
+
+beforeEach ->
+  resetGlobals()
+
+get '/test', -> { test: true }
+```
+
+## Utility Functions
+
+### isBlank
+
+```coffee
+import { isBlank } from '@rip-lang/server'
+
+isBlank null        # true
+isBlank undefined   # true
+isBlank ''          # true
+isBlank '   '       # true
+isBlank []          # true
+isBlank {}          # true
+isBlank false       # true
+isBlank 'hello'     # false
+isBlank [1, 2]      # false
+```
+
+### toName
+
+Advanced name formatting with intelligent capitalization:
+
+```coffee
+import { toName } from '@rip-lang/server'
+
+toName 'john doe'           # 'John Doe'
+toName 'JANE SMITH'         # 'Jane Smith'
+toName "o'brien"            # "O'Brien"
+toName 'mcdonald'           # 'McDonald'
+toName 'los angeles', 'address'  # 'Los Angeles'
+```
+
+### toPhone
+
+US phone number formatting:
+
+```coffee
+import { toPhone } from '@rip-lang/server'
+
+toPhone '5551234567'        # '(555) 123-4567'
+toPhone '555-123-4567'      # '(555) 123-4567'
+toPhone '555.123.4567 x99'  # '(555) 123-4567, ext. 99'
+toPhone '+1 555 123 4567'   # '(555) 123-4567'
+```
+
+## Migration from Hono
+
+### Before (Hono)
+
+```coffee
+import { Hono } from 'hono'
+
+app = new Hono()
+app.get '/users/:id', (c) ->
+  id = c.req.param 'id'
+  c.json { id }
+
+export default app
+```
+
+### After (@rip-lang/server)
+
+```coffee
+import { get, read, startHandler } from '@rip-lang/server'
+
+get '/users/:id', ->
+  id = read 'id', 'id!'
+  { id }
+
+export default startHandler()
+```
+
+### API Compatibility
+
+| Hono | @rip-lang/server |
+|------|------------------|
+| `app.get(path, handler)` | `get path, handler` |
+| `app.post(path, handler)` | `post path, handler` |
+| `app.use(middleware)` | `use middleware` |
+| `app.basePath(path)` | `prefix path, -> ...` |
+| `c.json(data)` | `@json(data)` or return `{ data }` |
+| `c.req.param('id')` | `@req.param('id')` or `read 'id'` |
+| `c.req.query('q')` | `@req.query('q')` or `read 'q'` |
+
+## Real-World Example
+
+```coffee
+import { get, post, put, del, use, read, start, before, after, onError } from '@rip-lang/server'
+import { logger } from '@rip-lang/server/middleware'
+
+use logger()
+
+before ->
+  @start = Date.now()
+
+after ->
+  console.log "#{@req.method} #{@req.path} - #{Date.now() - @start}ms"
+
+onError (err) ->
+  @json { error: err.message }, err.status or 500
+
+get '/', ->
+  { name: 'My API', version: '1.0' }
+
+get '/users', ->
+  page = read 'page', 'int', [1, 100]
+  limit = read 'limit', 'int', [1, 50]
+  users = db.listUsers! page or 1, limit or 10
+  { users, page, limit }
+
+get '/users/:id', ->
+  id = read 'id', 'id!'
+  user = db.getUser!(id)
+  unless user
+    throw { message: 'User not found', status: 404 }
+  { user }
+
+post '/users', ->
+  email = read 'email', 'email!'
+  name = read 'name', 'string', [1, 100]
+  phone = read 'phone', 'phone'
+  user = db.createUser! { email, name, phone }
+  { user, created: true }
+
+put '/users/:id', ->
+  id = read 'id', 'id!'
+  email = read 'email', 'email'
+  name = read 'name', 'string', [1, 100]
+  user = db.updateUser! id, { email, name }
+  { user, updated: true }
+
+del '/users/:id', ->
+  id = read 'id', 'id!'
+  db.deleteUser!(id)
+  { deleted: true }
+
+start port: 3000
+```
+
 ## App Path & Naming
 
 ### Entry File Resolution
 
-When you run `rip-server`, it looks for your app's entry file:
+When you run `rip serve`, it looks for your app's entry file:
 
 ```bash
 # No arguments: looks for index.rip (or index.ts) in current directory
-rip-server
+rip serve
 
 # Directory path: looks for index.rip (or index.ts) in that directory
-rip-server ./myapp/
+rip serve ./myapp/
 
 # Explicit file: uses that file directly
-rip-server ./app.rip
-rip-server ./src/server.ts
+rip serve ./app.rip
+rip serve ./src/server.ts
 ```
 
 ### App Naming
@@ -126,44 +780,36 @@ The **app name** is used for mDNS discovery (e.g., `myapp.local`) and logging. I
 
 ```bash
 # Default: current directory name becomes app name
-~/projects/api$ rip-server        # app name = "api"
+~/projects/api$ rip serve         # app name = "api"
 
 # Explicit name: pass a name that's not a file path
-rip-server myapp                  # app name = "myapp"
+rip serve myapp                   # app name = "myapp"
 
 # With aliases: name@alias1,alias2
-rip-server myapp@api,backend      # accessible at myapp.local, api.local, backend.local
+rip serve myapp@api,backend       # accessible at myapp.local, api.local, backend.local
 
 # Path with alias
-rip-server ./app.rip@myapp        # explicit file + custom app name
+rip serve ./app.rip@myapp         # explicit file + custom app name
 ```
 
 **Examples:**
 
 ```bash
 # In ~/projects/api/ with index.rip
-rip-server                        # app = "api", entry = ./index.rip
-rip-server -w                     # same, with file watching
-rip-server myapp                  # app = "myapp", entry = ./index.rip
-rip-server myapp -w               # same, with file watching
-rip-server ./server.rip           # app = "api", entry = ./server.rip
-rip-server ./server.rip@myapp     # app = "myapp", entry = ./server.rip
+rip serve                         # app = "api", entry = ./index.rip
+rip serve myapp                   # app = "myapp", entry = ./index.rip
+rip serve ./server.rip            # app = "api", entry = ./server.rip
+rip serve ./server.rip@myapp      # app = "myapp", entry = ./server.rip
 ```
 
 ## File Watching
 
-### Development Mode with `-w`/`--watch`
-
-The `-w` flag enables **directory watching** — any `.rip` file change in your app directory triggers an automatic hot reload:
+Directory watching is **on by default** — any `.rip` file change in your app directory triggers an automatic rolling restart. Use `--watch=<glob>` to customize the pattern, or `--static` to disable watching entirely.
 
 ```bash
-# Watch all .rip files (default pattern: *.rip)
-rip-server -w
-rip-server --watch
-
-# Watch a custom pattern
-rip-server -w=*.ts
-rip-server --watch=*.tsx
+rip serve                         # Watches *.rip (default)
+rip serve --watch=*.ts            # Watch TypeScript files instead
+rip serve --static                # No watching, no hot reload (production)
 ```
 
 **How it works:**
@@ -171,48 +817,17 @@ rip-server --watch=*.tsx
 1. Uses OS-native file watching (FSEvents on macOS, inotify on Linux)
 2. Watches the entire app directory recursively
 3. When a matching file changes, touches the entry file
-4. The existing hot-reload mechanism detects the change and does a rolling restart
-
-**This is efficient:**
-
-- Single watcher in the main process (not per-worker)
-- No polling — OS notifies on changes
-- Zero overhead when files aren't changing
-
-**Examples:**
-
-```bash
-# Typical development setup
-rip-server -w                     # Watch *.rip files
-
-# TypeScript project
-rip-server -w=*.ts                # Watch *.ts files
+4. The hot-reload mechanism detects the mtime change and does a rolling restart
 
-# React/frontend project
-rip-server -w=*.tsx               # Watch *.tsx files
-
-# Multiple concerns? Just use the broader pattern
-rip-server -w=*.rip               # Only Rip files (default)
-```
-
-**Without `-w`:** Only the entry file (`index.rip`) is watched. Changes to imported files won't trigger reload unless you also touch the entry file.
+This is a single kernel-level file descriptor in the main process — no polling, zero overhead when files aren't changing.
 
 ## CLI Reference
 
 ### Basic Syntax
 
 ```bash
-rip-server [flags] [app-path] [app-name]
-rip-server [flags] [app-path]@<alias1>,<alias2>,...
-```
-
-### Getting Help
-
-```bash
-rip-server -h          # Show help
-rip-server --help      # Show help
-rip-server -v          # Show version
-rip-server --version   # Show version
+rip serve [flags] [app-path] [app-name]
+rip serve [flags] [app-path]@<alias1>,<alias2>,...
 ```
 
 ### Flags
@@ -221,15 +836,14 @@ rip-server --version   # Show version
 |------|-------------|---------|
 | `-h`, `--help` | Show help and exit | — |
 | `-v`, `--version` | Show version and exit | — |
-| `-w`, `--watch` | Watch `*.rip` files for changes | Disabled |
-| `-w=<glob>`, `--watch=<glob>` | Watch custom pattern (e.g., `*.ts`) | — |
+| `--watch=<glob>` | Watch glob pattern | `*.rip` |
+| `--static` | Disable hot reload and file watching | — |
 | `--env=<mode>` | Environment mode (`dev`, `prod`) | `development` |
 | `--debug` | Enable debug logging | Disabled |
-| `--static` | Disable hot reload (production) | Hot reload enabled |
 | `http` | HTTP-only mode (no HTTPS) | HTTPS enabled |
 | `https` | HTTPS mode (explicit) | Auto |
-| `http:<port>` | Set HTTP port | 80 or 5700 |
-| `https:<port>` | Set HTTPS port | 443 or 5700 |
+| `http:<port>` | Set HTTP port | 80, fallback 3000 |
+| `https:<port>` | Set HTTPS port | 443, fallback 3443 |
 | `w:<n>` | Worker count (`auto`, `half`, `2x`, `3x`, or number) | `half` of cores |
 | `r:<reqs>,<secs>s` | Restart policy: requests, seconds (e.g., `5000,3600s`) | `10000,3600s` |
 | `--cert=<path>` | TLS certificate path | Auto-generated |
@@ -243,42 +857,39 @@ rip-server --version   # Show version
 ### Subcommands
 
 ```bash
-# Stop running server
-rip-server stop
-
-# List registered hosts
-rip-server list
+rip serve stop                    # Stop running server
+rip serve list                    # List registered hosts
 ```
 
 ### Examples
 
 ```bash
-# Development with file watching (recommended)
-rip-server -w
+# Development (default: watches *.rip, HTTPS, hot reload)
+rip serve
 
-# Development: HTTP on any available port
-rip-server http
+# HTTP only
+rip serve http
 
-# Development: HTTPS with mkcert
-rip-server --auto-tls
+# HTTPS with mkcert
+rip serve --auto-tls
 
-# Production: 8 workers, HTTPS, no hot reload
-rip-server --env=prod --static w:8
+# Production: 8 workers, no hot reload
+rip serve --static w:8
 
 # Custom port
-rip-server http:3000
+rip serve http:3000
 
 # With mDNS aliases (accessible as myapp.local and api.local)
-rip-server myapp@api
+rip serve myapp@api
 
-# Watch TypeScript files
-rip-server -w=*.ts
+# Watch TypeScript files instead of Rip
+rip serve --watch=*.ts
 
-# Debug mode to troubleshoot issues
-rip-server --debug -w
+# Debug mode
+rip serve --debug
 
 # Restart workers after 5000 requests or 1 hour
-rip-server r:5000,3600s
+rip serve r:5000,3600s
 ```
 
 ## Architecture
@@ -328,10 +939,12 @@ When `RIP_SETUP_MODE=1` is set, the same file runs the one-time setup phase. Whe
 
 ### Hot Reloading
 
-Two layers of hot reload work together in development:
+Two layers of hot reload work together by default:
 
-- **API changes** (`-w` flag) — The Manager watches for `.rip` file changes in the API directory and triggers rolling worker restarts (zero downtime, server-side).
-- **UI changes** (`watch: true` in `serve`) — Workers register their app's component directories with the Manager via the control socket. The Manager watches those directories and broadcasts SSE reload events to connected browsers (client-side). SSE connections are held by the long-lived Server process, not by workers.
+- **API changes** — The Manager watches for `.rip` file changes in the app directory and triggers rolling worker restarts (zero downtime, server-side).
+- **UI changes** (`watch: true` in `serve` middleware) — Workers register their component directories with the Manager via the control socket. The Manager watches those directories and broadcasts SSE reload events to connected browsers (client-side).
+
+SSE connections are held by the long-lived Server process, not by recyclable workers, ensuring stable hot-reload connections. Each app prefix gets its own SSE pool for multi-app isolation.
 
 Use `--static` in production to disable hot reload entirely.
 
@@ -365,7 +978,7 @@ Certificates are stored in `~/.rip/certs/`.
 ### Custom Certificates
 
 ```bash
-rip-server --cert=/path/to/cert.pem --key=/path/to/key.pem
+rip serve --cert=/path/to/cert.pem --key=/path/to/key.pem
 ```
 
 ## mDNS Service Discovery
@@ -374,10 +987,10 @@ The server automatically advertises itself via mDNS (Bonjour/Zeroconf):
 
 ```bash
 # App accessible at myapp.local
-rip-server myapp
+rip serve myapp
 
 # Multiple aliases
-rip-server myapp@api,backend
+rip serve myapp@api,backend
 ```
 
 Requires `dns-sd` (available on macOS by default).
@@ -386,17 +999,17 @@ Requires `dns-sd` (available on macOS by default).
 
 Your app must provide a fetch handler. Three patterns are supported:
 
-### Pattern 1: Use `@rip-lang/api` with `start()` (Recommended)
+### Pattern 1: Use `@rip-lang/server` with `start()` (Recommended)
 
 ```coffee
-import { get, start } from '@rip-lang/api'
+import { get, start } from '@rip-lang/server'
 
 get '/', -> 'Hello!'
 
 start()
 ```
 
-The `start()` function automatically detects when running under `rip-server` and registers the handler.
+The `start()` function automatically detects when running under `rip serve` and registers the handler.
 
 ### Pattern 2: Export fetch function directly
 
@@ -414,7 +1027,7 @@ export default
 
 ## One-Time Setup
 
-If a `setup.rip` file exists next to your entry file, rip-server runs it
+If a `setup.rip` file exists next to your entry file, `rip serve` runs it
 automatically **once** before spawning any workers. This is ideal for database
 migrations, table creation, and seeding.
 
@@ -464,7 +1077,7 @@ The server includes a built-in dashboard accessible at `http://rip.local/` (when
 - **Registered Hosts** — All mDNS aliases being advertised
 - **Server Ports** — HTTP/HTTPS port configuration
 
-The dashboard uses the same mDNS infrastructure as your app, so it's always available at `rip.local` when any rip-server instance is running.
+The dashboard uses the same mDNS infrastructure as your app, so it's always available at `rip.local` when any `rip serve` instance is running.
 
 ## Troubleshooting
 
@@ -474,13 +1087,13 @@ The dashboard uses the same mDNS infrastructure as your app, so it's always avai
 
 **Workers keep restarting**: Use `--debug` (or `RIP_DEBUG=1`) to see import errors in your app.
 
-**Changes not triggering reload**: Make sure you're using `-w` flag for directory watching, or touch your entry file manually.
+**Changes not triggering reload**: Ensure you're not using `--static`. Check that the file matches the watch pattern (default: `*.rip`).
 
 ## Serving Rip UI Apps
 
 Rip Server works seamlessly with the `serve` middleware for serving
 reactive web applications with hot reload. The `serve` middleware handles
-framework files, page manifests, and SSE hot-reload — rip-server adds HTTPS,
+framework files, page manifests, and SSE hot-reload — `rip serve` adds HTTPS,
 mDNS, multi-worker load balancing, and rolling restarts on top.
 
 ### Example: Rip UI App
@@ -488,8 +1101,8 @@ mDNS, multi-worker load balancing, and rolling restarts on top.
 Create `index.rip`:
 
 ```coffee
-import { get, use, start, notFound } from '@rip-lang/api'
-import { serve } from '@rip-lang/api/serve'
+import { get, use, start, notFound } from '@rip-lang/server'
+import { serve } from '@rip-lang/server/middleware'
 
 dir = import.meta.dir
 
@@ -505,7 +1118,7 @@ start()
 Run it:
 
 ```bash
-rip-server -w
+rip serve
 ```
 
 This gives you:
@@ -518,29 +1131,16 @@ This gives you:
 - **Multi-worker** — load balanced across CPU cores
 - **Rolling restarts** — zero-downtime file-watch reloading
 
-### How Hot Reload Works with rip-server
-
-When running with `-w`, two layers of hot reload work together:
-
-1. **API hot reload** (`-w` flag) — The Manager watches for `.rip` file changes
-   in the API directory and triggers rolling worker restarts (server-side).
-2. **UI hot reload** (`watch: true`) — Workers register their component
-   directories with the Manager via the control socket. The Manager watches
-   those directories and tells the Server to broadcast SSE reload events to
-   connected browsers (client-side).
-
-SSE connections are held by the long-lived Server process, not by recyclable
-workers, ensuring stable hot-reload connections. Each app prefix gets its own
-SSE pool for multi-app isolation.
+See [Hot Reloading](#hot-reloading) for details on how the two layers (API + UI) work together.
 
 ## Comparison with Other Servers
 
-| Feature | rip-server | PM2 | Nginx |
-|---------|------------|-----|-------|
+| Feature | rip serve | PM2 | Nginx |
+|---------|-----------|-----|-------|
 | Pure Rip | ✅ | ❌ | ❌ |
 | Single File | ✅ (~1,200 lines) | ❌ | ❌ |
-| Hot Reload | ✅ | ✅ | ❌ |
-| Directory Watch | ✅ (`-w` flag) | ✅ | ❌ |
+| Hot Reload | ✅ (default) | ✅ | ❌ |
+| Directory Watch | ✅ (default) | ✅ | ❌ |
 | Multi-Worker | ✅ | ✅ | ✅ |
 | Auto HTTPS | ✅ | ❌ | ❌ |
 | mDNS | ✅ | ❌ | ❌ |
@@ -563,7 +1163,5 @@ MIT
 
 ## Links
 
-- [Rip Language](https://github.com/shreeve/rip-lang)
-- [@rip-lang/api](../api/README.md) — API framework (routing, middleware, `@send`)
-- [Rip](https://github.com/shreeve/rip-lang) — Compiler + reactive UI framework
+- [Rip Language](https://github.com/shreeve/rip-lang) — Compiler + reactive UI framework
 - [Report Issues](https://github.com/shreeve/rip-lang/issues)