threadforge 0.1.1 → 0.2.1

package/dist/core/config.js

@@ -0,0 +1,694 @@
+/**
+ * ThreadForge Configuration v2
+ *
+ * Key design changes:
+ *
+ * 1. Services declare their TYPE:
+ *    - "edge"       → binds an HTTP port, receives external traffic
+ *    - "internal"   → no port, only reachable via IPC from other services
+ *    - "background" → no port, no inbound IPC, runs tasks (cron, queue consumer)
+ *
+ *    Only edge services need ports. Internal services live behind the
+ *    IPC bus and are never directly exposed.
+ *
+ * 2. Services declare DEPENDENCIES (connects):
+ *    Instead of a full mesh (N*(N-1)/2 channels), services declare
+ *    which other services they talk to. This means 8 services might
+ *    only need 8 channels instead of 28.
+ *
+ * 3. Services can be COLOCATED into process groups:
+ *    Lightweight internal services can share a process. One Node.js
+ *    event loop handles multiple services via in-process function calls
+ *    (zero IPC overhead). Only CPU-heavy services need isolated processes.
+ *
+ *    This means 8 services might run in 3 processes instead of 8,
+ *    saving ~200MB of memory.
+ *
+ * 4. Thread allocation is per-PROCESS GROUP, not per-service.
+ */
+import { validateRpcOptions } from "./RpcConfig.js";
+import { LogLevel, LOG_LEVELS, REGISTRY_MODES, RoutingStrategyName, ROUTING_STRATEGY_NAMES, SERVICE_MODES, SERVICE_TYPES, ServiceMode, ServiceType, } from "./config-enums.js";
+export { LogLevel, LOG_LEVELS, RegistryMode, REGISTRY_MODES, RoutingStrategyName, ROUTING_STRATEGY_NAMES, ServiceMode, SERVICE_MODES, ServiceType, SERVICE_TYPES, } from "./config-enums.js";
+const WEBSOCKET_PATH_RE = /^\/[a-zA-Z0-9/_-]*$/;
+function normalizeWebsocketConfig(serviceName, serviceType, websocket) {
+    if (websocket === undefined || websocket === null || websocket === false)
+        return null;
+    if (serviceType !== ServiceType.EDGE) {
+        throw new Error(`Service "${serviceName}": websocket config is only valid for edge services`);
+    }
+    let paths = ["/ws"];
+    let enabled = true;
+    if (websocket === true) {
+        paths = ["/ws"];
+    }
+    else if (Array.isArray(websocket)) {
+        paths = websocket;
+    }
+    else if (typeof websocket === "object") {
+        enabled = websocket.enabled !== false;
+        if (websocket.paths !== undefined) {
+            if (!Array.isArray(websocket.paths)) {
+                throw new Error(`Service "${serviceName}": websocket.paths must be an array`);
+            }
+            paths = websocket.paths;
+        }
+    }
+    else {
+        throw new Error(`Service "${serviceName}": websocket must be boolean, array of paths, or { enabled, paths } object`);
+    }
+    if (!enabled)
+        return { enabled: false, paths: [] };
+    if (paths.length === 0) {
+        throw new Error(`Service "${serviceName}": websocket.paths must include at least one path when enabled`);
+    }
+    const normalizedPaths = [...new Set(paths)].map((p) => {
+        if (typeof p !== "string" || !WEBSOCKET_PATH_RE.test(p)) {
+            throw new Error(`Service "${serviceName}": invalid websocket path "${p}". Use absolute paths containing [a-zA-Z0-9/_-]`);
+        }
+        return p;
+    });
+    return { enabled: true, paths: normalizedPaths };
+}
+/**
+ * Validate and normalize service config.
+ */
+function normalizeService(name, config) {
+    const VALID_SERVICE_NAME = /^[a-z][a-z0-9_-]*(:[a-z][a-z0-9_-]*)?$/;
+    if (!VALID_SERVICE_NAME.test(name)) {
+        throw new Error(`Invalid service name "${name}": must start with a lowercase letter and contain only [a-z0-9_-] (or use appname:servicename format)`);
+    }
+    if (name.length > 63) {
+        throw new Error(`Service name "${name}" exceeds max length of 63 characters`);
+    }
+    const type = config.type ?? ServiceType.INTERNAL;
+    if (!SERVICE_TYPES.includes(type)) {
+        throw new Error(`Service "${name}" has invalid type: ${type}. Use: ${SERVICE_TYPES.join(", ")}`);
+    }
+    const modeInput = config.mode;
+    if (modeInput && !SERVICE_MODES.includes(modeInput)) {
+        const hint = modeInput === "worker"
+            ? ` mode 'worker' (worker_threads) is not yet implemented. Use mode '${ServiceMode.CLUSTER}' (default).`
+            : "";
+        throw new Error(`Service "${name}": invalid mode "${modeInput}".${hint} Valid modes: ${SERVICE_MODES.join(", ")}`);
+    }
+    // Remote services don't need an entry file — they're on another machine
+    if (type === ServiceType.REMOTE) {
+        if (!config.address) {
+            throw new Error(`Remote service "${name}" requires an address (e.g., 'http://billing.internal:4001')`);
+        }
+        if (!/^https?:\/\/.+/.test(config.address)) {
+            throw new Error(`Remote service "${name}": address must be a valid HTTP(S) URL, got "${config.address}"`);
+        }
+        try {
+            new URL(config.address);
+        }
+        catch {
+            throw new Error(`Remote service "${name}": address is not a parseable URL: "${config.address}"`);
+        }
+        // CFG-2: Validate routing.strategy for remote services too
+        const remoteRouting = { strategy: config.routing?.strategy ?? RoutingStrategyName.ROUND_ROBIN };
+        if (remoteRouting.strategy && !ROUTING_STRATEGY_NAMES.includes(remoteRouting.strategy)) {
+            throw new Error(`Service "${name}": invalid routing strategy "${remoteRouting.strategy}". Valid strategies: ${ROUTING_STRATEGY_NAMES.join(", ")}`);
+        }
+        if (config.connects && config.connects.length > 0) {
+            console.warn(`[ThreadForge] Warning: Remote service "${name}" specifies "connects" which has no effect. ` +
+                `Remote services are on another machine and do not participate in local channel resolution.`);
+        }
+        return {
+            name,
+            entry: null,
+            type: ServiceType.REMOTE,
+            port: null,
+            address: config.address,
+            connects: [],
+            group: null,
+            threads: 0,
+            weight: 0,
+            mode: ServiceMode.CLUSTER,
+            env: {},
+            routing: remoteRouting,
+            websocket: null,
+        };
+    }
+    if (!config.entry) {
+        throw new Error(`Service "${name}" is missing required field: entry`);
+    }
+    // Only edge services need a port
+    if (type === ServiceType.EDGE && !config.port) {
+        throw new Error(`Edge service "${name}" requires a port`);
+    }
+    if (type !== ServiceType.EDGE && config.port && !config.group && !config.remotePort) {
+        console.warn(`[ThreadForge] Note: Service "${name}" has type "${type}" with port ${config.port}. ` +
+            `This port will be used for cross-machine HTTP access (/__forge/invoke, /__forge/event).`);
+    }
+    if (config.group?.startsWith("_isolated:")) {
+        throw new Error(`Service "${name}": group name cannot start with "_isolated:" (reserved prefix)`);
+    }
+    if (config.env) {
+        if (typeof config.env !== "object" || Array.isArray(config.env)) {
+            throw new Error(`Service "${name}": env must be a plain object`);
+        }
+        for (const [k, v] of Object.entries(config.env)) {
+            if (typeof v !== "string") {
+                throw new Error(`Service "${name}": env.${k} must be a string, got ${typeof v}`);
+            }
+        }
+    }
+    const connects = config.connects ?? [];
+    if (!Array.isArray(connects)) {
+        throw new Error(`Service "${name}" connects must be an array of service names`);
+    }
+    for (const c of connects) {
+        if (typeof c !== "string" || c.length === 0) {
+            throw new Error(`Service "${name}": each element in connects must be a non-empty string, got ${JSON.stringify(c)}`);
+        }
+    }
+    if (config.port !== undefined && config.port !== null) {
+        if (!Number.isInteger(config.port) || config.port < 1 || config.port > 65535) {
+            throw new Error(`Service "${name}": port must be an integer between 1-65535, got ${config.port}`);
+        }
+    }
+    if (config.weight !== undefined) {
+        if (typeof config.weight !== "number" || !Number.isInteger(config.weight) || config.weight < 1) {
+            throw new Error(`Service "${name}": weight must be a positive integer, got ${config.weight}`);
+        }
+    }
+    if (config.prefix !== undefined && config.prefix !== null) {
+        if (typeof config.prefix !== "string" || !config.prefix.startsWith("/")) {
+            throw new Error(`Service "${name}": prefix must start with /, got "${config.prefix}"`);
+        }
+        if (config.prefix.includes("?") || config.prefix.includes("#")) {
+            throw new Error(`Service "${name}": prefix cannot contain query strings or fragments`);
+        }
+    }
+    const websocket = normalizeWebsocketConfig(name, type, config.websocket);
+    // CFG-1: Validate threads — must be "auto" or a positive integer
+    const threads = config.threads ?? "auto";
+    if (threads !== "auto") {
+        if (typeof threads !== "number" || !Number.isInteger(threads) || threads <= 0 || !Number.isFinite(threads)) {
+            throw new Error(`Service "${name}": threads must be "auto" or a positive integer, got ${JSON.stringify(threads)}`);
+        }
+    }
+    // CFG-2: Validate routing.strategy
+    const routing = { strategy: config.routing?.strategy ?? RoutingStrategyName.ROUND_ROBIN };
+    if (routing.strategy && !ROUTING_STRATEGY_NAMES.includes(routing.strategy)) {
+        throw new Error(`Service "${name}": invalid routing strategy "${routing.strategy}". Valid strategies: ${ROUTING_STRATEGY_NAMES.join(", ")}`);
+    }
+    // Validate RPC configuration shape
+    validateRpcOptions(name, "rpc", config.rpc);
+    if (config.rpcTargets) {
+        if (typeof config.rpcTargets !== "object" || Array.isArray(config.rpcTargets)) {
+            throw new Error(`Service "${name}": rpcTargets must be an object`);
+        }
+        for (const [targetName, targetOpts] of Object.entries(config.rpcTargets)) {
+            validateRpcOptions(name, `rpcTargets.${targetName}`, targetOpts);
+        }
+    }
+    return {
+        name,
+        entry: config.entry,
+        type,
+        port: config.port ?? null,
+        connects,
+        group: config.group ?? null, // colocation group name
+        threads,
+        weight: config.weight ?? 1,
+        mode: config.mode ?? ServiceMode.CLUSTER,
+        env: config.env ?? {},
+        routing,
+        prefix: config.prefix ?? null,
+        plugins: config.plugins ?? null, // null = all plugins, [...] = specific
+        websocket,
+        rpc: config.rpc,
+        rpcTargets: config.rpcTargets,
+    };
+}
+/**
+ * Resolve colocation groups.
+ *
+ * Services in the same group run in the same process(es).
+ * They communicate via direct function calls (zero overhead).
+ * Services without a group get their own isolated process.
+ *
+ * Returns a map of group name → array of service configs.
+ */
+function resolveGroups(services) {
+    const groups = new Map();
+    for (const [name, svc] of Object.entries(services)) {
+        // Remote services don't run locally — no process group needed
+        if (svc.type === ServiceType.REMOTE)
+            continue;
+        const groupName = svc.group ?? `_isolated:${name}`;
+        if (!groups.has(groupName)) {
+            groups.set(groupName, {
+                name: groupName,
+                services: [],
+                threads: 0,
+                weight: 0,
+                hasEdge: false,
+                port: null,
+            });
+        }
+        const group = groups.get(groupName);
+        group.services.push(svc);
+        /**
+         * H4: Max-weight semantics for colocation groups.
+         *
+         * The group's weight equals its heaviest member service. This is intentional:
+         * since all services in a group share the same OS process (same event loop),
+         * the heaviest service determines the group's resource needs — it is the
+         * bottleneck. For example, a group with one weight-10 and two weight-1
+         * services gets the same thread allocation as a single weight-10 service,
+         * because the weight-10 service dominates the process's CPU budget.
+         */
+        group.weight = Math.max(group.weight, svc.weight);
+        if (svc.type === ServiceType.EDGE) {
+            if (group.hasEdge && group.port !== svc.port) {
+                throw new Error(`Group "${groupName}": multiple edge services with different ports (${group.port} vs ${svc.port}). ` +
+                    `Edge services in the same group must use the same port.`);
+            }
+            group.hasEdge = true;
+            group.port = svc.port;
+        }
+        // Group inherits the highest thread count / weight of its members
+        if (typeof svc.threads === "number" && svc.threads > 0) {
+            group.threads = typeof group.threads === "number" ? Math.max(group.threads, svc.threads) : svc.threads;
+        }
+        else if (svc.threads === "auto" && group.threads === 0) {
+            group.threads = "auto";
+        }
+    }
+    return groups;
+}
+/**
+ * Resolve the channel topology from dependency declarations.
+ *
+ * Instead of full mesh, only create channels between services
+ * that actually declare they need to talk to each other.
+ *
+ * Returns array of { from, to } pairs.
+ */
+function detectCycles(services) {
+    const WHITE = 0, GRAY = 1, BLACK = 2;
+    const color = {};
+    const parent = {};
+    for (const name of Object.keys(services)) {
+        color[name] = WHITE;
+    }
+    function dfs(name) {
+        color[name] = GRAY;
+        for (const target of services[name]?.connects ?? []) {
+            if (!services[target])
+                continue;
+            if (color[target] === GRAY) {
+                // Found a back edge — reconstruct the cycle path
+                const cycle = [target];
+                let cur = name;
+                while (cur !== target) {
+                    cycle.push(cur);
+                    cur = parent[cur];
+                }
+                cycle.push(target);
+                cycle.reverse();
+                // Skip bidirectional pairs (A→B→A) — those are valid IPC channels
+                if (cycle.length === 3 && cycle[0] === cycle[2])
+                    continue;
+                throw new Error(`Circular dependency detected: ${cycle.join(" \u2192 ")}`);
+            }
+            if (color[target] === WHITE) {
+                parent[target] = name;
+                dfs(target);
+            }
+        }
+        color[name] = BLACK;
+    }
+    for (const name of Object.keys(services)) {
+        if (color[name] === WHITE) {
+            dfs(name);
+        }
+    }
+}
+function resolveChannels(services) {
+    const channels = [];
+    const seen = new Set();
+    for (const [name, svc] of Object.entries(services)) {
+        for (const target of svc.connects) {
+            if (!services[target]) {
+                throw new Error(`Service "${name}" declares connection to "${target}", but no such service exists.`);
+            }
+            // Deduplicate bidirectional
+            const key = [name, target].sort().join("<->");
+            if (!seen.has(key)) {
+                seen.add(key);
+                channels.push({ from: name, to: target });
+            }
+        }
+    }
+    detectCycles(services);
+    return channels;
+}
+/**
+ * Detect circular dependencies at the group level.
+ * Self-loops (a group connecting to itself) are allowed — that's colocated.
+ */
+function detectGroupCycles(services, groups) {
+    // Build service→group mapping
+    const svcToGroup = {};
+    for (const [groupName, group] of groups) {
+        for (const svc of group.services) {
+            svcToGroup[svc.name] = groupName;
+        }
+    }
+    // Build group-level adjacency
+    const groupAdj = new Map();
+    for (const [name, svc] of Object.entries(services)) {
+        const fromGroup = svcToGroup[name];
+        if (!fromGroup)
+            continue;
+        for (const target of svc.connects) {
+            const toGroup = svcToGroup[target];
+            if (!toGroup || toGroup === fromGroup)
+                continue; // skip self-loops
+            if (!groupAdj.has(fromGroup))
+                groupAdj.set(fromGroup, new Set());
+            groupAdj.get(fromGroup).add(toGroup);
+        }
+    }
+    // DFS cycle detection
+    const WHITE = 0, GRAY = 1, BLACK = 2;
+    const color = {};
+    const parent = {};
+    for (const [groupName] of groups) {
+        color[groupName] = WHITE;
+    }
+    function dfs(g) {
+        color[g] = GRAY;
+        for (const target of groupAdj.get(g) ?? []) {
+            if (color[target] === GRAY) {
+                const cycle = [target];
+                let cur = g;
+                while (cur !== target) {
+                    cycle.push(cur);
+                    cur = parent[cur];
+                }
+                cycle.push(target);
+                cycle.reverse();
+                // Skip bidirectional pairs (A→B→A)
+                if (cycle.length === 3 && cycle[0] === cycle[2])
+                    continue;
+                throw new Error(`Circular group dependency detected: ${cycle.join(" \u2192 ")}`);
+            }
+            if (color[target] === WHITE) {
+                parent[target] = g;
+                dfs(target);
+            }
+        }
+        color[g] = BLACK;
+    }
+    for (const [groupName] of groups) {
+        if (color[groupName] === WHITE)
+            dfs(groupName);
+    }
+}
+/**
+ * Define services for the ThreadForge runtime.
+ */
+export function defineServices(servicesMap, options = {}) {
+    if (!servicesMap || typeof servicesMap !== "object") {
+        throw new Error("defineServices() requires a services object");
+    }
+    // D5: Accept plugins as top-level key in servicesMap or in options.
+    // If plugins appears inside the services object, emit a deprecation warning
+    // and prefer options.plugins when both are provided.
+    let plugins;
+    if (options.plugins) {
+        plugins = options.plugins;
+    }
+    else if (servicesMap.plugins) {
+        console.warn(`[ThreadForge] Deprecation: "plugins" inside the services object is deprecated. ` +
+            `Pass it as a separate top-level key: defineServices({ ...services }, { plugins: [...] })`);
+        plugins = servicesMap.plugins;
+    }
+    else {
+        plugins = [];
+    }
+    const filteredMap = { ...servicesMap };
+    delete filteredMap.plugins;
+    if (options.frontendPlugins !== undefined && !Array.isArray(options.frontendPlugins)) {
+        throw new Error("defineServices(): frontendPlugins must be an array when provided");
+    }
+    if (options.sites !== undefined && (typeof options.sites !== "object" || Array.isArray(options.sites))) {
+        throw new Error("defineServices(): sites must be an object map when provided");
+    }
+    const entries = Object.entries(filteredMap);
+    if (entries.length === 0) {
+        throw new Error("defineServices() requires at least one service");
+    }
+    // H1: Check for reserved service names
+    for (const [name] of entries) {
+        if (name === "plugins") {
+            throw new Error(`"plugins" is a reserved name and cannot be used as a service name`);
+        }
+    }
+    // Check for duplicate ports among all services
+    const ports = new Map();
+    for (const [name, config] of entries) {
+        if (config.port) {
+            if (ports.has(config.port)) {
+                throw new Error(`Port ${config.port} is used by both "${ports.get(config.port)}" and "${name}"`);
+            }
+            ports.set(config.port, name);
+        }
+    }
+    // Validate metricsPort
+    if (options.metricsPort !== undefined && options.metricsPort !== null) {
+        if (typeof options.metricsPort !== "number" || !Number.isInteger(options.metricsPort) ||
+            options.metricsPort < 1 || options.metricsPort > 65535) {
+            throw new Error(`metricsPort must be an integer between 1-65535, got ${JSON.stringify(options.metricsPort)}`);
+        }
+    }
+    // Check for metricsPort collision
+    const metricsPort = options.metricsPort ?? 9090;
+    for (const [name, config] of entries) {
+        if (config.port === metricsPort) {
+            throw new Error(`Service "${name}" port ${config.port} conflicts with metricsPort (${metricsPort})`);
+        }
+    }
+    // Normalize all services
+    const services = {};
+    for (const [name, config] of entries) {
+        services[name] = normalizeService(name, config);
+    }
+    // Validate thread counts and plugin arrays
+    for (const [name, svc] of Object.entries(services)) {
+        if (svc.type !== ServiceType.REMOTE && typeof svc.threads === "number") {
+            if (!Number.isInteger(svc.threads) || svc.threads <= 0 || !Number.isFinite(svc.threads)) {
+                throw new Error(`Service "${name}": threads must be a positive integer or "auto", got ${svc.threads}`);
+            }
+        }
+        if (svc.plugins) {
+            if (!Array.isArray(svc.plugins)) {
+                throw new Error(`Service "${name}": plugins must be an array`);
+            }
+            for (const p of svc.plugins) {
+                if (typeof p !== "string" || p.trim() === "") {
+                    throw new Error(`Service "${name}": plugin name must be a non-empty string`);
+                }
+            }
+            if (new Set(svc.plugins).size !== svc.plugins.length) {
+                throw new Error(`Service "${name}": duplicate plugin entries detected`);
+            }
+        }
+    }
+    // Self-reference check
+    for (const [name, svc] of Object.entries(services)) {
+        if (svc.connects.includes(name)) {
+            throw new Error(`Service "${name}" cannot connect to itself.`);
+        }
+    }
+    // Validate rpcTargets keys against connects[] (requires full service map)
+    for (const [name, svc] of Object.entries(services)) {
+        if (svc.rpcTargets) {
+            for (const target of Object.keys(svc.rpcTargets)) {
+                if (!svc.connects.includes(target)) {
+                    throw new Error(`Service "${name}": rpcTargets key "${target}" is not in connects array. ` +
+                        `Add "${target}" to connects or remove it from rpcTargets.`);
+                }
+            }
+        }
+    }
+    // Resolve topology
+    const groups = resolveGroups(services);
+    const channels = resolveChannels(services);
+    // M3: Detect group-level circular dependencies
+    detectGroupCycles(services, groups);
+    // M-14: Warn on unknown option keys to catch typos early
+    const KNOWN_OPTIONS = new Set([
+        "metricsPort",
+        "logging",
+        "watch",
+        "registryMode",
+        "host",
+        "httpBasePort",
+        "ingress",
+        "plugins",
+        "frontendPlugins",
+        "sites",
+        // Internal keys used by platform/host modes
+        "_configUrl",
+        "_isHostMode",
+        "_isPlatformMode",
+        "_hostMeta",
+        "_hostMetaJSON",
+    ]);
+    for (const key of Object.keys(options)) {
+        if (!KNOWN_OPTIONS.has(key) && !key.startsWith("_")) {
+            console.warn(`[ThreadForge] Unknown option "${key}" in defineServices(). Known options: ${[...KNOWN_OPTIONS].filter((k) => !k.startsWith("_")).join(", ")}`);
+        }
+    }
+    // Validate logging.level
+    if (options.logging?.level !== undefined) {
+        if (typeof options.logging.level !== "string" || !LOG_LEVELS.includes(options.logging.level)) {
+            throw new Error(`Invalid logging.level: ${JSON.stringify(options.logging.level)}. Valid levels: ${LOG_LEVELS.join(", ")}`);
+        }
+    }
+    if (options.registryMode !== undefined) {
+        if (typeof options.registryMode !== "string" || !REGISTRY_MODES.includes(options.registryMode)) {
+            throw new Error(`Invalid registryMode: ${JSON.stringify(options.registryMode)}. Valid modes: ${REGISTRY_MODES.join(", ")}`);
+        }
+    }
+    // Only pass through known option keys to prevent typos polluting the config
+    // A12: Namespace internal fields into _internal sub-object
+    const _internal = {
+        configUrl: options._configUrl,
+        isHostMode: options._isHostMode,
+        isPlatformMode: options._isPlatformMode,
+        hostMeta: options._hostMeta,
+        hostMetaJSON: options._hostMetaJSON,
+    };
+    const result = {
+        services,
+        groups: Object.fromEntries(groups),
+        channels,
+        plugins,
+        frontendPlugins: options.frontendPlugins ?? [],
+        sites: options.sites ?? {},
+        metricsPort: options.metricsPort !== undefined ? options.metricsPort : 9090,
+        logging: { level: LogLevel.INFO, structured: true, ...(options.logging ?? {}) },
+        watch: options.watch ?? false,
+        registryMode: options.registryMode,
+        host: options.host,
+        httpBasePort: options.httpBasePort,
+        ingress: options.ingress,
+        _internal,
+        // Backward compat: expose legacy underscore keys
+        get _configUrl() {
+            return this._internal.configUrl;
+        },
+        set _configUrl(value) {
+            this._internal.configUrl = value;
+        },
+        get _isHostMode() {
+            return this._internal.isHostMode;
+        },
+        set _isHostMode(value) {
+            this._internal.isHostMode = value;
+        },
+        get _isPlatformMode() {
+            return this._internal.isPlatformMode;
+        },
+        set _isPlatformMode(value) {
+            this._internal.isPlatformMode = value;
+        },
+        get _hostMeta() {
+            return this._internal.hostMeta;
+        },
+        set _hostMeta(value) {
+            this._internal.hostMeta = value;
+        },
+        get _hostMetaJSON() {
+            return this._internal.hostMetaJSON;
+        },
+        set _hostMetaJSON(value) {
+            this._internal.hostMetaJSON = value;
+        },
+    };
+    for (const svc of Object.values(services)) {
+        Object.freeze(svc);
+        Object.freeze(svc.connects);
+        if (svc.env)
+            Object.freeze(svc.env);
+        if (svc.routing)
+            Object.freeze(svc.routing);
+        if (svc.websocket)
+            Object.freeze(svc.websocket);
+    }
+    Object.freeze(services);
+    for (const group of Object.values(result.groups)) {
+        Object.freeze(group.services);
+        Object.freeze(group);
+    }
+    Object.freeze(result.groups);
+    Object.freeze(channels);
+    Object.freeze(result.logging);
+    return result;
+}
+/**
+ * Detect if a config object is already normalized by defineServices().
+ * This lets loadConfig accept both:
+ *   1) raw service maps
+ *   2) pre-normalized defineServices(...) exports
+ */
+function isNormalizedConfig(config) {
+    if (!config || typeof config !== "object" || Array.isArray(config))
+        return false;
+    const obj = config;
+    if (!obj.services || typeof obj.services !== "object" || Array.isArray(obj.services))
+        return false;
+    if (!obj.groups || typeof obj.groups !== "object" || Array.isArray(obj.groups))
+        return false;
+    if (!Array.isArray(obj.channels))
+        return false;
+    return Object.values(obj.services).every((svc) => {
+        return (svc &&
+            typeof svc === "object" &&
+            !Array.isArray(svc) &&
+            typeof svc.name === "string" &&
+            typeof svc.type === "string" &&
+            Array.isArray(svc.connects));
+    });
+}
+/**
+ * Load a forge config file from disk.
+ */
+export async function loadConfig(configPath) {
+    try {
+        const module = (await import(configPath));
+        const config = module.default ?? module;
+        // Accept configs that already exported defineServices(...) output.
+        if (isNormalizedConfig(config)) {
+            return config;
+        }
+        // Accept configs exported via definePlatform(...) / defineHost(...).
+        // Use lazy imports to avoid circular module initialization at load time.
+        if (config && typeof config === "object" && !Array.isArray(config)) {
+            if (config._isPlatformConfig) {
+                const { resolveAndDefinePlatform } = (await import("./platform-config.js"));
+                return await resolveAndDefinePlatform(config);
+            }
+            if (config._isHostConfig) {
+                const { resolveAndDefine } = (await import("./host-config.js"));
+                return await resolveAndDefine(config);
+            }
+        }
+        // Raw object exports are normalized/validated here.
+        return defineServices(config);
+    }
+    catch (err) {
+        if (err.code === "ERR_MODULE_NOT_FOUND") {
+            throw new Error(`Config file not found or import error: ${configPath}\n  ${err.message}`);
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=config.js.map