@thoughtpivot/flight 2.0.1 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 3.0.0
+
+### Breaking
+
+- **Vite 8** toolchain: `vite` `^8.3.2`, `@vitejs/plugin-react` `^6.1.1`, `@vitejs/plugin-vue` `^6.0.9`, and `vite-plugin-vuetify` `^2.1.3`. `@vitejs/plugin-react` 6 requires Vite 8 (`vite/internal`). Apps that still pin Vite 6 should stay on `@thoughtpivot/flight@2.0.2` until they upgrade.
+- **`ioredis` 6**: requires Node.js 20+ and uses **RESP3** by default. Set `protocol: 2` on the Redis client if a server still needs the ioredis v5 wire protocol.
+- **Node engines**: `^20.19.0 || >=22.12.0` (aligned with Vite 8 / ioredis 6).
+
+### Added
+
+- **Bun runtime** (`src/bun`, `flight-bun` / `bun src/bun/server.ts`): `Bun.serve`, `/healthz`, and the same middleware jobs (logging, security headers, CORS, gzip, rate limit, sessions, response cache) on the native Bun path.
+- **Koa compatibility on that runtime.** A `*.backend.ts` file may still `export default router.routes()`. Those backends are mounted through Koa and `koa-bodyparser`. Compiled `*.backend.js` files are discovered too.
+- **`FLIGHT_TRUST_PROXY` on the Bun rate limiter.** `X-Forwarded-For` is ignored unless the proxy is trusted.
+- **`@vitejs/plugin-react`** as a dependency (alongside `@vitejs/plugin-vue`) so React + Vite apps get the same style of transitive plugin coverage as Vue apps.
+- Broader Node test coverage for SPA fallback, env flags, rate-limit skips, and backend exclude paths. `npm test` runs every compiled `dist/*.test.js` file.
+- GitHub Actions **CI** (`.github/workflows/ci.yml`) and **npm publish** (`.github/workflows/publish.yml`) with provenance. CircleCI is retired.
+
+### Changed
+
+- Dependency majors also include `koa-helmet` 9 and `koa-ratelimit` 6.
+- SPA index paths with `..` stay inside the dist root; exclude paths named `..foo` stay inside `app_home`; `.` / app-root excludes warn instead of ignoring everything.
+
+### Notes
+
+- The Node / Koa `flight` binary is unchanged in role. Sessions on Bun stay off until `FLIGHT_SESSION_SECRET` is set. Rate limiting on Bun stays off until `FLIGHT_RATE_LIMIT_MAX` is greater than zero.
+- Git changelog entry **2.1.0** below was prepared in-repo but never published to npm; its React + Vite docs/plugin work ships in this 3.0.0 release together with the Vite 8 upgrade.
+
+## 2.1.0
+
+### Added
+
+- **`@vitejs/plugin-react`** as a **dependency** (alongside **`@vitejs/plugin-vue`**), so React + Vite apps that depend on `@thoughtpivot/flight` get the same style of transitive Vite plugin coverage as Vue apps. Install **`react`**, **`react-dom`**, and (for TypeScript) **`@types/react`** / **`@types/react-dom`** in your application; Flight remains the server/runtime, not the UI runtime.
+
+### Documentation
+
+- README: **React + Vite** quick path (sample `vite.config`, `index.html`, `main.tsx`, `App.tsx`), highlights updated for Vue and React, and clarification that **Flight does not pick Vue vs React**—your **`vite.config`** does.
+
+### Changed
+
+- Development log lines refer to the **Vite** dev server generically (Vue/React per app config).
+
 ## 2.0.0
 
 ### Breaking

package/README.md

@@ -4,17 +4,18 @@
 
 # Flight
 
-**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).
+**Flight** is an 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).
 
-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.
+Think **platform-agnostic**: not framework-as-a-platform, but a clear runtime you can run wherever **Node** or **Bun** runs—VMs, Kubernetes, bare metal, your cloud of choice. The `flight` binary is the Node / Koa server. `flight-bun` is the Bun server (`Bun.serve`), and it can still mount existing Koa `router.routes()` backends while you move routes over. Flight is aimed at **hyperscale-friendly** designs (cluster workers on Node, a single Bun process with native TypeScript on the Bun path), **ephemeral** processes, and **component-shaped** backends so routes stay colocated with the features they serve. **Vue** and **React** are both supported through the same **Vite** dev and production flows (your app’s **`vite.config`** chooses the UI stack; Flight does not).
 
 Flight is **open source** from **[ThoughtPivot](https://github.com/thoughtpivot)**.
 
 ## Highlights
 
-- **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
+- **Two runtimes**: **Node / Koa** (`flight`) and **Bun** (`flight-bun`). The Bun server loads TypeScript directly, exposes `GET /healthz`, and still accepts existing Koa backends
+- **Performance-focused**: Cluster mode on Node, compression, Redis-backed caching hooks, rate limiting in production
+- **Developer velocity**: **Vite** dev server with HMR on port **3001** for **Vue** or **React** (per your project’s Vite config)
+- **Composable backends**: Discover `**/*.backend.ts` (and `**/*.backend.js` on Bun) under your app root and mount them 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
@@ -50,6 +51,8 @@ npm init -y
 npm install @thoughtpivot/flight ioredis
 ```
 
+For a **React** UI, also install `react`, `react-dom`, and (with TypeScript) `@types/react` / `@types/react-dom` as dev dependencies. For **Vue**, install `vue` and wire **`@vitejs/plugin-vue`** in **`vite.config`**.
+
 3. Ensure Redis is running locally or set environment variables (see table below).
 
 4. Create a component with a backend route:
@@ -103,24 +106,42 @@ npx flight --mode production
 
 **`--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):
+**Try without adding a dependency** (downloads the package for this invocation). Use **`--package=@scope/pkg`** (equals form) and a literal **`--`** before the binary name so `npx` does not treat `flight` as a separate package or lose the install’s **`node_modules/.bin`** on your `PATH` (otherwise you can see `sh: flight: command not found`):
+
+```bash
+npx --yes --package=@thoughtpivot/flight -- flight --mode development
+```
+
+Equivalent:
 
 ```bash
-npx --yes --package @thoughtpivot/flight flight --mode development
+npm exec --yes --package=@thoughtpivot/flight -- flight --mode development
 ```
 
 **Global install** (optional): `npm install -g @thoughtpivot/flight`, then run **`flight`** from your PATH the same way as **`npx flight`**.
 
+**Bun** (same app directory, [Bun](https://bun.sh) 1.x on your PATH):
+
+```bash
+# development: API on :3000, Vite on :3001
+FLIGHT_MODE=development flight-bun
+
+# production: serve dist/ plus backends
+FLIGHT_MODE=production flight-bun
+```
+
+From a clone of this repo, before the package is published, that is `bun src/bun/server.ts`. Existing `export default router.routes()` files keep working. New files can export a Web `Request` / `Response` route map. Details, env vars, and the backend contract are in [Bun runtime](#bun-runtime).
+
 ## 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.
+The Node server picks **`mode`** as: **`FLIGHT_MODE`** (if set and non-empty), else **`--mode`** from argv, else **`production`**. The table below is that Node / Koa process. It assumes Redis is reachable unless you only use routes that avoid session, rate limit, and cache. The Bun server is documented in [Bun runtime](#bun-runtime).
 
-| 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).                                                                               |
+| Topic            | Development                                                                                              | Production                                                                                                                                  |
+| ---------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Vite**         | Child process: `npx vite --port 3001 --host 0.0.0.0` (HMR for **Vue or React**, per your `vite.config`). | 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**
 
@@ -163,6 +184,8 @@ Flight loads a **`.env`** file from the **current working directory** at startup
 | _(n/a)_                              | `FLIGHT_REDIS_PORT`                  | `6379`           | Redis port.                                                                                                                                                                                                     |
 | _(n/a)_                              | `FLIGHT_MAX_WORKERS`                 | CPU count        | Cap cluster worker count on small nodes.                                                                                                                                                                        |
 
+`1`, `true`, and `yes` are matched exactly. `TRUE` does not turn those settings on.
+
 Example `.env` fragment:
 
 ```bash
@@ -227,9 +250,72 @@ router.get('/hello', async (ctx) => {
 export default router.routes()
 ```
 
+## React + Vite (same Flight commands)
+
+Flight does **not** choose Vue vs React—it runs **`vite`** / **`vite build`** from your **`app_home`**; your **`vite.config.*`** and app **`package.json`** select the framework. The `@thoughtpivot/flight` package includes **`@vitejs/plugin-react`** alongside **`@vitejs/plugin-vue`** so React+Vite apps get the same style of transitive plugin coverage as Vue apps. You still install the UI runtime in **your** app. Flight ships **Vite 8** and matching plugins; apps that stay on Vite 6 should pin **`@thoughtpivot/flight@2.0.2`** until they upgrade.
+
+```bash
+npm install react react-dom
+npm install -D @types/react @types/react-dom
+```
+
+Set **`"type": "module"`** in the app **`package.json`** (or use a `.mts` / `.mjs` Vite config) so Vite 8 loads ESM config without falling back to the deprecated CommonJS path.
+
+`vite.config.ts` (project root):
+
+```typescript
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+    plugins: [react()]
+})
+```
+
+`index.html`:
+
+```html
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>Flight + React</title>
+    </head>
+    <body>
+        <div id="root"></div>
+        <script type="module" src="/src/main.tsx"></script>
+    </body>
+</html>
+```
+
+`src/main.tsx`:
+
+```tsx
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import App from './App'
+
+createRoot(document.getElementById('root')!).render(
+    <StrictMode>
+        <App />
+    </StrictMode>
+)
+```
+
+`src/App.tsx`:
+
+```tsx
+export default function App() {
+    return <h1>Hello from Flight + React</h1>
+}
+```
+
+Use the same **`npx flight --mode development`** / **`--mode production`** flow as Vue. Production **`dist`**, **`FLIGHT_DISABLE_VITE`**, and the **Production SPA pipeline** behave the same for a Vite-built React SPA.
+
 ## Development mode
 
-- **Vue** + **Vite** with HMR on port **3001**
+- **Vite** with HMR on port **3001** for **Vue or React** (whatever your `vite.config` configures)
 - Backend worker on **`--port`** (default **3000**)
 - Request logging via **`koa-logger`**
 
@@ -283,19 +369,97 @@ flowchart TD
 
 See **[CHANGELOG.md](CHANGELOG.md)** for the full **2.0.0** notes.
 
+## Bun runtime
+
+`flight-bun` is the Bun entry. `npx flight` remains the Node server. From an installed package:
+
+```bash
+FLIGHT_MODE=development flight-bun
+```
+
+From a clone of this repo:
+
+```bash
+FLIGHT_MODE=development bun src/bun/server.ts
+```
+
+`npm run test:bun` runs the Bun suite. `npm test` stays the Node suite.
+
+The Bun server uses `Bun.serve` and loads TypeScript directly. It exposes `GET /healthz` and the same edge jobs as the Node server (logging, security headers, CORS, gzip, rate limit, sessions, response cache) without Koa packages on the native path. Redis is optional (`FLIGHT_REDIS_URL`); without it, sessions and cache use memory.
+
+**Two backend contracts can be mixed in one app.**
+
+Bun-native files default-export a path map. Handlers are `(req: Request) => Response`. Path params use Bun's `:id` routes.
+
+```typescript
+export default {
+    '/api/hello': {
+        GET: () => Response.json({ message: 'Hello from Flight!' })
+    }
+}
+```
+
+Existing Koa files keep working. `export default router.routes()` is mounted through Koa, including JSON body parsing. That is the on-ramp: boot the app on Bun, then rewrite routes file by file. `*.backend.js` is discovered as well as `*.backend.ts`.
+
+In development (`FLIGHT_MODE=development`) the API stays on `FLIGHT_PORT` (default 3000) and Vite is spawned on 3001. In production the built SPA is read from `FLIGHT_DIST_PATH` (default `<app home>/dist`) with an `index.html` fallback. `/api`, `/health`, and `/healthz` do not fall back.
+
+| Variable                 | Default          | Bun runtime                                                                                      |
+| ------------------------ | ---------------- | ------------------------------------------------------------------------------------------------ |
+| `FLIGHT_SESSION_SECRET`  | unset            | Sessions stay **off** until this is set. There is no baked-in secret.                            |
+| `FLIGHT_RATE_LIMIT_MAX`  | `0`              | Rate limit stays **off** until this is greater than zero.                                        |
+| `FLIGHT_TRUST_PROXY`     | false            | When `1` / `true` / `yes`, the limiter uses `X-Forwarded-For`. Otherwise that header is ignored. |
+| `FLIGHT_REDIS_URL`       | unset            | `redis://host:6379` for shared sessions and cache.                                               |
+| `FLIGHT_CACHE_ENABLED`   | false            | Cache GET responses that send `Cache-Control: max-age`.                                          |
+| `FLIGHT_STATIC_PREFIXES` | `/assets,/fonts` | GET/HEAD under these prefixes skip the rate limit.                                               |
+
+Other `FLIGHT_*` knobs from the Node server (`FLIGHT_MODE`, `FLIGHT_PORT`, `FLIGHT_APP_HOME`, `FLIGHT_EXCLUDE_PATHS`, `FLIGHT_SPA_DENY_PREFIXES`, `FLIGHT_PAYLOAD_LIMIT`) apply here too. `GET /healthz` returns `ok` and is not rate limited.
+
 ## Requirements
 
-- Node.js **16.x** or higher
-- **Redis** (sessions / rate limit / cache integrations)
+- Node.js **`^20.19.0` or `>=22.12.0`** (the `flight` binary; matches Vite 8 / ioredis 6)
+- [Bun](https://bun.sh) 1.x (only for `flight-bun` / `npm run test:bun`)
+- **Redis** (sessions / rate limit / cache integrations on the Node server; optional for the Bun runtime)
 - **TypeScript** in your app if you author `.backend.ts` modules as TS
 
+## CI and npm publish
+
+GitHub Actions is the only CI/publish path:
+
+| Workflow                                                         | When                                                     | What it does                                                    |
+| ---------------------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------- |
+| [`.github/workflows/ci.yml`](.github/workflows/ci.yml)           | Pull requests and pushes to `main`                       | `npm ci`, `lint:check`, `npm test` on Node 20 and 22            |
+| [`.github/workflows/publish.yml`](.github/workflows/publish.yml) | GitHub Release published (or manual `workflow_dispatch`) | Re-runs checks, then `npm publish --access public --provenance` |
+
+### One-time npm setup (Trusted Publishing)
+
+Preferred: no long-lived npm token in GitHub.
+
+1. Sign in at [npmjs.com](https://www.npmjs.com/) as a maintainer of `@thoughtpivot/flight`.
+2. Open the package → **Settings** → **Trusted Publisher**.
+3. Add GitHub Actions with:
+    - **Organization / user:** `thoughtpivot`
+    - **Repository:** `flight`
+    - **Workflow filename:** `publish.yml`
+    - **Environment name:** `npm` (must match the workflow `environment:`)
+4. In the GitHub repo, create an **Environment** named `npm` (Settings → Environments). Optional: require reviewers before publish.
+
+Fallback if Trusted Publishing is unavailable: add a repository or environment secret **`NPM_TOKEN`** (granular token with read/write to `@thoughtpivot/flight`). The publish workflow already passes it as `NODE_AUTH_TOKEN` when present.
+
+### Cut a release
+
+1. Land the version bump on `main` (`package.json` + `CHANGELOG.md`).
+2. Create a GitHub Release whose tag is `v` + that version (example: package `3.0.0` → tag `v3.0.0`).
+3. Publishing the release runs `.github/workflows/publish.yml`. The job fails if the tag and `package.json` version disagree.
+
+Dry-run without publishing: Actions → **Publish** → **Run workflow** → leave **dry_run** checked.
+
 ## License
 
 MIT
 
 ## Contributing
 
-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.
+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. Run `npm test` and `npm run lint:check` before opening a PR.
 
 ## Acknowledgments
 

package/dist/backend-discovery.js

@@ -0,0 +1,61 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeExcludePaths = normalizeExcludePaths;
+exports.dedupeStrings = dedupeStrings;
+exports.mergeExcludePaths = mergeExcludePaths;
+exports.backendDiscoveryIgnorePatterns = backendDiscoveryIgnorePatterns;
+const path_1 = __importDefault(require("path"));
+/** Turn a CLI value or env string into trimmed, comma-split directory names. */
+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;
+}
+/** Preserve first-seen order while dropping duplicate strings. */
+function dedupeStrings(items) {
+    return [...new Set(items)];
+}
+/** Combine CLI and FLIGHT_EXCLUDE_PATHS values, CLI first, without duplicates. */
+function mergeExcludePaths(cliValue, envValue) {
+    return dedupeStrings([...normalizeExcludePaths(cliValue), ...normalizeExcludePaths(envValue)]);
+}
+/**
+ * Build fast-glob ignore globs for trees rooted under `appRootAbs`.
+ * Entries that resolve outside that root, or to the root itself, are skipped.
+ * Folder names are not escaped, so a name like `[abc]` is still a fast-glob pattern.
+ */
+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) {
+            console.warn(`Flight: exclude_paths entry skipped (would ignore all of app_home): ${trimmed}`);
+            continue;
+        }
+        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;
+}

package/dist/flight.js

@@ -22,44 +22,8 @@ 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 backend_discovery_js_1 = require("./backend-discovery.js");
 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 yargsEntry = typeof _yargs === 'function' ? _yargs : _yargs.default;
 const argv = yargsEntry(process.argv.slice(2))
@@ -72,7 +36,7 @@ const argv = yargsEntry(process.argv.slice(2))
 })
     .option('mode', {
     type: 'string',
-    describe: 'development (Vite HMR) or production'
+    describe: 'development (Vite HMR for Vue/React per vite.config) or production'
 })
     .option('port', {
     type: 'number',
@@ -145,11 +109,8 @@ if (argv.disable_vite === undefined) {
 // 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);
+const excludePathsConfigured = (0, backend_discovery_js_1.mergeExcludePaths)(argv.exclude_paths, process.env.FLIGHT_EXCLUDE_PATHS);
+const backendDiscoveryIgnores = (0, backend_discovery_js_1.backendDiscoveryIgnorePatterns)(appHomePath, excludePathsConfigured);
 process.chdir(appHomePath);
 console.log(appHomePath);
 if (backendDiscoveryIgnores.length > 0) {
@@ -230,7 +191,7 @@ else {
         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([
+        const rateLimitSkipPrefixes = (0, backend_discovery_js_1.dedupeStrings)([
             ...staticPrefixes,
             ...(0, spa_pipeline_js_1.parseCommaPrefixes)(process.env.FLIGHT_RATE_LIMIT_EXCLUDE_PREFIXES, '')
         ]);
@@ -286,17 +247,17 @@ else {
             shell: true
         });
         viteProcess.on('error', (error) => {
-            console.error('Failed to start vite server:', error);
+            console.error('Failed to start Vite dev server:', error);
         });
         viteProcess.on('exit', (code) => {
             if (code !== 0) {
-                console.error(`Vite server exited with code ${code}`);
+                console.error(`Vite dev server exited with code ${code}`);
             }
         });
         process.on('SIGINT', () => {
             viteProcess.kill('SIGINT');
             process.exit(0);
         });
-        console.log(`Vite development server with hot module reload ${process.pid} started on 3001`);
+        console.log(`Vite dev server (HMR for Vue/React per your vite.config) for worker ${process.pid} on port 3001`);
     }
 }

package/dist/spa-pipeline.js

@@ -30,6 +30,7 @@ function applyTrustProxy(app, env = process.env) {
     const t = env.FLIGHT_TRUST_PROXY;
     app.proxy = t === '1' || t === 'true' || t === 'yes';
 }
+/** Use `fallback` only when `value` is missing. Add a leading `/` to entries that lack one. */
 function parseCommaPrefixes(value, fallback) {
     const raw = (value ?? fallback).trim();
     if (!raw)
@@ -41,11 +42,18 @@ function parseCommaPrefixes(value, fallback) {
         .map((p) => (p.startsWith('/') ? p : `/${p}`));
 }
 function resolveDistRoot(cwd, env = process.env) {
-    return path_1.default.resolve(cwd, env.FLIGHT_DIST_PATH || '../dist');
+    const configured = env.FLIGHT_DIST_PATH?.trim();
+    return path_1.default.resolve(cwd, configured || '../dist');
 }
+/** SPA shell path inside the dist root. `..` segments and blank values fall back to `index.html`. */
 function spaIndexRelative(env = process.env) {
-    const v = (env.FLIGHT_SPA_INDEX || 'index.html').trim();
-    return v.replace(/^\/+/, '');
+    const configured = env.FLIGHT_SPA_INDEX?.trim().replace(/^\/+/, '');
+    if (!configured)
+        return 'index.html';
+    const normalized = configured.replace(/\\/g, '/');
+    if (normalized.split('/').includes('..'))
+        return 'index.html';
+    return normalized;
 }
 const DEFAULT_DENY_PREFIXES = ['/api', '/health'];
 /** Match connect-history-api-fallback default: do not rewrite paths whose last segment looks like a file name. */
@@ -56,8 +64,16 @@ function lastPathSegmentLooksLikeFile(urlPath) {
 /**
  * After koa-static: serve index.html for document navigations that are not API, health, or static-like paths.
  */
+function indexInsideDist(distRoot, indexRel) {
+    const indexAbs = path_1.default.resolve(distRoot, indexRel);
+    const rel = path_1.default.relative(distRoot, indexAbs);
+    const relPosix = rel.replace(/\\/g, '/');
+    if (!relPosix || relPosix === '..' || relPosix.startsWith('../') || path_1.default.isAbsolute(rel))
+        return undefined;
+    return indexAbs;
+}
 function spaIndexHtmlFallback(distRoot, indexRel, extraDenyPrefixes = []) {
-    const indexAbs = path_1.default.join(distRoot, indexRel);
+    const indexAbs = indexInsideDist(distRoot, indexRel);
     const deny = dedupePathList([...DEFAULT_DENY_PREFIXES, ...extraDenyPrefixes]);
     return async (ctx, next) => {
         if (ctx.method !== 'GET' && ctx.method !== 'HEAD')
@@ -75,6 +91,8 @@ function spaIndexHtmlFallback(distRoot, indexRel, extraDenyPrefixes = []) {
                 return next();
             }
         }
+        if (!indexAbs)
+            return next();
         try {
             await fs_1.default.promises.access(indexAbs, fs_1.default.constants.R_OK);
         }

package/package.json

@@ -1,18 +1,25 @@
 {
     "name": "@thoughtpivot/flight",
-    "version": "2.0.1",
+    "version": "3.0.0",
     "description": "A web server designed for running full stack, component based applications at enterprise scale.",
     "main": "src/flight.ts",
     "publishConfig": {
         "access": "public"
     },
+    "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+    },
     "bin": {
-        "flight": "dist/flight.js"
+        "flight": "dist/flight.js",
+        "flight-bun": "src/bun/server.ts"
     },
     "scripts": {
         "lint": "eslint . --fix && prettier -w .",
+        "lint:check": "eslint . && prettier -c .",
         "build": "rm -rf dist; node_modules/.bin/tsc --project .",
-        "test": "npm run build && node --test dist/spa-pipeline.test.js",
+        "test": "npm run build && node --test dist/*.test.js",
+        "test:bun": "bun test src/bun/app.test.ts",
+        "start:bun": "bun src/bun/server.ts",
         "prepublishOnly": "npm run build"
     },
     "repository": {
@@ -28,6 +35,8 @@
     "files": [
         "dist/flight.js",
         "dist/spa-pipeline.js",
+        "dist/backend-discovery.js",
+        "src/bun",
         "README.md",
         "CHANGELOG.md",
         "readme-assets"
@@ -35,28 +44,29 @@
     "dependencies": {
         "@koa/cors": "^5.0.0",
         "@koa/router": "^13.1.0",
-        "@vitejs/plugin-vue": "^5.2.1",
+        "@vitejs/plugin-react": "^6.1.1",
+        "@vitejs/plugin-vue": "^6.0.9",
         "@vue/language-plugin-pug": "^2.2.0",
         "core-js": "^3.40.0",
         "dotenv": "^17.4.2",
         "esbuild": "^0.28.0",
         "fast-glob": "^3.3.3",
-        "ioredis": "^5.4.2",
+        "ioredis": "^6.0.0",
         "koa": "^2.15.3",
         "koa-bodyparser": "^4.4.1",
         "koa-cash": "^5.0.0",
         "koa-compress": "^5.1.1",
         "koa-connect-history-api-fallback": "^0.3.1",
-        "koa-helmet": "^8.0.1",
-        "koa-logger": "^3.2.1",
-        "koa-ratelimit": "^5.1.0",
+        "koa-helmet": "^9.0.0",
+        "koa-logger": "^4.0.0",
+        "koa-ratelimit": "^6.0.0",
         "koa-redis": "^4.0.1",
         "koa-send": "^5.0.1",
         "koa-session": "^6.4.0",
         "koa-static": "^5.0.0",
         "unplugin-fonts": "^2.0.0",
-        "vite": "^6.1.7",
-        "vite-plugin-vuetify": "^2.0.4",
+        "vite": "^8.3.2",
+        "vite-plugin-vuetify": "^2.1.3",
         "yargs": "^18.0.0"
     },
     "devDependencies": {