@fulmenhq/tsfulmen 0.2.2 → 0.2.4

package/dist/config/index.d.ts

@@ -1,3 +1,33 @@
+/**
+ * Environment variable alias utilities.
+ *
+ * Workhorse templates sometimes support both canonical nested env vars and
+ * convenience aliases (e.g. TUVAN_SERVER_PORT vs TUVAN_PORT).
+ *
+ * This helper standardizes alias resolution and conflict reporting.
+ */
+interface EnvAliasConflict {
+    canonicalKey: string;
+    aliasKey: string;
+    canonicalValue: string;
+    aliasValue: string;
+}
+interface ResolveEnvAliasesResult {
+    env: Record<string, string | undefined>;
+    applied: Array<{
+        aliasKey: string;
+        canonicalKey: string;
+    }>;
+    conflicts: EnvAliasConflict[];
+}
+/**
+ * Resolve env var aliases into canonical keys.
+ *
+ * - If canonical key is unset and alias is set, the alias value is copied to canonical.
+ * - If both are set and differ, a conflict is recorded (canonical is left unchanged).
+ */
+declare function resolveEnvAliases(env: Record<string, string | undefined>, aliasToCanonical: Record<string, string>): ResolveEnvAliasesResult;
+
 /**
  * Config Path API errors - implements Fulmen Config Path Standard error handling
  */
@@ -119,6 +149,13 @@ interface LoadConfigOptions {
      * Defaults to identity.app.config_name or identity.app
      */
     userConfigName?: string;
+    /**
+     * Include env var consumption metadata for diagnostics.
+     *
+     * When enabled, loadConfig() records which environment variable keys were
+     * consumed for prefix-based overrides.
+     */
+    includeEnvVarReport?: boolean;
 }
 /**
  * Metadata about the loaded configuration
@@ -136,6 +173,14 @@ interface ConfigMetadata {
      * Environment variable prefix used for overrides
      */
     envPrefix: string;
+    /**
+     * Environment variable keys consumed (only when includeEnvVarReport is enabled)
+     */
+    envVarsConsumed?: string[];
+    /**
+     * Count of environment variable keys consumed (only when includeEnvVarReport is enabled)
+     */
+    envVarsConsumedCount?: number;
     /**
      * List of active configuration layers ("defaults", "user", "env")
      */
@@ -232,4 +277,4 @@ declare function resolveConfigPath(filename: string, searchPaths: string[], opti
  */
 declare const VERSION = "0.1.0";
 
-export { type AppIdentifier, type ConfigMetadata, ConfigPathError, type ConfigPathOptions, ConfigValidationError, type LoadConfigOptions, type LoadedConfig, type PlatformDirs, VERSION, type XDGBaseDirs, ensureDirExists, getAppCacheDir, getAppConfigDir, getAppDataDir, getConfigSearchPaths, getFulmenCacheDir, getFulmenConfigDir, getFulmenDataDir, getXDGBaseDirs, loadConfig, resolveConfigPath };
+export { type AppIdentifier, type ConfigMetadata, ConfigPathError, type ConfigPathOptions, ConfigValidationError, type EnvAliasConflict, type LoadConfigOptions, type LoadedConfig, type PlatformDirs, type ResolveEnvAliasesResult, VERSION, type XDGBaseDirs, ensureDirExists, getAppCacheDir, getAppConfigDir, getAppDataDir, getConfigSearchPaths, getFulmenCacheDir, getFulmenConfigDir, getFulmenDataDir, getXDGBaseDirs, loadConfig, resolveConfigPath, resolveEnvAliases };

package/dist/config/index.js

@@ -1,3 +1,4 @@
+import addFormats from 'ajv-formats';
 import { spawn } from 'child_process';
 import { readFile, access, mkdir, writeFile } from 'fs/promises';
 import { parse, stringify } from 'yaml';
@@ -8,7 +9,6 @@ import Ajv from 'ajv';
 import Ajv2019 from 'ajv/dist/2019';
 import Ajv2020 from 'ajv/dist/2020';
 import AjvDraft04 from 'ajv-draft-04';
-import addFormats from 'ajv-formats';
 import { Readable } from 'stream';
 import picomatch from 'picomatch';
 import { suggest as suggest$1, substringSimilarity, score as score$1, normalize as normalize$1, jaro_winkler, damerau_levenshtein, osa_distance, levenshtein } from '@3leaps/string-metrics-wasm';
@@ -25,6 +25,27 @@ var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
 };
+function applyFulmenAjvFormats(ajv, options = {}) {
+  const mode = options.mode ?? "fast";
+  const formats = options.formats ?? DEFAULT_FORMATS;
+  addFormats(ajv, { mode, formats });
+  return ajv;
+}
+var DEFAULT_FORMATS;
+var init_ajv_formats = __esm({
+  "src/schema/ajv-formats.ts"() {
+    DEFAULT_FORMATS = [
+      "date-time",
+      "email",
+      "hostname",
+      "ipv4",
+      "ipv6",
+      "uri",
+      "uri-reference",
+      "uuid"
+    ];
+  }
+});
 
 // src/schema/errors.ts
 var errors_exports = {};
@@ -1580,10 +1601,7 @@ function createAjv(dialect) {
     // Enable async schema loading for YAML references
     loadSchema: loadReferencedSchema
   });
-  addFormats(ajv, {
-    mode: "fast",
-    formats: ["date-time", "email", "hostname", "ipv4", "ipv6", "uri", "uri-reference"]
-  });
+  applyFulmenAjvFormats(ajv);
   return ajv;
 }
 async function getAjv(dialect) {
@@ -1829,6 +1847,7 @@ var ajvInstances, metaschemaReady, schemaCache;
 var init_validator = __esm({
   "src/schema/validator.ts"() {
     init_telemetry();
+    init_ajv_formats();
     init_errors();
     init_registry();
     init_utils();
@@ -3788,6 +3807,224 @@ var init_capabilities2 = __esm({
   }
 });
 
+// src/foundry/signals/config-reload-endpoint.ts
+function createConfigReloadEndpoint(options) {
+  const { loader, validator, onReload: onReload2, auth, rateLimit, logger, telemetry } = options;
+  return async (payload, req) => {
+    const correlationId = payload.correlation_id ?? generateCorrelationId();
+    const authResult = await auth(req);
+    if (!authResult.authenticated) {
+      if (logger) {
+        logger.warn("Config reload endpoint: authentication failed", {
+          correlation_id: correlationId,
+          reason: authResult.reason
+        });
+      }
+      if (telemetry) {
+        telemetry.emit("fulmen.config.http_endpoint.auth_failed", {
+          correlation_id: correlationId
+        });
+      }
+      return {
+        status: "error",
+        error: "authentication_failed",
+        message: authResult.reason || "Authentication required",
+        statusCode: 401
+      };
+    }
+    const identity = authResult.identity || "unknown";
+    if (rateLimit) {
+      const rateLimitResult = await rateLimit(identity);
+      if (!rateLimitResult.allowed) {
+        if (logger) {
+          logger.warn("Config reload endpoint: rate limit exceeded", {
+            correlation_id: correlationId,
+            identity
+          });
+        }
+        if (telemetry) {
+          telemetry.emit("fulmen.config.http_endpoint.rate_limited", {
+            correlation_id: correlationId
+          });
+        }
+        return {
+          status: "error",
+          error: "rate_limit_exceeded",
+          message: "Rate limit exceeded. Please try again later.",
+          statusCode: 429
+        };
+      }
+    }
+    if (telemetry) {
+      telemetry.emit("fulmen.config.http_endpoint.reload_requested", {
+        correlation_id: correlationId
+      });
+    }
+    try {
+      const config = await loader();
+      if (validator) {
+        const validation = await validator(config);
+        if (!validation.valid) {
+          if (logger) {
+            logger.warn("Config reload endpoint: validation failed", {
+              correlation_id: correlationId,
+              error_count: validation.errors?.length ?? 0
+            });
+          }
+          if (telemetry) {
+            telemetry.emit("fulmen.config.http_endpoint.reload_rejected", {
+              correlation_id: correlationId,
+              reason: "validation_failed"
+            });
+          }
+          return {
+            status: "error",
+            error: "validation_failed",
+            message: "Configuration validation failed",
+            validation_errors: validation.errors,
+            statusCode: 422
+          };
+        }
+      }
+      if (onReload2) {
+        await onReload2(config);
+      }
+      if (telemetry) {
+        telemetry.emit("fulmen.config.http_endpoint.reload_accepted", {
+          correlation_id: correlationId
+        });
+      }
+      if (logger) {
+        logger.info("Config reload endpoint: reload accepted", {
+          correlation_id: correlationId,
+          reason: payload.reason
+        });
+      }
+      return {
+        status: "reloaded",
+        correlation_id: correlationId,
+        message: "Configuration reloaded",
+        statusCode: 200
+      };
+    } catch (error) {
+      if (logger) {
+        logger.warn("Config reload endpoint: reload failed", {
+          correlation_id: correlationId,
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+      if (telemetry) {
+        telemetry.emit("fulmen.config.http_endpoint.reload_error", {
+          correlation_id: correlationId,
+          error_type: error instanceof Error ? error.constructor.name : "unknown"
+        });
+      }
+      return {
+        status: "error",
+        error: "reload_failed",
+        message: error instanceof Error ? error.message : String(error),
+        statusCode: 500
+      };
+    }
+  };
+}
+function generateCorrelationId() {
+  return `cfg-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+}
+var init_config_reload_endpoint = __esm({
+  "src/foundry/signals/config-reload-endpoint.ts"() {
+  }
+});
+
+// src/appidentity/runtime.ts
+function detectRuntime() {
+  const versions = process.versions;
+  if (typeof versions.bun === "string" && versions.bun.length > 0) {
+    return { name: "bun", version: versions.bun };
+  }
+  if (typeof versions.node === "string" && versions.node.length > 0) {
+    return { name: "node", version: versions.node };
+  }
+  return { name: "unknown" };
+}
+function buildRuntimeInfo(options = {}) {
+  const runtime = detectRuntime();
+  const serviceName = options.serviceName ?? options.identity?.app.binary_name ?? "unknown-service";
+  const vendor = options.vendor ?? options.identity?.app.vendor;
+  return {
+    service: {
+      name: serviceName,
+      vendor,
+      version: options.version
+    },
+    runtime,
+    platform: {
+      os: process.platform,
+      arch: process.arch
+    }
+  };
+}
+var init_runtime = __esm({
+  "src/appidentity/runtime.ts"() {
+  }
+});
+
+// src/foundry/signals/control-discovery-endpoint.ts
+function createControlDiscoveryEndpoint(options) {
+  const { identity, version, endpoints, auth, authSummary, logger, telemetry } = options;
+  return async (req) => {
+    if (auth) {
+      const authResult = await auth(req);
+      if (!authResult.authenticated) {
+        if (logger) {
+          logger.warn("Control discovery endpoint: authentication failed", {
+            reason: authResult.reason
+          });
+        }
+        if (telemetry) {
+          telemetry.emit("fulmen.control.discovery.auth_failed", {
+            service: identity.app.binary_name
+          });
+        }
+        return {
+          status: "error",
+          error: "authentication_failed",
+          message: authResult.reason || "Authentication required",
+          statusCode: 401
+        };
+      }
+    }
+    if (telemetry) {
+      telemetry.emit("fulmen.control.discovery.served", {
+        service: identity.app.binary_name
+      });
+    }
+    const runtime = buildRuntimeInfo({ identity, version });
+    return {
+      status: "ok",
+      service: {
+        name: identity.app.binary_name,
+        vendor: identity.app.vendor,
+        version
+      },
+      runtime: {
+        name: runtime.runtime.name,
+        version: runtime.runtime.version,
+        platform: runtime.platform.os,
+        arch: runtime.platform.arch
+      },
+      auth_summary: authSummary,
+      endpoints,
+      statusCode: 200
+    };
+  };
+}
+var init_control_discovery_endpoint = __esm({
+  "src/foundry/signals/control-discovery-endpoint.ts"() {
+    init_runtime();
+  }
+});
+
 // src/foundry/signals/convenience.ts
 async function onShutdown(manager, handler, options = {}) {
   await manager.register("SIGTERM", handler, options);
@@ -4047,7 +4284,7 @@ var init_guards = __esm({
 function createSignalEndpoint(options) {
   const { manager, auth, rateLimit, logger, telemetry, allowedSignals } = options;
   return async (payload, req) => {
-    const correlationId = payload.correlation_id ?? generateCorrelationId();
+    const correlationId = payload.correlation_id ?? generateCorrelationId2();
     const authResult = await auth(req);
     if (!authResult.authenticated) {
       if (logger) {
@@ -4170,7 +4407,7 @@ function normalizeSignalName(signal) {
   }
   return `SIG${upper}`;
 }
-function generateCorrelationId() {
+function generateCorrelationId2() {
   return `sig-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
 }
 function createBearerTokenAuth(expectedToken) {
@@ -4637,6 +4874,8 @@ var init_signals = __esm({
   "src/foundry/signals/index.ts"() {
     init_capabilities2();
     init_catalog();
+    init_config_reload_endpoint();
+    init_control_discovery_endpoint();
     init_convenience();
     init_double_tap();
     init_guards();
@@ -4782,7 +5021,9 @@ __export(foundry_exports, {
   clearMimeTypeCache: () => clearMimeTypeCache,
   clearPatternCache: () => clearPatternCache,
   createBearerTokenAuth: () => createBearerTokenAuth,
+  createConfigReloadEndpoint: () => createConfigReloadEndpoint,
   createConfigReloadHandler: () => createConfigReloadHandler,
+  createControlDiscoveryEndpoint: () => createControlDiscoveryEndpoint,
   createDoubleTapTracker: () => createDoubleTapTracker,
   createSignalEndpoint: () => createSignalEndpoint,
   createSignalManager: () => createSignalManager,
@@ -5838,6 +6079,7 @@ var init_cli = __esm({
 // src/schema/index.ts
 var init_schema = __esm({
   "src/schema/index.ts"() {
+    init_ajv_formats();
     init_cli();
     init_errors();
     init_export();
@@ -5849,6 +6091,32 @@ var init_schema = __esm({
   }
 });
 
+// src/config/env-alias.ts
+function resolveEnvAliases(env, aliasToCanonical) {
+  const out = { ...env };
+  const applied = [];
+  const conflicts = [];
+  for (const [aliasKey, canonicalKey] of Object.entries(aliasToCanonical)) {
+    const aliasValue = env[aliasKey];
+    if (aliasValue === void 0 || aliasValue === "") continue;
+    const canonicalValue = env[canonicalKey];
+    if (canonicalValue === void 0 || canonicalValue === "") {
+      out[canonicalKey] = aliasValue;
+      applied.push({ aliasKey, canonicalKey });
+      continue;
+    }
+    if (canonicalValue !== aliasValue) {
+      conflicts.push({
+        canonicalKey,
+        aliasKey,
+        canonicalValue,
+        aliasValue
+      });
+    }
+  }
+  return { env: out, applied, conflicts };
+}
+
 // src/config/errors.ts
 var ConfigPathError = class _ConfigPathError extends Error {
   constructor(message, cause) {
@@ -6200,6 +6468,33 @@ function parseEnvVars(prefix) {
   }
   return config;
 }
+function parseEnvVarsWithReport(prefix) {
+  const config = {};
+  const consumedKeys = [];
+  const prefixWithSeparator = `${prefix}_`;
+  for (const [key, value] of Object.entries(process.env)) {
+    if (!value) continue;
+    if (key.startsWith(prefixWithSeparator)) {
+      consumedKeys.push(key);
+      const keyWithoutPrefix = key.slice(prefixWithSeparator.length);
+      const parts = keyWithoutPrefix.split("_").filter((p) => p.length > 0);
+      let current = config;
+      for (let i = 0; i < parts.length; i++) {
+        const part = parts[i].toLowerCase();
+        if (i === parts.length - 1) {
+          current[part] = parseEnvValue(value);
+        } else {
+          if (!current[part] || typeof current[part] !== "object") {
+            current[part] = {};
+          }
+          current = current[part];
+        }
+      }
+    }
+  }
+  consumedKeys.sort();
+  return { config, consumedKeys };
+}
 async function parseConfigFile(path) {
   const content = await readFile(path, "utf-8");
   const ext = extname(path).toLowerCase();
@@ -6233,8 +6528,10 @@ async function loadConfig(options) {
     activeLayers.push("user");
   }
   const envPrefix = options.envPrefix || (identity.app ? identity.app.toUpperCase().replace(/-/g, "_") : "APP");
-  const envConfig = parseEnvVars(envPrefix);
-  if (Object.keys(envConfig).length > 0) {
+  const includeEnvVarReport = options.includeEnvVarReport === true;
+  const envVars = includeEnvVarReport ? parseEnvVarsWithReport(envPrefix) : null;
+  const envConfig = includeEnvVarReport ? envVars?.config : parseEnvVars(envPrefix);
+  if (envConfig && typeof envConfig === "object" && Object.keys(envConfig).length > 0) {
     mergedConfig = deepMerge(mergedConfig, envConfig);
     activeLayers.push("env");
   }
@@ -6263,6 +6560,8 @@ async function loadConfig(options) {
       defaultsPath,
       userConfigPath,
       envPrefix,
+      envVarsConsumed: includeEnvVarReport ? envVars?.consumedKeys : void 0,
+      envVarsConsumedCount: includeEnvVarReport ? envVars?.consumedKeys.length : void 0,
       activeLayers,
       schema: {
         path: options.schemaPath || null,
@@ -6275,6 +6574,6 @@ async function loadConfig(options) {
 // src/config/index.ts
 var VERSION2 = "0.1.0";
 
-export { ConfigPathError, ConfigValidationError, VERSION2 as VERSION, ensureDirExists, getAppCacheDir, getAppConfigDir, getAppDataDir, getConfigSearchPaths, getFulmenCacheDir, getFulmenConfigDir, getFulmenDataDir, getXDGBaseDirs, loadConfig, resolveConfigPath };
+export { ConfigPathError, ConfigValidationError, VERSION2 as VERSION, ensureDirExists, getAppCacheDir, getAppConfigDir, getAppDataDir, getConfigSearchPaths, getFulmenCacheDir, getFulmenConfigDir, getFulmenDataDir, getXDGBaseDirs, loadConfig, resolveConfigPath, resolveEnvAliases };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map