threadforge 0.1.0

package/src/core/platform-config.js

@@ -0,0 +1,308 @@
+/**
+ * Platform Mode Configuration
+ *
+ * Transforms a user-facing `platform.apps` config into ForgeHost's
+ * internal `projects` format. Platform Mode is a config transformation
+ * layer on top of ForgeHost — it reuses resolveHostConfig() as the engine.
+ *
+ * Usage:
+ *
+ *   import { definePlatform } from 'threadforge';
+ *
+ *   export default definePlatform({
+ *     platform: {
+ *       globalAuth: true,
+ *       apps: {
+ *         coolapp: {
+ *           domains: ['coolapp.io'],
+ *           services: ['coolapp-api'],
+ *           schema: 'coolapp',
+ *         },
+ *       },
+ *     },
+ *     plugins: [redis(), postgres()],
+ *     identity: { entry: './services/identity.js', type: 'edge', port: 3001 },
+ *     auth: { entry: './services/auth.js', type: 'edge', port: 3002 },
+ *     'coolapp-api': { entry: './apps/coolapp/api.js', type: 'edge', port: 4001 },
+ *   });
+ */
+
+import { defineServices } from "./config.js";
+import { resolveHostConfig } from "./host-config.js";
+
+const APP_ID_RE = /^[a-z][a-z0-9_-]*$/;
+const BASE_PATH_RE = /^\/[^\s?#]*$/;
+
+function isPlainObject(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function normalizeFrontendConfig(appId, frontend) {
+  if (!isPlainObject(frontend)) {
+    throw new Error(`App "${appId}" frontend must be an object`);
+  }
+
+  if (typeof frontend.plugin !== "string" || frontend.plugin.trim() === "") {
+    throw new Error(`App "${appId}" frontend.plugin must be a non-empty string`);
+  }
+
+  if (typeof frontend.root !== "string" || frontend.root.trim() === "") {
+    throw new Error(`App "${appId}" frontend.root must be a non-empty string`);
+  }
+
+  if (frontend.outDir !== undefined && (typeof frontend.outDir !== "string" || frontend.outDir.trim() === "")) {
+    throw new Error(`App "${appId}" frontend.outDir must be a non-empty string when provided`);
+  }
+
+  if (frontend.basePath !== undefined) {
+    if (typeof frontend.basePath !== "string" || !BASE_PATH_RE.test(frontend.basePath)) {
+      throw new Error(
+        `App "${appId}" frontend.basePath must start with "/" and cannot include query strings or fragments`,
+      );
+    }
+  }
+
+  if (frontend.spaFallback !== undefined && typeof frontend.spaFallback !== "boolean") {
+    throw new Error(`App "${appId}" frontend.spaFallback must be a boolean when provided`);
+  }
+
+  if (frontend.env !== undefined && !isPlainObject(frontend.env)) {
+    throw new Error(`App "${appId}" frontend.env must be an object when provided`);
+  }
+  if (frontend.options !== undefined && !isPlainObject(frontend.options)) {
+    throw new Error(`App "${appId}" frontend.options must be an object when provided`);
+  }
+
+  return {
+    plugin: frontend.plugin,
+    root: frontend.root,
+    outDir: frontend.outDir ?? `.threadforge/build/${appId}`,
+    basePath: frontend.basePath ?? "/",
+    spaFallback: frontend.spaFallback ?? true,
+    env: frontend.env ?? {},
+    options: frontend.options ?? {},
+  };
+}
+
+/**
+ * Normalize an app's domain(s) to an array.
+ * Accepts either `domains: [...]` or `domain: '...'`.
+ *
+ * @param {{ domains?: string[], domain?: string }} app
+ * @returns {string[]}
+ */
+export function resolveAppDomains(app) {
+  if (app.domains) return app.domains;
+  if (app.domain) return [app.domain];
+  return [];
+}
+
+/**
+ * Validate the platform config shape.
+ *
+ * @param {Object} config - Raw platform config
+ * @throws {Error} On invalid config
+ */
+export function validatePlatformConfig(config) {
+  if (!config || typeof config !== "object") {
+    throw new Error("definePlatform() requires a config object");
+  }
+
+  if (!config.platform || typeof config.platform !== "object") {
+    throw new Error("definePlatform() requires a platform block");
+  }
+
+  const { apps } = config.platform;
+  if (!apps || typeof apps !== "object") {
+    throw new Error("platform.apps must be a non-empty object");
+  }
+
+  const appIds = Object.keys(apps);
+  if (appIds.length === 0) {
+    throw new Error("platform.apps must contain at least one app");
+  }
+
+  const schemas = new Set();
+
+  for (const appId of appIds) {
+    if (!APP_ID_RE.test(appId)) {
+      throw new Error(
+        `Invalid app ID "${appId}": must start with a lowercase letter and contain only lowercase letters, digits, hyphens, and underscores`,
+      );
+    }
+
+    const app = apps[appId];
+    if (!app || typeof app !== "object") {
+      throw new Error(`App "${appId}" must be an object`);
+    }
+
+    if (!app.domains && !app.domain) {
+      throw new Error(`App "${appId}" must have a domains array`);
+    }
+
+    const domains = resolveAppDomains(app);
+    if (domains.length === 0) {
+      throw new Error(`App "${appId}" must have at least one domain`);
+    }
+
+    if (!app.services && !app.config) {
+      throw new Error(`App "${appId}" must have either services or config`);
+    }
+
+    if (app.frontend) {
+      normalizeFrontendConfig(appId, app.frontend);
+    }
+
+    const schema = app.schema ?? appId;
+    if (schemas.has(schema)) {
+      throw new Error(`Duplicate schema "${schema}" — each app must have a unique schema`);
+    }
+    schemas.add(schema);
+  }
+}
+
+/**
+ * Transform platform config into ForgeHost's internal projects format.
+ *
+ * Maps platform.apps → hostConfig.projects, preserving custom schemas
+ * and auto-injecting identity+auth when globalAuth is enabled.
+ *
+ * @param {Object} config - Validated platform config
+ * @returns {Object} ForgeHost-compatible config
+ */
+export function transformToHostConfig(config) {
+  const { platform } = config;
+  const apps = platform.apps;
+  const globalAuth = platform.globalAuth ?? false;
+
+  // Collect all service names claimed by apps
+  const claimedServices = new Set();
+  for (const app of Object.values(apps)) {
+    for (const svcName of app.services ?? []) {
+      claimedServices.add(svcName);
+    }
+  }
+
+  // Build shared services: any service definition in config that is not
+  // claimed by an app and not a reserved top-level key
+  const shared = {};
+  for (const [key, value] of Object.entries(config)) {
+    if (key === "platform" || key === "plugins") continue;
+    if (claimedServices.has(key)) continue;
+    if (typeof value !== "object" || value === null) continue;
+    if (!value.entry && !value.type) continue;
+    shared[key] = value;
+  }
+
+  // Auto-inject identity + auth as shared services when globalAuth is enabled
+  if (globalAuth) {
+    if (!shared.identity) {
+      shared.identity = {
+        entry: "./shared/identity.js",
+        type: "edge",
+        port: 3001,
+      };
+    }
+    if (!shared.auth) {
+      shared.auth = {
+        entry: "./shared/auth.js",
+        type: "edge",
+        port: 3002,
+      };
+    }
+  }
+
+  // Build projects map from apps
+  const projects = {};
+  for (const [appId, app] of Object.entries(apps)) {
+    const domains = resolveAppDomains(app);
+
+    // Build inline service map from claimed service names
+    const inlineServices = {};
+    for (const svcName of app.services ?? []) {
+      const svcConfig = config[svcName];
+      if (svcConfig) {
+        inlineServices[svcName] = svcConfig;
+      }
+    }
+
+    const hasInlineServices = Object.keys(inlineServices).length > 0;
+    const frontend = app.frontend ? normalizeFrontendConfig(appId, app.frontend) : null;
+    if (frontend && app.static) {
+      console.warn(
+        `[ThreadForge] App "${appId}" defines both "frontend" and legacy "static". ` +
+          `Using frontend plugin config and ignoring "static".`,
+      );
+    }
+
+    projects[appId] = {
+      domain: domains[0],
+      domains,
+      schema: app.schema ?? appId,
+      static: frontend ? null : (app.static ?? null),
+      frontend,
+      services: hasInlineServices ? inlineServices : undefined,
+      config: app.config,
+    };
+  }
+
+  return {
+    domain: platform.domain ?? null,
+    basePort: platform.basePort ?? 3200,
+    metricsPort: platform.metricsPort ?? 9090,
+    projects,
+    shared,
+    plugins: config.plugins ?? [],
+    frontendPlugins: config.frontendPlugins ?? [],
+  };
+}
+
+/**
+ * Define a Platform Mode config.
+ *
+ * Validates the config and returns a marked config object.
+ *
+ * @param {Object} config - Platform config
+ * @returns {Object} Validated config marked with _isPlatformConfig
+ */
+export function definePlatform(config) {
+  validatePlatformConfig(config);
+
+  return {
+    _isPlatformConfig: true,
+    _raw: config,
+    platform: config.platform,
+    plugins: config.plugins ?? [],
+    frontendPlugins: config.frontendPlugins ?? [],
+  };
+}
+
+/**
+ * Resolve a platform config fully: transform → resolveHostConfig → defineServices.
+ *
+ * @param {Object} config - Output from definePlatform() or raw platform config
+ * @returns {Object} Fully resolved config ready for Supervisor
+ */
+export async function resolveAndDefinePlatform(config) {
+  const raw = config._isPlatformConfig ? config._raw : config;
+  validatePlatformConfig(raw);
+
+  const hostConfig = transformToHostConfig(raw);
+  const resolved = await resolveHostConfig(hostConfig);
+
+  const result = defineServices(resolved.services, {
+    plugins: resolved.plugins,
+    frontendPlugins: resolved.frontendPlugins,
+    sites: resolved.sites,
+    metricsPort: resolved.metricsPort,
+  });
+
+  result._isPlatformMode = true;
+  result._isHostMode = true;
+  result._hostMeta = resolved.hostMeta;
+  result._hostDomain = resolved.domain;
+  result._sites = resolved.sites;
+  result._platformConfig = raw.platform;
+
+  return result;
+}