threadforge 0.1.0

package/bin/platform-commands.js

@@ -0,0 +1,570 @@
+/**
+ * ForgePlatform CLI Commands
+ *
+ * Subcommands for `forge platform`:
+ *   forge platform init              Scaffold forge.platform.js + shared services + apps/
+ *   forge platform start             Start the platform
+ *   forge platform add <name>        Scaffold a new app
+ *   forge platform remove <id>       Print removal instructions
+ *   forge platform status            Show per-app status table
+ *   forge platform generate          Generate nginx + platform.yaml + route manifests
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const PLATFORM_CONFIG_NAMES = ["forge.platform.js", "forge.platform.mjs"];
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const LOCAL_PKG_PATH = path.resolve(__dirname, "..", "package.json");
+
+async function findPlatformConfig() {
+  const cwd = process.cwd();
+  for (const name of PLATFORM_CONFIG_NAMES) {
+    const fullPath = path.join(cwd, name);
+    try {
+      await fs.promises.access(fullPath);
+      return fullPath;
+    } catch {}
+  }
+  return null;
+}
+
+/**
+ * Compute the import path for threadforge from a given source directory.
+ * Returns a relative path when running from a local clone, or "threadforge"
+ * when installed as a dependency.
+ *
+ * @param {string} fromDir - The directory the import will appear in
+ * @returns {string}
+ */
+function computeImportPath(fromDir) {
+  try {
+    if (fs.existsSync(LOCAL_PKG_PATH)) {
+      const pkg = JSON.parse(fs.readFileSync(LOCAL_PKG_PATH, "utf8"));
+      if (pkg.name === "threadforge") {
+        const indexAbsolute = fs.realpathSync(path.resolve(__dirname, "..", "src", "index.js"));
+        const realFrom = fs.realpathSync(fromDir);
+        let rel = path.relative(realFrom, indexAbsolute);
+        if (!rel.startsWith(".")) rel = `./${rel}`;
+        return rel;
+      }
+    }
+  } catch {}
+  return "threadforge";
+}
+
+async function loadPlatformConfig() {
+  const configPath = await findPlatformConfig();
+  if (!configPath) {
+    console.error("  Error: No forge.platform.js found in current directory.");
+    console.error("  Run `forge platform init` to create one.");
+    process.exit(1);
+  }
+  const configUrl = pathToFileURL(configPath).href;
+  const mod = await import(configUrl);
+  return mod.default ?? mod;
+}
+
+function loadFrontendBuildManifest(cwd) {
+  const manifestPath = path.join(cwd, ".threadforge", "frontend-manifest.json");
+  if (!fs.existsSync(manifestPath)) return null;
+  try {
+    const json = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    return { path: manifestPath, data: json };
+  } catch (err) {
+    console.warn(`  Warning: Could not parse ${manifestPath}: ${err.message}`);
+    return null;
+  }
+}
+
+// ── forge platform init ──────────────────────────────────────────────────
+
+async function cmdPlatformInit() {
+  const cwd = process.cwd();
+  const configPath = path.join(cwd, "forge.platform.js");
+
+  if (fs.existsSync(configPath)) {
+    console.error("  forge.platform.js already exists in this directory.");
+    process.exit(1);
+  }
+
+  const importPath = computeImportPath(cwd);
+  const serviceImportPath = computeImportPath(path.join(cwd, "shared"));
+
+  // Create directories
+  for (const dir of ["shared", "apps"]) {
+    fs.mkdirSync(path.join(cwd, dir), { recursive: true });
+  }
+
+  // Write platform config
+  fs.writeFileSync(
+    configPath,
+    `import { definePlatform } from '${importPath}';
+
+export default definePlatform({
+  platform: {
+    globalAuth: true,
+    sessionSharing: true,
+
+    apps: {
+      // Add apps here:
+      // myapp: {
+      //   domains: ['myapp.example.com'],
+      //   services: ['myapp-api'],
+      //   schema: 'myapp',
+      // },
+    },
+  },
+
+  // Plugins (shared across all apps)
+  // plugins: [postgres(), redis()],
+
+  // Shared services (run once, serve all apps)
+  identity: {
+    entry: './shared/identity.js',
+    type: 'edge',
+    port: 3001,
+  },
+  auth: {
+    entry: './shared/auth.js',
+    type: 'edge',
+    port: 3002,
+    prefix: '/auth',
+  },
+
+  // Per-app services go here:
+  // 'myapp-api': {
+  //   entry: './apps/myapp/api.js',
+  //   type: 'edge',
+  //   port: 4001,
+  //   connects: ['auth'],
+  // },
+});
+`,
+  );
+
+  // Write identity service stub
+  const identityPath = path.join(cwd, "shared", "identity.js");
+  if (!fs.existsSync(identityPath)) {
+    fs.writeFileSync(
+      identityPath,
+      `import { Service } from '${serviceImportPath}';
+
+export default class IdentityService extends Service {
+  static contract = {
+    expose: ['getUser', 'getUserByEmail', 'createUser', 'listMembers'],
+    routes: [
+      { method: 'POST', path: '/login', handler: 'login' },
+      { method: 'POST', path: '/register', handler: 'register' },
+      { method: 'GET', path: '/users/:id', handler: 'getUserRoute' },
+      { method: 'GET', path: '/users', handler: 'listUsersRoute' },
+    ],
+  };
+
+  async onStart(ctx) {
+    ctx.logger.info('Identity service ready');
+  }
+
+  async login(_body) { return { error: 'Not implemented' }; }
+  async register(_body) { return { error: 'Not implemented' }; }
+  async getUserRoute(_body, params) { return this.getUser(params.id); }
+  async listUsersRoute() { return { error: 'Not implemented' }; }
+  async getUser(_userId) { return { error: 'Not implemented' }; }
+  async getUserByEmail(_email) { return { error: 'Not implemented' }; }
+  async createUser(_data) { return { error: 'Not implemented' }; }
+  async listMembers(_appId) { return { error: 'Not implemented' }; }
+}
+`,
+    );
+  }
+
+  // Write auth service stub
+  const authPath = path.join(cwd, "shared", "auth.js");
+  if (!fs.existsSync(authPath)) {
+    fs.writeFileSync(
+      authPath,
+      `import { Service } from '${serviceImportPath}';
+
+export default class AuthService extends Service {
+  static contract = {
+    expose: ['validateToken', 'issueToken', 'revokeToken'],
+    routes: [
+      { method: 'POST', path: '/token', handler: 'issueTokenRoute' },
+      { method: 'POST', path: '/token/validate', handler: 'validateTokenRoute' },
+      { method: 'POST', path: '/token/revoke', handler: 'revokeTokenRoute' },
+      { method: 'POST', path: '/token/refresh', handler: 'refreshTokenRoute' },
+    ],
+  };
+
+  async onStart(ctx) {
+    ctx.logger.info('Auth service ready');
+  }
+
+  async issueTokenRoute(_body) { return { error: 'Not implemented' }; }
+  async validateTokenRoute(_body) { return { error: 'Not implemented' }; }
+  async revokeTokenRoute(_body) { return { error: 'Not implemented' }; }
+  async refreshTokenRoute(_body) { return { error: 'Not implemented' }; }
+  async validateToken(_token) { return { error: 'Not implemented' }; }
+  async issueToken(_payload) { return { error: 'Not implemented' }; }
+  async revokeToken(_token) { return { error: 'Not implemented' }; }
+}
+`,
+    );
+  }
+
+  console.log(`
+  ⚡ ForgePlatform initialized!
+
+  Created:
+    forge.platform.js        - Platform configuration
+    shared/identity.js       - Identity service (stub)
+    shared/auth.js           - Auth service (stub)
+    apps/                    - App directory
+
+  Next steps:
+    1. Edit forge.platform.js to configure your apps
+    2. forge platform add myapp
+    3. forge platform start
+  `);
+}
+
+// ── forge platform start ─────────────────────────────────────────────────
+
+async function cmdPlatformStart() {
+  const platformConfig = await loadPlatformConfig();
+  const { ForgePlatform } = await import("../src/core/ForgePlatform.js");
+
+  const platform = new ForgePlatform(platformConfig);
+  await platform.start();
+}
+
+// ── forge platform add <name> ────────────────────────────────────────────
+
+async function cmdPlatformAdd(args) {
+  const appName = args[0];
+  if (!appName) {
+    console.error("  Usage: forge platform add <app-name>");
+    process.exit(1);
+  }
+
+  if (!/^[a-z][a-z0-9_-]*$/.test(appName)) {
+    console.error(`  Invalid app name "${appName}": must start with a lowercase letter and contain only lowercase letters, digits, hyphens, and underscores.`);
+    process.exit(1);
+  }
+
+  const cwd = process.cwd();
+  const appDir = path.join(cwd, "apps", appName);
+
+  if (fs.existsSync(appDir)) {
+    console.error(`  App directory already exists: apps/${appName}/`);
+    process.exit(1);
+  }
+
+  const serviceImportPath = computeImportPath(path.join(cwd, "apps", appName));
+
+  // Create app directory + migrations
+  fs.mkdirSync(path.join(appDir, "migrations"), { recursive: true });
+
+  // Write service file
+  fs.writeFileSync(
+    path.join(appDir, "api.js"),
+    `import { Service } from '${serviceImportPath}';
+
+export default class ${capitalize(appName)}ApiService extends Service {
+  static contract = {
+    expose: ['getStatus'],
+    routes: [
+      { method: 'GET', path: '/health', handler: 'healthCheck' },
+      { method: 'GET', path: '/hello/:name', handler: 'hello' },
+    ],
+  };
+
+  async onStart(ctx) {
+    ctx.logger.info('${appName} API service ready');
+  }
+
+  async healthCheck() {
+    return { status: 'ok', app: '${appName}', worker: this.ctx.workerId };
+  }
+
+  async hello(_body, params) {
+    return { message: \`Hello from ${appName}, \${params.name}!\` };
+  }
+
+  async getStatus() {
+    return { app: '${appName}', status: 'running' };
+  }
+}
+`,
+  );
+
+  // Write migration template
+  const safeName = appName.replace(/"/g, '""');
+  fs.writeFileSync(
+    path.join(appDir, "migrations", "001_init.sql"),
+    `-- Migration: ${appName} initial schema
+-- This runs in the app's isolated schema (SET search_path = ${appName})
+
+CREATE TABLE IF NOT EXISTS "${safeName}_items" (
+  id          SERIAL PRIMARY KEY,
+  name        TEXT NOT NULL,
+  created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS "idx_${safeName}_items_created"
+  ON "${safeName}_items" (created_at);
+`,
+  );
+
+  console.log(`
+  ⚡ App "${appName}" scaffolded!
+
+  Created:
+    apps/${appName}/api.js                   - API service
+    apps/${appName}/migrations/001_init.sql  - Initial migration
+
+  Add this to your forge.platform.js:
+
+    // In platform.apps:
+    ${appName}: {
+      domains: ['${appName}.example.com'],
+      services: ['${appName}-api'],
+      schema: '${appName}',
+    },
+
+    // As a top-level service:
+    '${appName}-api': {
+      entry: './apps/${appName}/api.js',
+      type: 'edge',
+      port: 4001,
+      connects: ['auth'],
+    },
+  `);
+}
+
+function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+// ── forge platform remove <id> ───────────────────────────────────────────
+
+async function cmdPlatformRemove(args) {
+  const appId = args[0];
+  if (!appId) {
+    console.error("  Usage: forge platform remove <app-id>");
+    process.exit(1);
+  }
+
+  const dropData = args.includes("--drop-data");
+
+  console.log(`
+  To remove app "${appId}":
+  1. Remove its entry from platform.apps in forge.platform.js
+  2. Remove its service definitions from forge.platform.js
+  3. Restart: forge platform start
+  ${dropData ? `4. To drop data, manually run this SQL:\n     DROP SCHEMA "${appId}" CASCADE;` : `4. Data preserved in schema "${appId}"`}
+  5. Optionally delete: rm -rf apps/${appId}/
+  `);
+}
+
+// ── forge platform status ────────────────────────────────────────────────
+
+async function cmdPlatformStatus() {
+  const metricsPort = parseInt(process.env.FORGE_METRICS_PORT || '9090', 10);
+  try {
+    const res = await fetch(`http://localhost:${metricsPort}/status`);
+    const data = await res.json();
+
+    console.log("");
+    console.log("  ForgePlatform Status");
+    console.log("  ──────────────────────────────────────");
+
+    if (data.projects) {
+      console.log("");
+      console.log("  ┌──────────────────┬─────────────────────────┬──────────┬─────────┬────────────────┐");
+      console.log("  │ App              │ Domain                  │ Services │ Workers │ Schema         │");
+      console.log("  ├──────────────────┼─────────────────────────┼──────────┼─────────┼────────────────┤");
+
+      for (const [id, proj] of Object.entries(data.projects)) {
+        const name = id.padEnd(16);
+        const domain = (proj.domain ?? "—").substring(0, 23).padEnd(23);
+        const services = String(proj.services).padEnd(8);
+        const workers = String(proj.workers).padEnd(7);
+        const schema = (proj.schema ?? "—").substring(0, 14).padEnd(14);
+        console.log(`  │ ${name} │ ${domain} │ ${services} │ ${workers} │ ${schema} │`);
+      }
+
+      console.log("  └──────────────────┴─────────────────────────┴──────────┴─────────┴────────────────┘");
+    } else {
+      console.log("  Not running in platform mode.");
+    }
+
+    console.log(`  Uptime: ${Math.floor(data.uptime)}s`);
+    console.log("");
+  } catch {
+    console.error("  Could not connect to ForgePlatform runtime.");
+    console.error("  Is it running? (forge platform start)");
+    process.exit(1);
+  }
+}
+
+// ── forge platform generate ──────────────────────────────────────────────
+
+async function cmdPlatformGenerate() {
+  const platformConfig = await loadPlatformConfig();
+  const { resolveAppDomains, transformToHostConfig } = await import("../src/core/platform-config.js");
+  const { resolveHostConfig } = await import("../src/core/host-config.js");
+  const { generatePlatformNginxConfig } = await import("../src/deploy/NginxGenerator.js");
+  const { generatePlatformManifest } = await import("../src/deploy/PlatformManifestGenerator.js");
+
+  const raw = platformConfig._isPlatformConfig ? platformConfig._raw : platformConfig;
+  const hostConfig = transformToHostConfig(raw);
+  const resolved = await resolveHostConfig(hostConfig);
+
+  const cwd = process.cwd();
+  const routesDir = path.join(cwd, "routes");
+  const deployDir = path.join(cwd, "deploy");
+  fs.mkdirSync(routesDir, { recursive: true });
+  fs.mkdirSync(deployDir, { recursive: true });
+  const frontendManifest = loadFrontendBuildManifest(cwd);
+
+  /** @type {Record<string, string>} */
+  const builtOutDirBySite = {};
+  if (frontendManifest?.data?.sites && Array.isArray(frontendManifest.data.sites)) {
+    for (const site of frontendManifest.data.sites) {
+      if (site?.siteId && site?.outDir) {
+        builtOutDirBySite[site.siteId] = site.outDir;
+      }
+    }
+  }
+
+  /** @type {Record<string, any[]>} */
+  const mountsFromManifest = {};
+  if (frontendManifest?.data?.mounts && typeof frontendManifest.data.mounts === "object") {
+    for (const [siteId, mounts] of Object.entries(frontendManifest.data.mounts)) {
+      if (Array.isArray(mounts)) mountsFromManifest[siteId] = mounts;
+    }
+  }
+
+  const apps = {};
+  for (const [appId, app] of Object.entries(raw.platform.apps)) {
+    const site = resolved.sites?.[appId];
+    const frontend = site?.frontend ? { ...site.frontend } : (app.frontend ? { ...app.frontend } : null);
+    if (frontend && builtOutDirBySite[appId]) {
+      frontend.outDir = builtOutDirBySite[appId];
+    }
+
+    const staticMounts = mountsFromManifest[appId]
+      ? mountsFromManifest[appId]
+      : (() => {
+          if (frontend) {
+            return [{
+              siteId: appId,
+              domains: site?.domains ?? resolveAppDomains(app),
+              basePath: frontend.basePath ?? "/",
+              dir: frontend.outDir,
+              spaFallback: frontend.spaFallback ?? true,
+              cachePolicy: "short",
+            }];
+          }
+          const legacyStatic = site?.staticDir ?? app.static ?? null;
+          if (!legacyStatic) return [];
+          return [{
+            siteId: appId,
+            domains: site?.domains ?? resolveAppDomains(app),
+            basePath: "/static",
+            dir: legacyStatic,
+            spaFallback: false,
+            cachePolicy: "short",
+          }];
+        })();
+
+    apps[appId] = {
+      domains: resolveAppDomains(app),
+      ssl: app.ssl ?? null,
+      static: site?.staticDir ?? app.static ?? null,
+      frontend,
+      staticMounts,
+      services: app.services ?? [],
+    };
+  }
+
+  // Generate nginx config
+  const nginxConfig = generatePlatformNginxConfig({
+    apps,
+    services: resolved.services,
+    hostMeta: resolved.hostMeta,
+    defaultSsl: raw.platform.ssl ?? null,
+    maxBodySize: raw.platform.maxBodySize ?? 10,
+  });
+  fs.writeFileSync(path.join(deployDir, "nginx.conf"), nginxConfig);
+
+  // Generate platform.yaml
+  const manifestWithSites = generatePlatformManifest(raw.platform, resolved.hostMeta, resolved.sites);
+  fs.writeFileSync(path.join(routesDir, "platform.yaml"), manifestWithSites);
+
+  // Generate per-service route manifests
+  let manifestCount = 0;
+  for (const [name, svc] of Object.entries(resolved.services)) {
+    if (svc.type !== "edge") continue;
+    const safeName = name.replace(/:/g, "_");
+    let yaml = `# Auto-generated for ForgePlatform\n`;
+    yaml += `service: ${name}\n`;
+    yaml += `prefix: ${svc.prefix ?? "/"}\n`;
+    if (svc._projectId) yaml += `project_id: ${svc._projectId}\n`;
+    const domain = svc._projectId ? resolved.hostMeta[svc._projectId]?.domain : null;
+    if (domain) yaml += `host: ${domain}\n`;
+    yaml += `\nroutes:\n`;
+    yaml += `  - method: GET\n`;
+    yaml += `    path: ""\n`;
+    yaml += `    handler: index\n`;
+    fs.writeFileSync(path.join(routesDir, `${safeName}.yaml`), yaml);
+    manifestCount++;
+  }
+
+  console.log(`
+  ForgePlatform artifacts generated:
+
+    deploy/nginx.conf         Platform nginx config
+    routes/platform.yaml      Platform manifest for ForgeProxy
+    routes/                   ${manifestCount} service route manifest(s)
+    ${frontendManifest ? `.threadforge/frontend-manifest.json  Frontend build manifest (source)` : "(no frontend manifest found)"}
+
+  ForgeProxy reads ./routes/*.yaml automatically.
+  `);
+}
+
+// ── Main dispatch ────────────────────────────────────────────────────────
+
+export async function cmdPlatform(args) {
+  const subcommand = args[0];
+  const subArgs = args.slice(1);
+
+  switch (subcommand) {
+    case "init":
+      return cmdPlatformInit();
+    case "start":
+      return cmdPlatformStart();
+    case "add":
+      return cmdPlatformAdd(subArgs);
+    case "remove":
+      return cmdPlatformRemove(subArgs);
+    case "status":
+      return cmdPlatformStatus();
+    case "generate":
+      return cmdPlatformGenerate();
+    default:
+      console.log(`
+  ForgePlatform Commands:
+
+    forge platform init              Scaffold a platform project
+    forge platform start             Start the platform
+    forge platform add <name>        Scaffold a new app
+    forge platform remove <id>       Remove an app
+    forge platform status            Show per-app status
+    forge platform generate          Generate nginx + route manifests
+      `);
+  }
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "threadforge",
+  "version": "0.1.0",
+  "description": "Multi-threaded Node.js service runtime framework",
+  "type": "module",
+  "bin": {
+    "forge": "./bin/forge.js"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./service": "./src/services/Service.js",
+    "./config": "./src/core/config.js",
+    "./decorators": "./src/decorators/index.js",
+    "./plugins": "./src/plugins/index.js",
+    "./plugins/redis": "./src/plugins/redis.js",
+    "./plugins/postgres": "./src/plugins/postgres.js",
+    "./ingress": "./src/core/Ingress.js",
+    "./frontend": "./src/frontend/index.js",
+    "./frontend/plugins": "./src/frontend/plugins/index.js",
+    "./internals": "./src/internals.js"
+  },
+  "scripts": {
+    "dev": "node bin/forge.js dev",
+    "start": "node bin/forge.js start",
+    "test": "node --test tests/*.test.js",
+    "test:watch": "node --test --watch tests/*.test.js",
+    "test:coverage": "node --experimental-test-coverage --test tests/*.test.js",
+    "lint": "biome check ."
+  },
+  "keywords": [
+    "microservices",
+    "multi-threaded",
+    "cluster",
+    "multi-process",
+    "ipc",
+    "service-mesh",
+    "service-runtime"
+  ],
+  "author": "ThreadForge Contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ChrisBland/threadforge.git"
+  },
+  "homepage": "https://github.com/ChrisBland/threadforge#readme",
+  "bugs": {
+    "url": "https://github.com/ChrisBland/threadforge/issues"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "shared/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "peerDependencies": {
+    "ioredis": "^5.3.0",
+    "pg": "^8.11.0"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": { "optional": true },
+    "pg": { "optional": true }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.15"
+  }
+}