@thoughtpivot/flight 1.0.7

package/.circleci/config.yml

@@ -0,0 +1,83 @@
+filter-run-always: &filter-run-always
+    filters:
+        tags:
+            only: /.*/
+
+filter-run-on-master-and-version-tag-only: &filter-run-on-master-and-version-tag-only
+    filters:
+        tags:
+            only: /^v.*/
+        branches:
+            only: main
+
+aliases:
+    - &step-checkout checkout
+    - &step-restore-cache
+      restore_cache:
+          keys:
+              - v1-dependencies-{{ checksum "package.json" }}
+              - v1-dependencies-
+    - &step-install
+      run: npm install
+    - &step-save-cache
+      save_cache:
+          paths:
+              - node_modules
+          key: v1-dependencies-{{ checksum "package.json" }}
+    - &step-build
+      run: npm run build
+
+build-node-common: &common-build
+    working_directory: ~/repo
+    steps:
+        - *step-checkout
+        - *step-restore-cache
+        - *step-install
+        - *step-save-cache
+        - *step-build
+        - run:
+              name: Testing
+              command: npm run test
+
+version: 2
+jobs:
+    deploy:
+        working_directory: ~/repo
+        docker:
+            - image: cimg/node:20.12
+        steps:
+            - *step-checkout
+            - *step-restore-cache
+            - *step-install
+            - *step-save-cache
+            - *step-build
+            - run:
+                  name: Authenticate with registry
+                  command: echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" > ~/repo/.npmrc
+            - run:
+                  name: Publish Package
+                  command: npm publish
+
+    build-node18:
+        <<: *common-build
+        docker:
+            - image: cimg/node:18.20
+
+    build-node20:
+        <<: *common-build
+        docker:
+            - image: cimg/node:20.11
+
+workflows:
+    version: 2
+    build_all:
+        jobs:
+            - build-node18:
+                  <<: *filter-run-always
+            - build-node20:
+                  <<: *filter-run-always
+            - deploy:
+                  requires:
+                      - build-node18
+                      - build-node20
+                  <<: *filter-run-on-master-and-version-tag-only

package/.editorconfig

@@ -0,0 +1,5 @@
+[*.{js,jsx,ts,tsx,cs, json, md, yml, yaml, html, css, scss, less, graphql, mdx, vue, svelte, php, py, rb, rs, toml, go, java, sh, fish, bash, zsh, ksh, sql, tex, r, rmd, dart, xml, cfml, cfc, cfm, tcl, liquid, lisp, el, vue, svelte, swift, scala, groovy, kt, kts, clj, cljs, edn, hs, lhs, lua, moon, ml, mli, mll, mly, pascal, pas, pl, pm, t, pod, php, php3, php4, php5, php6, php7, php8, phtml, ps1, psm1, py, py3, pyi, pyx, r, rkt, rpy, rpy2, rb, rs, rli}]
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+insert_final_newline = true

package/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+    - package-ecosystem: 'npm'
+      directory: '/' # Location of package manifests
+      schedule:
+          interval: 'weekly'

package/.nvmrc

@@ -0,0 +1 @@
+20.11

package/.prettierrc

@@ -0,0 +1,11 @@
+{
+    "arrowParens": "always",
+    "endOfLine": "auto",
+    "printWidth": 120,
+    "semi": false,
+    "singleAttributePerLine": false,
+    "singleQuote": true,
+    "tabWidth": 4,
+    "trailingComma": "none",
+    "useTabs": false
+}

package/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+    "recommendations": ["esbenp.prettier-vscode"]
+}

package/.vscode/settings.json

@@ -0,0 +1,10 @@
+{
+    // exclude .vscode, .github and node_modules from the explorer
+    "files.exclude": {
+        "**/.vscode": true,
+        "**/.github": true,
+        "**/node_modules": true,
+        "**/dist": true,
+        ".circleci": true
+    }
+}

package/LICENSE.md

@@ -0,0 +1,19 @@
+# MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,266 @@
+# Flight
+
+Flight is a modern, high-performance web application server built on Node.js, designed for building scalable, component-driven applications. It represents the evolution of the [Avian](https://github.com/ispyhumanfly/avian) component application server, incorporating modern best practices and improved developer experience.
+
+## Overview
+
+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.
+
+### Key Features
+
+- **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
+
+## Installation
+
+```bash
+npm install @thoughtpivot/flight
+# or
+yarn add @thoughtpivot/flight
+```
+
+Previously published on npm as `@spytech/flight`; switch your dependency to `@thoughtpivot/flight`.
+
+## Quick Start
+
+1. Create a new project directory and initialize:
+
+```bash
+mkdir my-flight-app
+cd my-flight-app
+npm init -y
+```
+
+2. Install Flight and its dependencies:
+
+```bash
+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
+```
+
+4. Create a component with a backend route:
+
+```bash
+mkdir -p components/hello
+```
+
+Create `components/hello/hello.backend.ts`:
+
+```typescript
+import Router from '@koa/router'
+
+const router = new Router()
+
+router.get('/hello', async (ctx) => {
+    ctx.body = { message: 'Hello from Flight!' }
+})
+
+export default router.routes()
+```
+
+5. Start the server:
+
+Development mode:
+
+```bash
+node flight.js --mode development --app_home .
+# Starts development server on port 3001 with HMR
+# Backend API available on port 3000
+```
+
+Production mode:
+
+```bash
+node flight.js --mode production --app_home .
+# Builds and serves application on port 3000
+```
+
+Available CLI options:
+
+- `--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')
+
+## 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
+└── 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:
+
+`components/hello/Index.vue`:
+
+```vue
+<template>
+    <div>
+        <h1>{{ message }}</h1>
+    </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const message = ref('Hello from Flight!')
+</script>
+```
+
+`components/hello/Index.backend.ts`:
+
+```typescript
+import Router from '@koa/router'
+
+const router = new Router()
+
+router.get('/hello', async (ctx) => {
+    ctx.body = { message: 'Hello from Flight!' }
+})
+
+export default router.routes()
+```
+
+## Configuration
+
+Flight can be configured through environment variables or command-line arguments:
+
+```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 includes:
+
+- Optimized builds
+- Rate limiting
+- Response compression
+- Redis caching
+- Cluster mode for load balancing
+- Production server on port 3000
+
+## Comparison with Avian
+
+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:
+
+### Framework Evolution
+
+- **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
+
+### Architectural Improvements
+
+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
+
+3. **Session Management**
+    - Avian: Express-session with Redis store
+    - Flight: Koa-session with Redis store, improved security defaults
+
+4. **Performance Features**
+    - Built-in rate limiting
+    - Redis-based caching
+    - Automatic compression in production
+    - Cluster mode for CPU utilization
+
+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
+
+3. **Simplified Architecture**
+    - Reduced configuration complexity
+    - More intuitive component organization
+    - Better separation of concerns
+    - Modern middleware approach
+
+### Migration from Avian
+
+If you're migrating from Avian, the main changes you'll need to make are:
+
+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
+
+## Requirements
+
+- Node.js 16.x or higher
+- Redis server
+- TypeScript 4.x or higher
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Acknowledgments
+
+Flight is built upon the solid foundation laid by the [Avian](https://github.com/ispyhumanfly/avian) framework, created by FlyPaper Technologies, LLC. We're grateful for their pioneering work in component-driven architecture.
+
+## ThoughtPivot
+
+Flight is a [ThoughtPivot](https://github.com/thoughtpivot) technology: developed and maintained as part of the ThoughtPivot organization and ecosystem.

package/dist/flight.js

@@ -0,0 +1,187 @@
+#!ts-node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const child_process_1 = require("child_process");
+const koa_1 = __importDefault(require("koa"));
+const ioredis_1 = __importDefault(require("ioredis"));
+const koa_redis_1 = __importDefault(require("koa-redis"));
+const router_1 = __importDefault(require("@koa/router"));
+const koa_bodyparser_1 = __importDefault(require("koa-bodyparser"));
+const cluster_1 = __importDefault(require("cluster"));
+const koa_compress_1 = __importDefault(require("koa-compress"));
+const cors_1 = __importDefault(require("@koa/cors"));
+const fast_glob_1 = __importDefault(require("fast-glob"));
+const koa_cash_1 = __importDefault(require("koa-cash"));
+const koa_logger_1 = __importDefault(require("koa-logger"));
+const os_1 = __importDefault(require("os"));
+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 argv = require('yargs/yargs')(process.argv.slice(2)).argv;
+// 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
+argv.session_duration = Number(process.env.FLIGHT_SESSION_DURATION_MS) || argv.session_duration;
+// Validate session duration
+if (isNaN(argv.session_duration) || argv.session_duration < 0) {
+    console.error('Invalid session duration specified. Using default of 24 hours (86400000ms).');
+    argv.session_duration = DEFAULT_SESSION_DURATION;
+}
+if (!argv.app_home) {
+    argv.app_home = '.';
+}
+if (!argv.app_key) {
+    argv.app_key = 'flightApp';
+}
+if (!argv.app_secret) {
+    argv.app_secret = 'the best secret key in the world';
+}
+// Set default port values
+if (!argv.port) {
+    // Check for environment variable first, then use default
+    argv.port = process.env.FLIGHT_PORT || 3000;
+}
+if (!argv.payload_limit) {
+    argv.payload_limit = process.env.FLIGHT_PAYLOAD_LIMIT || '1mb';
+}
+// Convert port to number
+argv.port = Number(argv.port);
+// Validate port is a valid number
+if (isNaN(argv.port) || argv.port < 1 || argv.port > 65535) {
+    console.error('Invalid port specified. Using default port 3000.');
+    argv.port = 3000;
+}
+// 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;
+}
+// Ensure the value is a boolean
+argv.disable_vite = Boolean(argv.disable_vite);
+const appHomePath = path_1.default.resolve(argv.app_home);
+process.chdir(appHomePath);
+console.log(appHomePath);
+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}):`;
+const origConsoleLog = console.log.bind(console);
+console.log = (first, ...rest) => {
+    if (typeof first === 'string' && /%[sdjifoO%]/.test(first)) {
+        origConsoleLog(`${flightModeLabel} ${first}`, ...rest);
+    }
+    else if (first !== undefined) {
+        origConsoleLog(flightModeLabel, first, ...rest);
+    }
+    else {
+        origConsoleLog(flightModeLabel);
+    }
+};
+const redis = new ioredis_1.default({
+    host: process.env.FLIGHT_REDIS_HOST || 'localhost',
+    port: Number(process.env.FLIGHT_REDIS_PORT) || 6379
+});
+if (cluster_1.default.isPrimary) {
+    const numCPUs = os_1.default.cpus().length;
+    const maxWorkers = Number(process.env.FLIGHT_MAX_WORKERS) || numCPUs;
+    const workersCount = Math.min(maxWorkers, numCPUs);
+    for (let i = 0; i < workersCount; i++) {
+        cluster_1.default.fork();
+    }
+    cluster_1.default.on('exit', () => {
+        cluster_1.default.fork();
+    });
+}
+else {
+    const app = new koa_1.default();
+    app.use((0, koa_logger_1.default)());
+    app.keys = argv.app_secret.split(',');
+    const SESSION_CONFIG = {
+        key: argv.app_key,
+        maxAge: argv.session_duration,
+        sameSite: true,
+        path: '/',
+        store: (0, koa_redis_1.default)({
+            client: redis
+        })
+    };
+    app.use((0, koa_session_1.default)(SESSION_CONFIG, app));
+    const router = new router_1.default();
+    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');
+    backEndFiles.forEach((file) => {
+        const serverRoutes = require(path_1.default.resolve(file));
+        console.log('Found component backend file: ' + path_1.default.resolve(file));
+        if (serverRoutes && serverRoutes.default) {
+            router.use(serverRoutes.default);
+        }
+    });
+    app.use(router.routes()).use(router.allowedMethods());
+    if (mode === 'production') {
+        console.log('Starting flight in production mode');
+        if (!argv.disable_vite) {
+            (0, child_process_1.exec)('npx vite build', (error, stdout, stderr) => {
+                if (error) {
+                    console.error(`exec error: ${error}`);
+                    return;
+                }
+                console.log(`stdout: ${stdout}`);
+                console.error(`stderr: ${stderr}`);
+            });
+        }
+        app.use((0, koa_compress_1.default)());
+        app.use((0, koa_ratelimit_1.default)({
+            driver: 'redis',
+            db: redis,
+            duration: 60000,
+            errorMessage: 'Sometimes You Just Have to Slow Down.',
+            id: (ctx) => ctx.get('x-forwarded-for') || ctx.ip,
+            headers: {
+                remaining: 'Rate-Limit-Remaining',
+                reset: 'Rate-Limit-Reset',
+                total: 'Rate-Limit-Total'
+            },
+            max: 1200,
+            disableHeader: false
+        }));
+        app.use((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 (!argv.disable_vite) {
+            console.log(`App served out of dist/ and available on port ${argv.port}`);
+        }
+        else {
+            console.log(`App served out of ${appHomePath} and available on port ${argv.port}`);
+        }
+    }
+    app.listen(argv.port, () => {
+        console.log(`Server worker ${process.pid} started, All backend services are running on port ${argv.port}`);
+    });
+    if (mode === 'development') {
+        console.log('Starting flight in development mode');
+        const viteProcess = (0, child_process_1.spawn)('npx', ['vite', '--port', '3001', '--host', '0.0.0.0'], {
+            stdio: 'inherit',
+            shell: true
+        });
+        viteProcess.on('error', (error) => {
+            console.error('Failed to start vite server:', error);
+        });
+        viteProcess.on('exit', (code) => {
+            if (code !== 0) {
+                console.error(`Vite 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`);
+    }
+}

package/eslint.config.mjs

@@ -0,0 +1,32 @@
+import jsdoc from 'eslint-plugin-jsdoc'
+import tsParser from '@typescript-eslint/parser'
+
+export default [
+    {
+        files: ['**/*.js'],
+        plugins: {
+            jsdoc: jsdoc
+        },
+        rules: {
+            'jsdoc/require-description': 'error',
+            'jsdoc/check-values': 'error'
+        }
+    },
+    {
+        files: ['**/*.ts'],
+        languageOptions: {
+            parser: tsParser,
+            parserOptions: {
+                ecmaVersion: 'latest',
+                sourceType: 'module'
+            }
+        },
+        plugins: {
+            jsdoc: jsdoc
+        },
+        rules: {
+            'jsdoc/require-description': 'error',
+            'jsdoc/check-values': 'error'
+        }
+    }
+]

package/package.json

@@ -0,0 +1,75 @@
+{
+    "name": "@thoughtpivot/flight",
+    "version": "1.0.7",
+    "description": "A web server designed for running full stack, component based applications at enterprise scale.",
+    "main": "src/flight.ts",
+    "publishConfig": {
+        "access": "public"
+    },
+    "bin": {
+        "flight": "dist/flight.js"
+    },
+    "scripts": {
+        "lint": "eslint . --fix && prettier -w .",
+        "build": "rm -rf dist; node_modules/.bin/tsc --project .",
+        "test": "echo \"Error: no test specified\" && exit 0"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/thoughtpivot/flight.git"
+    },
+    "author": "",
+    "license": "MIT",
+    "bugs": {
+        "url": "https://github.com/thoughtpivot/flight/issues"
+    },
+    "homepage": "https://github.com/thoughtpivot/flight#readme",
+    "dependencies": {
+        "@koa/cors": "^5.0.0",
+        "@koa/router": "^13.1.0",
+        "@vitejs/plugin-vue": "^5.2.1",
+        "@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",
+        "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-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",
+        "yargs": "^18.0.0"
+    },
+    "devDependencies": {
+        "@types/koa": "^2.15.0",
+        "@types/koa__cors": "^5.0.0",
+        "@types/koa__router": "^12.0.4",
+        "@types/koa-bodyparser": "^4.3.12",
+        "@types/koa-compress": "^4.0.6",
+        "@types/koa-logger": "^3.1.5",
+        "@types/koa-ratelimit": "^5.0.5",
+        "@types/koa-redis": "^4.0.5",
+        "@types/koa-redis-cache": "^3.0.4",
+        "@types/koa-session": "^6.4.5",
+        "@types/koa-static": "^4.0.4",
+        "@types/node": "^22.19.17",
+        "@typescript-eslint/parser": "^8.59.1",
+        "eslint": "^9.39.4",
+        "eslint-plugin-jsdoc": "^50.8.0",
+        "eslint-plugin-vue": "^9.33.0",
+        "prettier": "^3.8.3",
+        "ts-node": "^10.9.2",
+        "typescript": "^5.9.3"
+    }
+}

package/src/flight.ts

@@ -0,0 +1,226 @@
+#!ts-node
+
+import { exec, spawn } from 'child_process'
+
+import Koa from 'koa'
+import Redis from 'ioredis'
+import RedisStore from 'koa-redis'
+import Router from '@koa/router'
+import bodyParser from 'koa-bodyparser'
+import cluster from 'cluster'
+import compress from 'koa-compress'
+import cors from '@koa/cors'
+import fg from 'fast-glob'
+import koaCash from 'koa-cash'
+import logger from 'koa-logger'
+import os from 'os'
+import path from 'path'
+import ratelimit from 'koa-ratelimit'
+import serve from 'koa-static'
+import session from 'koa-session'
+
+const argv = require('yargs/yargs')(process.argv.slice(2)).argv
+
+// 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
+argv.session_duration = Number(process.env.FLIGHT_SESSION_DURATION_MS) || argv.session_duration
+
+// Validate session duration
+if (isNaN(argv.session_duration) || argv.session_duration < 0) {
+    console.error('Invalid session duration specified. Using default of 24 hours (86400000ms).')
+    argv.session_duration = DEFAULT_SESSION_DURATION
+}
+
+if (!argv.app_home) {
+    argv.app_home = '.'
+}
+
+if (!argv.app_key) {
+    argv.app_key = 'flightApp'
+}
+
+if (!argv.app_secret) {
+    argv.app_secret = 'the best secret key in the world'
+}
+
+// Set default port values
+if (!argv.port) {
+    // Check for environment variable first, then use default
+    argv.port = process.env.FLIGHT_PORT || 3000
+}
+
+if (!argv.payload_limit) {
+    argv.payload_limit = process.env.FLIGHT_PAYLOAD_LIMIT || '1mb'
+}
+
+// Convert port to number
+argv.port = Number(argv.port)
+
+// Validate port is a valid number
+if (isNaN(argv.port) || argv.port < 1 || argv.port > 65535) {
+    console.error('Invalid port specified. Using default port 3000.')
+    argv.port = 3000
+}
+
+// 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
+}
+
+// Ensure the value is a boolean
+argv.disable_vite = Boolean(argv.disable_vite)
+
+const appHomePath = path.resolve(argv.app_home)
+process.chdir(appHomePath)
+
+console.log(appHomePath)
+
+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}):`
+const origConsoleLog = console.log.bind(console)
+console.log = (first?: unknown, ...rest: unknown[]): void => {
+    if (typeof first === 'string' && /%[sdjifoO%]/.test(first)) {
+        origConsoleLog(`${flightModeLabel} ${first}`, ...rest)
+    } else if (first !== undefined) {
+        origConsoleLog(flightModeLabel, first, ...rest)
+    } else {
+        origConsoleLog(flightModeLabel)
+    }
+}
+
+const redis = new Redis({
+    host: process.env.FLIGHT_REDIS_HOST || 'localhost',
+    port: Number(process.env.FLIGHT_REDIS_PORT) || 6379
+})
+
+if (cluster.isPrimary) {
+    const numCPUs = os.cpus().length
+    const maxWorkers = Number(process.env.FLIGHT_MAX_WORKERS) || numCPUs
+    const workersCount = Math.min(maxWorkers, numCPUs)
+
+    for (let i = 0; i < workersCount; i++) {
+        cluster.fork()
+    }
+
+    cluster.on('exit', () => {
+        cluster.fork()
+    })
+} else {
+    const app = new Koa()
+    app.use(logger())
+
+    app.keys = argv.app_secret.split(',')
+
+    const SESSION_CONFIG = {
+        key: argv.app_key,
+        maxAge: argv.session_duration,
+        sameSite: true,
+        path: '/',
+        store: RedisStore({
+            client: redis
+        })
+    }
+
+    app.use(session(SESSION_CONFIG, app))
+
+    const router = new Router()
+
+    app.use(cors()).use(
+        bodyParser({
+            jsonLimit: argv.payload_limit
+        })
+    )
+
+    const backEndFiles = fg.sync('**/*.backend.ts')
+    backEndFiles.forEach((file) => {
+        const serverRoutes = require(path.resolve(file))
+
+        console.log('Found component backend file: ' + path.resolve(file))
+
+        if (serverRoutes && serverRoutes.default) {
+            router.use(serverRoutes.default)
+        }
+    })
+
+    app.use(router.routes()).use(router.allowedMethods())
+
+    if (mode === 'production') {
+        console.log('Starting flight in production mode')
+
+        if (!argv.disable_vite) {
+            exec('npx vite build', (error, stdout, stderr) => {
+                if (error) {
+                    console.error(`exec error: ${error}`)
+                    return
+                }
+                console.log(`stdout: ${stdout}`)
+                console.error(`stderr: ${stderr}`)
+            })
+        }
+
+        app.use(compress())
+        app.use(
+            ratelimit({
+                driver: 'redis',
+                db: redis,
+                duration: 60000,
+                errorMessage: 'Sometimes You Just Have to Slow Down.',
+                id: (ctx) => ctx.get('x-forwarded-for') || ctx.ip,
+                headers: {
+                    remaining: 'Rate-Limit-Remaining',
+                    reset: 'Rate-Limit-Reset',
+                    total: 'Rate-Limit-Total'
+                },
+                max: 1200,
+                disableHeader: false
+            })
+        )
+        app.use(
+            koaCash({
+                get: (key) => redis.get(key),
+                set: (key, value) => redis.set(key, value, 'EX', 30)
+            })
+        )
+        app.use(serve(process.env.FLIGHT_DIST_PATH || '../dist'))
+
+        if (!argv.disable_vite) {
+            console.log(`App served out of dist/ and available on port ${argv.port}`)
+        } else {
+            console.log(`App served out of ${appHomePath} and available on port ${argv.port}`)
+        }
+    }
+
+    app.listen(argv.port, () => {
+        console.log(`Server worker ${process.pid} started, All backend services are running on port ${argv.port}`)
+    })
+
+    if (mode === 'development') {
+        console.log('Starting flight in development mode')
+        const viteProcess = spawn('npx', ['vite', '--port', '3001', '--host', '0.0.0.0'], {
+            stdio: 'inherit',
+            shell: true
+        })
+
+        viteProcess.on('error', (error) => {
+            console.error('Failed to start vite server:', error)
+        })
+
+        viteProcess.on('exit', (code) => {
+            if (code !== 0) {
+                console.error(`Vite 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`)
+    }
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+    "compilerOptions": {
+        "target": "ESNext",
+        "module": "NodeNext",
+        "experimentalDecorators": true,
+        "emitDecoratorMetadata": true,
+        "moduleResolution": "NodeNext",
+        "outDir": "dist"
+    }
+}