threadforge 0.1.1 → 0.2.1

package/bin/forge.js

@@ -1,1059 +1,3 @@
 #!/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"];
-const FORGE_PLATFORM_CONFIG_NAMES = ["forge.platform.js", "forge.platform.mjs", "forge.host.js", "forge.host.mjs"];
-
-function resolveConfigSearchNames(commandName = command) {
-  if (["dev", "start", "build", "status", "stop"].includes(commandName)) {
-    return [...FORGE_CONFIG_NAMES, ...FORGE_PLATFORM_CONFIG_NAMES];
-  }
-  return [...FORGE_CONFIG_NAMES];
-}
-
-function printNoConfigError(commandName = command) {
-  const names = resolveConfigSearchNames(commandName);
-  console.error("  Error: No config file found in current directory.");
-  console.error(`  Searched for: ${names.join(", ")}`);
-  console.error("  Run `forge init` to create one, or use `--config <path>` to specify manually.");
-}
-
-async function findConfig(commandName = command) {
-  const searchNames = resolveConfigSearchNames(commandName);
-  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 searchNames) {
-    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(isDev ? "dev" : "start");
-  if (!configPath) {
-    printNoConfigError(isDev ? "dev" : "start");
-    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") {
-    // Use npm dist-tag so generated package.json is directly installable.
-    return { spec: "latest", 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(command).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("build");
-  if (!configPath) {
-    printNoConfigError("build");
-    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("deploy");
-  if (!configPath) {
-    printNoConfigError("deploy");
-    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("generate");
-  if (!configPath) {
-    printNoConfigError("generate");
-    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);
-}
+import { execute } from "@oclif/core";
+await execute({ dir: import.meta.url });