@sava-info-systems/api-maker-engine 0.0.0-stage → 4.0.0-beta.7

package/README.md

@@ -1,3 +1,313 @@
-# Temporary Holding Version
+<div align="center">
+  <a href="https://apimaker.dev">
+    <img width="220" src="https://apimaker.dev/assets/images/logo.svg" alt="API Maker"/>
+  </a>
+</div>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">API Maker® v4</h1>
+
+<h3 align="center">The backend engine for the AI era</h3>
+
+<p align="center">
+  AI writes the logic. API Maker builds, guards and runs the rest.<br/>
+  <sub>A self-hosted backend engine: one self-contained program, written in Rust.</sub>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@sava-info-systems/api-maker-engine"><img src="https://img.shields.io/npm/v/%40sava-info-systems%2Fapi-maker-engine?style=flat-square&label=npm&color=0C53A4" alt="npm version"/></a>
+  <img src="https://img.shields.io/badge/engine-Rust-DEA584?style=flat-square&logo=rust&logoColor=black" alt="Engine written in Rust"/>
+  <img src="https://img.shields.io/badge/Linux-x64%20%7C%20arm64-2FB36A?style=flat-square&logo=linux&logoColor=white" alt="Linux x64 and arm64"/>
+  <img src="https://img.shields.io/badge/macOS-Apple%20silicon%20%7C%20Intel-2FB36A?style=flat-square&logo=apple&logoColor=white" alt="macOS Apple silicon and Intel"/>
+  <img src="https://img.shields.io/badge/Windows-x64-2FB36A?style=flat-square&logo=windows&logoColor=white" alt="Windows x64"/>
+  <img src="https://img.shields.io/badge/databases-8-2FB36A?style=flat-square" alt="8 database types"/>
+  <img src="https://img.shields.io/badge/license-proprietary-64748b?style=flat-square" alt="Proprietary license"/>
+</p>
+
+<p align="center">
+  <a href="#-install"><b>Install</b></a> ·
+  <a href="#-upgrade"><b>Upgrade</b></a> ·
+  <a href="https://docs.apimaker.dev/v4/docs/getting-started/first-api.html"><b>First API</b></a> ·
+  <a href="https://docs.apimaker.dev"><b>Documentation</b></a> ·
+  <a href="https://apimaker.dev/features"><b>Features</b></a> ·
+  <a href="https://apimaker.dev"><b>Website</b></a>
+</p>
+
+<hr/>
+
+API Maker connects to your databases and gives every table secure REST APIs at once. You add your own logic in TypeScript — custom APIs, pre and post hooks, schedulers and events — and run it all from one admin panel, on your own servers. Caching, access control, logging, monitoring and Git deployment are built in.
+
+> **New in v4** — API Maker is now **one program written in Rust**. A single process serves the APIs, the WebSockets **and** the admin panel on every core of the machine. Nothing of Node.js is installed on a server, and the code of your accounts runs in sandboxes with a native agent for each of its eight languages.
+
+<div align="center">
+<table>
+  <tr>
+    <td align="center"><b>~30</b><br/>APIs for each table</td>
+    <td align="center"><b>8</b><br/>database types</td>
+    <td align="center"><b>8</b><br/>languages for your code</td>
+    <td align="center"><b>1</b><br/>program to run</td>
+  </tr>
+</table>
+</div>
+
+Nobody wrote an endpoint for this call. The table was there, so the API is there:
+
+```http
+GET /api/gen/admin/shop/main/products?find={stock:{$gt:0}}&sort=-price&limit=10&select=name,price
+x-am-authorization: <API user token>
+```
+
+```json
+{
+    "success": true,
+    "statusCode": 200,
+    "data": [
+        { "_id": "66f1c3…", "name": "Keyboard", "price": 49 },
+        { "_id": "66f1c2…", "name": "Mouse", "price": 19 }
+    ]
+}
+```
+
+`admin` is the API path of your account, `shop` the instance, `main` the database and `products` the table. Every API answers in this shape.
+
+## 🚀 Install
+
+Pick the way that fits. Each one installs the build for **your operating system and processor** on its own.
+
+| | Where | Command |
+|---|---|---|
+| 🖥️ **Server** | A fresh Ubuntu server (x64 or arm64) | `curl -fsSL https://apimaker.dev/v4/install.sh -o install.sh && bash install.sh --license_key=YOUR_KEY` |
+| 📦 **npm** | Any Linux or macOS machine, Windows x64 | `npm install -g @sava-info-systems/api-maker-engine` |
+| 🗜️ **Archive** | A server without internet access | `bash install.sh --package=api-maker-<version>-linux-<arch>.tar.gz` |
+
+### 🖥️ On a server — the install script
+
+Run it as **root on a fresh Ubuntu server**, with your license key at the end:
+
+```sh
+curl -fsSL https://apimaker.dev/v4/install.sh -o install.sh && \
+  bash install.sh --version=latest --license_key=YOUR_KEY
+```
+
+It reads the processor of the server, downloads the matching release and checks it before anything changes. Then it installs everything around API Maker:
+
+- **API Maker** itself, run by systemd as the service `api_maker_be` — the APIs, the WebSockets and the admin panel.
+- **Docker** for the sandboxes, with **MongoDB** and **Redis** as containers.
+- **Caddy** in front, with HTTPS certificates from Let's Encrypt that renew on their own.
+
+It ends with the admin panel URL, the API and WebSocket URLs, and the commands to start, stop and watch API Maker. Run it again to upgrade, to change a setting or to repair an installation: a version that does not start is rolled back on its own.
+
+<details>
+<summary><b>What the server needs, and the flags of the installer</b></summary>
+
+**The server**
+
+- Ubuntu 22.04, 24.04 or 26.04, the root user, and a CPU with AVX (MongoDB needs it).
+- x86-64 or ARM64, at least 1 CPU core, 1 GB of RAM (the installer adds swap) and 20 GB of storage.
+
+**The flags** — every question has one, so the installer can run without questions too:
+
+| Flag | What it does |
+|---|---|
+| `--license_key=YOUR_KEY` | Your license key, written to `license.txt` and bound to the server. |
+| `--version=latest` | The version to install, or an exact one like `--version=4.0.0`. |
+| `--package=<file or URL>` | Install from a release archive (`.tar.gz`) or an npm `.tgz` instead of downloading. |
+| `--default` | Keep the default ports and names, ask only a few questions. |
+| `--primary` · `--secondary` | The first server of an installation, or one more server attached to it. |
+| `--caddy=yes\|no` · `--ssl=yes\|no` | Caddy in front of API Maker, and HTTPS with `--api_domain`, `--ws_domain`, `--panel_domain`. |
+| `--mongoVersion=8.0.10` | The MongoDB image to run. |
+
+Secrets and connection strings are never flags: the variables `AM_PASS_COMMUNICATION`, `AM_PASS_JWT`, `AM_PASS_DB_ENCRYPT_DECRYPT`, `AM_MONGO_CONNECTION`, `AM_REDIS_INTERNAL` and `AM_REDIS_EXTERNAL` answer those questions.
+
+**Note for AWS users**
+
+```sh
+chmod 400 ~/Desktop/aws_server.pem                     # avoid a permission error
+ssh -i ~/Desktop/aws_server.pem ubuntu@__server_ip__   # sign in to the server
+sudo -s                                                # become root, then run the installer
+```
+
+The whole guide: [Install on a server](https://docs.apimaker.dev/v4/docs/getting-started/install-on-server.html).
+
+</details>
+
+### 📦 With npm — Linux, macOS and Windows
+
+```sh
+npm install -g @sava-info-systems/api-maker-engine
+```
+
+npm reads your system and processor and downloads only the build that runs on your machine:
+
+| Your machine | What npm installs |
+|---|---|
+| Linux x64 | `@sava-info-systems/api-maker-engine-linux-x64` |
+| Linux arm64 (Graviton, Ampere, Raspberry Pi 5…) | `@sava-info-systems/api-maker-engine-linux-arm64` |
+| macOS Apple silicon (M1 and newer) | `@sava-info-systems/api-maker-engine-darwin-arm64` + `@sava-info-systems/api-maker-engine-sandbox-linux-arm64`, the agents of its sandboxes |
+| macOS Intel | `@sava-info-systems/api-maker-engine-darwin-x64` + `@sava-info-systems/api-maker-engine-sandbox-linux-x64`, the agents of its sandboxes |
+| Windows x64 (10, 11, Server 2016 and newer) | `@sava-info-systems/api-maker-engine-win32-x64` + `@sava-info-systems/api-maker-engine-sandbox-linux-x64`, the agents of its sandboxes, which run in [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/) |
+| Windows on Arm | Run the Linux build inside [WSL 2](https://learn.microsoft.com/windows/wsl/install) |
+
+The sandboxes of a Mac and of Windows are Linux containers: their package holds only what runs inside them (the
+`am_agent` launcher and the agent libraries), never the Linux server or its admin panel.
+
+Then, in the folder your installation lives in:
+
+```sh
+mkdir my-api-maker && cd my-api-maker
+
+api-maker init --license_key=YOUR_KEY --docker   # .env with new secrets, license.txt, MongoDB + Redis in Docker
+api-maker                                         # start API Maker
+```
+
+Open the admin panel at **http://localhost:4626**. The APIs and the WebSockets answer on **http://localhost:48246**.
+
+<details>
+<summary><b>The <code>api-maker</code> command</b></summary>
+
+| Command | What it does |
+|---|---|
+| `api-maker` | Starts API Maker in the current folder: `.env`, `license.txt` and `uploads/` are read and written there. Every option of the server works: `api-maker --am.port=5000`. |
+| `api-maker init` | Writes a `.env` with new secrets for a local MongoDB and Redis. `--license_key=KEY` writes `license.txt`, `--docker` starts MongoDB (a replica set) and Redis in Docker, `--mongo_port` and `--redis_port` choose their ports, `--force` replaces an existing `.env`. |
+| `api-maker info` | Shows the version, the platform, and the files API Maker runs from. |
+| `api-maker --version` | Prints the version of the server. |
+| `api-maker help` | Shows this help and the options of the server. |
+
+Without `--docker`, point `.env` at your own MongoDB (it has to be a replica set: a Git pull is one transaction) and Redis.
+
+</details>
+
+### 🗜️ From an archive — no internet needed
+
+Every release has one archive per processor for Linux servers: `api-maker-<version>-linux-x64.tar.gz` and `api-maker-<version>-linux-arm64.tar.gz`, each with its `.sha256`. Copy it to the server and give it to the installer:
+
+```sh
+bash install.sh --package=api-maker-4.0.0-linux-x64.tar.gz --license_key=YOUR_KEY
+```
+
+For Windows, `api-maker-<version>-win32-x64.zip` holds the server (`api_maker_be.exe`), the agents for code that runs on Windows itself, and the admin panel: unzip it and start `api_maker_be.exe` in the folder of your installation.
+
+### 👤 First sign-in
+
+```text
+admin@admin.com | Admin_123456789
+root@root.com   | R00t_123456789
+```
+
+Change both passwords right after the first sign-in: the root user in **Root Settings**, the admin user in its profile. The admin account comes with a sample shop to read: an instance, schemas, custom APIs and hooks.
+
+### 🔑 License key
+
+API Maker needs a license key. Write to [contact@apimaker.dev](mailto:contact@apimaker.dev) for one. The key is the first line of `license.txt` in the folder API Maker runs in; the installer and `api-maker init --license_key=…` write it for you.
+
+## ⬆️ Upgrade
+
+| Installed with | Upgrade with |
+|---|---|
+| The install script | Run it again: `bash install.sh --version=latest` (or `--version=4.0.1`). |
+| The install script, from the admin panel | **Deploy API Maker**: pick a version, or upload the release `.tar.gz`. Every server of the installation takes it, checks it and restarts, with a roll-back when the new version does not answer. |
+| An archive, offline | `bash install.sh --package=api-maker-<version>-linux-<arch>.tar.gz` |
+| npm | `npm install -g @sava-info-systems/api-maker-engine@latest` |
+
+Each version keeps its own folder on a server (`~/projects/api_maker/releases/<version>`, the last three are kept), so going back is instant.
+
+## 📦 What's inside
+
+Every platform package is a complete API Maker: the server, the agents of its sandboxes, and the admin panel.
+
+| File | What it is |
+|---|---|
+| `api_maker_be` | The server: the APIs, the WebSockets and the admin panel, in one program (`api_maker_be.exe` on Windows). |
+| `admin-panel/` | The admin panel, served by the server itself on `am__adminPanel__port` (4626). |
+| `am_agent` | The program of the sandboxes, copied into every sandbox image. |
+| `am_agent.node` | The agent of **Node.js** and **Bun** code — a Node-API addon. |
+| `am_agent.abi3.so` | The agent of **Python** code — an extension module, for every Python 3.9+. |
+| `libam_agent_jni.so` | The agent of **Java** and **Kotlin** code — a JVM library. |
+| `libam_agent.so` | The agent of **.NET, Go, Rust and PHP** code — a C library. |
+| `libam_*.dylib` | On macOS: the same agents for code that runs on the Mac itself (`runOnNativeProcess`). |
+| `am_*.dll` | On Windows: the same agents for code that runs on Windows itself (`runOnNativeProcess`). |
+
+The agents are release builds of the same sources as the server. Code of an account calls `g.sys.db.getAll(...)` and the agent inside its sandbox reads the database itself — no round trip to the server. The server only takes agents built from its own sources, so a release always runs with the agents it was built with.
+
+## ⚙️ Configuration
+
+API Maker reads its settings from `.env` in the folder it runs in (or `--envPath=<file>`), then from the environment and the command line. A setting is its path in the `am` block, with `__` between the names.
+
+| Setting | What it is |
+|---|---|
+| `BE_HOST_PORT` | Where browsers reach the APIs: `http://__ip_address__:48246` or `https://api.example.com`. |
+| `am__port` | The port of the APIs and the WebSockets. |
+| `am__adminPanel__port` · `am__adminPanel__folder` | The admin panel: its port, and the folder it is served from. |
+| `am__mongo_db_connection` | The MongoDB API Maker keeps its own data in (a replica set). |
+| `am__redisInternal` | The Redis of the processes of the installation: `{"nodes": [{port:6379, host:"127.0.0.1", pass: ""}]}` |
+| `am__passCommunication` · `am__passJWT` · `am__passDBEncryptDecrypt` | Three secrets of your own (`passDBEncryptDecrypt`: 32 characters). |
+
+Every setting: [API Maker configurations](https://docs.apimaker.dev/v4/docs/am-resources/api-maker-configurations.html).
+
+## ✨ Everything in the box
+
+| Category | Features |
+|---|---|
+| **Database APIs** | [Auto Generated APIs](https://apimaker.dev/auto-generated-apis-from-database) · [Schema & Validation](https://apimaker.dev/schema-validation) · [Deep Populate](https://apimaker.dev/deep-populate) · [Find and Join](https://apimaker.dev/find-and-join) · [Master Save](https://apimaker.dev/master-save) · [Multi-Tenant](https://apimaker.dev/multi-tenant) · [JSON, XML & YAML Output](https://apimaker.dev/get-output) |
+| **Your code** | [Custom APIs](https://apimaker.dev/custom-api) · [Pre & Post Hooks](https://apimaker.dev/hooks) · [Utility Classes](https://apimaker.dev/utility-classes) · [System APIs](https://apimaker.dev/inbuilt-system) · [Schedulers](https://apimaker.dev/schedule) · [Events & Listeners](https://apimaker.dev/events-management) · [WebSockets](https://apimaker.dev/websockets) · [Internationalization](https://apimaker.dev/internationalization) |
+| **Security** | [Access Management](https://apimaker.dev/access-management) · [APIs Security Report & Actions](https://apimaker.dev/api-security-report) · [Single Sign-On](https://apimaker.dev/single-sign) · [Secrets Management](https://apimaker.dev/secrets-management) · [Secure Sandbox](https://apimaker.dev/secure-sandbox) · [Security Features](https://apimaker.dev/security) |
+| **Performance** | [Automatic Caching](https://apimaker.dev/automatic-caching) · [Low Memory Footprint](https://apimaker.dev/low-memory-footprint) · [Index Maker](https://apimaker.dev/index-maker) |
+| **Team & delivery** | [Git Deployment](https://apimaker.dev/git-deployment) · [Developer Accounts](https://apimaker.dev/developer-accounts) · [Database Migrations](https://apimaker.dev/database-migrations) · [Testing Framework](https://apimaker.dev/inbuilt-testing) · [Developer Tools](https://apimaker.dev/developer-tools) |
+| **Operations** | [API Logging](https://apimaker.dev/logging-api) · [Monitoring](https://apimaker.dev/monitoring) · [Deploy API Maker from the panel](https://docs.apimaker.dev/v4/docs/features/deploy-api-maker.html) |
+
+**Databases**: MongoDB · MySQL · MariaDB · PostgreSQL · SQL Server · Oracle · TiDB · Percona XtraDB — in one account at the same time, with queries and joins across them.
+
+**Languages of your code**: TypeScript and JavaScript (Node.js, Bun) · Python · Java · Kotlin · C# (.NET) · Go · Rust · PHP.
+
+## 🤖 Built for the AI era
+
+An AI assistant writes code in seconds. On a traditional backend, all of that code is still yours to review, secure, test and scale. On API Maker, the assistant writes only the business logic, and the framework generates, checks and runs everything around it.
+
+- **Every item is a file.** The local client keeps your account in sync with a Git repository: custom APIs, hooks, schemas, schedulers, tests and settings are plain files any assistant can edit.
+- **Types come with the code.** `import * as T from 'types'` gives every interface of API Maker, `import * as db from 'db-interfaces'` the interfaces of your own tables.
+- **Tests run from the terminal.** `npm run test` runs the test cases of the account and writes the coverage.
+- **Documentation an assistant can read**: [docs.apimaker.dev/llms.txt](https://docs.apimaker.dev/llms.txt), and every page as Markdown.
+
+```ts
+import * as T from 'types';
+import * as db from 'db-interfaces';
+
+async function main(g: T.IAMGlobal) {
+    const products = await g.sys.db.getAll<db.shop.main.IProducts>({
+        instance: 'shop', database: 'main', collection: 'products',
+    });
+    return products.map(p => p.name); // p is typed
+}
+module.exports = main;
+```
+
+Save it, and the custom API is live: no build, no deployment.
+
+## 🔐 Security, enforced by the framework
+
+| Layer | What API Maker does |
+|---|---|
+| **Tokens by default** | Every API needs a token unless you make it public. No valid token: 401. No group that grants the call: 403, before anything runs. |
+| **Access down to the field** | Groups decide the instances, databases, tables, APIs and fields of every user. |
+| **Validated writes** | Schema APIs convert and validate every write; fields can be stored encrypted or hashed. |
+| **Your code in a sandbox** | Custom code runs in Docker containers, apart from API Maker, with a time and a memory limit. |
+| **An encrypted admin panel** | Every request of the panel travels inside an encrypted channel (ECDH P-256, AES-256-GCM), on top of HTTP or HTTPS. |
+| **A security report** | API Maker reads your groups, users and hooks and shows where a person could read rows that are not theirs — with a fix in one click for many findings. |
+
+## 🔗 Resources
+
+- [Documentation](https://docs.apimaker.dev) · [Your first API](https://docs.apimaker.dev/v4/docs/getting-started/first-api.html) · [How it works](https://docs.apimaker.dev/v4/docs/getting-started/how-it-works.html) · [Cheat sheet](https://docs.apimaker.dev/v4/docs/cheat-sheet.html)
+- [Install on a server](https://docs.apimaker.dev/v4/docs/getting-started/install-on-server.html) · [Deploy API Maker from the panel](https://docs.apimaker.dev/v4/docs/features/deploy-api-maker.html)
+- [Release notes](https://docs.apimaker.dev/v4/docs/blog/release-notes/release_notes_summary.html) · [FAQ](https://apimaker.dev/faq)
+- [Video tutorials on YouTube](https://www.youtube.com/@api_maker) · [LinkedIn](https://www.linkedin.com/company/api-maker) · [Twitter](https://twitter.com/api_maker)
+
+## 💬 Support & license
+
+- A license key, a question, a feature request or a bug: [contact@apimaker.dev](mailto:contact@apimaker.dev) or the [contact page](https://apimaker.dev/contact).
+- API Maker is proprietary software. Its use needs a license key: see the [terms](https://apimaker.dev/terms).
+- Working on this repository? The developer guide is [internal/README.md](internal/README.md).
+
+<hr/>
+
+<p align="center">
+  API Maker® is developed and maintained by <a href="https://savainfosystems.com">SAVA Info Systems Pvt. Ltd.</a>
+</p>

package/bin/api-maker.js

@@ -0,0 +1,497 @@
+#!/usr/bin/env node
+'use strict';
+// `api-maker` : starts API Maker v4 for the system and the processor of this machine.
+//
+// npm installs this package with the one package of its platform (`optionalDependencies` : each platform package says
+// its `os` and `cpu`, npm takes the one that matches) : the server `api_maker_be`, the agents of its sandboxes and the
+// admin panel. This file finds that package and starts its server in the current folder, with what the server can not
+// find by itself :
+// - the admin panel of the package (`am__adminPanel__folder`), unless the settings already name one ;
+// - on macOS and Windows, the agents of the sandboxes : the sandboxes are Linux containers, so their agents are the
+//   ones of the sandbox package of the same processor (`-sandbox-linux-<arch>` : the launcher am_agent and the four
+//   agent libraries of Linux, nothing of the server), which npm installs next to the one of the machine
+//   (`AM_SANDBOX_AGENT`, `AM_SANDBOX_CORE`). The agents for code which runs on the Mac or the Windows machine itself are
+//   next to its server.
+//
+// No dependency : only Node.js (18 or newer) itself. Built into the package by scripts/release/release.sh of
+// api_maker_be_rust, tested by scripts/release/npm/test/api-maker.test.js.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { spawn, spawnSync } = require('node:child_process');
+
+const ROOT = path.join(__dirname, '..');
+const PKG = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+const [SCOPE, BASE] = PKG.name.split('/');
+
+/** The platforms a package is built for, as `<process.platform>-<process.arch>`. */
+const PLATFORMS = ['linux-x64', 'linux-arm64', 'darwin-arm64', 'darwin-x64', 'win32-x64'];
+const PROGRAM = 'api_maker_be';
+/** The program of the sandboxes and the four agent libraries, as a sandbox package (and a Linux package) delivers them. */
+const SANDBOX_FILES = ['am_agent', 'am_agent.node', 'am_agent.abi3.so', 'libam_agent_jni.so', 'libam_agent.so'];
+/** The agent libraries for code which runs on a Mac itself, next to its server. */
+const MAC_FILES = ['libam_napi.dylib', 'libam_pyo3.dylib', 'libam_jni.dylib', 'libam_ffi.dylib'];
+/** The agent libraries for code which runs on a Windows machine itself, next to its server. */
+const WINDOWS_FILES = ['am_napi.dll', 'am_pyo3.dll', 'am_jni.dll', 'am_ffi.dll'];
+
+const DEFAULTS = { port: 48246, panelPort: 4626, mongoPort: 27017, redisPort: 6379 };
+const MONGO_IMAGE = 'mongo:8.0.10';
+const REDIS_IMAGE = 'redis:7.0.5-alpine';
+
+/** An error that is told to the person as it is, without a stack. */
+class Told extends Error {}
+
+// ───────────────────────────────────────────── the platform
+
+/** `linux-x64`… for this machine, `null` where no package is built. */
+function platformKey(platform = process.platform, arch = process.arch) {
+    const key = `${platform}-${arch}`;
+    return PLATFORMS.includes(key) ? key : null;
+}
+
+/** The npm package of a platform : `@sava-info-systems/api-maker-engine-linux-x64`. */
+function packageOf(key) {
+    return `${SCOPE}/${BASE}-${key}`;
+}
+
+/** The file of the server in the package of a system : `api_maker_be.exe` on Windows. */
+function programOf(platform) {
+    return platform === 'win32' ? `${PROGRAM}.exe` : PROGRAM;
+}
+
+/**
+ * Whether the sandboxes of a platform take their agents from the sandbox package of its processor : a Mac and Windows
+ * run them as Linux containers.
+ */
+function sandboxesFromLinux(key) {
+    return !key.startsWith('linux-');
+}
+
+/**
+ * The sandbox package of a processor : what the sandboxes of a Mac and of Windows run, the launcher am_agent and the
+ * agent libraries of Linux alone (`@sava-info-systems/api-maker-engine-sandbox-linux-arm64`).
+ */
+function sandboxPackageOf(arch) {
+    return packageOf(`sandbox-linux-${arch}`);
+}
+
+/** The folder npm installed a package in, as Node.js finds it from this package, `null` when it is not installed. */
+function folderOf(name, from = ROOT) {
+    try {
+        return path.dirname(require.resolve(`${name}/package.json`, { paths: [from] }));
+    } catch {
+        return null;
+    }
+}
+
+function readVersion(folder) {
+    try {
+        return fs.readFileSync(path.join(folder, 'VERSION'), 'utf8').trim();
+    } catch {
+        return null;
+    }
+}
+
+function unsupported(platform = process.platform, arch = process.arch) {
+    const lines = [`API Maker v4 is not built for ${platform}-${arch}.`, `It runs on ${PLATFORMS.join(', ')}.`];
+    if (platform === 'win32') {
+        lines.push('On Windows, install it inside WSL 2 (Ubuntu) : https://learn.microsoft.com/windows/wsl/install');
+    }
+    return lines.join('\n');
+}
+
+/**
+ * What runs on this machine : the folder of its server, the folder of the agents of its sandboxes (the same one on
+ * Linux, the sandbox package of the same processor on a Mac and on Windows) and the admin panel. Throws a `Told` error
+ * when the package of the platform is not there.
+ */
+function resolveRuntime(platform = process.platform, arch = process.arch) {
+    const key = platformKey(platform, arch);
+    if (!key) throw new Told(unsupported(platform, arch));
+    const name = packageOf(key);
+    const server = folderOf(name);
+    if (!server) {
+        throw new Told(
+            `${name} is not installed : it holds API Maker for this machine.\n` +
+                'npm installs it with this package unless optional dependencies are left out (--omit=optional, ' +
+                `--no-optional). Install again : npm install -g ${PKG.name}`,
+        );
+    }
+    const program = path.join(server, programOf(platform));
+    if (!fs.existsSync(program)) throw new Told(`${name} has no ${programOf(platform)} (${server}) : install it again.`);
+    // On a Mac and on Windows, the sandbox package ; the Linux package holds the same files besides its server, and is
+    // taken when it is the one installed (a package of Linux installed by hand).
+    const sandboxes = sandboxesFromLinux(key) ? folderOf(sandboxPackageOf(arch)) || folderOf(packageOf(`linux-${arch}`)) : server;
+    const panel =
+        [server, sandboxes]
+            .filter(Boolean)
+            .map((folder) => path.join(folder, 'admin-panel'))
+            .find((folder) => fs.existsSync(path.join(folder, 'index.html'))) || null;
+    return { key, name, server, program, sandboxes, panel, version: readVersion(server) };
+}
+
+// ───────────────────────────────────────────── the settings the person gave
+
+/** The arguments of the server by name, as it reads them (`--name=value`, a bare `--name` is true). */
+function argumentsByName(args) {
+    const named = new Map();
+    for (const argument of args) {
+        const at = argument.indexOf('=');
+        const name = (at < 0 ? argument : argument.slice(0, at)).replace(/^-+/, '');
+        named.set(name, at < 0 ? true : argument.slice(at + 1));
+    }
+    return named;
+}
+
+/** The `.env` file the server reads : `--envPath`, else `.env` of `--appRoot` (the current folder by default). */
+function envFileOf(args, cwd = process.cwd()) {
+    const named = argumentsByName(args);
+    const envPath = named.get('envPath');
+    if (typeof envPath === 'string' && envPath) return path.resolve(cwd, envPath);
+    const appRoot = named.get('appRoot');
+    return path.join(typeof appRoot === 'string' && appRoot ? path.resolve(cwd, appRoot) : cwd, '.env');
+}
+
+/** Whether the text of a `.env` file sets one of these names (to anything, empty included). */
+function envFileSets(text, names) {
+    return names.some((name) =>
+        new RegExp(`^\\s*(?:export\\s+)?${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*=`, 'm').test(text),
+    );
+}
+
+/**
+ * Whether the person set a setting already : on the command line (`arguments`), in the environment, or in the `.env`
+ * file the server reads (`envNames`). What they set is never replaced.
+ */
+function isSet({ argNames, envNames }, args, env, envText) {
+    const named = argumentsByName(args);
+    return (
+        argNames.some((name) => named.has(name)) ||
+        envNames.some((name) => env[name] !== undefined) ||
+        envFileSets(envText, envNames)
+    );
+}
+
+const PANEL_SETTING = { argNames: ['am.adminPanel.folder', 'am__adminPanel__folder'], envNames: ['am__adminPanel__folder'] };
+const AGENT_SETTING = { argNames: ['sandboxAgent'], envNames: ['AM_SANDBOX_AGENT'] };
+const CORE_SETTING = { argNames: ['sandboxCore'], envNames: ['AM_SANDBOX_CORE'] };
+
+/** The environment the server starts with : the one of this process, with what the package adds. */
+function environmentFor(runtime, args, env = process.env, cwd = process.cwd()) {
+    const out = { ...env };
+    let envText = '';
+    try {
+        envText = fs.readFileSync(envFileOf(args, cwd), 'utf8');
+    } catch {
+        // No .env : the settings come from the environment and the arguments.
+    }
+    if (sandboxesFromLinux(runtime.key) && runtime.sandboxes) {
+        const agent = path.join(runtime.sandboxes, 'am_agent');
+        if (fs.existsSync(agent) && !isSet(AGENT_SETTING, args, env, envText)) out.AM_SANDBOX_AGENT = agent;
+        if (fs.existsSync(path.join(runtime.sandboxes, 'am_agent.node')) && !isSet(CORE_SETTING, args, env, envText)) {
+            out.AM_SANDBOX_CORE = runtime.sandboxes;
+        }
+    }
+    if (runtime.panel && !isSet(PANEL_SETTING, args, env, envText)) out.am__adminPanel__folder = runtime.panel;
+    return out;
+}
+
+// ───────────────────────────────────────────── start
+
+/** npm keeps the modes of the files of a package, a copy made another way may not : the programs are made executable. */
+function ensureExecutable(file) {
+    // Windows runs a program by its name (.exe) : files have no executable mode there.
+    if (process.platform === 'win32') return;
+    try {
+        const mode = fs.statSync(file).mode;
+        if ((mode & 0o111) === 0) fs.chmodSync(file, mode | 0o755);
+    } catch {
+        // Read only (a global install of root) : the start says so if it can not run.
+    }
+}
+
+function start(args) {
+    const runtime = resolveRuntime();
+    ensureExecutable(runtime.program);
+    if (sandboxesFromLinux(runtime.key) && !runtime.sandboxes) {
+        process.stderr.write(
+            `⚠️  ${sandboxPackageOf(process.arch)} is not installed : the sandboxes have no agent of their own, so ` +
+                'API Maker answers what their code asks of g.sys itself. Install again to get it.\n',
+        );
+    }
+    const child = spawn(runtime.program, args, { stdio: 'inherit', env: environmentFor(runtime, args) });
+    // The signals a terminal or a service manager sends this process go to the server ; it stops on its own. Windows
+    // has no signals : Ctrl+C reaches the server itself, through the console both share, and a `kill` of Node.js would
+    // end it at once, whatever the signal. There this process only waits for the server to end.
+    for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+        process.on(signal, () => {
+            if (process.platform === 'win32') return;
+            if (child.exitCode === null && child.signalCode === null) child.kill(signal);
+        });
+    }
+    child.on('error', (error) => {
+        process.stderr.write(`❌  ${runtime.program} could not be started : ${error.message}\n`);
+        process.exit(1);
+    });
+    child.on('exit', (code, signal) => {
+        if (signal) {
+            process.removeAllListeners(signal);
+            process.kill(process.pid, signal);
+            return;
+        }
+        process.exit(code === null ? 1 : code);
+    });
+}
+
+// ───────────────────────────────────────────── init
+
+/** Characters at random, as the installer makes its secrets : letters, digits and `_`. */
+function randomText(length) {
+    const alphabet = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_';
+    let text = '';
+    while (text.length < length) {
+        for (const byte of crypto.randomBytes(length)) {
+            // 252 = 4 × 63 : no letter is more likely than another.
+            if (byte < 252 && text.length < length) text += alphabet[byte % alphabet.length];
+        }
+    }
+    return text;
+}
+
+function portOption(named, name, fallback) {
+    const value = named.get(name);
+    if (value === undefined) return fallback;
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Told(`--${name} is a port (1 to 65535), not '${value}'.`);
+    return port;
+}
+
+/** The `.env` of a new installation on this machine : new secrets, a MongoDB and a Redis of this machine. */
+function envText({ port, panelPort, mongoPort, redisPort }) {
+    return `# The settings of API Maker v4, written by \`api-maker init\`. A setting is its path in the "am" block, with "__"
+# between the names (am__logs__enableLogs=false is am.logs.enableLogs). Every setting :
+# https://docs.apimaker.dev/v4/docs/am-resources/api-maker-configurations.html
+
+# Where the admin panel (and the browsers of your users) reach API Maker : its web sockets too, ws:// or wss://.
+BE_HOST_PORT="http://__ip_address__:${port}"
+
+am__serverName=server1
+am__port=${port} # the APIs and the web sockets
+am__adminPanel__port=${panelPort} # the admin panel (\`api-maker\` serves the one of its package)
+
+# API Maker's own data : a MongoDB replica set (a pull of git is one transaction), and a Redis.
+am__mongo_db_connection="mongodb://127.0.0.1:${mongoPort}/api_maker?replicaSet=rs0&directConnection=true"
+am__redisInternal='{"nodes": [{port:${redisPort}, host:"127.0.0.1", pass: ""}]}'
+
+# Three secrets of this installation. Keep them : what API Maker encrypts can only be read with them.
+am__passCommunication="${randomText(20)}"
+am__passJWT="${randomText(32)}"
+am__passDBEncryptDecrypt="${randomText(32)}" # 👈 32 characters : the data of the databases and of the git repositories is encrypted with it.
+`;
+}
+
+function writeSecretFile(file, text) {
+    fs.writeFileSync(file, text, { mode: 0o600 });
+    try {
+        fs.chmodSync(file, 0o600);
+    } catch {
+        // A file system without modes.
+    }
+}
+
+function docker(args, options = {}) {
+    return spawnSync('docker', args, { encoding: 'utf8', ...options });
+}
+
+function sleep(milliseconds) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+
+function waitFor(what, test, seconds) {
+    const until = Date.now() + seconds * 1000;
+    while (Date.now() < until) {
+        if (test()) return;
+        sleep(1000);
+    }
+    throw new Told(`${what} did not answer within ${seconds} seconds.`);
+}
+
+/** A container of Docker by name : `running`, `stopped`, or `null` when there is none. */
+function containerState(name) {
+    const found = docker(['ps', '-a', '--filter', `name=^/${name}$`, '--format', '{{.State}}']);
+    const state = (found.stdout || '').trim();
+    if (!state) return null;
+    return state === 'running' ? 'running' : 'stopped';
+}
+
+function ensureContainer(name, runArgs) {
+    const state = containerState(name);
+    if (state === 'running') return `${name} runs already`;
+    const done = state === 'stopped' ? docker(['start', name]) : docker(['run', '-d', '--name', name, ...runArgs]);
+    if (done.status !== 0) throw new Told(`Docker could not start ${name} :\n${(done.stderr || done.stdout || '').trim()}`);
+    return state === 'stopped' ? `${name} started again` : `${name} started`;
+}
+
+/** MongoDB (a replica set of one member) and Redis in Docker, on ports of this machine only. */
+function startDatabases({ mongoPort, redisPort }) {
+    const info = docker(['info', '--format', '{{.ServerVersion}}']);
+    if (info.error || info.status !== 0) {
+        throw new Told('Docker does not answer : start Docker (Docker Desktop, OrbStack, or the docker service) and run this again.');
+    }
+    const mongo = `api_maker_mongodb_${mongoPort}`;
+    const redis = `api_maker_redis_${redisPort}`;
+    say(`🔶  ${ensureContainer(mongo, ['--restart', 'unless-stopped', '-p', `127.0.0.1:${mongoPort}:27017`, '-v', `${mongo}:/data/db`, MONGO_IMAGE, '--replSet', 'rs0', '--bind_ip_all'])}`);
+    const shell = (script) => docker(['exec', mongo, 'mongosh', '--quiet', '--eval', script]);
+    waitFor('MongoDB', () => (shell('db.runCommand({ ping: 1 }).ok').stdout || '').trim() === '1', 90);
+    // The member is named as the container sees itself : clients connect to it directly (directConnection=true).
+    shell("try { rs.status().ok } catch (e) { rs.initiate({ _id: 'rs0', members: [{ _id: 0, host: '127.0.0.1:27017' }] }).ok }");
+    waitFor('The replica set of MongoDB', () => (shell('db.hello().isWritablePrimary').stdout || '').trim() === 'true', 60);
+    say(`✅  MongoDB (replica set rs0) on 127.0.0.1:${mongoPort}`);
+    say(`🔶  ${ensureContainer(redis, ['--restart', 'unless-stopped', '-p', `127.0.0.1:${redisPort}:6379`, REDIS_IMAGE])}`);
+    waitFor('Redis', () => (docker(['exec', redis, 'redis-cli', 'ping']).stdout || '').trim() === 'PONG', 30);
+    say(`✅  Redis on 127.0.0.1:${redisPort}`);
+}
+
+function init(args, cwd = process.cwd()) {
+    const named = argumentsByName(args);
+    const known = new Set(['force', 'license_key', 'docker', 'port', 'panel_port', 'mongo_port', 'redis_port']);
+    for (const name of named.keys()) {
+        if (!known.has(name)) throw new Told(`api-maker init : unknown option --${name} (api-maker help).`);
+    }
+    const ports = {
+        port: portOption(named, 'port', DEFAULTS.port),
+        panelPort: portOption(named, 'panel_port', DEFAULTS.panelPort),
+        mongoPort: portOption(named, 'mongo_port', DEFAULTS.mongoPort),
+        redisPort: portOption(named, 'redis_port', DEFAULTS.redisPort),
+    };
+    const force = named.get('force') === true;
+    const envFile = path.join(cwd, '.env');
+    if (fs.existsSync(envFile) && !force) {
+        say(`👉  ${envFile} is there already : it is kept (--force writes a new one, with new secrets).`);
+    } else {
+        writeSecretFile(envFile, envText(ports));
+        say(`✅  Settings written : ${envFile}`);
+    }
+    const key = named.get('license_key');
+    if (key !== undefined) {
+        if (typeof key !== 'string' || !key.trim()) throw new Told('--license_key needs the key : --license_key=YOUR_KEY');
+        const licenseFile = path.join(cwd, 'license.txt');
+        if (fs.existsSync(licenseFile) && !force) {
+            say(`👉  ${licenseFile} is there already : it is kept (--force replaces it).`);
+        } else {
+            writeSecretFile(licenseFile, `${key.trim()}\n`);
+            say(`✅  License key written : ${licenseFile}`);
+        }
+    }
+    if (named.get('docker') === true) startDatabases(ports);
+    say('');
+    if (named.get('docker') !== true) {
+        say('API Maker needs a MongoDB replica set and a Redis, as the .env names them. In Docker :');
+        say(`  docker run -d --name api_maker_mongodb_${ports.mongoPort} -p 127.0.0.1:${ports.mongoPort}:27017 ${MONGO_IMAGE} --replSet rs0 --bind_ip_all`);
+        say(`  docker exec api_maker_mongodb_${ports.mongoPort} mongosh --quiet --eval "rs.initiate({_id:'rs0',members:[{_id:0,host:'127.0.0.1:27017'}]})"`);
+        say(`  docker run -d --name api_maker_redis_${ports.redisPort} -p 127.0.0.1:${ports.redisPort}:6379 ${REDIS_IMAGE}`);
+        say('(or run `api-maker init --docker`, which does it)');
+        say('');
+    }
+    say('Start API Maker in this folder :  api-maker');
+    say(`The admin panel :                 http://localhost:${ports.panelPort}`);
+}
+
+// ───────────────────────────────────────────── info, help
+
+function info() {
+    const key = platformKey();
+    say(`${PKG.name} ${PKG.version}`);
+    say(`Machine           ${process.platform}-${process.arch}${key ? '' : ' (no build for it)'}`);
+    say(`Node.js           ${process.version}`);
+    if (!key) {
+        say('');
+        say(unsupported());
+        return;
+    }
+    const runtime = resolveRuntime();
+    say(`Package           ${runtime.name} ${runtime.version || '?'}${runtime.version && runtime.version !== PKG.version ? `  ⚠️  not ${PKG.version}` : ''}`);
+    say(`Server            ${runtime.program}`);
+    say(`Admin panel       ${runtime.panel || '(none)'}`);
+    const files = (folder, names) => names.map((name) => `${fs.existsSync(path.join(folder, name)) ? '✔' : '✘'} ${name}`).join('  ');
+    say(`Sandbox agents    ${runtime.sandboxes ? `${runtime.sandboxes}\n                  ${files(runtime.sandboxes, SANDBOX_FILES)}` : `(${sandboxPackageOf(process.arch)} is not installed)`}`);
+    if (runtime.key.startsWith('darwin-')) say(`Mac agents        ${files(runtime.server, MAC_FILES)}`);
+    if (runtime.key.startsWith('win32-')) say(`Windows agents    ${files(runtime.server, WINDOWS_FILES)}`);
+    const version = spawnSync(runtime.program, ['--version'], { encoding: 'utf8' });
+    say(`Runs here         ${version.status === 0 ? `yes : ${version.stdout.trim()}` : `no : ${(version.stderr || version.error?.message || '').trim()}`}`);
+}
+
+function help() {
+    say(`api-maker : API Maker v4 (${PKG.version}) for this machine.
+
+  api-maker [server options]      Start API Maker in the current folder (.env, license.txt and uploads/ are there).
+                                  Every option of the server works, e.g. api-maker --am.port=5000
+  api-maker init [options]        Write a .env with new secrets for a MongoDB and a Redis of this machine.
+      --license_key=KEY             write license.txt with the key
+      --docker                      start MongoDB (a replica set) and Redis in Docker
+      --port=${DEFAULTS.port} --panel_port=${DEFAULTS.panelPort} --mongo_port=${DEFAULTS.mongoPort} --redis_port=${DEFAULTS.redisPort}
+      --force                       replace an existing .env and license.txt
+  api-maker info                  The version, the platform and the files API Maker runs from.
+  api-maker --version             The version of the server.
+  api-maker help                  This help, then the options of the server.
+
+Documentation : https://docs.apimaker.dev`);
+    if (!platformKey()) return;
+    try {
+        const runtime = resolveRuntime();
+        const server = spawnSync(runtime.program, ['--help'], { encoding: 'utf8' });
+        if (server.status === 0) say(`\nThe server :\n${server.stdout.trimEnd()}`);
+    } catch {
+        // The package of the platform is missing : `api-maker info` says so.
+    }
+}
+
+function say(line) {
+    process.stdout.write(`${line}\n`);
+}
+
+function main(argv) {
+    const [command, ...rest] = argv;
+    switch (command) {
+        case 'init':
+            return init(rest);
+        case 'info':
+            return info();
+        case 'help':
+        case '-h':
+        case '--help':
+            return help();
+        case 'start':
+            return start(rest);
+        default:
+            return start(argv);
+    }
+}
+
+if (require.main === module) {
+    try {
+        main(process.argv.slice(2));
+    } catch (error) {
+        if (!(error instanceof Told)) throw error;
+        process.stderr.write(`❌  ${error.message}\n`);
+        process.exit(1);
+    }
+}
+
+module.exports = {
+    PLATFORMS,
+    platformKey,
+    packageOf,
+    sandboxPackageOf,
+    folderOf,
+    resolveRuntime,
+    argumentsByName,
+    envFileOf,
+    envFileSets,
+    environmentFor,
+    envText,
+    randomText,
+    init,
+    Told,
+};

package/package.json

@@ -1,6 +1,56 @@
 {
-  "name": "@sava-info-systems/api-maker-engine",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@sava-info-systems/api-maker-engine",
+    "version": "4.0.0-beta.7",
+    "description": "🚀 API Maker® v4 — the backend engine for the AI era. Connect a database, get every API, add your logic : API Maker locks every API and checks your code for data leaks. One program written in Rust : npm installs the build of your system and processor.",
+    "homepage": "https://apimaker.dev",
+    "author": "SAVA INFO SYSTEMS PRIVATE LIMITED",
+    "contributors": [
+        "SAVA Info Systems Pvt. Ltd. <savainfosystems4@gmail.com> (https://savainfosystems.com)"
+    ],
+    "license": "proprietary",
+    "keywords": [
+        "api maker",
+        "backend solution",
+        "backend engine for the ai era",
+        "self-hosted backend",
+        "automatic api generator",
+        "rest api generator",
+        "custom apis",
+        "websocket notifications",
+        "schedulers",
+        "graphql alternative",
+        "supabase alternative",
+        "firebase alternative",
+        "xano alternative",
+        "automatic caching",
+        "database migration scripts",
+        "git integration",
+        "low code backend",
+        "mongodb apis generator",
+        "mysql apis generator",
+        "postgresql apis generator",
+        "sql server apis generator",
+        "oracle apis generator",
+        "mariadb apis generator",
+        "rust"
+    ],
+    "bin": {
+        "api-maker": "bin/api-maker.js"
+    },
+    "os": ["linux", "darwin", "win32"],
+    "cpu": ["x64", "arm64"],
+    "engines": {
+        "node": ">=18"
+    },
+    "optionalDependencies": {
+        "@sava-info-systems/api-maker-engine-linux-x64": "4.0.0-beta.7",
+        "@sava-info-systems/api-maker-engine-linux-arm64": "4.0.0-beta.7",
+        "@sava-info-systems/api-maker-engine-darwin-arm64": "4.0.0-beta.7",
+        "@sava-info-systems/api-maker-engine-darwin-x64": "4.0.0-beta.7",
+        "@sava-info-systems/api-maker-engine-win32-x64": "4.0.0-beta.7",
+        "@sava-info-systems/api-maker-engine-sandbox-linux-arm64": "4.0.0-beta.7",
+        "@sava-info-systems/api-maker-engine-sandbox-linux-x64": "4.0.0-beta.7"
+    },
+    "files": ["bin", "README.md"],
+    "publishConfig": { "access": "public" }
+}