@thoughtpivot/flight 1.0.8 → 2.0.1

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 2.0.0
+
+### Breaking
+
+- **Production middleware order** when `FLIGHT_MODE` / `mode` is `production` **and** built-assets mode is on (`--disable_vite` or `FLIGHT_DISABLE_VITE` of `true` / `1` / `yes`): Flight now uses the **production SPA pipeline** by default. Static files from `FLIGHT_DIST_PATH` (default `../dist`) and the SPA `index.html` fallback run **immediately after** the Koa `router` (your `**/*.backend.ts` routes), **before** `koa-compress`, Redis-backed rate limiting, and optional response caching.
+- **`koa-cash` is off by default** in that SPA pipeline (to avoid caching HTML or mixed `vary` surprises). Enable with **`FLIGHT_HTTP_CACHE=true`** (or `1` / `yes`) if you want the previous Redis-backed cache layer in that configuration.
+- **Legacy stack** (previous order: `compress` → `ratelimit` → `koa-cash` → `koa-static` after the router) remains when **either** Vite is **not** disabled in production **or** you set **`FLIGHT_DISABLE_SPA_PIPELINE=true`** (or `1` / `yes`).
+
+### Added
+
+- **Yargs CLI parity** for **`--mode`**, **`--port`**, **`--app_home`**, **`--app_key`**, **`--app_secret`**, **`--payload_limit`**, and **`--disable_vite`** (plus kebab-case aliases), so documented flags populate `argv` reliably instead of being dropped by the parser.
+- **`FLIGHT_TRUST_PROXY`**: when `true` / `1` / `yes`, sets `app.proxy = true` so `ctx.ip` and rate-limit identity honor `X-Forwarded-For` behind a reverse proxy or load balancer.
+- **`FLIGHT_STATIC_PREFIXES`**: comma-separated URL path prefixes (default `/assets,/fonts`) used to build the **rate-limit skip** list for `GET`/`HEAD` (hashed assets should not burn the API limiter).
+- **`FLIGHT_RATE_LIMIT_EXCLUDE_PREFIXES`**: extra comma-separated prefixes merged into that skip list.
+- **`FLIGHT_SPA_INDEX`**: path to the SPA shell inside the dist root (default `index.html`).
+- **`FLIGHT_SPA_DENY_PREFIXES`**: extra comma-separated path prefixes that never receive the SPA HTML fallback (always merged with `/api` and `/health`).
+- **`npm test`**: regression tests for the SPA pipeline (assets, deep links, API prefix, file-like paths).
+- **`files` field** in `package.json` so publishes include only `dist/flight.js`, `dist/spa-pipeline.js`, and docs assets.
+
+### Notes
+
+- `FLIGHT_DISABLE_VITE` accepts **`true`**, **`1`**, or **`yes`** (case-sensitive values as implemented for the string checks).

package/README.md

@@ -1,23 +1,24 @@
+<p align="center">
+  <img src="readme-assets/thoughtpivot-logo.svg" alt="ThoughtPivot" width="280" />
+</p>
+
 # Flight
 
-Flight is a modern, high-performance web application server built on Node.js, designed for building scalable, component-driven applications. It is the successor to [Avian](https://github.com/ispyhumanfly/avian): originally created by ThoughtPivot, handed to FlyPaper Technologies, LLC, where Avian matured—Flight builds on those advancements with modern tooling and developer experience.
+**Flight** is a Node.js application server for teams who want something **fast**, **boring in the good way**, and **ready for serious traffic**. You bring your own hosting—there is no lock-in to a proprietary edge or a single vendor’s deployment story. It fits **twelve-factor** style workflows: configuration via environment variables, horizontal scaling, and state kept where it belongs (for Flight, that includes **Redis** for sessions and cache-friendly layers).
 
-## Overview
+Think **platform-agnostic**: not framework-as-a-platform, but a clear runtime you can run wherever Node runs—VMs, Kubernetes, bare metal, your cloud of choice. Flight is aimed at **hyperscale-friendly** designs (cluster workers out of the box), **ephemeral** processes, and **component-shaped** backends so routes stay colocated with the features they serve. **Vue** and **Vite** are first-class today; **React** support is on the roadmap.
 
-Flight takes the best concepts from Avian and enhances them with modern tooling and practices. It provides a robust foundation for building enterprise-grade applications while maintaining simplicity and developer productivity.
+Flight is **open source** from **[ThoughtPivot](https://github.com/thoughtpivot)**.
 
-### Key Features
+## Highlights
 
-- **Modern Stack**: Built on Koa.js with TypeScript support
-- **Component-Based Architecture**: Organize your application into reusable components
-- **Built-in Development Server**: Powered by Vite for lightning-fast development
-- **Production-Ready**: Includes rate limiting, compression, and caching out of the box
-- **Cluster Mode**: Automatic load balancing across CPU cores
-- **Redis Integration**: Built-in support for session management and caching
-- **TypeScript First**: Native TypeScript support throughout the framework
-- **Hot Module Replacement**: Fast development with instant updates
-- **CORS Enabled**: Ready for modern web applications
-- **Security Features**: Rate limiting, secure session handling, and more
+- **Performance-focused**: Cluster mode, compression, Redis-backed caching hooks, rate limiting in production
+- **Developer velocity**: Vite-powered dev server with HMR for **Vue** (React roadmap)
+- **Composable backends**: Discover `**/*.backend.ts` under your app root and mount Koa routes per component
+- **Production SPA**: Built-in **`dist` + `index.html`** fallback (option B) when running **`production`** with **`disable_vite`**, with an explicit opt-out for API-only processes
+- **Configurable discovery**: `--exclude_paths` / `FLIGHT_EXCLUDE_PATHS` to skip directories when scanning backends
+- **TypeScript-native**: Written for TS projects; sensible defaults, minimal ceremony
+- **Interop-friendly**: Correct handling of `yargs` when launched via **tsx** or similar loaders (no patch-package needed from **v1.0.8** onward)
 
 ## Installation
 
@@ -27,11 +28,11 @@ npm install @thoughtpivot/flight
 yarn add @thoughtpivot/flight
 ```
 
-Previously published on npm as `@spytech/flight`; switch your dependency to `@thoughtpivot/flight`.
+Legacy npm scope: the package was previously published as `@spytech/flight`—use `@thoughtpivot/flight` going forward.
 
-### Downstream apps (tsx / patch-package)
+### Downstream apps (tsx)
 
-From **v1.0.8** onward, Flight normalizes `require('yargs/yargs')` when loaders such as **tsx** expose it as `{ default: factory }` instead of the factory. If you only added **patch-package** for that workaround, upgrade `@thoughtpivot/flight`, delete `patches/@thoughtpivot+flight+*.patch`, and remove any **postinstall** hook that existed solely to apply it.
+From **v1.0.8** onward, Flight normalizes `require('yargs/yargs')` under loaders that expose `{ default: factory }`. If you added **patch-package** only for that issue, upgrade Flight and drop that patch.
 
 ## Quick Start
 
@@ -49,13 +50,7 @@ npm init -y
 npm install @thoughtpivot/flight ioredis
 ```
 
-3. Ensure Redis is running locally or set environment variables:
-
-```bash
-# Default values shown below
-export FLIGHT_REDIS_HOST=localhost
-export FLIGHT_REDIS_PORT=6379
-```
+3. Ensure Redis is running locally or set environment variables (see table below).
 
 4. Create a component with a backend route:
 
@@ -77,49 +72,130 @@ router.get('/hello', async (ctx) => {
 export default router.routes()
 ```
 
-5. Start the server:
+5. Add scripts to **`package.json`** (the `flight` binary comes from **`node_modules/.bin`** after install):
+
+```json
+{
+    "scripts": {
+        "dev": "flight --mode development",
+        "start": "flight --mode production"
+    }
+}
+```
+
+Use **`FLIGHT_DISABLE_VITE`**, **`FLIGHT_DIST_PATH`**, and related env vars in **`.env`** for production built-assets mode (see the configuration table below).
 
-Development mode:
+6. Start the server:
+
+**Development (Vite on 3001, API on 3000):**
+
+```bash
+npx flight --mode development
+# or: npm run dev
+```
+
+**Production:**
 
 ```bash
-node flight.js --mode development --app_home .
-# Starts development server on port 3001 with HMR
-# Backend API available on port 3000
+npx flight --mode production
+# or: npm run start
 ```
 
-Production mode:
+**`--app_home`** defaults to **`.`** (the current working directory). Pass **`--app_home path/to/app`** only when your app root is not the directory you run the command from.
+
+**Try without adding a dependency** (downloads the package for this invocation):
 
 ```bash
-node flight.js --mode production --app_home .
-# Builds and serves application on port 3000
+npx --yes --package @thoughtpivot/flight flight --mode development
 ```
 
-Available CLI options:
+**Global install** (optional): `npm install -g @thoughtpivot/flight`, then run **`flight`** from your PATH the same way as **`npx flight`**.
 
-- `--app_home`: Application root directory (default: current directory)
-- `--app_key`: Application key for sessions (default: 'flightApp')
-- `--app_secret`: Secret key for session encryption (default: 'the best secret key in the world')
-- `--mode`: 'development' or 'production' (default: 'production')
+## Development vs production
+
+Flight picks **`mode`** as: **`FLIGHT_MODE`** (if set and non-empty), else **`--mode`** from argv, else **`production`**. Everything below assumes Redis is reachable unless you only use routes that avoid session/ratelimit/cache.
+
+| Topic            | Development                                                                                   | Production                                                                                                                                  |
+| ---------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Vite**         | Child process: `npx vite --port 3001 --host 0.0.0.0` (HMR).                                   | If **`disable_vite` is false**: `exec('npx vite build')` is triggered once at worker startup. If **`disable_vite` is true**: no Vite build. |
+| **Listen port**  | API + sessions on **`--port`** / `FLIGHT_PORT` (default **3000**). UI dev server on **3001**. | Same **`--port`** / `FLIGHT_PORT` for the worker.                                                                                           |
+| **Static / SPA** | The Vite dev server serves UI; Flight does **not** mount the production static/SPA stack.     | See **Production SPA pipeline** below: when **`production`** + **`disable_vite`**, Flight uses **Option A** by default unless opted out.    |
+| **Typical use**  | Local full-stack with HMR.                                                                    | CI-built `dist` served by Flight (or behind a load balancer).                                                                               |
+
+**Edge cases**
+
+- **`production` + `disable_vite` false**: Vite build still runs; **legacy** middleware order applies (`compress` → `ratelimit` → `koa-cash` → static), because built-assets-only mode is off.
+- **`production` + `disable_vite` true + `FLIGHT_DISABLE_SPA_PIPELINE`**: **Legacy** stack only—no SPA HTML fallback for unknown GETs; tail `koa-static` only after compress/ratelimit/cache.
+- **`development`**: unchanged—Redis session store and production-only static/SPA branches do not apply the SPA pipeline section (the dev Vite server owns UI URLs).
+
+## Configuration: CLI, `.env`, and environment variables
+
+Flight loads a **`.env`** file from the **current working directory** at startup (via **`dotenv`**). Use **`FLIGHT_*`** in real deployments.
+
+**Precedence**
+
+- **`mode`**: **`FLIGHT_MODE`** wins over **`--mode`** when the variable is set (non-empty).
+- **`disable_vite`**: explicit CLI wins; if omitted, **`FLIGHT_DISABLE_VITE`** (`true` / `1` / `yes` → on); otherwise **`false`**.
+- Other settings: argv value if your launcher passes it, else the **`FLIGHT_*`** column, then default.
+
+**Registered CLI options:** Flight registers **`--exclude_paths`**, **`--mode`**, **`--port`**, **`--app_home`**, **`--app_key`**, **`--app_secret`**, **`--payload_limit`**, and **`--disable_vite`** (with kebab-case aliases where listed in `--help`). yargs is not in **strict** mode, so additional flags may still appear on argv if you extend the entrypoint.
+
+| Setting (CLI / argv)                 | Environment variable                 | Default          | Use case                                                                                                                                                                                                        |
+| ------------------------------------ | ------------------------------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--exclude_paths`, `--exclude-paths` | `FLIGHT_EXCLUDE_PATHS`               | _(empty)_        | Skip subtrees when globbing `**/*.backend.ts` (monorepo vendor trees, fixtures).                                                                                                                                |
+| `--app_home`                         | `FLIGHT_APP_HOME`                    | `.`              | Repository root; `process.chdir` target before discovery and static paths.                                                                                                                                      |
+| `--app_key`                          | `FLIGHT_APP_KEY`                     | `flightApp`      | Session cookie name.                                                                                                                                                                                            |
+| `--app_secret`                       | `FLIGHT_APP_SECRET`                  | _(see code)_     | Cookie signing secret(s); comma-separated for key rotation.                                                                                                                                                     |
+| _(argv)_                             | `FLIGHT_SESSION_DURATION_MS`         | `86400000`       | Session `maxAge` in ms.                                                                                                                                                                                         |
+| `--port`                             | `FLIGHT_PORT`                        | `3000`           | HTTP listen port (all modes).                                                                                                                                                                                   |
+| `--payload_limit`                    | `FLIGHT_PAYLOAD_LIMIT`               | `1mb`            | `koa-bodyparser` JSON limit.                                                                                                                                                                                    |
+| `--disable_vite`                     | `FLIGHT_DISABLE_VITE`                | `false`          | **`true` / `1` / `yes`**: skip `vite build` and treat the process as **built-assets** mode (triggers SPA pipeline rules in production).                                                                         |
+| `--mode`                             | `FLIGHT_MODE`                        | `production`     | `development` spawns Vite; `production` enables production middleware.                                                                                                                                          |
+| _(n/a)_                              | `FLIGHT_DIST_PATH`                   | `../dist`        | Filesystem root for `koa-static` (relative to cwd **after** chdir to `app_home`).                                                                                                                               |
+| _(n/a)_                              | `FLIGHT_DISABLE_SPA_PIPELINE`        | _(unset)_        | **`1` / `true` / `yes`**: force **legacy** production stack (no in-router SPA fallback) while keeping `production` + `disable_vite`. Use for **API-only** workers or until duplicate app middleware is removed. |
+| _(n/a)_                              | `FLIGHT_STATIC_PREFIXES`             | `/assets,/fonts` | Baseline URL prefixes for **rate-limit skipping** on `GET`/`HEAD` (static hashed chunks).                                                                                                                       |
+| _(n/a)_                              | `FLIGHT_RATE_LIMIT_EXCLUDE_PREFIXES` | _(empty)_        | Extra prefixes merged with `FLIGHT_STATIC_PREFIXES` for the same skip list.                                                                                                                                     |
+| _(n/a)_                              | `FLIGHT_SPA_INDEX`                   | `index.html`     | SPA shell file inside the dist root for HTML fallback.                                                                                                                                                          |
+| _(n/a)_                              | `FLIGHT_SPA_DENY_PREFIXES`           | _(empty)_        | Extra prefixes that never get SPA fallback (merged with `/api`, `/health`).                                                                                                                                     |
+| _(n/a)_                              | `FLIGHT_TRUST_PROXY`                 | `false`          | **`1` / `true` / `yes`**: set **`app.proxy = true`** so `ctx.ip` / rate-limit id use **`X-Forwarded-For`** behind an L7 LB.                                                                                     |
+| _(n/a)_                              | `FLIGHT_HTTP_CACHE`                  | `false`          | **`1` / `true` / `yes`**: enable **`koa-cash`** in the **SPA pipeline** branch only (off by default there). Legacy branch always attaches `koa-cash`.                                                           |
+| _(n/a)_                              | `FLIGHT_REDIS_HOST`                  | `localhost`      | Redis for sessions, rate limit, and cache adapter.                                                                                                                                                              |
+| _(n/a)_                              | `FLIGHT_REDIS_PORT`                  | `6379`           | Redis port.                                                                                                                                                                                                     |
+| _(n/a)_                              | `FLIGHT_MAX_WORKERS`                 | CPU count        | Cap cluster worker count on small nodes.                                                                                                                                                                        |
+
+Example `.env` fragment:
+
+```bash
+FLIGHT_MODE=development
+FLIGHT_APP_HOME=.
+FLIGHT_REDIS_HOST=127.0.0.1
+FLIGHT_REDIS_PORT=6379
+FLIGHT_PORT=3000
+FLIGHT_MAX_WORKERS=4
+```
+
+Production behind a proxy:
+
+```bash
+FLIGHT_MODE=production
+FLIGHT_DISABLE_VITE=true
+FLIGHT_TRUST_PROXY=1
+```
 
 ## Project Structure
 
 ```
 my-app/
-├── components/           # Application components
-│   ├── Hello/   # Component directory
-│   │   ├── Hello.vue    # Vue component view
-│   │   └── Hello.backend.ts  # Backend routes and logic
-├── assets/              # Static assets
-├── dist/                # Production build output
+├── components/
+│   └── Hello/
+│       ├── Hello.vue          # Vue UI (example)
+│       └── Hello.backend.ts   # Koa routes for this component
+├── assets/
+├── dist/                      # Production build output
 └── package.json
 ```
 
-Each component follows a simple structure:
-
-- `Index.vue`: Contains the Vue component template, script, and styles
-- `Index.backend.ts`: Contains the backend routes and logic for the component
-
-Example component files:
+Example Vue + backend snippets:
 
 `components/hello/Index.vue`:
 
@@ -151,107 +227,67 @@ router.get('/hello', async (ctx) => {
 export default router.routes()
 ```
 
-## Configuration
+## Development mode
 
-Flight can be configured through environment variables or command-line arguments:
+- **Vue** + **Vite** with HMR on port **3001**
+- Backend worker on **`--port`** (default **3000**)
+- Request logging via **`koa-logger`**
 
-```bash
-FLIGHT_MODE=development
-FLIGHT_REDIS_HOST=localhost
-FLIGHT_REDIS_PORT=6379
-FLIGHT_MAX_WORKERS=4
-```
-
-## Development Mode
-
-In development mode, Flight provides:
-
-- Hot Module Replacement (HMR)
-- Fast refresh for React components
-- Detailed error messages
-- Development server on port 3001
-
-## Production Mode
+## Production mode
 
-Production mode includes:
+- Optional **`npx vite build`** before serving static assets when **`disable_vite`** is **false**
+- Cluster workers capped by **`FLIGHT_MAX_WORKERS`**
+- Compression + Redis-backed rate limiting in all production configurations
+- Static dist + SPA behavior depends on **built-assets mode**—see next section
 
-- Optimized builds
-- Rate limiting
-- Response compression
-- Redis caching
-- Cluster mode for load balancing
-- Production server on port 3000
+## Production SPA pipeline (v2)
 
-## Comparison with Avian
+**When it is on (option B):** `mode === 'production'` **and** **`disable_vite === true`** **and** **`FLIGHT_DISABLE_SPA_PIPELINE` is not truthy.**
 
-Flight is a modern reimagining of the Avian framework, making several architectural improvements while maintaining the core philosophy of component-driven applications. Here are the key differences:
+**What it does:** After your **`router`** (all `**/*.backend.ts` routes), Flight serves **`FLIGHT_DIST_PATH`** with **`koa-static`**, then applies an **`index.html`** fallback for typical browser navigations (see tests in `src/spa-pipeline.test.ts` for the behavioral contract). Only then runs **`koa-compress`**, Redis **`koa-ratelimit`** (with **`GET`/`HEAD` skipped** under `FLIGHT_STATIC_PREFIXES` ∪ `FLIGHT_RATE_LIMIT_EXCLUDE_PREFIXES`), and optionally **`koa-cash`** when **`FLIGHT_HTTP_CACHE`** is enabled.
 
-### Framework Evolution
+**Path ownership**
 
-- **Koa Instead of Express**: Flight uses Koa.js as its foundation instead of Express, providing better async/await support and a more modern middleware architecture
-- **Vite Instead of Webpack**: Replaced Webpack bundling with Vite for significantly faster development experience and simpler configuration
-- **TypeScript First**: While Avian supported TypeScript, Flight is built with TypeScript from the ground up
+- **API / BFF:** Implement on your `Router` in `*.backend.ts` under prefixes you own (conventionally **`/api/...`**). Those paths are excluded from the SPA fallback, along with **`/health`** and any **`FLIGHT_SPA_DENY_PREFIXES`**.
+- **Static:** Any file present under the dist root is served by **`koa-static`** first.
+- **SPA:** Remaining **`GET`/`HEAD`** requests that look like document navigations and whose last path segment has **no dot** (so `file.ext` URLs are not rewritten) may receive **`FLIGHT_SPA_INDEX`**.
 
-### Architectural Improvements
+**Load balancers and `X-Forwarded-For`**
 
-1. **Simplified Component Structure**
-    - Avian: Complex component hierarchy with multiple file types (.client, .server, .view, .config)
-    - Flight: Streamlined with `.backend.ts` files and modern frontend frameworks
-2. **Development Experience**
-    - Avian: Webpack-based bundling with slower rebuild times
-    - Flight: Vite-powered development with instant HMR and no bundle step in development
+- Set **`FLIGHT_TRUST_PROXY=1`** when Flight sits behind a trusted reverse proxy so **`ctx.ip`** and the rate limiter’s **`id`** reflect the client. Configure your proxy to append **one** well-formed **`X-Forwarded-For`** chain.
+- Sessions use cookies (`sameSite: true` in code today); sticky sessions or shared Redis are operational choices outside Flight’s defaults.
 
-3. **Session Management**
-    - Avian: Express-session with Redis store
-    - Flight: Koa-session with Redis store, improved security defaults
+### Middleware order (mermaid)
 
-4. **Performance Features**
-    - Built-in rate limiting
-    - Redis-based caching
-    - Automatic compression in production
-    - Cluster mode for CPU utilization
+**SPA pipeline (default when production + `disable_vite`):**
 
-5. **Configuration**
-    - Avian: Complex webpack configuration and multiple build modes
-    - Flight: Simplified configuration with sensible defaults and Vite's zero-config approach
-
-### What's Different
-
-1. **Removed Features**
-    - Removed Webpack-specific configurations
-    - Removed legacy view engine support (EJS, Twig, Pug)
-    - Removed Sentry integration (can be added as middleware if needed)
-    - Removed built-in cron job scheduler (better handled by dedicated services)
-
-2. **New Features**
-    - Native ESM support
-    - Built-in CORS support
-    - Improved Redis integration
-    - Better security defaults
-    - Simpler API for backend routes
-    - Modern frontend tooling support
+```mermaid
+flowchart TD
+  A[cors + bodyparser + session] --> B[router + *.backend.ts]
+  B --> C[koa-static dist]
+  C --> D[SPA index.html fallback]
+  D --> E[koa-compress]
+  E --> F[koa-ratelimit with prefix skips]
+  F --> G{koa-cash}
+  G -->|FLIGHT_HTTP_CACHE on| H[Redis-backed cache]
+  G -->|default| I[no cache middleware]
+```
 
-3. **Simplified Architecture**
-    - Reduced configuration complexity
-    - More intuitive component organization
-    - Better separation of concerns
-    - Modern middleware approach
+**Legacy production stack** (`disable_vite` false, or **`FLIGHT_DISABLE_SPA_PIPELINE`** set): `router` → **`compress`** → **`ratelimit`** → **`koa-cash`** → **`koa-static`**.
 
-### Migration from Avian
+### Migrating from Flight 1.x
 
-If you're migrating from Avian, the main changes you'll need to make are:
+1. If you rely on the **old** order (everything after `router` saw compress/ratelimit/cache **before** static), set **`FLIGHT_DISABLE_SPA_PIPELINE=1`** until you validate the new behavior.
+2. If your app already shipped **custom SPA / history fallback** middleware in `*.backend.ts`, remove the duplicate once you confirm Flight’s fallback matches your routes (especially non-`/api` prefixes—use **`FLIGHT_SPA_DENY_PREFIXES`**).
+3. Expect **`koa-cash` off** in the SPA pipeline unless you opt in with **`FLIGHT_HTTP_CACHE`**.
 
-1. Update your component structure to use `.backend.ts` files
-2. Move from Express middleware to Koa middleware
-3. Update your frontend bundling to use Vite
-4. Adapt to the new session management system
-5. Update your static file serving configuration
+See **[CHANGELOG.md](CHANGELOG.md)** for the full **2.0.0** notes.
 
 ## Requirements
 
-- Node.js 16.x or higher
-- Redis server
-- TypeScript 4.x or higher
+- Node.js **16.x** or higher
+- **Redis** (sessions / rate limit / cache integrations)
+- **TypeScript** in your app if you author `.backend.ts` modules as TS
 
 ## License
 
@@ -259,14 +295,10 @@ MIT
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Issues and pull requests are welcome. Flight improves fastest with real workloads—if you hit an edge case, open an issue with a minimal repro.
 
 ## Acknowledgments
 
-Flight succeeds the [Avian](https://github.com/ispyhumanfly/avian) framework. Avian began at ThoughtPivot and was later handed to FlyPaper Technologies, LLC, where it grew into the platform many teams relied on. Flight is born from that lineage—the ideas and hardening FlyPaper contributed to Avian—carried forward as ThoughtPivot’s next-generation server.
-
-We’re grateful to FlyPaper Technologies for stewarding Avian and advancing component-driven architecture.
-
-## ThoughtPivot
+**Flight** succeeds **[Avian](https://github.com/ispyhumanfly/avian)**—the component-oriented Node server that helped prove this programming model. **Dan Stevenson** created Avian and carried it into **FlyPaper Technologies**, where **Nick Fredericks**, Dan, and the FlyPaper team sharpened Avian’s component boundaries and pushed its operational story. Dan continued to maintain Avian while **Flight** took shape to embrace newer tooling and a cleaner baseline for the next decade.
 
-Today Flight is an official ThoughtPivot technology: developed and maintained by the [ThoughtPivot](https://github.com/thoughtpivot) organization as part of its ecosystem.
+Today **Flight** is maintained by the **ThoughtPivot** engineering team and **contributors like you**—the same spirit of openness and iteration, with a hard focus on speed, clarity, and deployment flexibility.

package/dist/flight.js

@@ -1,9 +1,10 @@
-#!ts-node
+#!/usr/bin/env node
 "use strict";
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+require("dotenv/config");
 const child_process_1 = require("child_process");
 const koa_1 = __importDefault(require("koa"));
 const ioredis_1 = __importDefault(require("ioredis"));
@@ -21,9 +22,88 @@ const path_1 = __importDefault(require("path"));
 const koa_ratelimit_1 = __importDefault(require("koa-ratelimit"));
 const koa_static_1 = __importDefault(require("koa-static"));
 const koa_session_1 = __importDefault(require("koa-session"));
+const spa_pipeline_js_1 = require("./spa-pipeline.js");
+function normalizeExcludePaths(value) {
+    if (value == null || value === '')
+        return [];
+    const parts = Array.isArray(value) ? value : [value];
+    const out = [];
+    for (const p of parts) {
+        const s = String(p).trim();
+        if (!s)
+            continue;
+        out.push(...s
+            .split(',')
+            .map((x) => x.trim())
+            .filter(Boolean));
+    }
+    return out;
+}
+function dedupeStrings(items) {
+    return [...new Set(items)];
+}
+/** Build fast-glob ignore globs for trees rooted under `appRootAbs`. */
+function backendDiscoveryIgnorePatterns(appRootAbs, excludeRelativeDirs) {
+    const patterns = [];
+    for (const raw of excludeRelativeDirs) {
+        const trimmed = raw.trim();
+        if (!trimmed)
+            continue;
+        const resolved = path_1.default.resolve(appRootAbs, trimmed);
+        const rel = path_1.default.relative(appRootAbs, resolved);
+        const relPosix = rel.replace(/\\/g, '/');
+        if (!relPosix || relPosix.startsWith('..') || path_1.default.isAbsolute(rel)) {
+            console.warn(`Flight: exclude_paths entry skipped (outside app_home): ${trimmed}`);
+            continue;
+        }
+        patterns.push(`${relPosix}/**`);
+    }
+    return patterns;
+}
 const _yargs = require('yargs/yargs');
-const yargsFactory = typeof _yargs === 'function' ? _yargs : _yargs.default;
-const argv = yargsFactory(process.argv.slice(2)).argv;
+const yargsEntry = typeof _yargs === 'function' ? _yargs : _yargs.default;
+const argv = yargsEntry(process.argv.slice(2))
+    .option('exclude_paths', {
+    alias: 'exclude-paths',
+    type: 'array',
+    string: true,
+    default: [],
+    describe: 'Directories under app_home to skip when discovering **/*.backend.ts (repeat flag or comma-separated)'
+})
+    .option('mode', {
+    type: 'string',
+    describe: 'development (Vite HMR) or production'
+})
+    .option('port', {
+    type: 'number',
+    describe: 'HTTP listen port'
+})
+    .option('app_home', {
+    alias: 'app-home',
+    type: 'string',
+    describe: 'Application root directory'
+})
+    .option('app_key', {
+    alias: 'app-key',
+    type: 'string',
+    describe: 'Session cookie name'
+})
+    .option('app_secret', {
+    alias: 'app-secret',
+    type: 'string',
+    describe: 'Session signing secret(s), comma-separated for rotation'
+})
+    .option('payload_limit', {
+    alias: 'payload-limit',
+    type: 'string',
+    describe: 'koa-bodyparser JSON body limit'
+})
+    .option('disable_vite', {
+    alias: 'disable-vite',
+    type: 'boolean',
+    describe: 'Skip vite build in production; enables built-assets / SPA pipeline when mode is production'
+})
+    .parseSync();
 // Set default session duration (24 hours in milliseconds)
 const DEFAULT_SESSION_DURATION = 86400000; // 24 hours in milliseconds
 // Get session duration from environment variable or command line argument
@@ -34,13 +114,13 @@ if (isNaN(argv.session_duration) || argv.session_duration < 0) {
     argv.session_duration = DEFAULT_SESSION_DURATION;
 }
 if (!argv.app_home) {
-    argv.app_home = '.';
+    argv.app_home = process.env.FLIGHT_APP_HOME || '.';
 }
 if (!argv.app_key) {
-    argv.app_key = 'flightApp';
+    argv.app_key = process.env.FLIGHT_APP_KEY || 'flightApp';
 }
 if (!argv.app_secret) {
-    argv.app_secret = 'the best secret key in the world';
+    argv.app_secret = process.env.FLIGHT_APP_SECRET || 'the best secret key in the world';
 }
 // Set default port values
 if (!argv.port) {
@@ -59,14 +139,22 @@ if (isNaN(argv.port) || argv.port < 1 || argv.port > 65535) {
 }
 // Set default value for disable_vite flag
 if (argv.disable_vite === undefined) {
-    // Check for environment variable first, then default to false
-    argv.disable_vite = process.env.FLIGHT_DISABLE_VITE === 'true' ? true : false;
+    const dv = process.env.FLIGHT_DISABLE_VITE;
+    argv.disable_vite = dv === 'true' || dv === '1' || dv === 'yes';
 }
 // Ensure the value is a boolean
 argv.disable_vite = Boolean(argv.disable_vite);
 const appHomePath = path_1.default.resolve(argv.app_home);
+const excludePathsConfigured = dedupeStrings([
+    ...normalizeExcludePaths(argv.exclude_paths),
+    ...normalizeExcludePaths(process.env.FLIGHT_EXCLUDE_PATHS)
+]);
+const backendDiscoveryIgnores = backendDiscoveryIgnorePatterns(appHomePath, excludePathsConfigured);
 process.chdir(appHomePath);
 console.log(appHomePath);
+if (backendDiscoveryIgnores.length > 0) {
+    console.log('Flight: excluding **/*.backend.ts discovery under:', backendDiscoveryIgnores.map((g) => g.replace(/\*\*$/, '')).join(', '));
+}
 const mode = process.env.FLIGHT_MODE || argv.mode || 'production';
 /** Prefix without breaking printf-style logs (koa-logger uses `%s` as the first argument). */
 const flightModeLabel = `Flight (${mode}):`;
@@ -99,6 +187,7 @@ if (cluster_1.default.isPrimary) {
 }
 else {
     const app = new koa_1.default();
+    (0, spa_pipeline_js_1.applyTrustProxy)(app);
     app.use((0, koa_logger_1.default)());
     app.keys = argv.app_secret.split(',');
     const SESSION_CONFIG = {
@@ -115,7 +204,9 @@ else {
     app.use((0, cors_1.default)()).use((0, koa_bodyparser_1.default)({
         jsonLimit: argv.payload_limit
     }));
-    const backEndFiles = fast_glob_1.default.sync('**/*.backend.ts');
+    const backEndFiles = fast_glob_1.default.sync('**/*.backend.ts', {
+        ignore: backendDiscoveryIgnores
+    });
     backEndFiles.forEach((file) => {
         const serverRoutes = require(path_1.default.resolve(file));
         console.log('Found component backend file: ' + path_1.default.resolve(file));
@@ -136,8 +227,15 @@ else {
                 console.error(`stderr: ${stderr}`);
             });
         }
-        app.use((0, koa_compress_1.default)());
-        app.use((0, koa_ratelimit_1.default)({
+        const distRoot = (0, spa_pipeline_js_1.resolveDistRoot)(process.cwd());
+        const useSpaPipeline = (0, spa_pipeline_js_1.productionSpaPipelineActive)(mode, Boolean(argv.disable_vite));
+        const staticPrefixes = (0, spa_pipeline_js_1.parseCommaPrefixes)(process.env.FLIGHT_STATIC_PREFIXES, '/assets,/fonts');
+        const rateLimitSkipPrefixes = dedupeStrings([
+            ...staticPrefixes,
+            ...(0, spa_pipeline_js_1.parseCommaPrefixes)(process.env.FLIGHT_RATE_LIMIT_EXCLUDE_PREFIXES, '')
+        ]);
+        const spaDenyExtra = (0, spa_pipeline_js_1.parseCommaPrefixes)(process.env.FLIGHT_SPA_DENY_PREFIXES, '');
+        const productionRatelimit = (0, koa_ratelimit_1.default)({
             driver: 'redis',
             db: redis,
             duration: 60000,
@@ -150,12 +248,27 @@ else {
             },
             max: 1200,
             disableHeader: false
-        }));
-        app.use((0, koa_cash_1.default)({
+        });
+        const productionKoaCash = (0, koa_cash_1.default)({
             get: (key) => redis.get(key),
             set: (key, value) => redis.set(key, value, 'EX', 30)
-        }));
-        app.use((0, koa_static_1.default)(process.env.FLIGHT_DIST_PATH || '../dist'));
+        });
+        if (useSpaPipeline) {
+            console.log('Flight: production SPA pipeline (static + index.html fallback before compress / rate limit); opt out with FLIGHT_DISABLE_SPA_PIPELINE=1');
+            app.use((0, koa_static_1.default)(distRoot));
+            app.use((0, spa_pipeline_js_1.spaIndexHtmlFallback)(distRoot, (0, spa_pipeline_js_1.spaIndexRelative)(), spaDenyExtra));
+            app.use((0, koa_compress_1.default)());
+            app.use((0, spa_pipeline_js_1.ratelimitWithPrefixSkips)(redis, rateLimitSkipPrefixes));
+            if ((0, spa_pipeline_js_1.httpCacheEnabledInSpaPipeline)()) {
+                app.use(productionKoaCash);
+            }
+        }
+        else {
+            app.use((0, koa_compress_1.default)());
+            app.use(productionRatelimit);
+            app.use(productionKoaCash);
+            app.use((0, koa_static_1.default)(distRoot));
+        }
         if (!argv.disable_vite) {
             console.log(`App served out of dist/ and available on port ${argv.port}`);
         }