@rip-lang/server 0.7.11 → 0.8.0

package/README.md

@@ -6,9 +6,9 @@
 
 ## Overview
 
-`@rip-lang/server` is a production-grade application server written entirely in Rip. It provides multi-worker process management, hot reloading, automatic HTTPS, and mDNS service discovery — all in a single ~1,110 line file.
+`@rip-lang/server` is a production-grade application server written entirely in Rip. It provides multi-worker process management, hot reloading, automatic HTTPS, and mDNS service discovery — all in a single ~1,200 line file.
 
-- **`server.rip`** (~1,110 lines) — Complete server: CLI, workers, load balancing, TLS, mDNS
+- **`server.rip`** (~1,200 lines) — Complete server: CLI, workers, load balancing, TLS, mDNS
 
 **Core Philosophy**: Application servers should be simple, fast, and reliable. No complex configuration files. No dependency on external process managers. Just run your app.
 
@@ -16,6 +16,7 @@
 
 - **Multi-Worker Architecture** — Automatic worker spawning based on CPU cores
 - **Hot Module Reloading** — File-watch based reloading in development
+- **Directory Watching** — Watch all `.rip` files with `-w` flag for instant reload
 - **Rolling Restarts** — Zero-downtime deployments
 - **Automatic HTTPS** — TLS with mkcert or self-signed certificates
 - **mDNS Discovery** — `.local` hostname advertisement
@@ -39,19 +40,25 @@ bun add -g rip-lang @rip-lang/server
 ### Running Your App
 
 ```bash
-# Basic usage (HTTPS on port 443, or 5700 if unavailable)
+# From your app directory (uses ./index.rip by default)
+rip-server
+
+# With file watching (recommended for development)
+rip-server -w
+
+# Name your app (for mDNS: myapp.local)
+rip-server myapp
+
+# Explicit entry file
 rip-server ./app.rip
 
 # HTTP only mode
-rip-server http ./app.rip
-
-# With mDNS alias
-rip-server ./app.rip@myapp
+rip-server http
 ```
 
 ### Example App
 
-Create `app.rip`:
+Create `index.rip`:
 
 ```coffee
 import { get, read, start } from '@rip-lang/api'
@@ -72,7 +79,7 @@ start()
 Run it:
 
 ```bash
-rip-server http app.rip
+rip-server -w
 ```
 
 Test it:
@@ -88,23 +95,131 @@ curl http://localhost/users/42
 # {"user":{"id":42,"name":"User 42"}}
 
 curl http://localhost/status
-# {"status":"healthy","app":"myapp","workers":5,"ports":{"http":80}}
+# {"status":"healthy","app":"myapp","workers":5,"ports":{"https":443}}
+```
+
+## App Path & Naming
+
+### Entry File Resolution
+
+When you run `rip-server`, it looks for your app's entry file:
+
+```bash
+# No arguments: looks for index.rip (or index.ts) in current directory
+rip-server
+
+# Directory path: looks for index.rip (or index.ts) in that directory
+rip-server ./myapp/
+
+# Explicit file: uses that file directly
+rip-server ./app.rip
+rip-server ./src/server.ts
+```
+
+### App Naming
+
+The **app name** is used for mDNS discovery (e.g., `myapp.local`) and logging. It's determined by:
+
+```bash
+# Default: current directory name becomes app name
+~/projects/api$ rip-server        # app name = "api"
+
+# Explicit name: pass a name that's not a file path
+rip-server myapp                  # app name = "myapp"
+
+# With aliases: name@alias1,alias2
+rip-server myapp@api,backend      # accessible at myapp.local, api.local, backend.local
+
+# Path with alias
+rip-server ./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
+```
+
+## 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:
+
+```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
+```
+
+**How it works:**
+
+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
+
+# 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.
+
 ## CLI Reference
 
 ### Basic Syntax
 
 ```bash
-rip-server [flags] <app-path>[@alias1,alias2,...]
+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
 ```
 
 ### Flags
 
 | Flag | Description | Default |
 |------|-------------|---------|
+| `-h`, `--help` | Show help and exit | — |
 | `-v`, `--version` | Show version and exit | — |
-| `--env=<mode>` | Environment mode (`dev`, `prod`, `development`, `production`) | `development` |
+| `-w`, `--watch` | Watch `*.rip` files for changes | Disabled |
+| `-w=<glob>`, `--watch=<glob>` | Watch custom pattern (e.g., `*.ts`) | — |
+| `--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 |
@@ -124,9 +239,6 @@ rip-server [flags] <app-path>[@alias1,alias2,...]
 ### Subcommands
 
 ```bash
-# Show version
-rip-server --version
-
 # Stop running server
 rip-server stop
 
@@ -137,26 +249,32 @@ rip-server list
 ### Examples
 
 ```bash
+# Development with file watching (recommended)
+rip-server -w
+
 # Development: HTTP on any available port
-rip-server http app.rip
+rip-server http
 
 # Development: HTTPS with mkcert
-rip-server --auto-tls app.rip
+rip-server --auto-tls
 
 # Production: 8 workers, HTTPS, no hot reload
-rip-server --env=prod w:8 https app.rip
-
-# Debug mode to troubleshoot issues
-rip-server --debug http app.rip
+rip-server --env=prod --static w:8
 
-# Custom ports
-rip-server http:3000 app.rip
+# Custom port
+rip-server http:3000
 
 # With mDNS aliases (accessible as myapp.local and api.local)
-rip-server app.rip@myapp,api
+rip-server myapp@api
+
+# Watch TypeScript files
+rip-server -w=*.ts
+
+# Debug mode to troubleshoot issues
+rip-server --debug -w
 
 # Restart workers after 5000 requests or 1 hour
-rip-server r:5000,3600s app.rip
+rip-server r:5000,3600s
 ```
 
 ## Architecture
@@ -201,7 +319,14 @@ When `RIP_WORKER_MODE=1` is set, the same `server.rip` file runs as a worker ins
 
 ### Hot Reloading
 
-By default, file changes trigger a rolling restart of all workers. Use `--static` in production to disable.
+In development mode, the server watches for file changes:
+
+- **Default**: Only the entry file is watched
+- **With `-w`**: All matching files in the app directory are watched
+
+When a change is detected, a rolling restart of all workers is triggered — zero downtime.
+
+Use `--static` in production to disable hot reload entirely.
 
 ### Worker Lifecycle
 
@@ -233,7 +358,7 @@ Certificates are stored in `~/.rip/certs/`.
 ### Custom Certificates
 
 ```bash
-rip-server --cert=/path/to/cert.pem --key=/path/to/key.pem app.rip
+rip-server --cert=/path/to/cert.pem --key=/path/to/key.pem
 ```
 
 ## mDNS Service Discovery
@@ -242,10 +367,10 @@ The server automatically advertises itself via mDNS (Bonjour/Zeroconf):
 
 ```bash
 # App accessible at myapp.local
-rip-server app.rip@myapp
+rip-server myapp
 
 # Multiple aliases
-rip-server app.rip@myapp,api,backend
+rip-server myapp@api,backend
 ```
 
 Requires `dns-sd` (available on macOS by default).
@@ -318,19 +443,22 @@ The dashboard uses the same mDNS infrastructure as your app, so it's always avai
 
 ## Troubleshooting
 
-**Port 80 requires sudo**: Use `http:3000` or another high port, or run with sudo.
+**Port 80/443 requires sudo**: Use `http:3000` or another high port, or run with sudo.
 
 **mDNS not working**: Ensure `dns-sd` is available (built into macOS). On Linux, install Avahi.
 
 **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.
+
 ## Comparison with Other Servers
 
 | Feature | rip-server | PM2 | Nginx |
 |---------|------------|-----|-------|
 | Pure Rip | ✅ | ❌ | ❌ |
-| Single File | ✅ (~1,110 lines) | ❌ | ❌ |
+| Single File | ✅ (~1,200 lines) | ❌ | ❌ |
 | Hot Reload | ✅ | ✅ | ❌ |
+| Directory Watch | ✅ (`-w` flag) | ✅ | ❌ |
 | Multi-Worker | ✅ | ✅ | ✅ |
 | Auto HTTPS | ✅ | ❌ | ❌ |
 | mDNS | ✅ | ❌ | ❌ |
@@ -343,7 +471,6 @@ The dashboard uses the same mDNS infrastructure as your app, so it's always avai
 
 - [ ] Request ID tracing for debugging
 - [ ] Metrics endpoint (Prometheus format)
-- [ ] Multi-file hot reload (watch entire directory)
 - [ ] Static file serving
 - [ ] Rate limiting
 - [ ] Performance benchmarks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rip-lang/server",
-  "version": "0.7.11",
+  "version": "0.8.0",
   "description": "Pure Rip application server — multi-worker, hot reload, HTTPS, mDNS",
   "type": "module",
   "main": "server.rip",