threadforge 0.1.1 → 0.2.1

package/dist/deploy/index.js

@@ -0,0 +1,918 @@
+/**
+ * Deployment System
+ *
+ * The problem: you have 8 services and 3 machines. You need to
+ * decide what runs where, generate the right configs for each
+ * machine, ensure discovery works, handle rolling deploys, and
+ * do it all without the developer manually editing addresses.
+ *
+ * From a manifest, `forge deploy` generates:
+ *
+ *   1. Per-node forge.config.js files
+ *   2. Docker Compose for local dev
+ *   3. Systemd unit files for production
+ *   4. HTTP-based inter-service communication configs
+ *   5. Deployment scripts (rsync + restart)
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { RegistryMode, ServiceType } from "../core/config-enums.js";
+import { resolveAppDomains } from "../core/platform-config.js";
+import { buildNginxServiceMap, buildNginxWebSocketRoutes, generateNginxConfig, generatePlatformNginxConfig, } from "./NginxGenerator.js";
+import { generatePlatformManifest } from "./PlatformManifestGenerator.js";
+// ── Secrets validation ────────────────────────────────────────
+/**
+ * Required environment variables for production deployments.
+ * `forge deploy --check-secrets` verifies these are set and non-empty.
+ */
+const REQUIRED_SECRETS = [
+    "DATABASE_URL",
+    "REDIS_URL",
+    "JWT_SECRET",
+    "FORGE_CLUSTER_SECRET",
+];
+/**
+ * Validate that required secrets are set in the environment.
+ * Returns a result object with missing and warning lists.
+ */
+export function checkSecrets(env = process.env) {
+    const missing = [];
+    const warnings = [];
+    for (const key of REQUIRED_SECRETS) {
+        const value = env[key];
+        if (!value || value.trim() === "") {
+            missing.push(key);
+        }
+    }
+    // Warn about insecure default values
+    if (env.JWT_SECRET && (env.JWT_SECRET === "CHANGE_ME_BEFORE_DEPLOY" || env.JWT_SECRET === "secret")) {
+        warnings.push("JWT_SECRET is set to an insecure default value");
+    }
+    if (env.NODE_ENV !== "production") {
+        warnings.push("NODE_ENV is not set to 'production'");
+    }
+    return {
+        ok: missing.length === 0,
+        missing,
+        warnings,
+    };
+}
+// ── Port assignment helper ────────────────────────────────────
+/**
+ * Assign HTTP ports to all services across all nodes.
+ *
+ * Edge services keep their configured port; internal/background services
+ * get sequential ports starting from httpBasePort, skipping any already
+ * claimed by edge services on that node.
+ */
+function _assignPorts(manifest, serviceConfigs, httpBasePort) {
+    const servicePorts = {};
+    for (const [nodeName, node] of Object.entries(manifest.nodes)) {
+        const usedPorts = new Set();
+        for (const svcName of node.services) {
+            const existingPort = serviceConfigs[svcName]?.port;
+            if (existingPort)
+                usedPorts.add(existingPort);
+        }
+        let nextPort = httpBasePort;
+        for (const svcName of node.services) {
+            const existingPort = serviceConfigs[svcName]?.port;
+            if (existingPort) {
+                if (!servicePorts[svcName])
+                    servicePorts[svcName] = [];
+                servicePorts[svcName].push({ host: node.host, port: existingPort });
+            }
+            else {
+                while (usedPorts.has(nextPort))
+                    nextPort++;
+                if (nextPort > 65535) {
+                    throw new Error(`Port exhaustion on node "${nodeName}": cannot allocate ports beyond 65535`);
+                }
+                const port = nextPort++;
+                usedPorts.add(port);
+                if (!servicePorts[svcName])
+                    servicePorts[svcName] = [];
+                servicePorts[svcName].push({ host: node.host, port });
+            }
+        }
+    }
+    return servicePorts;
+}
+// ── Input validation for deploy safety ───────────────────────
+const NODE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+const HOSTNAME_RE = /^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)*$/;
+const IPV4_RE = /^(\d{1,3}\.){3}\d{1,3}$/;
+const IPV6_RE = /^[0-9a-fA-F:]+$/;
+const SHELL_METACHAR_RE = /[`$;|&<>(){}[\]\\'"!\s]/;
+function validateNodeName(name) {
+    if (!NODE_NAME_RE.test(name)) {
+        throw new Error(`Invalid node name "${name}": must start with alphanumeric and contain only [a-zA-Z0-9_-]`);
+    }
+}
+function validateHostname(host, nodeName) {
+    // H-DEPLOY-2: Reject hosts with shell metacharacters first
+    if (SHELL_METACHAR_RE.test(host)) {
+        throw new Error(`Invalid host "${host}" for node "${nodeName}": contains shell metacharacters`);
+    }
+    if (HOSTNAME_RE.test(host) || IPV4_RE.test(host) || IPV6_RE.test(host)) {
+        return;
+    }
+    throw new Error(`Invalid host "${host}" for node "${nodeName}": must be a valid hostname, IPv4, or IPv6 address`);
+}
+function validateForgeProxyConfig(forgeProxy) {
+    if (forgeProxy === undefined || forgeProxy === null || forgeProxy === true)
+        return;
+    if (forgeProxy === false) {
+        throw new Error("forgeProxy cannot be false in deploy mode");
+    }
+    if (typeof forgeProxy !== "object" || Array.isArray(forgeProxy)) {
+        throw new Error("forgeProxy must be true or an object in deploy mode");
+    }
+    if (forgeProxy.enabled === false) {
+        throw new Error("forgeProxy.enabled cannot be false in deploy mode");
+    }
+    if (forgeProxy.enabled !== undefined && forgeProxy.enabled !== true) {
+        throw new Error("forgeProxy.enabled must be true when provided");
+    }
+    if (forgeProxy.host !== undefined) {
+        if (typeof forgeProxy.host !== "string" || forgeProxy.host.trim() === "") {
+            throw new Error("forgeProxy.host must be a non-empty string when provided");
+        }
+    }
+    if (forgeProxy.port !== undefined) {
+        if (!Number.isInteger(forgeProxy.port) || forgeProxy.port < 1 || forgeProxy.port > 65535) {
+            throw new Error("forgeProxy.port must be an integer between 1 and 65535");
+        }
+    }
+    if (forgeProxy.keepalive !== undefined) {
+        if (!Number.isInteger(forgeProxy.keepalive) || forgeProxy.keepalive < 1) {
+            throw new Error("forgeProxy.keepalive must be a positive integer");
+        }
+    }
+}
+/**
+ * Load and validate a deployment manifest.
+ */
+export function loadManifest(manifest, serviceConfigs) {
+    validateForgeProxyConfig(manifest?.forgeProxy);
+    if (!manifest.nodes || Object.keys(manifest.nodes).length === 0) {
+        throw new Error("Deployment manifest must define at least one node");
+    }
+    // DEP-M3: Validate httpBasePort range
+    if (manifest.httpBasePort !== undefined) {
+        if (!Number.isInteger(manifest.httpBasePort) || manifest.httpBasePort < 1024 || manifest.httpBasePort > 65000) {
+            throw new Error(`httpBasePort must be an integer between 1024 and 65000, got ${manifest.httpBasePort}`);
+        }
+    }
+    // Validate nodes
+    const allAssigned = new Set();
+    for (const [nodeName, node] of Object.entries(manifest.nodes)) {
+        validateNodeName(nodeName);
+        if (!node.host) {
+            throw new Error(`Node "${nodeName}" is missing a host address`);
+        }
+        validateHostname(node.host, nodeName);
+        if (!node.services || node.services.length === 0) {
+            throw new Error(`Node "${nodeName}" has no services assigned`);
+        }
+        for (const svc of node.services) {
+            allAssigned.add(svc);
+        }
+    }
+    // Check for unassigned services
+    for (const svcName of Object.keys(serviceConfigs)) {
+        if (!allAssigned.has(svcName)) {
+            throw new Error(`Service "${svcName}" from forge.config.js is not assigned to any node. ` +
+                `Add it to a node in forge.deploy.js.`);
+        }
+    }
+    // Build the map: service -> [nodes]
+    const serviceToNodes = {};
+    for (const [nodeName, node] of Object.entries(manifest.nodes)) {
+        for (const svc of node.services) {
+            if (!serviceToNodes[svc])
+                serviceToNodes[svc] = [];
+            serviceToNodes[svc].push({ node: nodeName, host: node.host });
+        }
+    }
+    return {
+        ...manifest,
+        serviceToNode: serviceToNodes, // now an array
+        allServices: Object.keys(serviceConfigs),
+    };
+}
+function serviceTypeToEnumExpr(type) {
+    switch (type ?? ServiceType.INTERNAL) {
+        case ServiceType.EDGE:
+            return "ServiceType.EDGE";
+        case ServiceType.BACKGROUND:
+            return "ServiceType.BACKGROUND";
+        case ServiceType.REMOTE:
+            return "ServiceType.REMOTE";
+        case ServiceType.INTERNAL:
+        default:
+            return "ServiceType.INTERNAL";
+    }
+}
+function registryModeToEnumExpr(mode) {
+    switch (mode ?? RegistryMode.MULTICAST) {
+        case RegistryMode.EMBEDDED:
+            return "RegistryMode.EMBEDDED";
+        case RegistryMode.EXTERNAL:
+            return "RegistryMode.EXTERNAL";
+        case RegistryMode.MULTICAST:
+        default:
+            return "RegistryMode.MULTICAST";
+    }
+}
+/**
+ * Generate per-node forge.config.js files.
+ *
+ * Each node gets a config where:
+ *   - Services it runs are defined with their full config (entry, type, etc.)
+ *   - Services on OTHER nodes are defined as type: 'remote' with HTTP addresses
+ */
+export function generateNodeConfigs(manifest, serviceConfigs, _options = {}) {
+    const configs = new Map();
+    const httpBasePort = manifest.httpBasePort ?? 4000;
+    const registryMode = manifest.registry ?? RegistryMode.MULTICAST;
+    // Global port collision check BEFORE assignment
+    const globalPorts = new Map(); // "nodeName:port" -> service name
+    for (const [nodeName, node] of Object.entries(manifest.nodes)) {
+        for (const svcName of node.services) {
+            const port = serviceConfigs[svcName]?.port;
+            if (port) {
+                const key = `${nodeName}:${port}`;
+                const existing = globalPorts.get(key);
+                if (existing) {
+                    throw new Error(`Port ${port} collision on node "${nodeName}": services "${existing}" and "${svcName}" both claim port ${port}`);
+                }
+                globalPorts.set(key, svcName);
+            }
+        }
+    }
+    const servicePorts = _assignPorts(manifest, serviceConfigs, httpBasePort);
+    // Final duplicate check per node
+    for (const [nodeName, node] of Object.entries(manifest.nodes)) {
+        const nodePorts = node.services
+            .map((s) => servicePorts[s]?.find((e) => e.host === node.host)?.port)
+            .filter(Boolean);
+        const uniquePorts = new Set(nodePorts);
+        if (uniquePorts.size !== nodePorts.length) {
+            // M-DEPLOY-1: Include both service names and node name in collision message
+            const portToServices = {};
+            for (const svc of node.services) {
+                const port = servicePorts[svc]?.find((e) => e.host === node.host)?.port;
+                if (port) {
+                    if (!portToServices[port])
+                        portToServices[port] = [];
+                    portToServices[port].push(svc);
+                }
+            }
+            const dupeDescs = Object.entries(portToServices)
+                .filter(([, svcs]) => svcs.length > 1)
+                .map(([p, svcs]) => `port ${p} (services: ${svcs.join(", ")})`);
+            throw new Error(`Port collision on node "${nodeName}": ${dupeDescs.join("; ")}. Note: ports can be reused across different nodes.`);
+        }
+    }
+    for (const [nodeName, node] of Object.entries(manifest.nodes)) {
+        const overrides = manifest.overrides?.[nodeName] ?? {};
+        let config = `// forge.config.js — Auto-generated for node: ${nodeName}
+// Host: ${node.host} | Role: ${node.role ?? "general"}
+// Generated by: forge deploy
+// Do not edit manually — regenerate with: forge deploy --generate
+
+import { defineServices, RegistryMode, ServiceType } from 'threadforge';
+
+export default defineServices({
+
+  // ── Local services (this node runs these) ──
+`;
+        // Local services
+        for (const svcName of node.services) {
+            const svc = serviceConfigs[svcName];
+            if (!svc) {
+                throw new Error(`Node "${nodeName}" references service "${svcName}" which has no configuration`);
+            }
+            const override = overrides[svcName] ?? {};
+            const merged = { ...svc, ...override };
+            const assignedPort = servicePorts[svcName]?.find((e) => e.host === node.host)?.port;
+            config += `\n  ${svcName}: {\n`;
+            config += `    entry: '${merged.entry}',\n`;
+            config += `    type: ${serviceTypeToEnumExpr(merged.type)},\n`;
+            // All services get an HTTP port in multi-machine mode
+            config += `    port: ${assignedPort},\n`;
+            if (merged.threads) {
+                config += `    threads: ${typeof merged.threads === "string" ? `'${merged.threads}'` : merged.threads},\n`;
+            }
+            if (merged.weight && merged.weight > 1) {
+                config += `    weight: ${merged.weight},\n`;
+            }
+            if (merged.connects && merged.connects.length > 0) {
+                config += `    connects: [${merged.connects.map((c) => `'${c}'`).join(", ")}],\n`;
+            }
+            if (merged.group) {
+                config += `    group: '${merged.group}',\n`;
+            }
+            if (merged.websocket) {
+                config += `    websocket: ${JSON.stringify(merged.websocket)},\n`;
+            }
+            if (merged.routing && merged.routing.strategy !== "round-robin") {
+                config += `    routing: ${JSON.stringify(merged.routing)},\n`;
+            }
+            config += `  },\n`;
+        }
+        // Remote services
+        const remoteServices = manifest.allServices.filter((s) => !node.services.includes(s));
+        if (remoteServices.length > 0) {
+            config += `\n  // ── Remote services (on other machines, via HTTP) ──\n`;
+            for (const svcName of remoteServices) {
+                const remote = servicePorts[svcName]?.[0]; // Use first endpoint as primary
+                if (!remote)
+                    continue;
+                const targetNodes = manifest.serviceToNode[svcName];
+                const targetLabel = targetNodes ? targetNodes.map((n) => n.node).join(", ") : "unknown";
+                config += `\n  ${svcName}: {\n`;
+                config += `    type: ${serviceTypeToEnumExpr(ServiceType.REMOTE)},\n`;
+                config += `    address: 'http://${remote.host}:${remote.port}',`;
+                config += `  // ${targetLabel}\n`;
+                if (servicePorts[svcName]?.length > 1) {
+                    config += `    endpoints: ${JSON.stringify(servicePorts[svcName])},\n`;
+                }
+                config += `  },\n`;
+            }
+        }
+        config += `\n}, {\n`;
+        config += `  registryMode: ${registryModeToEnumExpr(registryMode)},\n`;
+        config += `  host: '${node.host}',\n`;
+        config += `  metricsPort: ${manifest.metricsPort ?? 9090},\n`;
+        config += `});\n`;
+        configs.set(nodeName, config);
+    }
+    return configs;
+}
+/**
+ * Generate Docker Compose for local development that simulates
+ * the multi-machine topology.
+ */
+export function generateDockerCompose(manifest, serviceConfigs) {
+    let compose = `# docker-compose.yml — Auto-generated by forge deploy
+# Simulates multi-machine topology for local development
+
+services:
+`;
+    // Compute HTTP ports using the shared helper
+    const httpBasePort = manifest.httpBasePort ?? 4000;
+    const portMap = _assignPorts(manifest, serviceConfigs, httpBasePort);
+    // Build a flat nodeName:svc -> port lookup for Docker Compose (keyed per-node)
+    const servicePorts = {};
+    for (const [nodeName, node] of Object.entries(manifest.nodes)) {
+        for (const svc of node.services) {
+            const entry = portMap[svc]?.find((e) => e.host === node.host);
+            if (entry)
+                servicePorts[`${nodeName}:${svc}`] = entry.port;
+        }
+    }
+    // Build a service->endpoint map using Docker hostnames instead of IPs
+    const serviceEndpointMap = {};
+    for (const [nn, nd] of Object.entries(manifest.nodes)) {
+        for (const svc of nd.services) {
+            const port = servicePorts[`${nn}:${svc}`];
+            if (port) {
+                if (!serviceEndpointMap[svc])
+                    serviceEndpointMap[svc] = [];
+                serviceEndpointMap[svc].push({ host: nn, port: Number(port), remote: true });
+            }
+        }
+    }
+    for (const [nodeName, node] of Object.entries(manifest.nodes)) {
+        // Build FORGE_SERVICE_ENDPOINTS using Docker hostnames for this node (JSON format)
+        const endpointMap = {};
+        for (const [svc, endpoints] of Object.entries(serviceEndpointMap)) {
+            if (!node.services.includes(svc)) {
+                endpointMap[svc] = endpoints;
+            }
+        }
+        const endpointsEnv = Object.keys(endpointMap).length > 0 ? JSON.stringify(endpointMap) : "";
+        // YAML single-quoted strings escape ' as '' (per YAML spec 7.3.2).
+        // The value is JSON (double-quoted keys/values) so single quotes are
+        // unlikely, but we handle them defensively for correctness.
+        const yamlSafeEndpoints = endpointsEnv.replace(/'/g, "''");
+        compose += `
+  ${nodeName}:
+    build: .
+    hostname: ${nodeName}
+    restart: on-failure
+    env_file: ./.env
+    environment:
+      - FORGE_NODE=${nodeName}
+      - FORGE_HOST=${nodeName}
+      - FORGE_REGION=${manifest.region ?? "local"}${yamlSafeEndpoints ? `\n      - FORGE_SERVICE_ENDPOINTS='${yamlSafeEndpoints}'` : ""}
+    volumes:
+      - ./deploy/${nodeName}/forge.config.js:/app/deploy/${nodeName}/forge.config.js:ro
+    working_dir: /app
+    command: node bin/forge.js start --config ./deploy/${nodeName}/forge.config.js
+    stop_grace_period: 35s
+    healthcheck:
+      test: ["CMD", "wget", "-q", "--spider", "http://localhost:9090/health"]
+      interval: 10s
+      timeout: 3s
+      retries: 3
+      start_period: 30s
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
+    deploy:
+      resources:
+        limits:
+          cpus: "${node.resources?.cpus ?? "2"}"
+          memory: ${node.resources?.memory ?? "2G"}
+`;
+        // Expose HTTP ports for all services (edge + internal with assigned ports)
+        const ports = node.services
+            .map((svc) => ({
+            svc,
+            port: servicePorts[`${nodeName}:${svc}`],
+            type: serviceConfigs[svc]?.type ?? ServiceType.INTERNAL,
+        }))
+            .filter((p) => p.port);
+        if (ports.length > 0) {
+            const edgePorts = ports.filter((p) => p.type === ServiceType.EDGE);
+            const internalPorts = ports.filter((p) => p.type !== ServiceType.EDGE);
+            if (edgePorts.length > 0) {
+                compose += `    ports:\n`;
+                for (const { svc, port } of edgePorts) {
+                    compose += `      - "${port}:${port}"  # ${svc} HTTP\n`;
+                }
+            }
+            if (internalPorts.length > 0) {
+                compose += `    expose:\n`;
+                for (const { svc, port } of internalPorts) {
+                    compose += `      - "${port}"  # ${svc} HTTP (internal)\n`;
+                }
+            }
+        }
+        compose += `    networks:\n`;
+        compose += `      - forge-net\n`;
+    }
+    compose += `
+networks:
+  forge-net:
+    driver: bridge
+`;
+    return compose;
+}
+/**
+ * Generate a systemd service unit file for a node.
+ */
+export function generateSystemdUnit(nodeName, node, manifest) {
+    const endpoints = node.endpoints || {};
+    const envFilePath = `/etc/threadforge/${nodeName}.env`;
+    const _envFileContent = `FORGE_SERVICE_ENDPOINTS=${JSON.stringify(endpoints)}`;
+    // DEP-M1: Configurable resource limits per node
+    const nodeMemory = node.resources?.memory ?? "2G";
+    return `[Unit]
+Description=ThreadForge - ${nodeName}
+After=network-online.target
+Wants=network-online.target
+StartLimitIntervalSec=300
+StartLimitBurst=5
+
+[Service]
+Type=simple
+User=forge
+Group=forge
+WorkingDirectory=/opt/forge
+ExecStart=/usr/bin/node bin/forge.js start --config ./deploy/${nodeName}/forge.config.js
+ExecStop=/bin/kill -SIGTERM $MAINPID
+Restart=always
+RestartSec=5
+TimeoutStopSec=30
+Environment=NODE_ENV=production
+Environment=FORGE_NODE=${nodeName}
+Environment=FORGE_HOST=${node.host}
+Environment=FORGE_REGION=${manifest.region ?? "production"}
+EnvironmentFile=${envFilePath}
+EnvironmentFile=-/etc/threadforge/secrets/${nodeName}.env
+
+# Security hardening
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ReadWritePaths=/opt/forge
+
+# Resource limits
+LimitNOFILE=65536
+MemoryMax=${nodeMemory}
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+/**
+ * Generate the environment file content for a systemd unit.
+ * Write this to /etc/threadforge/<nodeName>.env
+ */
+export function generateSystemdEnvFile(nodeName, node) {
+    const endpoints = node.endpoints || {};
+    return {
+        path: `/etc/threadforge/${nodeName}.env`,
+        content: `FORGE_SERVICE_ENDPOINTS='${JSON.stringify(endpoints).replace(/'/g, "'\\''")}'\n`,
+    };
+}
+/**
+ * Generate a deployment script that syncs code and restarts services.
+ */
+export function generateDeployScript(manifest) {
+    let script = `#!/bin/bash
+# deploy.sh — Auto-generated by forge deploy
+# Usage: ./deploy.sh [node-name]     Deploy to a specific node
+#        ./deploy.sh                  Deploy to all nodes
+#        ./deploy.sh --rolling        Rolling deploy (one at a time)
+#        ./deploy.sh --rollback <node> Rollback a node to latest backup
+
+set -euo pipefail
+
+DEPLOY_DIR="/opt/forge"
+PROJECT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+BACKUP_BASE="/opt/forge/backups"
+
+# ── Rollback helper ──────────────────────────────────────────
+rollback() {
+  local node_host="$1"
+  local node_name="$2"
+  echo "Rolling back \${node_name} (\${node_host})..."
+  local latest
+  latest=$(ssh "forge@\${node_host}" "ls -1t \\"\${BACKUP_BASE}\\" 2>/dev/null | head -1")
+  if [ -z "$latest" ]; then
+    echo "  No backup found for \${node_name}"
+    return 1
+  fi
+  ssh "forge@\${node_host}" "rsync -a \\"\${BACKUP_BASE}/\${latest}/\\" \\"\${DEPLOY_DIR}/\\""
+  ssh "forge@\${node_host}" "sudo systemctl restart forge-\${node_name}"
+  echo "  Rolled back to backup: \${latest}"
+}
+
+`;
+    // Validate node names to prevent shell injection
+    for (const nodeName of Object.keys(manifest.nodes)) {
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(nodeName)) {
+            throw new Error(`Invalid node name "${nodeName}": must contain only alphanumeric characters, hyphens, and underscores`);
+        }
+    }
+    // Node deployment functions
+    for (const [nodeName, node] of Object.entries(manifest.nodes)) {
+        script += `deploy_${nodeName.replace(/-/g, "_")}() {
+  echo "Deploying to ${nodeName} (${node.host})..."
+
+  # Create timestamped backup of current deployment
+  local BACKUP_DIR="\${BACKUP_BASE}/$(date +%Y%m%d-%H%M%S)"
+  ssh "forge@${node.host}" "mkdir -p \\"\${BACKUP_DIR}\\" && rsync -a \\"\${DEPLOY_DIR}/\\" \\"\${BACKUP_DIR}/\\" 2>/dev/null || true"
+
+  # Sync code (excluding node_modules, .git)
+  rsync -azP --delete \\
+    --exclude 'node_modules' \\
+    --exclude '.git' \\
+    --exclude 'deploy/*/node_modules' \\
+    "\${PROJECT_DIR}/" "forge@${node.host}:\${DEPLOY_DIR}/"
+
+  # Install dependencies on remote
+  ssh "forge@${node.host}" "cd \\"\${DEPLOY_DIR}\\" && npm ci --omit=dev"
+
+  # Generate route manifests if needed
+  ssh "forge@${node.host}" "cd \\"\${DEPLOY_DIR}\\" && node bin/forge.js generate --config ./deploy/${nodeName}/forge.config.js" 2>/dev/null || true
+
+  # Restart service
+  ssh "forge@${node.host}" "sudo systemctl restart forge-${nodeName}"
+
+  # Wait for health check
+  echo -n "  Waiting for health..."
+  for i in $(seq 1 30); do
+    if ssh "forge@${node.host}" "curl -sf http://localhost:9090/health" >/dev/null 2>&1; then
+      echo " \u2713 healthy"
+      return 0
+    fi
+    echo -n "."
+    sleep 1
+  done
+  echo " \u2717 FAILED — rolling back..."
+  rollback "${node.host}" "${nodeName}"
+  return 1
+}
+
+`;
+    }
+    // Main dispatch
+    const nodeNames = Object.keys(manifest.nodes);
+    const funcNames = nodeNames.map((n) => `deploy_${n.replace(/-/g, "_")}`);
+    // Build a node->host map for rollback dispatch
+    const nodeHostEntries = Object.entries(manifest.nodes).map(([n, nd]) => `    "${n}") rollback "${nd.host}" "${n}" ;;`);
+    script += `# \u2500\u2500 Main \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\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+if [ "\${1:-}" = "--rollback" ]; then
+  if [ -z "\${2:-}" ]; then
+    echo "Usage: ./deploy.sh --rollback <node-name>"
+    echo "Available: ${nodeNames.join(", ")}"
+    exit 1
+  fi
+  [[ "$2" =~ ^[a-zA-Z0-9_-]+$ ]] || { echo "Invalid node name: $2"; exit 1; }
+  case "$2" in
+${nodeHostEntries.join("\n")}
+    *) echo "Unknown node: $2"; echo "Available: ${nodeNames.join(", ")}"; exit 1 ;;
+  esac
+elif [ "\${1:-}" = "--rolling" ]; then
+  echo "Rolling deploy to ${nodeNames.length} nodes..."
+  for fn in ${funcNames.join(" ")}; do
+    $fn
+    echo "  Draining for 10s..."
+    sleep 10
+  done
+elif [ -n "\${1:-}" ]; then
+  # Validate node name to prevent command injection
+  [[ "$1" =~ ^[a-zA-Z0-9_-]+$ ]] || { echo "Invalid node name: $1"; exit 1; }
+  fn="deploy_\${1//-/_}"
+  if type "$fn" &>/dev/null; then
+    $fn
+  else
+    echo "Unknown node: $1"
+    echo "Available: ${nodeNames.join(", ")}"
+    exit 1
+  fi
+else
+  echo "Deploying to all ${nodeNames.length} nodes in parallel..."
+  PIDS=()
+  ${funcNames.map((fn) => `${fn} & PIDS+=($!)`).join("\n  ")}
+  FAIL=0
+  for pid in "\${PIDS[@]}"; do
+    wait $pid || FAIL=1
+  done
+  if [ $FAIL -ne 0 ]; then
+    echo "ERROR: One or more deployments failed"
+    exit 1
+  fi
+fi
+
+echo "Deploy complete."
+`;
+    return script;
+}
+/**
+ * Generate a Dockerfile for the deployment.
+ */
+export function generateDockerfile(manifest, serviceConfigs) {
+    // Find the first edge service port, or fall back to httpBasePort
+    let httpPort = manifest.httpBasePort ?? 4000;
+    for (const svc of Object.values(serviceConfigs)) {
+        if (svc.type === ServiceType.EDGE && svc.port) {
+            httpPort = svc.port;
+            break;
+        }
+    }
+    return `FROM node:20.11-slim AS base
+RUN apt-get update && apt-get install -y tini && rm -rf /var/lib/apt/lists/*
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --omit=dev
+COPY . .
+ENV NODE_ENV=production
+EXPOSE ${httpPort}
+ENTRYPOINT ["/usr/bin/tini", "--"]
+CMD ["node", "bin/forge.js", "start"]
+`;
+}
+/**
+ * Generate a .dockerignore file.
+ */
+export function generateDockerignore() {
+    return `.git
+node_modules
+forgeproxy/target
+.env
+secrets/
+*.log
+deploy/
+`;
+}
+/**
+ * Generate all deployment artifacts from a manifest.
+ */
+export function generateAll(manifest, serviceConfigs, outputDir) {
+    const validated = loadManifest(manifest, serviceConfigs);
+    // DEP-M4: Write to a temp directory first, then copy on success
+    // to avoid partial output on failure
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "forge-deploy-"));
+    try {
+        // Per-node configs
+        const nodeConfigs = generateNodeConfigs(validated, serviceConfigs);
+        for (const [nodeName, config] of nodeConfigs) {
+            const dir = path.join(tmpDir, nodeName);
+            fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(path.join(dir, "forge.config.js"), config);
+        }
+        // Docker Compose
+        const compose = generateDockerCompose(validated, serviceConfigs);
+        fs.writeFileSync(path.join(tmpDir, "docker-compose.yml"), compose);
+        // Compute endpoint map for systemd env files using shared helper
+        const httpBasePort = validated.httpBasePort ?? 4000;
+        const servicePorts = _assignPorts(validated, serviceConfigs, httpBasePort);
+        // Systemd units + env files
+        for (const [nodeName, node] of Object.entries(validated.nodes)) {
+            // Build endpoint map for this node: remote services -> host:port
+            const endpointMap = {};
+            for (const [svcName, endpoints] of Object.entries(servicePorts)) {
+                if (!node.services.includes(svcName)) {
+                    endpointMap[svcName] = endpoints.map((e) => ({ host: e.host, port: Number(e.port), remote: true }));
+                }
+            }
+            const nodeWithEndpoints = { ...node, endpoints: endpointMap };
+            const unit = generateSystemdUnit(nodeName, nodeWithEndpoints, validated);
+            fs.writeFileSync(path.join(tmpDir, `forge-${nodeName}.service`), unit);
+            const envFile = generateSystemdEnvFile(nodeName, nodeWithEndpoints);
+            fs.writeFileSync(path.join(tmpDir, `${nodeName}.env`), envFile.content);
+        }
+        // Deploy script
+        const deployScript = generateDeployScript(validated);
+        const scriptPath = path.join(tmpDir, "deploy.sh");
+        fs.writeFileSync(scriptPath, deployScript);
+        fs.chmodSync(scriptPath, "755");
+        // Nginx config — routes ingress through ForgeProxy
+        const nginxServices = buildNginxServiceMap(validated, serviceConfigs);
+        const websocketRoutes = buildNginxWebSocketRoutes(serviceConfigs, nginxServices, {
+            websockets: manifest.websockets ?? false,
+            websocketPaths: manifest.websocketPaths ?? ["/ws"],
+        });
+        const nginxConfig = generateNginxConfig({
+            domain: manifest.domain ?? "localhost",
+            services: nginxServices,
+            ssl: manifest.ssl,
+            rateLimits: manifest.rateLimits ?? {},
+            staticDir: manifest.staticDir,
+            forgeProxy: manifest.forgeProxy,
+            websocketRoutes,
+            // Backward compatibility for older manifests that don't define service.websocket
+            websockets: manifest.websockets ?? false,
+            websocketPaths: manifest.websocketPaths ?? ["/ws"],
+            maxBodySize: manifest.maxBodySize ?? 10,
+        });
+        fs.writeFileSync(path.join(tmpDir, "nginx.conf"), nginxConfig);
+        // C1: Generate Dockerfile
+        const dockerfile = generateDockerfile(manifest, serviceConfigs);
+        fs.writeFileSync(path.join(tmpDir, "Dockerfile"), dockerfile);
+        // H4: Generate .dockerignore
+        const dockerignore = generateDockerignore();
+        fs.writeFileSync(path.join(tmpDir, ".dockerignore"), dockerignore);
+        // C-DEPLOY-1: Generate .env.example template for secrets management
+        const envExample = `# ThreadForge Deployment Secrets — DO NOT COMMIT TO VERSION CONTROL
+# Copy to .env and fill in values
+DATABASE_URL=
+REDIS_URL=
+JWT_SECRET=CHANGE_ME_BEFORE_DEPLOY
+NODE_ENV=production
+FORGE_METRICS_PORT=9090
+FORGE_METRICS_BIND=127.0.0.1
+FORGE_CLUSTER_SECRET=
+FORGE_LOG_LEVEL=info
+`;
+        fs.writeFileSync(path.join(tmpDir, ".env.example"), envExample);
+        // Generate .gitignore to protect .env from accidental commits
+        const gitignore = `# Secrets — never commit
+.env
+`;
+        fs.writeFileSync(path.join(tmpDir, ".gitignore"), gitignore);
+        // All files generated successfully — copy to final output directory
+        fs.mkdirSync(outputDir, { recursive: true });
+        for (const entry of fs.readdirSync(tmpDir)) {
+            const src = path.join(tmpDir, entry);
+            const dest = path.join(outputDir, entry);
+            fs.cpSync(src, dest, { recursive: true });
+        }
+        return {
+            nodes: [...nodeConfigs.keys()],
+            files: [
+                ...[...nodeConfigs.keys()].map((n) => `${n}/forge.config.js`),
+                "docker-compose.yml",
+                "nginx.conf",
+                ...Object.keys(validated.nodes).map((n) => `forge-${n}.service`),
+                ...Object.keys(validated.nodes).map((n) => `${n}.env`),
+                "deploy.sh",
+                "Dockerfile",
+                ".dockerignore",
+                ".env.example",
+                ".gitignore",
+            ],
+        };
+    }
+    finally {
+        // Clean up temp directory
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+/**
+ * Generate all platform deployment artifacts.
+ */
+export function generatePlatformAll(platformConfig, services, hostMeta, outputDir, options = {}) {
+    // DEP-M4: Write to a temp directory first, then copy on success
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "forge-platform-"));
+    const deployDir = path.join(tmpDir, "deploy");
+    const routesDir = path.join(tmpDir, "routes");
+    fs.mkdirSync(deployDir, { recursive: true });
+    fs.mkdirSync(routesDir, { recursive: true });
+    try {
+        const files = [];
+        const sites = options.sites ?? {};
+        const builtOutDirBySite = {};
+        if (Array.isArray(options.frontendManifest?.sites)) {
+            for (const site of options.frontendManifest.sites) {
+                if (site?.siteId && site?.outDir) {
+                    builtOutDirBySite[site.siteId] = site.outDir;
+                }
+            }
+        }
+        const mountsFromManifest = {};
+        if (options.frontendManifest?.mounts && typeof options.frontendManifest.mounts === "object") {
+            for (const [siteId, mounts] of Object.entries(options.frontendManifest.mounts)) {
+                if (Array.isArray(mounts))
+                    mountsFromManifest[siteId] = mounts;
+            }
+        }
+        const apps = {};
+        for (const [appId, app] of Object.entries(platformConfig.apps ?? {})) {
+            const site = 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 platform nginx config
+        const nginxConfig = generatePlatformNginxConfig({
+            apps,
+            services,
+            hostMeta,
+            defaultSsl: platformConfig.ssl ?? null,
+            maxBodySize: platformConfig.maxBodySize ?? 10,
+            forgeProxy: platformConfig.forgeProxy,
+        });
+        fs.writeFileSync(path.join(deployDir, "nginx.conf"), nginxConfig);
+        files.push("deploy/nginx.conf");
+        // Generate platform.yaml manifest
+        const manifest = generatePlatformManifest(platformConfig, hostMeta, sites);
+        fs.writeFileSync(path.join(routesDir, "platform.yaml"), manifest);
+        files.push("routes/platform.yaml");
+        // All files generated successfully — copy to final output directory
+        fs.mkdirSync(outputDir, { recursive: true });
+        for (const entry of fs.readdirSync(tmpDir)) {
+            const src = path.join(tmpDir, entry);
+            const dest = path.join(outputDir, entry);
+            fs.cpSync(src, dest, { recursive: true });
+        }
+        return { files };
+    }
+    finally {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=index.js.map