threadforge 0.1.1 → 0.2.2

package/README.md

@@ -17,14 +17,29 @@ Node.js runs on a single thread. Modern servers have 16, 32, 64+ cores. ThreadFo
 - **Auto-restart** — crashed workers are automatically replaced
 - **Runtime scaling** — scale services up/down without restarting
 - **RequestContext propagation** — correlation IDs, auth, deadlines, and baggage across services
-- **Built-in metrics** — Prometheus-compatible endpoint out of the box
+- **Built-in metrics** — Prometheus-compatible endpoint with HTTP, RPC, and event loop lag metrics
 - **Multi-machine deployment** — grow from one machine to a full cluster with `forge.deploy.js`
 
 ## Quick Start
 
-> **Note:** ThreadForge is not yet published to npm. See installation options below.
+### Option 1: Install from npm (Recommended)
 
-### Option 1: Local Development (Recommended)
+```bash
+# Create and scaffold a new project
+mkdir my-app && cd my-app
+npm init -y
+npm install threadforge
+npx forge init . --source npm
+npm install
+
+# Start in development mode (hot reload)
+npm run dev
+
+# Start in production mode
+npm run start
+```
+
+### Option 2: Local Development (ThreadForge contributors only)
 
 ```bash
 # Clone and link ThreadForge locally
@@ -43,36 +58,17 @@ npm install
 npm run dev
 ```
 
-### Option 2: Install from GitHub
-
-```bash
-# Scaffold a new project
-npx github:ChrisBland/threadforge init my-app
-cd my-app
-npm install
-
-# Start in development mode (hot reload)
-npm run dev
-
-# Start in production mode
-npm run start
-```
-
-If `npx github:ChrisBland/threadforge ...` fails with npm cache permission errors (`EPERM` on `~/.npm/_cacache`), use a writable cache directory for the command:
-
-```bash
-NPM_CONFIG_CACHE=/tmp/threadforge-npm-cache npx github:ChrisBland/threadforge init my-app
-```
+`forge init` is backend-only by default. Add static frontend scaffolding with `npx forge scaffold frontend` (or `npx forge init . --with-frontend`), or generate Vite + React with `npx forge scaffold frontend --react` (or `npx forge init . --with-react`).
 
 Create `forge.config.js`:
 
 ```javascript
-import { defineServices } from 'threadforge';
+import { defineServices, ServiceType } from 'threadforge';
 
 export default defineServices({
   api: {
     entry: './services/api.js',
-    type: 'edge',
+    type: ServiceType.EDGE,
     port: 3000,
     threads: 'auto',
     connects: ['users'],
@@ -80,7 +76,7 @@ export default defineServices({
 
   users: {
     entry: './services/users.js',
-    type: 'internal',
+    type: ServiceType.INTERNAL,
   },
 });
 ```
@@ -88,15 +84,10 @@ export default defineServices({
 Create `services/api.js`:
 
 ```javascript
-import { Service } from 'threadforge';
+import { HttpMethod, Service, Route } from 'threadforge';
 
 export default class ApiService extends Service {
-  static contract = {
-    routes: [
-      { method: 'GET', path: '/users/:id', handler: 'getUser' },
-    ],
-  };
-
+  @Route(HttpMethod.GET, '/users/:id')
   async getUser(body, params) {
     return await this.users.getUser(params.id);
   }
@@ -106,29 +97,63 @@ export default class ApiService extends Service {
 Create `services/users.js`:
 
 ```javascript
-import { Service } from 'threadforge';
+import { Service, Expose } from 'threadforge';
 
 export default class UsersService extends Service {
-  static contract = {
-    expose: ['getUser'],
-  };
-
   async onStart(ctx) {
     this.store = new Map([['1', { id: '1', name: 'Alice' }]]);
   }
 
+  @Expose()
   async getUser(id) {
-    return this.store.get(String(id));
+    return this.store.get(String(id)) ?? null;
   }
 }
 ```
 
 ```bash
-forge start
+npm run start
 # curl http://localhost:3000/users/1
-# → { "id": "1", "name": "Alice" }
+# → {"id":"1","name":"Alice"}
+```
+
+## Platform Mode Quick Flow
+
+For multi-site projects (multiple apps/domains with per-app services/frontends):
+
+```bash
+mkdir platform-app && cd platform-app
+npm init -y
+npm install threadforge
+npx forge platform init
+npx forge platform add sitea
+npx forge platform add siteb
+
+# then edit forge.platform.js:
+# - add platform.apps.<appId> with domains/services/frontend
+# - add top-level '<appId>-api' service entries with unique ports
+# - register frontendPlugins (for example: viteFrontend())
+# - create each frontend project (for example: apps/sitea/web and apps/siteb/web)
+
+# install frontend deps for each site before build
+# (example)
+# cd apps/sitea/web && npm install
+# cd ../../siteb/web && npm install
+# cd ../../../
+
+npx forge build
+npx forge platform generate
+npx forge platform start
 ```
 
+See:
+- `docs/guides/plugins.md` for frontend plugin config (`viteFrontend`)
+- `docs/reference/configuration.md` for `definePlatform()` schema
+- `docs/reference/cli.md` for all `forge platform` subcommands
+- `examples/platform-two-app-react-date-time/README.md` for a runnable two-site date/time + React example
+- `examples/platform-kitchen-sink/README.md` for shared auth/users + event-driven multi-site example
+- `examples/threads-overprovision/README.md` for graceful handling when requested threads exceed host CPU capacity
+
 ## Documentation
 
 Full documentation is in the [`docs/`](./docs/) directory:
@@ -136,16 +161,18 @@ Full documentation is in the [`docs/`](./docs/) directory:
 - [**Getting Started**](./docs/getting-started.md) — Install, create your first service, and run it
 - [**Architecture**](./docs/architecture.md) — Process model, communication layers, request lifecycle
 - **Guides:**
+  - [Single-App React Date/Time Quickstart](./docs/guides/single-app-react-date-time.md) — One app with `/time`, `/date`, and a React frontend
   - [Services](./docs/guides/services.md) — Types, lifecycle, colocation, plain JS fallback
   - [IPC & Communication](./docs/guides/ipc.md) — Proxy clients, events, interceptors
   - [Plugins](./docs/guides/plugins.md) — Redis, PostgreSQL, S3, CORS, Cron, Realtime
+  - [Platform Two-App React Quickstart](./docs/guides/platform-two-app-react.md) — Multi-site apps with per-site API + frontend
   - [Deployment](./docs/guides/deployment.md) — Single machine to multi-machine scaling
 - **Reference:**
   - [Configuration](./docs/reference/configuration.md) — All `forge.config.js` options
   - [Decorators](./docs/reference/decorators.md) — Full decorator API
   - [CLI](./docs/reference/cli.md) — Commands, options, metrics endpoints
   - [API](./docs/reference/api.md) — All public exports
-- [**ForgeProxy**](./docs/FORGEPROXY_ARCHITECTURE.js) — Rust gateway design and performance
+- [**ForgeProxy**](./docs/architecture.md#three-layer-production-architecture) — Rust gateway architecture and ingress role
 
 ## License