@aravinthan_p/appnest-engine 1.0.12 → 1.0.13

package/README.md

@@ -0,0 +1,145 @@
+# Appnest Engine
+
+Development CLI and runtime for Appnest apps. It wires your **app-backend**, **app-frontend**, and optional **app-installation-frontend** behind a single proxy, runs checks, and helps you bundle and zip the app for distribution.
+
+---
+
+## Overview
+
+Appnest Engine runs in the **developer’s project directory** (where `app-backend`, `app-frontend`, etc. live). It provides:
+
+- **CLI** – Commands for setup, precheck, install, run, lint, bundle, and zip.
+- **Proxy** – One server on port **3000** that routes traffic to your app’s backend and frontends.
+- **Engine packages** – Shared runtime pieces (proxy, backend layer, frontend dev servers) that load your app code from the current directory.
+
+---
+
+## Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│  Developer runs:  appnest-engine run run-all                             │
+│  (from their app project directory: app-backend, app-frontend, etc.)      │
+└─────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│  CLI (cli.js)                                                            │
+│  • Parses "run run-all" → appnestAction("run-all")                        │
+│  • runtimeUtils.runApp() starts only: appnest-proxy                       │
+└─────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│  appnest-proxy (port 3000)                                               │
+│  • Reads .env from ORIGINAL_CWD (developer’s project)                    │
+│  • Allocates ports for app-backend, app-frontend, app-installation-*     │
+│  • Starts appnest-backend (loads user’s app-backend/server.js)            │
+│  • Starts appnest-frontend (Vite dev server for app-frontend)             │
+│  • Starts appnest-installation-frontend if folder exists                  │
+│  • Proxies:                                                              │
+│      /app-backend/*  → app-backend                                        │
+│      /app-frontend/* → app-frontend                                       │
+│      /app-installation-frontend/* → app-installation-frontend             │
+│  • Watches app-backend / app-frontend and restarts on change (backend)    │
+│    or on config change (frontends); HMR for normal frontend edits         │
+└─────────────────────────────────────────────────────────────────────────┘
+                                      │
+          ┌───────────────────────────┼───────────────────────────┐
+          ▼                           ▼                           ▼
+┌──────────────────┐    ┌────────────────────┐    ┌────────────────────────────┐
+│ appnest-backend   │    │ appnest-frontend    │    │ appnest-installation-       │
+│ (Express layer)   │    │ (Vite dev server)  │    │ frontend (Vite dev server)  │
+│ Loads user’s      │    │ Serves user’s      │    │ Serves user’s               │
+│ app-backend/      │    │ app-frontend/       │    │ app-installation-frontend/  │
+│ server.js         │    │                    │    │                             │
+└──────────────────┘    └────────────────────┘    └────────────────────────────┘
+```
+
+- **User directory** = where the developer runs the CLI (`process.cwd()` → `ORIGINAL_CWD` for child processes).
+- **Engine packages** = `appnest-backend`, `appnest-frontend`, `appnest-installation-frontend`, `appnest-proxy` (inside this repo). They are the runtime that loads and serves the **app** folders from the user directory.
+
+---
+
+## Project structure
+
+| Path | Role |
+|------|------|
+| `cli.js` | Entry point for `appnest-engine` CLI; uses Commander, delegates to `appnest-command-line`. |
+| `index.js` | Exports `appnestAction` for programmatic use. |
+| `package.json` | Root package; `bin.appnest-engine` → `cli.js`; version is read by CLI. |
+| **appnest-command-line/** | Implements all CLI actions (setup, precheck, install, run, lint, bundle, zip). |
+| **appnest-proxy/** | Express server on port 3000; env from user `.env`; starts backend + frontends; proxies and file watching. |
+| **appnest-backend/** | Express app that loads the user’s `app-backend/server.js` and exposes it under `/app-backend`. |
+| **appnest-frontend/** | Vite dev server for the user’s `app-frontend`. |
+| **appnest-installation-frontend/** | Vite dev server for the user’s `app-installation-frontend` (optional). |
+
+The developer’s project (user directory) is expected to have:
+
+- `app-backend/` (e.g. `server.js`)
+- `app-frontend/` (e.g. Vite/React app)
+- Optional: `app-installation-frontend/`
+- `.env` (read by the proxy for ports, `CLIENT_SCRIPT_URL`, `PROXY_DEBUG_LOGS`, etc.)
+
+---
+
+## Installation
+
+```bash
+cd appnest-engine
+npm install
+```
+
+If this repo uses **npm workspaces**, a single `npm install` at the root also installs dependencies for `appnest-backend`, `appnest-frontend`, `appnest-installation-frontend`, and `appnest-proxy`.
+
+---
+
+## CLI usage
+
+From the **appnest-engine** directory, or with the `appnest-engine` binary on `PATH`:
+
+| Command | Description |
+|---------|-------------|
+| `appnest-engine --version` | Print version (from root `package.json`). |
+| `appnest-engine run setup-app` | Download appnest-basecode from GitHub and extract into current directory (`app-backend`, `app-frontend`, etc.). |
+| `appnest-engine run precheck` | Check Node.js (≥22), ngrok, and that engine + app paths exist. |
+| `appnest-engine run install-packages` | Run `npm install` in engine packages (appnest-backend, -frontend, -installation-frontend, -proxy). |
+| `appnest-engine run run-all` | Start **appnest-proxy** only; the proxy then starts backend + frontends and proxies traffic. |
+| `appnest-engine run zip-app` | Bundle frontends, then zip `app-frontend`, `app-backend`, `app-installation-frontend` into `appnest-app-pack/`. |
+| `appnest-engine run lint` | Lint `app-backend` and `app-frontend` (and fix manifest checks). |
+| `appnest-engine run lint-fix` | Same as lint with auto-fix where possible. |
+| `appnest-engine help` | Show help. |
+
+**Typical developer flow:**
+
+1. In the **app project** directory: `appnest-engine run setup-app` (if not already set up).
+2. `appnest-engine run precheck` (optional).
+3. From **appnest-engine** (or with global/linked binary): `appnest-engine run install-packages`.
+4. From the **app project** directory: `appnest-engine run run-all` → proxy on port 3000, app at e.g. `http://localhost:3000/app-frontend/`, API at `http://localhost:3000/app-backend/`.
+
+---
+
+## Runtime flow (when `run-all` is used)
+
+1. **CLI** runs `runApp()`, which starts **appnest-proxy** with `ORIGINAL_CWD` set to the current working directory.
+2. **Proxy** reads `.env` from `ORIGINAL_CWD`, allocates ports for backend and frontends, then:
+   - Starts **appnest-backend** (which loads the user’s `app-backend/server.js`).
+   - Starts **appnest-frontend** (Vite for `app-frontend`).
+   - If `app-installation-frontend` exists, starts **appnest-installation-frontend**.
+3. Proxy mounts:
+   - `/app-backend` → app-backend
+   - `/app-frontend` → app-frontend
+   - `/app-installation-frontend` → app-installation-frontend
+4. **File watching**: Changes in `app-backend` restart the backend; changes in `app-frontend` / `app-installation-frontend` trigger restart only for config (e.g. `vite.config.js`, `.env`); other frontend changes use Vite HMR.
+
+---
+
+## Zip / bundle flow
+
+- **`run zip-app`** runs **bundle-frontend** first (builds appnest-frontend and appnest-installation-frontend), then zips the **user’s** `app-frontend`, `app-backend`, and `app-installation-frontend` into **appnest-app-pack** (and updates paths in `app-frontend/dist/index.html` as needed). Use this to produce a single pack for deployment or distribution.
+
+---
+
+## License
+
+ISC

package/appnest-proxy/server.js

@@ -7,7 +7,6 @@ const chokidar = require('chokidar');
 const fs = require('fs');
 
 const app = express();
-const PROXY_PORT = 3000;
 
 console.log('📂 User Directory from appnest-proxy', process.env.ORIGINAL_CWD);
 
@@ -177,6 +176,8 @@ const startAppServers = () => {
 async function startServers() {
   appInjectedEnv = getAppEnv();
   console.log('📂 App Injected Environment Variables:', appInjectedEnv);
+  const PROXY_PORT = appInjectedEnv.APPNEST_ENGINE_PORT || 3000;
+  console.log('📂 Proxy Port:', PROXY_PORT);
   await allocateAndVerifyAppUniquePorts();
   startAppServers();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aravinthan_p/appnest-engine",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "main": "index.js",
   "keywords": [],
   "bin": {