threadforge 0.1.0

package/bin/forge.js

@@ -0,0 +1,1050 @@
+#!/usr/bin/env node
+
+/**
+ * ThreadForge CLI
+ *
+ * Commands:
+ *   forge dev              - Start in development mode with hot reload
+ *   forge start            - Start in production mode
+ *   forge build            - Build frontend sites via frontend plugins
+ *   forge stop             - Stop a running supervisor (SIGTERM)
+ *   forge init [dir]       - Scaffold a new ThreadForge project
+ *   forge status           - Show runtime status (connects to metrics endpoint)
+ *
+ * TODO: implement `forge scale <svc> <n>` and `forge restart <svc>` commands
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { loadConfig } from "../src/core/config.js";
+import { Supervisor } from "../src/core/Supervisor.js";
+import { bindFrontendDevCleanup, wrapShutdownWithCleanup } from "../src/frontend/FrontendDevLifecycle.js";
+import { resolveFrontendSites, resolveSitesMap } from "../src/frontend/SiteResolver.js";
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+const FORGE_CONFIG_NAMES = ["forge.config.js", "forge.config.mjs", "threadforge.config.js", "threadforge.config.mjs"];
+
+async function findConfig() {
+  const cwd = process.cwd();
+
+  // Check for --config flag
+  const configIdx = args.indexOf("--config");
+  if (configIdx !== -1 && args[configIdx + 1]) {
+    const resolved = path.resolve(cwd, args[configIdx + 1]);
+    if (resolved !== cwd && !resolved.startsWith(cwd + path.sep)) {
+      console.error("Error: Config path must be within the project directory");
+      process.exit(1);
+    }
+    return resolved;
+  }
+
+  for (const name of FORGE_CONFIG_NAMES) {
+    const fullPath = path.join(cwd, name);
+    try {
+      await fs.promises.access(fullPath);
+      return fullPath;
+    } catch {}
+  }
+
+  return null;
+}
+
+async function stopFrontendDevHandle(handle) {
+  if (!handle) return;
+  if (typeof handle === "function") {
+    await handle();
+    return;
+  }
+
+  for (const method of ["dispose", "stop", "close", "kill"]) {
+    if (typeof handle[method] === "function") {
+      await handle[method]();
+      return;
+    }
+  }
+
+  if (handle.process?.pid && typeof handle.process.kill === "function") {
+    handle.process.kill("SIGTERM");
+  }
+}
+
+async function startFrontendDevSessions(config) {
+  const frontendSites = resolveFrontendSites(config);
+  if (frontendSites.length === 0) {
+    return null;
+  }
+
+  const { FrontendPluginOrchestrator } = await import("../src/frontend/FrontendPluginOrchestrator.js");
+  const orchestrator = new FrontendPluginOrchestrator();
+  const frontendPlugins = config.frontendPlugins ?? [];
+
+  orchestrator.register(frontendPlugins);
+  await orchestrator.validateAll({ logger: console, mode: "dev", config });
+  await orchestrator.registerAll({ logger: console, mode: "dev", config });
+
+  if (orchestrator.plugins.size === 0) {
+    throw new Error(
+      "Frontend sites are configured, but no frontendPlugins are registered in config.",
+    );
+  }
+
+  const handles = [];
+  let disposed = false;
+  const cleanup = async () => {
+    if (disposed) return;
+    disposed = true;
+    for (const session of [...handles].reverse()) {
+      try {
+        await stopFrontendDevHandle(session.handle);
+      } catch (err) {
+        console.warn(`  [dev] Failed to stop frontend session "${session.siteId}": ${err.message}`);
+      }
+    }
+    await orchestrator.disposeAll({ logger: console, mode: "dev", config });
+  };
+
+  let started = 0;
+  try {
+    for (const site of frontendSites) {
+      const plugin = orchestrator.resolvePluginForSite(site);
+      if (!plugin.capabilities.includes("frontend-dev")) {
+        console.log(`  [dev] Skipping frontend site "${site.siteId}" (${plugin.name} has no frontend-dev capability)`);
+        continue;
+      }
+
+      const handle = await orchestrator.devSite(site, { logger: console, mode: "dev", config });
+      handles.push({ siteId: site.siteId, plugin: plugin.name, handle });
+      started++;
+    }
+  } catch (err) {
+    await cleanup();
+    throw err;
+  }
+
+  if (started > 0) {
+    console.log(`  [dev] Frontend dev sessions started: ${started}`);
+  }
+
+  return { cleanup };
+}
+
+async function cmdStart(isDev = false) {
+  const configPath = await findConfig();
+  if (!configPath) {
+    console.error("  Error: No config file found in current directory.");
+    console.error(`  Searched for: ${FORGE_CONFIG_NAMES.join(", ")}`);
+    console.error("  Run `forge init` to create one, or use `--config <path>` to specify manually.");
+    process.exit(1);
+  }
+
+  let config;
+  try {
+    const configUrl = pathToFileURL(configPath).href;
+    config = await loadConfig(configUrl);
+    config._configUrl = configUrl; // workers reimport this for plugins
+  } catch (err) {
+    console.error(`\n  \u2717 Error loading ${path.basename(configPath)}:`);
+    console.error(`    ${err.message}`);
+    if (err.code === "ERR_MODULE_NOT_FOUND") {
+      console.error("  Hint: Check your import paths and run `npm install` to ensure dependencies are installed.");
+    }
+    process.exit(1);
+  }
+
+  if (isDev) {
+    config.watch = true;
+  }
+
+  const fileWatchers = [];
+  const closeDevWatchers = async () => {
+    for (const watcher of fileWatchers.splice(0)) {
+      try {
+        watcher.close();
+      } catch {}
+    }
+  };
+
+  let frontendDev = null;
+  if (isDev) {
+    try {
+      frontendDev = await startFrontendDevSessions(config);
+    } catch (err) {
+      console.error(`  Frontend dev setup failed: ${err.message}`);
+      process.exit(1);
+    }
+  }
+
+  // D11: Warn when `connects` targets undefined services
+  if (config.services) {
+    const serviceNames = new Set(Object.keys(config.services));
+    for (const [name, svc] of Object.entries(config.services)) {
+      if (Array.isArray(svc.connects)) {
+        for (const target of svc.connects) {
+          if (!serviceNames.has(target)) {
+            console.warn(`  Warning: service "${name}" connects to "${target}", which is not defined in the config.`);
+          }
+        }
+      }
+    }
+  }
+
+  const supervisor = new Supervisor(config);
+  const devLifecycle = isDev
+    ? bindFrontendDevCleanup(
+      async () => {
+        await closeDevWatchers();
+        if (frontendDev?.cleanup) {
+          await frontendDev.cleanup();
+        }
+      },
+      { logger: console },
+    )
+    : null;
+  if (devLifecycle) {
+    wrapShutdownWithCleanup(supervisor, devLifecycle.runCleanup);
+  }
+  try {
+    await supervisor.start();
+  } catch (err) {
+    if (devLifecycle) {
+      await devLifecycle.runCleanup();
+      devLifecycle.dispose();
+    }
+    console.error(`\n  \u2717 Startup failed:`);
+    console.error(`    ${err.message}`);
+    process.exit(1);
+  }
+
+  // D15: In dev mode, watch for file changes and log them
+  if (isDev) {
+    const watchDirs = new Set();
+    for (const svc of Object.values(config.services)) {
+      if (svc.entry) {
+        const entryDir = path.dirname(path.resolve(process.cwd(), svc.entry));
+        watchDirs.add(entryDir);
+      }
+    }
+    for (const dir of watchDirs) {
+      try {
+        const watcher = fs.watch(dir, { recursive: true }, (eventType, filename) => {
+          if (filename && (filename.endsWith('.js') || filename.endsWith('.mjs') || filename.endsWith('.ts'))) {
+            console.log(`  [dev] File change detected: ${filename} (${eventType})`);
+          }
+        });
+        fileWatchers.push(watcher);
+        // Prevent dev file-watch handles from blocking process exit during shutdown.
+        if (typeof watcher.unref === "function") watcher.unref();
+      } catch {
+        // Directory may not exist or be unwatchable — skip silently
+      }
+    }
+  }
+}
+
+function detectLocalThreadforgeDependency(cwd) {
+  const linkedPackagePath = path.join(cwd, "node_modules", "threadforge");
+  try {
+    const stat = fs.lstatSync(linkedPackagePath);
+    if (!stat.isSymbolicLink()) return null;
+
+    const realPath = fs.realpathSync(linkedPackagePath);
+    const relativePath = path.relative(cwd, realPath) || ".";
+    const normalized = (relativePath.startsWith(".") ? relativePath : `./${relativePath}`).split(path.sep).join("/");
+    return `file:${normalized}`;
+  } catch {
+    return null;
+  }
+}
+
+function resolveInitDependency(cwd, source = "auto") {
+  if (source === "npm") {
+    return { spec: "threadforge", label: "npm" };
+  }
+
+  if (source === "github") {
+    return { spec: "github:ChrisBland/threadforge", label: "github" };
+  }
+
+  if (source === "local" || source === "auto") {
+    const localSpec = detectLocalThreadforgeDependency(cwd);
+    if (localSpec) {
+      return { spec: localSpec, label: "local-link" };
+    }
+    if (source === "local") {
+      throw new Error('No linked local ThreadForge found at ./node_modules/threadforge. Run "npm link threadforge" first.');
+    }
+  }
+
+  return { spec: "github:ChrisBland/threadforge", label: "github" };
+}
+
+function parseInitArgs(initArgs = []) {
+  let targetDir = null;
+  let source = "auto";
+
+  for (let i = 0; i < initArgs.length; i++) {
+    const token = initArgs[i];
+
+    if (token === "--source") {
+      const value = initArgs[i + 1];
+      if (!value) {
+        console.error("  Error: --source requires a value: auto, github, local, npm");
+        process.exit(1);
+      }
+      source = value.toLowerCase();
+      i++;
+      continue;
+    }
+
+    if (token.startsWith("--source=")) {
+      source = token.slice("--source=".length).toLowerCase();
+      continue;
+    }
+
+    if (token === "--local") {
+      source = "local";
+      continue;
+    }
+
+    if (token === "--help" || token === "-h") {
+      console.log("\n  Usage: forge init [dir] [--source auto|github|local|npm]\n");
+      process.exit(0);
+    }
+
+    if (token.startsWith("-")) {
+      console.error(`  Unknown init option: ${token}`);
+      process.exit(1);
+    }
+
+    if (targetDir !== null) {
+      console.error(`  Unexpected argument: ${token}`);
+      console.error("  Usage: forge init [dir] [--source auto|github|local|npm]");
+      process.exit(1);
+    }
+
+    targetDir = token;
+  }
+
+  if (!["auto", "github", "local", "npm"].includes(source)) {
+    console.error(`  Invalid --source value: ${source}`);
+    console.error("  Valid values: auto, github, local, npm");
+    process.exit(1);
+  }
+
+  return { targetDir, source };
+}
+
+async function cmdInit(targetDir, options = {}) {
+  let cwd = process.cwd();
+  const source = options.source ?? "auto";
+
+  if (targetDir) {
+    cwd = path.resolve(cwd, targetDir);
+    fs.mkdirSync(cwd, { recursive: true });
+  }
+
+  const configPath = path.join(cwd, "forge.config.js");
+
+  if (fs.existsSync(configPath)) {
+    console.error("  forge.config.js already exists in this directory.");
+    process.exit(1);
+  }
+
+  let dependency;
+  let dependencySourceLabel;
+  try {
+    const resolved = resolveInitDependency(cwd, source);
+    dependency = resolved.spec;
+    dependencySourceLabel = resolved.label;
+  } catch (err) {
+    console.error(`  Error: ${err.message}`);
+    process.exit(1);
+  }
+
+  // Create package.json if it doesn't exist
+  const pkgPath = path.join(cwd, "package.json");
+  if (!fs.existsSync(pkgPath)) {
+    const projectName = path.basename(cwd);
+    fs.writeFileSync(
+      pkgPath,
+      `${JSON.stringify(
+        {
+          name: projectName,
+          version: "1.0.0",
+          type: "module",
+          scripts: {
+            dev: "forge dev",
+            start: "forge start",
+          },
+          dependencies: {
+            threadforge: dependency,
+          },
+        },
+        null,
+        2,
+      )}\n`,
+    );
+  }
+
+  // Always use package name for imports to ensure generated code works after npm install
+  const configImportPath = "threadforge";
+  const serviceImportPath = "threadforge";
+
+  // Create project structure
+  const dirs = ["services"];
+  for (const dir of dirs) {
+    fs.mkdirSync(path.join(cwd, dir), { recursive: true });
+  }
+
+  // Write config file
+  fs.writeFileSync(
+    configPath,
+    `import { defineServices } from '${configImportPath}';
+
+export default defineServices({
+  api: {
+    entry: './services/api.js',
+    type: 'edge',
+    port: 3000,
+    threads: 'auto',
+    weight: 2,
+    // connects: ['otherService'],  // add services this one calls
+  },
+});
+`,
+  );
+
+  // Write example service
+  fs.writeFileSync(
+    path.join(cwd, "services", "api.js"),
+    `import { Service } from '${serviceImportPath}';
+
+export default class ApiService extends Service {
+  static contract = {
+    expose: ['getGreeting'],
+    routes: [
+      { method: 'GET', path: '/health', handler: 'healthCheck' },
+      { method: 'GET', path: '/hello/:name', handler: 'hello' },
+    ],
+  };
+
+  async onStart(ctx) {
+    if (ctx.workerId === 0) {
+      ctx.logger.info('API service ready');
+    }
+  }
+
+  async healthCheck() {
+    return { status: 'ok', worker: this.ctx.workerId };
+  }
+
+  async hello(body, params) {
+    return { message: \`Hello, \${params.name}!\`, worker: this.ctx.workerId };
+  }
+
+  async getGreeting(name) {
+    return { message: \`Hello, \${name}!\` };
+  }
+
+  async onMessage(from, payload) {
+    this.ctx.logger.info(\`Message from \${from}\`, payload);
+  }
+}
+`,
+  );
+
+  const shouldSuggestCd = Boolean(targetDir) && path.resolve(process.cwd(), targetDir) !== process.cwd();
+  const cdStep = shouldSuggestCd ? `cd "${path.basename(cwd)}" && ` : "";
+  const usingLocalLink = dependencySourceLabel === "local-link";
+  console.log(`
+  \u26A1 ThreadForge project initialized!
+
+  Created:
+    forge.config.js        - Service configuration
+    services/api.js        - Example API service
+
+  Dependency source: ${dependency}
+
+  Next steps:
+    1. ${cdStep}npm install
+    2. npm run dev
+    3. curl http://localhost:3000/health
+
+  ${usingLocalLink ? "" : "Tip: for local linked development, run `forge init [dir] --source local` after `npm link threadforge`."}
+  `);
+}
+
+async function resolveMetricsPort() {
+  const config = await findConfig().then(async (p) => {
+    if (!p) return null;
+    try { return await loadConfig(pathToFileURL(p).href); } catch { return null; }
+  });
+  return config?.metricsPort ?? parseInt(process.env.FORGE_METRICS_PORT || "9090", 10);
+}
+
+async function cmdStatus() {
+  const metricsPort = await resolveMetricsPort();
+  try {
+    const res = await fetch(`http://localhost:${metricsPort}/status`);
+    const data = await res.json();
+
+    // M-CLI-2: --json flag outputs raw JSON and exits
+    if (args.includes("--json")) {
+      console.log(JSON.stringify(data, null, 2));
+      return;
+    }
+
+    console.log("");
+    console.log("  \u26A1 ThreadForge Status");
+    console.log("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+    console.log(`  Uptime: ${Math.floor(data.uptime)}s`);
+    console.log("");
+
+    console.log("  \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510");
+    console.log("  \u2502 Group            \u2502 Services                  \u2502 Port  \u2502 Workers \u2502 PIDs             \u2502");
+    console.log("  \u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524");
+
+    for (const pg of data.processGroups) {
+      const group = pg.group.replace("_isolated:", "").padEnd(16);
+      const svcNames = pg.services.map((s) => s.name).join(", ");
+      const services = svcNames.substring(0, 25).padEnd(25);
+      const edgeService = pg.services.find((s) => s.type === "edge");
+      const port = edgeService ? String(edgeService.port).padEnd(5) : "  \u2014  ";
+      const workers = String(pg.workers).padEnd(7);
+      const pidList = pg.pids.join(", ");
+      const pids = (pidList.length > 16 ? `${pg.pids.length} workers` : pidList).padEnd(16);
+      console.log(`  \u2502 ${group} \u2502 ${services} \u2502 ${port} \u2502 ${workers} \u2502 ${pids} \u2502`);
+    }
+
+    console.log("  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518");
+    console.log(`  CPUs: ${data.totalCpus} total`);
+    console.log("");
+  } catch (_err) {
+    console.error("  Could not connect to ThreadForge runtime.");
+    console.error("");
+    console.error("  Checklist:");
+    console.error("    - Is the runtime running? (forge start / forge dev)");
+    console.error(`    - Is the metrics port correct? (currently ${metricsPort})`);
+    console.error("    - Is a firewall blocking the connection?");
+    process.exit(1);
+  }
+}
+
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    if (err.code === "ESRCH") return false;
+    if (err.code === "EPERM") return true;
+    throw err;
+  }
+}
+
+async function cmdStop() {
+  let pid = null;
+
+  // H4: Try reading PID from .forge.pid first
+  const pidFilePath = path.join(process.cwd(), ".forge.pid");
+  try {
+    const pidStr = fs.readFileSync(pidFilePath, "utf8").trim();
+    const filePid = Number(pidStr);
+    if (Number.isInteger(filePid) && filePid > 1 && isProcessAlive(filePid)) {
+      pid = filePid;
+    }
+  } catch {}
+
+  // Fall back to metrics endpoint if PID file is missing or stale
+  if (!pid) {
+    const metricsPort = await resolveMetricsPort();
+    let data;
+    try {
+      const res = await fetch(`http://localhost:${metricsPort}/status`);
+      if (!res.ok) throw new Error(`status endpoint returned ${res.status}`);
+      data = await res.json();
+    } catch (_err) {
+      console.error("  Could not connect to ThreadForge runtime.");
+      console.error("  Ensure it is running and the metrics port is correct.");
+      process.exit(1);
+    }
+
+    pid = Number(data?.supervisorPid);
+    if (!Number.isInteger(pid) || pid < 2) {
+      console.error("  Could not determine supervisor PID from /status.");
+      process.exit(1);
+    }
+  }
+  if (pid === process.pid) {
+    console.error("  Refusing to signal current CLI process.");
+    process.exit(1);
+  }
+
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch (err) {
+    if (err.code === "ESRCH") {
+      console.log(`  Runtime already stopped (PID ${pid} not found).`);
+      return;
+    }
+    if (err.code === "EPERM") {
+      console.error(`  Permission denied stopping PID ${pid}.`);
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  const waitMs = 15000;
+  const deadline = Date.now() + waitMs;
+  while (Date.now() < deadline) {
+    if (!isProcessAlive(pid)) {
+      console.log(`  \u2713 Stopped ThreadForge supervisor (PID ${pid}).`);
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+
+  // Final short settle window to reduce false "still draining" reports
+  // when the process exits right at the timeout boundary.
+  const settleMs = 1000;
+  const settleDeadline = Date.now() + settleMs;
+  while (Date.now() < settleDeadline) {
+    if (!isProcessAlive(pid)) {
+      console.log(`  \u2713 Stopped ThreadForge supervisor (PID ${pid}).`);
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+
+  console.log(`  Shutdown in progress for supervisor PID ${pid} (waited ${Math.floor(waitMs / 1000)}s).`);
+  console.log("  It may still be draining (or may have exited moments ago). Run `forge status` to confirm.");
+}
+
+function printHelp() {
+  console.log(`
+  \u26A1 ThreadForge CLI
+
+  Usage: forge <command> [options]
+
+  Commands:
+    init [dir]              Scaffold a new ThreadForge project
+    dev                     Start in development mode
+    start                   Start in production mode
+    build                   Build frontend sites via frontend plugins
+    stop                    Stop a running ThreadForge supervisor
+    status                  Show runtime status
+    generate                Generate route manifests for ForgeProxy
+    deploy                  Generate multi-machine deployment artifacts
+    scale <svc> <n>         Scale a service (not yet implemented)
+    restart <svc>           Restart a service (not yet implemented)
+    host <subcommand>       Multi-project hosting (init, start, status, ...)
+    platform <subcommand>   Platform mode (init, start, add, generate, ...)
+
+  Options:
+    --config <path>         Path to config file (default: forge.config.js)
+    --source <mode>         Init dependency source: auto|github|local|npm
+    --local                 Shorthand for: forge init --source local
+    --version, -v           Show version number
+    --help                  Show this help message
+
+  Examples:
+    forge init
+    forge init my-app
+    forge init . --source local
+    forge dev
+    forge start --config ./my-config.js
+    forge build
+    forge stop
+    forge generate
+    forge status
+  `);
+}
+
+async function cmdBuild() {
+  const configPath = await findConfig();
+  if (!configPath) {
+    console.error("  Error: No config file found in current directory.");
+    console.error(`  Searched for: ${FORGE_CONFIG_NAMES.join(", ")}`);
+    console.error("  Run `forge init` to create one, or use `--config <path>` to specify manually.");
+    process.exit(1);
+  }
+
+  let config;
+  try {
+    const configUrl = pathToFileURL(configPath).href;
+    config = await loadConfig(configUrl);
+  } catch (err) {
+    console.error(`\n  ✗ Error loading ${path.basename(configPath)}:`);
+    console.error(`    ${err.message}`);
+    process.exit(1);
+  }
+
+  const sitesMap = resolveSitesMap(config);
+  const frontendSites = Object.values(sitesMap).filter((site) => site?.frontend);
+  if (frontendSites.length === 0) {
+    console.log("  No frontend sites configured. Nothing to build.");
+    return;
+  }
+
+  const { FrontendPluginOrchestrator } = await import("../src/frontend/FrontendPluginOrchestrator.js");
+  const orchestrator = new FrontendPluginOrchestrator();
+  const frontendPlugins = config.frontendPlugins ?? [];
+
+  try {
+    orchestrator.register(frontendPlugins);
+    await orchestrator.validateAll({ logger: console });
+    await orchestrator.registerAll({ logger: console });
+  } catch (err) {
+    console.error(`  Frontend plugin setup failed: ${err.message}`);
+    process.exit(1);
+  }
+
+  if (orchestrator.plugins.size === 0) {
+    console.error("  Frontend sites are configured, but no frontendPlugins are registered in config.");
+    process.exit(1);
+  }
+
+  const results = [];
+  const mountsBySite = {};
+  let failures = 0;
+
+  try {
+    console.log(`\n  ⚡ Building frontend sites (${frontendSites.length})\n`);
+
+    for (const site of frontendSites) {
+      const pluginName = site.frontend.plugin;
+      try {
+        console.log(`  • ${site.siteId} (${pluginName})`);
+        const result = await orchestrator.buildSite(site, { logger: console });
+        const mounts = await orchestrator.staticMounts(site, { logger: console });
+        mountsBySite[site.siteId] = mounts;
+        results.push({
+          siteId: site.siteId,
+          plugin: pluginName,
+          outDir: result?.outDir ?? site.frontend.outDir,
+        });
+        console.log(`    ✓ ${result?.outDir ?? site.frontend.outDir}`);
+      } catch (err) {
+        failures++;
+        console.error(`    ✗ ${err.message}`);
+      }
+    }
+  } finally {
+    await orchestrator.disposeAll({ logger: console });
+  }
+
+  const outputDir = path.join(process.cwd(), ".threadforge");
+  fs.mkdirSync(outputDir, { recursive: true });
+  const manifestPath = path.join(outputDir, "frontend-manifest.json");
+  fs.writeFileSync(
+    manifestPath,
+    JSON.stringify(
+      {
+        generatedAt: new Date().toISOString(),
+        sites: results,
+        mounts: mountsBySite,
+      },
+      null,
+      2,
+    ),
+  );
+
+  console.log(`\n  Wrote frontend manifest: ${manifestPath}`);
+  if (failures > 0) {
+    console.error(`  Frontend build completed with ${failures} failure(s).`);
+    process.exit(1);
+  }
+}
+
+async function cmdDeploy() {
+  const configPath = await findConfig();
+  if (!configPath) {
+    console.error("  Error: No config file found in current directory.");
+    console.error(`  Searched for: ${FORGE_CONFIG_NAMES.join(", ")}`);
+    console.error("  Run `forge init` to create one, or use `--config <path>` to specify manually.");
+    process.exit(1);
+  }
+
+  // Look for forge.deploy.js
+  const deployPath = path.join(process.cwd(), "forge.deploy.js");
+  if (!fs.existsSync(deployPath)) {
+    console.log(`  No forge.deploy.js found. Creating a template...`);
+    const template = generateDeployTemplate();
+    fs.writeFileSync(deployPath, template);
+    console.log(`  Created: ${deployPath}`);
+    console.log(`  Edit the manifest with your node addresses, then run 'forge deploy' again.`);
+    return;
+  }
+
+  const { generateAll } = await import("../src/deploy/index.js");
+
+  // Load base config
+  let config;
+  try {
+    const configUrl = pathToFileURL(configPath).href;
+    config = await loadConfig(configUrl);
+  } catch (err) {
+    console.error(`\n  \u2717 Error loading ${path.basename(configPath)}:`);
+    console.error(`    ${err.message}`);
+    if (err.code === "ERR_MODULE_NOT_FOUND") {
+      console.error("  Hint: Check your import paths and run `npm install` to ensure dependencies are installed.");
+    }
+    process.exit(1);
+  }
+
+  // Load deploy manifest
+  let deployMod;
+  try {
+    const deployUrl = pathToFileURL(deployPath).href;
+    deployMod = await import(deployUrl);
+  } catch (err) {
+    console.error(`\n  \u2717 Error loading ${path.basename(deployPath)}:`);
+    console.error(`    ${err.message}`);
+    process.exit(1);
+  }
+  const manifest = deployMod.default ?? deployMod;
+
+  const outputDir = path.join(process.cwd(), "deploy");
+  const isDryRun = args.includes("--dry-run");
+
+  try {
+    if (isDryRun) {
+      // M-CLI-3: Dry run — validate and show what would be generated without writing
+      const { loadManifest, generateNodeConfigs } = await import("../src/deploy/index.js");
+      const validated = loadManifest(manifest, config.services);
+
+      console.log(`\n  \u26A1 Dry run — no files will be written\n`);
+      console.log(`  Nodes:`);
+      for (const [nodeName, nodeDef] of Object.entries(manifest.nodes)) {
+        console.log(`    ${nodeName.padEnd(16)} ${nodeDef.host.padEnd(16)} [${nodeDef.services.join(", ")}]`);
+      }
+
+      const nodeNames = Object.keys(manifest.nodes);
+      const files = [
+        ...nodeNames.map((n) => `${n}/forge.config.js`),
+        "docker-compose.yml",
+        "nginx.conf",
+        ...nodeNames.map((n) => `forge-${n}.service`),
+        ...nodeNames.map((n) => `${n}.env`),
+        "deploy.sh",
+        ".env.example",
+        ".gitignore",
+      ];
+
+      console.log(`\n  Files that WOULD be generated:`);
+      for (const file of files) {
+        console.log(`    deploy/${file}`);
+      }
+      return;
+    }
+
+    const result = generateAll(manifest, config.services, outputDir);
+
+    console.log(`\n  \u26A1 Deployment artifacts generated\n`);
+    console.log(`  Nodes:`);
+    for (const node of result.nodes) {
+      const nodeDef = manifest.nodes[node];
+      console.log(`    ${node.padEnd(16)} ${nodeDef.host.padEnd(16)} [${nodeDef.services.join(", ")}]`);
+    }
+
+    console.log(`\n  Files:`);
+    for (const file of result.files) {
+      console.log(`    deploy/${file}`);
+    }
+
+    console.log(`\n  Next steps:`);
+    console.log(`    1. Review the generated configs in ./deploy/`);
+    console.log(`    2. Test locally:  docker compose -f deploy/docker-compose.yml up`);
+    console.log(`    3. Deploy:        ./deploy/deploy.sh`);
+    console.log(`    4. Rolling deploy: ./deploy/deploy.sh --rolling`);
+  } catch (err) {
+    console.error(`  Error: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+function generateDeployTemplate() {
+  return `// forge.deploy.js \u2014 Multi-machine deployment manifest
+// Edit this file with your node addresses, then run: forge deploy
+
+export default {
+  cluster: 'my-saas',
+
+  nodes: {
+    'web-1': {
+      host: '10.0.1.10',
+      services: ['gateway'],
+      role: 'edge',
+    },
+    'api-1': {
+      host: '10.0.1.20',
+      services: ['users'],
+      role: 'api',
+    },
+    'worker-1': {
+      host: '10.0.1.30',
+      services: ['notifications'],
+      role: 'worker',
+    },
+  },
+
+  registry: 'multicast',
+  httpBasePort: 4000,
+  metricsPort: 9090,
+};
+`;
+}
+
+async function cmdGenerate() {
+  const configPath = await findConfig();
+  if (!configPath) {
+    console.error("  Error: No config file found in current directory.");
+    console.error(`  Searched for: ${FORGE_CONFIG_NAMES.join(", ")}`);
+    console.error("  Run `forge init` to create one, or use `--config <path>` to specify manually.");
+    process.exit(1);
+  }
+
+  const { getContract } = await import("../src/decorators/index.js");
+  const { generateRouteManifest } = await import("../src/deploy/RouteManifestGenerator.js");
+
+  let config;
+  try {
+    const configUrl = pathToFileURL(configPath).href;
+    config = await loadConfig(configUrl);
+  } catch (err) {
+    console.error(`\n  \u2717 Error loading configuration:`);
+    console.error(`    ${err.message}`);
+    process.exit(1);
+  }
+
+  // Load all service classes to read their contracts
+  const serviceClasses = new Map();
+  for (const [name, svc] of Object.entries(config.services)) {
+    if (!svc.entry) continue;
+    try {
+      const entryPath = path.resolve(process.cwd(), svc.entry);
+      const entryUrl = pathToFileURL(entryPath).href;
+      const mod = await import(entryUrl);
+      serviceClasses.set(name, mod.default ?? mod);
+    } catch (err) {
+      console.warn(`  \u26A0  Could not load ${name}: ${err.message}`);
+    }
+  }
+
+  // Create output directory
+  const routesDir = path.join(process.cwd(), "routes");
+  fs.mkdirSync(routesDir, { recursive: true });
+
+  let routeManifests = 0;
+
+  for (const [name, ServiceClass] of serviceClasses) {
+    const contract = getContract(ServiceClass);
+    if (!contract || contract.methods.size === 0) continue;
+
+    // Generate route manifest for ForgeProxy
+    const svcConfig = config.services[name] ?? {};
+    const manifest = generateRouteManifest(name, ServiceClass, svcConfig);
+    if (manifest) {
+      const manifestPath = path.join(routesDir, `${name}.yaml`);
+      fs.writeFileSync(manifestPath, manifest);
+      routeManifests++;
+    }
+
+    console.log(`  \u2713 ${name}`);
+    if (manifest) console.log(`      routes/${name}.yaml`);
+  }
+
+  if (routeManifests === 0) {
+    console.log("  No services with contracts found. Add static contract to your services.");
+  } else {
+    console.log(`\n  Generated ${routeManifests} route manifest(s):`);
+    console.log(`    Routes: ./routes/ (${routeManifests} manifests for ForgeProxy)`);
+    console.log(`\n  ForgeProxy reads ./routes/*.yaml automatically on startup.`);
+  }
+}
+
+// -- Main --
+
+if (args.includes('--version') || args.includes('-v')) {
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+  console.log(`threadforge v${pkg.version}`);
+  process.exit(0);
+}
+
+switch (command) {
+  case "dev":
+    cmdStart(true);
+    break;
+
+  case "start":
+    cmdStart(false);
+    break;
+
+  case "build":
+    cmdBuild();
+    break;
+
+  case "init":
+    {
+      const { targetDir, source } = parseInitArgs(args.slice(1));
+      cmdInit(targetDir, { source });
+    }
+    break;
+
+  case "status":
+    cmdStatus();
+    break;
+
+  case "stop":
+    cmdStop();
+    break;
+
+  case "generate":
+    cmdGenerate();
+    break;
+
+  case "deploy":
+    cmdDeploy();
+    break;
+
+  case "scale":
+    console.error("  `forge scale` is not yet implemented.");
+    console.error("  To scale a service, update the `threads` field in your config and restart.");
+    console.error("  Auto-scaling recommendations are available via ScaleAdvisor (see `forge status`).");
+    process.exit(1);
+    break;
+
+  case "restart":
+    console.error("  `forge restart` is not yet implemented.");
+    console.error("  To restart, run `forge stop` followed by `forge start`.");
+    console.error("  For zero-downtime restarts, use a process manager (systemd, pm2) or rolling deploy.");
+    process.exit(1);
+    break;
+
+  case "host": {
+    const { cmdHost } = await import("./host-commands.js");
+    cmdHost(args.slice(1));
+    break;
+  }
+
+  case "platform": {
+    const { cmdPlatform } = await import("./platform-commands.js");
+    cmdPlatform(args.slice(1));
+    break;
+  }
+
+  case "help":
+  case "--help":
+  case "-h":
+  case undefined:
+    printHelp();
+    break;
+
+  default:
+    console.error(`  Unknown command: ${command}`);
+    printHelp();
+    process.exit(1);
+}