@lucapimenta/copy-chief-black 1.0.0

package/framework/.aios-core/copy-chief/config/config-resolver.ts

@@ -0,0 +1,329 @@
+/**
+ * Configuration Resolver — Layered Config Hierarchy
+ *
+ * Port of: aios-core/.aios-core/core/config/config-resolver.js
+ * Adapted for Copy Chief BLACK (TypeScript, Bun runtime)
+ *
+ * Implements 3-level configuration hierarchy:
+ *   L1 Framework  → ~/.claude/framework-config.yaml  (immutable defaults)
+ *   L2 Project    → ~/.claude/core-config.yaml        (quality gates, registry, handoffs)
+ *   L3 Offer      → {offer}/helix-state.yaml          (per-offer overrides)
+ *
+ * Provides:
+ * - resolveConfig(offerPath?) — main entry point, returns merged config
+ * - getCoreConfig() — shortcut for L2 (quality gates, registry)
+ * - getConfigAtLevel(level) — raw config from specific level
+ * - getQualityGates() — quality.gates from merged config
+ * - getRequiredTools(phase) — required_tools for a specific phase
+ * - getAgentRegistry() — agents.registry array
+ *
+ * @module lib/config-resolver
+ * @version 1.0.0
+ * @forked aios-core v4.4.6
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import yaml from 'js-yaml';
+import { globalConfigCache } from './config-cache';
+import { deepMerge as mergeDeep, mergeAll, isPlainObject } from './merge-utils';
+import { interpolateEnvVars } from './env-interpolator';
+
+const HOME = process.env.HOME || '/tmp';
+const CLAUDE_DIR = join(HOME, '.claude');
+const ECOSYSTEM_ROOT = join(HOME, 'copywriting-ecosystem');
+
+// ─── Config File Paths ───────────────────────────────────────────────────────
+
+const CONFIG_FILES = {
+  framework: join(CLAUDE_DIR, 'framework-config.yaml'),  // L1
+  project: join(CLAUDE_DIR, 'core-config.yaml'),          // L2
+  // L3 is dynamic: {offer}/helix-state.yaml
+} as const;
+
+const LEVELS = {
+  framework: 'L1',
+  project: 'L2',
+  offer: 'L3',
+} as const;
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface QualityGate {
+  required_tools: string[];
+  deliverables?: string[];
+  threshold?: string;
+}
+
+export interface AgentRegistryEntry {
+  id: string;
+  name: string;
+  handle: string;
+  title: string;
+  model: string;
+  icon: string;
+  dir: string;
+  triggers: string[];
+  direct?: boolean;
+}
+
+export interface HandoffRule {
+  pattern: string;
+  next_agent: string;
+  message: string;
+  condition?: string;
+}
+
+export interface ResolvedConfig {
+  // L1: Framework
+  quality?: {
+    thresholds?: Record<string, number>;
+    gates?: Record<string, QualityGate>;
+    max_iterations?: Record<string, number>;
+  };
+  workflow?: {
+    phases?: string[];
+    phase_descriptions?: Record<string, string>;
+    default_gates?: Record<string, string[]>;
+  };
+  // L2: Project
+  agents?: {
+    registry?: AgentRegistryEntry[];
+    location?: string;
+    format?: string;
+    activation?: Record<string, string>;
+  };
+  handoffs?: {
+    detection?: string;
+    rules?: HandoffRule[];
+  };
+  context?: {
+    always_load?: string[];
+    per_agent?: Record<string, string[]>;
+  };
+  constitution?: {
+    file?: string;
+    principles?: Array<{
+      id: string;
+      severity: string;
+      rule: string;
+      gate?: string;
+    }>;
+  };
+  stories?: Record<string, unknown>;
+  // L3: Offer
+  _offer_overrides?: Record<string, unknown>;
+  // Metadata
+  _sources?: Record<string, { level: string; file: string }>;
+  _legacy?: boolean;
+}
+
+// ─── YAML Parser (js-yaml — identical to AIOS Core) ─────────────────────────
+// Uses js-yaml for full YAML spec support including nested lists of objects,
+// multi-line strings, anchors, etc. Same dependency as aios-core.
+
+// ─── Deep Merge (delegated to merge-utils.ts) ────────────────────────────────
+// deepMerge follows ADR-PRO-002 rules (last-wins scalars, recursive objects,
+// +append arrays, null-deletes-key). Re-exported for callers that imported it
+// from this module previously.
+export { mergeDeep as deepMerge, mergeAll };
+
+// ─── YAML File Loading ───────────────────────────────────────────────────────
+
+function loadYamlFile(filePath: string): Record<string, any> | null {
+  try {
+    if (!existsSync(filePath)) return null;
+    const content = readFileSync(filePath, 'utf-8');
+    const data = yaml.load(content) as Record<string, any>;
+    return data || {};
+  } catch (error) {
+    console.error(`[CONFIG-RESOLVER] Failed to parse ${filePath}: ${error}`);
+    return null;
+  }
+}
+
+// ─── Source Tracking (debug mode) ────────────────────────────────────────────
+
+function trackSources(
+  sources: Record<string, { level: string; file: string }>,
+  data: Record<string, any>,
+  level: string,
+  file: string,
+  prefix: string = '',
+): void {
+  if (!sources || !data) return;
+
+  for (const [key, value] of Object.entries(data)) {
+    const fullKey = prefix ? `${prefix}.${key}` : key;
+    sources[fullKey] = { level, file };
+
+    if (isPlainObject(value)) {
+      trackSources(sources, value as Record<string, any>, level, file, fullKey);
+    }
+  }
+}
+
+// ─── Main API ────────────────────────────────────────────────────────────────
+
+/**
+ * Resolve the final configuration by merging all levels.
+ *
+ * L1 Framework → L2 Project → L3 Offer
+ *
+ * @param offerPath — Relative path to offer dir (e.g. "saude/florayla")
+ * @param options.debug — Enable source tracking per key
+ * @param options.skipCache — Bypass cache
+ */
+export function resolveConfig(
+  offerPath?: string,
+  options: { debug?: boolean; skipCache?: boolean } = {},
+): ResolvedConfig {
+  const cacheKey = `resolved:${offerPath || 'global'}:${options.debug ? 'debug' : 'std'}`;
+
+  if (!options.skipCache) {
+    const cached = globalConfigCache.get<ResolvedConfig>(cacheKey);
+    if (cached) return cached;
+  }
+
+  const sources: Record<string, { level: string; file: string }> = {};
+
+  // L1: Framework (immutable defaults)
+  const l1 = loadYamlFile(CONFIG_FILES.framework);
+  let config: Record<string, any> = l1 || {};
+
+  if (options.debug && l1) {
+    trackSources(sources, l1, LEVELS.framework, CONFIG_FILES.framework);
+  }
+
+  // L2: Project (quality gates, registry, handoffs)
+  const l2 = loadYamlFile(CONFIG_FILES.project);
+  if (l2) {
+    config = mergeDeep(config, l2);
+    if (options.debug) {
+      trackSources(sources, l2, LEVELS.project, CONFIG_FILES.project);
+    }
+  }
+
+  // L3: Offer (per-offer overrides)
+  if (offerPath) {
+    const helixStatePath = join(ECOSYSTEM_ROOT, offerPath, 'helix-state.yaml');
+    const l3 = loadYamlFile(helixStatePath);
+    if (l3) {
+      // Only merge specific sections from offer level
+      const offerOverrides: Record<string, any> = {};
+      if (l3.config) offerOverrides.quality = l3.config;
+      if (l3.gates_override) offerOverrides.quality = { ...offerOverrides.quality, gates_override: l3.gates_override };
+
+      config = mergeDeep(config, offerOverrides);
+      config._offer_overrides = l3;
+
+      if (options.debug) {
+        trackSources(sources, offerOverrides, LEVELS.offer, helixStatePath);
+      }
+    }
+  }
+
+  if (options.debug) {
+    config._sources = sources;
+  }
+
+  // Run env-var interpolation on the fully merged config (ADR-PRO-002: applied post-merge)
+  const interpolated = interpolateEnvVars(config) as Record<string, any>;
+  // Preserve debug-only _sources (not interpolated — it's metadata, not user config)
+  if (options.debug && config._sources) {
+    interpolated._sources = config._sources;
+  }
+
+  const result = interpolated as ResolvedConfig;
+  globalConfigCache.set(cacheKey, result);
+  return result;
+}
+
+/**
+ * Get raw config from a specific level (no merge).
+ */
+export function getConfigAtLevel(level: 'framework' | 'project' | 'offer', offerPath?: string): Record<string, any> | null {
+  switch (level) {
+    case 'framework':
+      return loadYamlFile(CONFIG_FILES.framework);
+    case 'project':
+      return loadYamlFile(CONFIG_FILES.project);
+    case 'offer':
+      if (!offerPath) return null;
+      return loadYamlFile(join(ECOSYSTEM_ROOT, offerPath, 'helix-state.yaml'));
+    default:
+      return null;
+  }
+}
+
+// ─── Convenience Accessors ───────────────────────────────────────────────────
+
+/**
+ * Get L2 core-config.yaml directly (most common use case).
+ */
+export function getCoreConfig(): Record<string, any> | null {
+  const cacheKey = 'core-config';
+  const cached = globalConfigCache.get<Record<string, any>>(cacheKey);
+  if (cached) return cached;
+
+  const config = loadYamlFile(CONFIG_FILES.project);
+  if (config) globalConfigCache.set(cacheKey, config);
+  return config;
+}
+
+/**
+ * Get quality.gates from merged config.
+ */
+export function getQualityGates(offerPath?: string): Record<string, QualityGate> {
+  const config = resolveConfig(offerPath);
+  return (config.quality?.gates || {}) as Record<string, QualityGate>;
+}
+
+/**
+ * Get required_tools for a specific phase.
+ */
+export function getRequiredTools(phase: string, offerPath?: string): string[] {
+  const gates = getQualityGates(offerPath);
+  return gates[phase]?.required_tools || [];
+}
+
+/**
+ * Get threshold for a specific quality metric.
+ */
+export function getThreshold(name: string, offerPath?: string): number {
+  const config = resolveConfig(offerPath);
+  const thresholds = config.quality?.thresholds || {};
+  return (thresholds as Record<string, number>)[name] || 0;
+}
+
+/**
+ * Get agent registry from L2 config.
+ */
+export function getAgentRegistry(): AgentRegistryEntry[] {
+  const config = getCoreConfig();
+  return (config?.agents?.registry || []) as AgentRegistryEntry[];
+}
+
+/**
+ * Get handoff rules from L2 config.
+ */
+export function getHandoffRules(): HandoffRule[] {
+  const config = getCoreConfig();
+  return (config?.handoffs?.rules || []) as HandoffRule[];
+}
+
+/**
+ * Get context injection rules from L2 config.
+ */
+export function getContextRules(): { always_load: string[]; per_agent: Record<string, string[]> } {
+  const config = getCoreConfig();
+  return {
+    always_load: (config?.context?.always_load || []) as string[],
+    per_agent: (config?.context?.per_agent || {}) as Record<string, string[]>,
+  };
+}
+
+// ─── Exports ─────────────────────────────────────────────────────────────────
+
+export const CONFIG_PATHS = CONFIG_FILES;
+export { LEVELS };

package/framework/.aios-core/copy-chief/config/env-interpolator.js

@@ -0,0 +1,88 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var env_interpolator_exports = {};
+__export(env_interpolator_exports, {
+  ENV_VAR_PATTERN: () => ENV_VAR_PATTERN,
+  interpolateEnvVars: () => interpolateEnvVars,
+  interpolateString: () => interpolateString,
+  lintEnvPatterns: () => lintEnvPatterns
+});
+module.exports = __toCommonJS(env_interpolator_exports);
+var import_merge_utils = require("./merge-utils");
+const ENV_VAR_PATTERN = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-(.*?))?\}/g;
+function interpolateString(value, options) {
+  const warnings = options?.warnings ?? [];
+  ENV_VAR_PATTERN.lastIndex = 0;
+  return value.replace(ENV_VAR_PATTERN, (_match, varName, defaultValue) => {
+    const envValue = process.env[varName];
+    if (envValue !== void 0) {
+      return envValue;
+    }
+    if (defaultValue !== void 0) {
+      return defaultValue;
+    }
+    warnings.push(`Missing environment variable: ${varName} (no default set)`);
+    return "";
+  });
+}
+function interpolateEnvVars(config, options) {
+  const warnings = options?.warnings ?? [];
+  if (typeof config === "string") {
+    return interpolateString(config, { warnings });
+  }
+  if (Array.isArray(config)) {
+    return config.map((item) => interpolateEnvVars(item, { warnings }));
+  }
+  if ((0, import_merge_utils.isPlainObject)(config)) {
+    const result = {};
+    for (const [key, value] of Object.entries(config)) {
+      result[key] = interpolateEnvVars(value, { warnings });
+    }
+    return result;
+  }
+  return config;
+}
+function lintEnvPatterns(config, sourceFile) {
+  const findings = [];
+  function walk(obj, path) {
+    if (typeof obj === "string") {
+      ENV_VAR_PATTERN.lastIndex = 0;
+      if (ENV_VAR_PATTERN.test(obj)) {
+        ENV_VAR_PATTERN.lastIndex = 0;
+        findings.push(`${sourceFile}: ${path} contains env variable pattern: ${obj}`);
+      }
+    } else if ((0, import_merge_utils.isPlainObject)(obj)) {
+      for (const [key, value] of Object.entries(obj)) {
+        walk(value, path ? `${path}.${key}` : key);
+      }
+    } else if (Array.isArray(obj)) {
+      obj.forEach((item, i) => {
+        walk(item, `${path}[${i}]`);
+      });
+    }
+  }
+  walk(config, "");
+  return findings;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ENV_VAR_PATTERN,
+  interpolateEnvVars,
+  interpolateString,
+  lintEnvPatterns
+});

package/framework/.aios-core/copy-chief/config/env-interpolator.ts

@@ -0,0 +1,125 @@
+// hooks/lib/env-interpolator.ts — Port of aios-core env-interpolator.js
+/**
+ * Environment Variable Interpolator
+ *
+ * Resolves ${ENV_VAR} and ${ENV_VAR:-default} patterns in configuration values.
+ * Applied at load time after merge, per ADR-PRO-002.
+ *
+ * Rules:
+ * - ${VAR}: resolves to process.env.VAR; warns if missing, returns ''
+ * - ${VAR:-default}: resolves to process.env.VAR or 'default' if unset
+ * - Recursive: walks nested objects and arrays
+ * - lintEnvPatterns: flags ${...} patterns in framework/project config files
+ *
+ * @module hooks/lib/env-interpolator
+ * @version 1.0.0
+ * @ported-from aios-core/.aios-core/core/config/env-interpolator.js
+ */
+
+import { isPlainObject } from './merge-utils';
+
+/**
+ * Regex for ${ENV_VAR} and ${ENV_VAR:-default_value}
+ * Captures: group 1 = var name, group 2 = default value (optional, after :-)
+ */
+export const ENV_VAR_PATTERN = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-(.*?))?\}/g;
+
+export interface InterpolateOptions {
+  warnings?: string[];
+}
+
+/**
+ * Interpolate environment variables in a single string value.
+ *
+ * @param value - String potentially containing ${VAR} or ${VAR:-default} patterns
+ * @param options - Options object; pass warnings array to collect missing-var messages
+ * @returns Interpolated string
+ */
+export function interpolateString(value: string, options?: InterpolateOptions): string {
+  const warnings = options?.warnings ?? [];
+
+  // Reset lastIndex since ENV_VAR_PATTERN is a shared module-level regex with /g flag
+  ENV_VAR_PATTERN.lastIndex = 0;
+
+  return value.replace(ENV_VAR_PATTERN, (_match: string, varName: string, defaultValue: string | undefined) => {
+    const envValue = process.env[varName];
+
+    if (envValue !== undefined) {
+      return envValue;
+    }
+
+    if (defaultValue !== undefined) {
+      return defaultValue;
+    }
+
+    // Missing required env var (no default)
+    warnings.push(`Missing environment variable: ${varName} (no default set)`);
+    return '';
+  });
+}
+
+/**
+ * Recursively interpolate environment variables in a config value.
+ *
+ * Walks all nested objects and arrays. Only string values are interpolated.
+ *
+ * @param config - Configuration value (object, array, or scalar)
+ * @param options - Options; pass warnings array to collect missing-var messages
+ * @returns Interpolated configuration (same shape, new object)
+ */
+export function interpolateEnvVars(config: unknown, options?: InterpolateOptions): unknown {
+  const warnings = options?.warnings ?? [];
+
+  if (typeof config === 'string') {
+    return interpolateString(config, { warnings });
+  }
+
+  if (Array.isArray(config)) {
+    return config.map(item => interpolateEnvVars(item, { warnings }));
+  }
+
+  if (isPlainObject(config)) {
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(config as Record<string, unknown>)) {
+      result[key] = interpolateEnvVars(value, { warnings });
+    }
+    return result;
+  }
+
+  // Numbers, booleans, null — return as-is
+  return config;
+}
+
+/**
+ * Check a config object for ${...} patterns that probably shouldn't be
+ * in committed files (L1/L2). Returns an array of findings.
+ *
+ * @param config - Configuration to lint
+ * @param sourceFile - File name for reporting
+ * @returns Array of warning strings
+ */
+export function lintEnvPatterns(config: unknown, sourceFile: string): string[] {
+  const findings: string[] = [];
+
+  function walk(obj: unknown, path: string): void {
+    if (typeof obj === 'string') {
+      // Reset lastIndex before test() since pattern has /g flag
+      ENV_VAR_PATTERN.lastIndex = 0;
+      if (ENV_VAR_PATTERN.test(obj)) {
+        ENV_VAR_PATTERN.lastIndex = 0;
+        findings.push(`${sourceFile}: ${path} contains env variable pattern: ${obj}`);
+      }
+    } else if (isPlainObject(obj)) {
+      for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
+        walk(value, path ? `${path}.${key}` : key);
+      }
+    } else if (Array.isArray(obj)) {
+      (obj as unknown[]).forEach((item, i) => {
+        walk(item, `${path}[${i}]`);
+      });
+    }
+  }
+
+  walk(config, '');
+  return findings;
+}

package/framework/.aios-core/copy-chief/config/merge-utils.js

@@ -0,0 +1,68 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var merge_utils_exports = {};
+__export(merge_utils_exports, {
+  deepMerge: () => deepMerge,
+  isPlainObject: () => isPlainObject,
+  mergeAll: () => mergeAll
+});
+module.exports = __toCommonJS(merge_utils_exports);
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object") return false;
+  if (Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function deepMerge(target, source) {
+  if (!isPlainObject(target) || !isPlainObject(source)) {
+    return source !== void 0 ? source : target;
+  }
+  const result = { ...target };
+  for (const [key, value] of Object.entries(source)) {
+    if (key.endsWith("+append")) {
+      const baseKey = key.slice(0, -7);
+      if (Array.isArray(value)) {
+        const existing = result[baseKey];
+        result[baseKey] = Array.isArray(existing) ? [...existing, ...value] : value;
+      }
+      continue;
+    }
+    if (value === null) {
+      delete result[key];
+      continue;
+    }
+    if (isPlainObject(value) && isPlainObject(result[key])) {
+      result[key] = deepMerge(result[key], value);
+      continue;
+    }
+    result[key] = value;
+  }
+  return result;
+}
+function mergeAll(...layers) {
+  return layers.reduce((result, layer) => {
+    if (!layer || !isPlainObject(layer)) return result;
+    return deepMerge(result, layer);
+  }, {});
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  deepMerge,
+  isPlainObject,
+  mergeAll
+});

package/framework/.aios-core/copy-chief/config/merge-utils.ts

@@ -0,0 +1,94 @@
+// hooks/lib/merge-utils.ts — Port of aios-core merge-utils.js
+/**
+ * Merge Utilities for Layered Configuration
+ *
+ * Implements the merge strategy defined in ADR-PRO-002:
+ * - Scalars: last-wins
+ * - Objects: deep merge (recursive)
+ * - Arrays: replace (default, last-wins)
+ * - Arrays with +append suffix: concatenate source onto target
+ * - null values: delete key from result
+ *
+ * @module hooks/lib/merge-utils
+ * @version 1.0.0
+ * @ported-from aios-core/.aios-core/core/config/merge-utils.js
+ */
+
+/**
+ * Check if value is a plain object (not array, null, Date, etc.)
+ */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object') return false;
+  if (Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+/**
+ * Deep merge two configuration objects following ADR-PRO-002 rules.
+ *
+ * Merge strategy:
+ * - Scalars (string, number, boolean): last-wins (source overrides target)
+ * - Objects/Maps: recursive deep merge
+ * - Arrays (default): replace (source replaces target)
+ * - Arrays with +append suffix: concatenate source onto target
+ * - null values: delete the key from result
+ *
+ * @param target - Base configuration (lower priority)
+ * @param source - Override configuration (higher priority)
+ * @returns Merged configuration (new object, inputs unchanged)
+ */
+export function deepMerge(
+  target: Record<string, any>,
+  source: Record<string, any>,
+): Record<string, any> {
+  if (!isPlainObject(target) || !isPlainObject(source)) {
+    return source !== undefined ? source : target;
+  }
+
+  const result: Record<string, any> = { ...target };
+
+  for (const [key, value] of Object.entries(source)) {
+    // Handle +append modifier for arrays
+    if (key.endsWith('+append')) {
+      const baseKey = key.slice(0, -7); // Remove '+append' (7 chars)
+      if (Array.isArray(value)) {
+        const existing = result[baseKey];
+        result[baseKey] = Array.isArray(existing)
+          ? [...existing, ...value]
+          : value;
+      }
+      continue;
+    }
+
+    // Handle null = delete key
+    if (value === null) {
+      delete result[key];
+      continue;
+    }
+
+    // Deep merge plain objects
+    if (isPlainObject(value) && isPlainObject(result[key])) {
+      result[key] = deepMerge(result[key] as Record<string, any>, value as Record<string, any>);
+      continue;
+    }
+
+    // Arrays and scalars: replace (last-wins)
+    result[key] = value;
+  }
+
+  return result;
+}
+
+/**
+ * Merge multiple config layers in order (left to right, last wins).
+ *
+ * @param layers - Configuration layers in priority order (lowest first)
+ * @returns Merged configuration
+ */
+export function mergeAll(...layers: Array<Record<string, any> | null | undefined>): Record<string, any> {
+  return layers.reduce<Record<string, any>>((result, layer) => {
+    if (!layer || !isPlainObject(layer)) return result;
+    return deepMerge(result, layer);
+  }, {});
+}