@zibby/core 0.1.0

package/src/framework/agents/utils/openai-proxy-formatter.js

@@ -0,0 +1,249 @@
+/**
+ * OpenAI Proxy Formatter Utility
+ * Handles structured output post-processing via Zibby's OpenAI proxy
+ * 
+ * Authentication Requirements:
+ * - Local/Dev: User must be logged in via `zibby login` (JWT token in ~/.zibby/config.json)
+ * - CI/CD: Must provide ZIBBY_USER_TOKEN env variable (Personal Access Token)
+ * - Project: Uses ZIBBY_API_KEY for project-scoped access
+ */
+
+import axios from 'axios';
+import { homedir } from 'os';
+import { join } from 'path';
+import { existsSync, readFileSync } from 'fs';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { logger } from '../../../utils/logger.js';
+import { DEFAULT_MODELS, TIMEOUTS } from '../../../constants.js';
+
+/**
+ * Get Zibby user authentication token
+ * Priority: ZIBBY_USER_TOKEN env > zibby login session
+ * @returns {string|null} JWT token or null if not authenticated
+ */
+function getUserToken() {
+  // 1. ECS: per-execution token (generated by ecs-executor, validated by proxy Lambda)
+  if (process.env.OPENAI_PROXY_TOKEN) {
+    logger.debug('[Auth] Using OPENAI_PROXY_TOKEN (ECS execution)');
+    return process.env.OPENAI_PROXY_TOKEN;
+  }
+
+  // 2. CI/CD: user's Personal Access Token (created in UI settings, set as env var)
+  if (process.env.ZIBBY_USER_TOKEN) {
+    logger.debug('[Auth] Using ZIBBY_USER_TOKEN (CI/CD PAT)');
+    return process.env.ZIBBY_USER_TOKEN;
+  }
+
+  // 3. Local dev: zibby login session (~/.zibby/config.json)
+  try {
+    const configPath = join(homedir(), '.zibby', 'config.json');
+    if (existsSync(configPath)) {
+      const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+      if (config.sessionToken) {
+        logger.debug('[Auth] Using session token from zibby login');
+        return config.sessionToken;
+      }
+    }
+  } catch (error) {
+    logger.debug(`[Auth] Could not read zibby login session: ${error.message}`);
+  }
+  
+  return null;
+}
+
+/**
+ * Get OpenAI proxy URL (always prod)
+ * @returns {string} Full URL to OpenAI proxy endpoint
+ */
+function getProxyUrl() {
+  if (process.env.OPENAI_PROXY_URL) {
+    return process.env.OPENAI_PROXY_URL.replace(/\/v1\/?$/, '');
+  }
+  return 'https://api-prod.zibby.app/openai-proxy';
+}
+
+/**
+ * Normalize Zod JSON schema for OpenAI Structured Outputs API
+ * @param {Object} schema - Zod-generated JSON schema
+ */
+function normalizeSchemaForOpenAI(schema) {
+  if (typeof schema !== 'object' || schema === null) return;
+  
+  // Empty objects need type definition
+  if (Object.keys(schema).length === 0) {
+    schema.type = 'object';
+    schema.additionalProperties = true;
+    return;
+  }
+  
+  // Infer type from structure if missing
+  if (!schema.type) {
+    if (schema.properties) {
+      schema.type = 'object';
+    } else if (schema.items) {
+      schema.type = 'array';
+    }
+  }
+  
+  // Objects must have additionalProperties: false and all keys in required for strict mode
+  if (schema.type === 'object') {
+    if (schema.properties) {
+      // Drop properties that use dynamic keys (additionalProperties as value schema)
+      // since OpenAI strict mode requires additionalProperties: false
+      for (const [key, prop] of Object.entries(schema.properties)) {
+        if (prop.type === 'object' && prop.additionalProperties && prop.additionalProperties !== false) {
+          if (!prop.properties || Object.keys(prop.properties).length === 0) {
+            // Dynamic-key object (e.g. Record<string, number>) — replace with empty nullable object
+            schema.properties[key] = { type: ['object', 'null'] };
+          }
+        }
+      }
+      
+      schema.additionalProperties = false;
+      schema.required = Object.keys(schema.properties);
+      Object.values(schema.properties).forEach(normalizeSchemaForOpenAI);
+    } else if (!('additionalProperties' in schema)) {
+      schema.additionalProperties = true;
+    }
+  }
+  
+  // Recursively normalize array items
+  if (schema.type === 'array' && schema.items) {
+    normalizeSchemaForOpenAI(schema.items);
+  }
+}
+
+/**
+ * Format raw AI output into structured JSON using OpenAI proxy
+ * 
+ * @param {string} rawText - Raw text output from AI agent
+ * @param {ZodSchema} zodSchema - Zod schema for validation
+ * @returns {Promise<Object>} { structured: Object, raw: string }
+ * @throws {Error} If authentication fails or OpenAI request fails
+ */
+export async function formatWithOpenAIProxy(rawText, zodSchema) {
+  logger.info('🔧 [OpenAI Proxy] Formatting structured output...');
+  
+  // 1. Check authentication
+  const userToken = getUserToken();
+  if (!userToken) {
+    throw new Error(
+      'Authentication required for structured output processing.\n' +
+      '  Local development: Run `zibby login`\n' +
+      '  CI/CD: Set ZIBBY_USER_TOKEN environment variable (Personal Access Token from UI settings)'
+    );
+  }
+  
+  // 2. Get proxy URL
+  const proxyUrl = getProxyUrl();
+  logger.info(`🔗 Using OpenAI proxy: ${proxyUrl}`);
+  
+  // 3. Convert Zod schema to JSON Schema
+  const fullSchema = zodToJsonSchema(zodSchema);
+  
+  let actualSchema = fullSchema;
+  
+  // Handle $ref definitions
+  if (fullSchema.$ref && fullSchema.definitions) {
+    const refKey = fullSchema.$ref.split('/').pop();
+    actualSchema = fullSchema.definitions[refKey] || fullSchema;
+    logger.debug(`Extracted schema from $ref: ${refKey}`);
+  }
+  
+  // Remove $schema meta field
+  delete actualSchema.$schema;
+  
+  // Normalize for OpenAI strict mode
+  normalizeSchemaForOpenAI(actualSchema);
+  
+  // 4. Prepare OpenAI request — truncate to fit model context (~120K tokens ≈ ~400K chars)
+  const MAX_TEXT_CHARS = 400_000;
+  let trimmedText = rawText;
+  if (rawText.length > MAX_TEXT_CHARS) {
+    logger.warn(`⚠️  [OpenAI Proxy] Raw text (${rawText.length} chars) exceeds limit, keeping last ${MAX_TEXT_CHARS} chars`);
+    trimmedText = `... [truncated early content] ...\n${  rawText.slice(-MAX_TEXT_CHARS)}`;
+  }
+
+  const formattingPrompt = `Extract and format the following information into structured JSON matching the schema.
+
+RAW CONTENT:
+${trimmedText}
+
+Extract all relevant information and format it according to the schema. If any required fields are missing, do your best to infer them from the content.`;
+
+  const requestBody = {
+    model: DEFAULT_MODELS.OPENAI_POSTPROCESSING,
+    messages: [
+      { role: 'user', content: formattingPrompt }
+    ],
+    response_format: {
+      type: 'json_schema',
+      json_schema: {
+        name: 'extract',
+        schema: actualSchema,
+        strict: true
+      }
+    }
+  };
+
+  logger.info(`📤 Sending to OpenAI proxy: model=${DEFAULT_MODELS.OPENAI_POSTPROCESSING}, schema keys=${Object.keys(actualSchema.properties || {}).join(', ')}`);
+  logger.debug(`   Schema size: ${JSON.stringify(actualSchema).length} chars`);
+  logger.debug(`   Prompt size: ${formattingPrompt.length} chars`);
+
+  // 5. Call Zibby OpenAI proxy
+  try {
+    const headers = { 'Content-Type': 'application/json' };
+
+    if (process.env.OPENAI_PROXY_TOKEN) {
+      // ECS: proxy Lambda validates x-proxy-token + x-execution-id against DynamoDB
+      headers['x-proxy-token'] = userToken;
+      headers['x-execution-id'] = process.env.EXECUTION_ID || '';
+    } else {
+      // Local/CI: user JWT or PAT in Authorization header
+      headers['Authorization'] = `Bearer ${userToken}`;
+      headers['x-api-key'] = process.env.ZIBBY_API_KEY || '';
+      headers['x-execution-id'] = process.env.EXECUTION_ID || '';
+    }
+
+    const response = await axios.post(proxyUrl, requestBody, {
+      headers,
+      timeout: TIMEOUTS.OPENAI_REQUEST
+    });
+
+    const content = response.data?.choices?.[0]?.message?.content;
+    if (!content) {
+      throw new Error('OpenAI proxy returned empty response');
+    }
+
+    const parsed = JSON.parse(content);
+    logger.info('✅ Successfully formatted with OpenAI proxy');
+    
+    return {
+      structured: parsed,
+      raw: rawText
+    };
+  } catch (error) {
+    if (error.response) {
+      const status = error.response.status;
+      const errorData = error.response.data;
+      
+      logger.error(`❌ OpenAI proxy request failed: ${status}`);
+      logger.error(`   Status: ${status}`);
+      logger.error(`   Response: ${JSON.stringify(errorData, null, 2)}`);
+      
+      if (status === 401 || status === 403) {
+        throw new Error(
+          'Authentication failed for OpenAI proxy.\n' +
+          '  Run `zibby login` or set ZIBBY_USER_TOKEN environment variable.\n' +
+          `  Response: ${JSON.stringify(errorData)}`,
+          { cause: error }
+        );
+      }
+      
+      throw new Error(`Failed to format Cursor output: ${errorData?.error?.message || 'Unknown error'}`, { cause: error });
+    }
+    
+    logger.error(`❌ OpenAI proxy request failed: ${error.message}`);
+    throw new Error(`Failed to format output: ${error.message}`, { cause: error });
+  }
+}

package/src/framework/code-generator.js

@@ -0,0 +1,301 @@
+import { NODE_DEFAULT_TOOLS } from './tool-resolver.js';
+import { getNodeTemplate } from './node-registry.js';
+
+export function generateWorkflowCode(config, meta = {}) {
+  const { nodes, edges, nodeConfigs = {} } = config;
+
+  const decisionNodeIds = new Set();
+  const executableNodes = [];
+  const nodeTypeMap = new Map();
+
+  for (const node of nodes) {
+    const nodeType = node.data?.nodeType || node.type;
+    nodeTypeMap.set(node.id, nodeType);
+    if (nodeType === 'decision') {
+      decisionNodeIds.add(node.id);
+    } else {
+      executableNodes.push({ id: node.id, nodeType, label: node.data?.label || node.id });
+    }
+  }
+
+  const usesRegisteredNodes = executableNodes.some(n => {
+    const nc = nodeConfigs[n.id] || {};
+    return !nc.customCode && !nc.executeCode;
+  });
+
+  const { toolsPerNode, toolIdsByVar } = collectToolBindings(executableNodes, nodeConfigs);
+  const { simpleEdges, conditionalEdges } = collapseEdges(edges, decisionNodeIds);
+  const entryNode = findEntryNode(executableNodes, edges, decisionNodeIds);
+
+  const lines = [];
+
+  const workflowType = meta.workflowType || 'workflow';
+  
+  lines.push(generateHeader(meta));
+  lines.push(generateImports(workflowType, { usesRegisteredNodes }));
+  lines.push(generateToolDeclarations(toolIdsByVar));
+  lines.push(generateConfigLoader(workflowType));
+  lines.push(generateNodeFunctions(executableNodes, nodeConfigs));
+  lines.push(generateBuildFunction(
+    executableNodes, entryNode,
+    simpleEdges, conditionalEdges, toolsPerNode, workflowType
+  ));
+
+  return lines.filter(Boolean).join('\n');
+}
+
+export function generateNodeConfigsJson(nodeConfigs) {
+  const cleaned = {};
+  for (const [nodeId, config] of Object.entries(nodeConfigs)) {
+    const { tools: _tools, ...rest } = config;
+    if (Object.keys(rest).length > 0) {
+      cleaned[nodeId] = rest;
+    }
+  }
+  return cleaned;
+}
+
+function generateHeader(meta) {
+  const wfType = meta.workflowType || 'workflow';
+  const lines = [
+    `// Generated by Zibby Visual Workflow Editor`,
+    `// ${meta.projectId ? `Project: ${meta.projectId} | ` : ''}Type: ${wfType} | Version: ${meta.version ?? 0}`,
+    `// Downloaded: ${new Date().toISOString()}`,
+    `//`,
+    `// Upload back:  zibby workflow upload --project <id> --type ${wfType}`,
+    '',
+  ];
+  return lines.join('\n');
+}
+
+function generateImports(workflowType, { usesRegisteredNodes = true } = {}) {
+  const lines = [
+    `import '@zibby/skills';`,
+    `import { WorkflowGraph } from '@zibby/core/framework/graph.js';`,
+    `import { invokeAgent } from '@zibby/core';`,
+    `import { getResolvedToolDefinitions } from '@zibby/core/framework/tool-resolver.js';`,
+  ];
+
+  if (usesRegisteredNodes) {
+    lines.push(`import '@zibby/core/templates/register-nodes.js';`);
+  }
+
+  lines.push(
+    `import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';`,
+    `import { join, dirname } from 'path';`,
+    `import { fileURLToPath } from 'url';`,
+    '',
+  );
+  return lines.join('\n');
+}
+
+function generateToolDeclarations(uniqueToolSets) {
+  if (uniqueToolSets.size === 0) return '';
+
+  const lines = [
+    `// ── Tool Bindings ────────────────────────────────────────────────────`,
+    `// Each call resolves skill IDs → full schemas + MCP server configs`,
+    `// from the skill registry (populated by @zibby/skills import above).`,
+  ];
+
+  for (const [varName, toolIds] of uniqueToolSets) {
+    const desc = toolIds.join(', ');
+    lines.push(`const ${varName} = getResolvedToolDefinitions(${JSON.stringify(toolIds)});  // ${desc}`);
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+function generateConfigLoader(workflowType) {
+  const lines = [
+    `// ── Node Configs (extra instructions, runtime settings) ─────────────`,
+    `const __filename = fileURLToPath(import.meta.url);`,
+    `const __dirname = dirname(__filename);`,
+    `const configPath = join(__dirname, 'workflow-${workflowType}.config.json');`,
+    `const nodeConfigs = existsSync(configPath)`,
+    `  ? JSON.parse(readFileSync(configPath, 'utf-8'))`,
+    `  : {};`,
+    '',
+  ];
+  return lines.join('\n');
+}
+
+
+function generateNodeFunctions(executableNodes, nodeConfigs) {
+  const lines = [
+    `// ── Node Implementations ─────────────────────────────────────────────`,
+    `// Each node's execute function is inlined below.`,
+    `// Edit any function to customize behavior. The upload command detects`,
+    `// changes via // @custom markers and persists them to the cloud.`,
+    '',
+  ];
+
+  for (const node of executableNodes) {
+    const varName = sanitizeVarName(node.id);
+    const customCode = nodeConfigs[node.id]?.customCode;
+
+    if (customCode) {
+      lines.push(`// @custom — modified from default "${node.nodeType}" template`);
+      lines.push(`const ${varName}_execute = ${customCode};`);
+    } else {
+      const template = getNodeTemplate(node.nodeType);
+      if (template) {
+        lines.push(`// Default "${node.nodeType}" implementation`);
+        lines.push(`const ${varName}_execute = ${template};`);
+      } else {
+        lines.push(`// No template available for "${node.nodeType}" — using passthrough`);
+        lines.push(`const ${varName}_execute = async (state) => ({ success: true, output: {}, raw: null });`);
+      }
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function generateBuildFunction(
+  executableNodes, entryNode,
+  simpleEdges, conditionalEdges, toolsPerNode, _workflowType = 'workflow'
+) {
+  const lines = [];
+
+  lines.push(`// ── Graph Builder ────────────────────────────────────────────────────`);
+  lines.push(`export function buildGraph(options = {}) {`);
+  lines.push(`  const graph = new WorkflowGraph(options);`);
+  lines.push('');
+
+  lines.push(`  // Nodes`);
+  for (const node of executableNodes) {
+    const varName = sanitizeVarName(node.id);
+    lines.push(`  graph.addNode('${node.id}', { name: '${node.id}', execute: ${varName}_execute });`);
+    lines.push(`  graph.setNodeType('${node.id}', '${node.nodeType}');`);
+  }
+
+  lines.push('');
+  lines.push(`  // Entry point`);
+  lines.push(`  graph.setEntryPoint('${entryNode}');`);
+  lines.push('');
+
+  if (simpleEdges.length > 0 || conditionalEdges.length > 0) {
+    lines.push(`  // Edges`);
+  }
+
+  for (const edge of simpleEdges) {
+    lines.push(`  graph.addEdge('${edge.source}', '${edge.target}');`);
+  }
+
+  for (const cond of conditionalEdges) {
+    const indented = cond.code.split('\n').map((line, i) => i === 0 ? line : `  ${line}`).join('\n');
+    lines.push(`  graph.addConditionalEdges('${cond.source}', ${indented});`);
+  }
+
+  const toolMapEntries = [];
+  for (const node of executableNodes) {
+    const toolVar = toolsPerNode.get(node.id);
+    if (toolVar) {
+      toolMapEntries.push(`    '${node.id}': ${toolVar},`);
+    }
+  }
+
+  if (toolMapEntries.length > 0) {
+    lines.push('');
+    lines.push(`  graph.resolvedToolsMap = {`);
+    for (const entry of toolMapEntries) {
+      lines.push(`  ${entry}`);
+    }
+    lines.push(`  };`);
+  }
+
+  lines.push('');
+  lines.push(`  return graph;`);
+  lines.push(`}`);
+  lines.push('');
+
+  lines.push(`// ── Exports ──────────────────────────────────────────────────────────`);
+  lines.push(`export { nodeConfigs };`);
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+function collectToolBindings(executableNodes, nodeConfigs) {
+  const toolsPerNode = new Map();
+  const toolIdsByVar = new Map();
+
+  for (const node of executableNodes) {
+    const userTools = nodeConfigs[node.id]?.tools;
+    let toolIds;
+
+    if (Array.isArray(userTools) && userTools.length > 0) {
+      toolIds = [...userTools].sort();
+    } else {
+      const defaults = NODE_DEFAULT_TOOLS[node.nodeType];
+      if (defaults && defaults.length > 0) {
+        toolIds = [...defaults].sort();
+      }
+    }
+
+    if (toolIds) {
+      const varName = `${toolIds.map(id => id.replace(/[^a-zA-Z0-9]/g, '')).join('And')  }Tools`;
+      toolsPerNode.set(node.id, varName);
+      if (!toolIdsByVar.has(varName)) {
+        toolIdsByVar.set(varName, toolIds);
+      }
+    }
+  }
+
+  return { toolsPerNode, toolIdsByVar };
+}
+
+
+function collapseEdges(edges, decisionNodeIds) {
+  const simpleEdges = [];
+  const conditionalEdges = [];
+  const edgesBySource = new Map();
+  const processedDecisions = new Set();
+
+  for (const edge of edges) {
+    const src = edge.source;
+    if (!edgesBySource.has(src)) edgesBySource.set(src, []);
+    edgesBySource.get(src).push(edge);
+  }
+
+  for (const edge of edges) {
+    if (decisionNodeIds.has(edge.source)) continue;
+
+    if (decisionNodeIds.has(edge.target)) {
+      if (processedDecisions.has(edge.target)) continue;
+      processedDecisions.add(edge.target);
+
+      const outgoing = edgesBySource.get(edge.target) || [];
+      const edgeWithCode = outgoing.find(
+        e => e.data?.conditionalCode || e.conditionalCode
+      );
+
+      if (edgeWithCode) {
+        const code = edgeWithCode.data?.conditionalCode || edgeWithCode.conditionalCode;
+        conditionalEdges.push({ source: edge.source, code });
+      }
+    } else {
+      simpleEdges.push({ source: edge.source, target: edge.target });
+    }
+  }
+
+  return { simpleEdges, conditionalEdges };
+}
+
+function findEntryNode(executableNodes, edges, decisionNodeIds) {
+  const incomingTargets = new Set();
+  for (const edge of edges) {
+    if (!decisionNodeIds.has(edge.target)) {
+      incomingTargets.add(edge.target);
+    }
+  }
+  const entry = executableNodes.find(n => !incomingTargets.has(n.id));
+  return entry ? entry.id : executableNodes[0]?.id;
+}
+
+function sanitizeVarName(nodeId) {
+  return nodeId.replace(/[^a-zA-Z0-9]/g, '_');
+}

package/src/framework/constants.js

@@ -0,0 +1,33 @@
+/**
+ * Framework constants for paths, filenames, and configuration defaults
+ */
+
+// Out directory structure
+export const DEFAULT_OUTPUT_BASE = '.zibby/output';
+export const SESSIONS_DIR = 'sessions';
+export const SESSION_INFO_FILE = '.session-info.json';
+
+// Node output files
+export const RESULT_FILE = 'result.json';
+export const RAW_OUTPUT_FILE = 'raw_stream_output.txt';
+export const EVENTS_FILE = 'events.json';
+
+// Node skills — declares what capabilities a node needs (agent-agnostic).
+// Skill definitions (MCP server configs, tool schemas) live in @zibby/skills.
+// Import @zibby/skills to register built-in skills, or call registerSkill()
+// from ./skill-registry.js for custom skills.
+export const SKILLS = {
+  BROWSER: 'browser',
+  JIRA: 'jira',
+  GITHUB: 'github',
+  SLACK: 'slack',
+  MEMORY: 'memory',
+};
+
+// CI environment variables for session ID detection
+export const CI_ENV_VARS = [
+  'CI_JOB_ID',
+  'GITHUB_RUN_ID',
+  'CIRCLE_WORKFLOW_ID',
+  'BUILD_ID'
+];

package/src/framework/context-loader.js

@@ -0,0 +1,101 @@
+import { existsSync, readFileSync } from 'fs';
+import { join, dirname } from 'path';
+
+export class ContextLoader {
+  static async loadContext(specPath, cwd, config = {}) {
+    const context = {};
+    
+    // Get list of context filenames to search for (default: CONTEXT.md, AGENTS.md)
+    const filenames = config.filenames || ['CONTEXT.md', 'AGENTS.md'];
+    
+    // Auto-discover cascade: search from spec directory up to root
+    if (specPath) {
+      const specDir = dirname(join(cwd, specPath));
+      
+      for (const filename of filenames) {
+        const content = await this.findAndMergeContextFiles(filename, specDir, cwd);
+        if (content) {
+          // Use filename without extension as key (e.g., CONTEXT.md -> context)
+          const key = filename.replace(/\.[^.]+$/, '').toLowerCase();
+          context[key] = content;
+        }
+      }
+    }
+    
+    // Also load any explicitly configured discovery files
+    const discovery = config.discovery || {};
+    for (const [key, pathTemplate] of Object.entries(discovery)) {
+      try {
+        const resolvedPath = join(cwd, pathTemplate);
+        if (existsSync(resolvedPath)) {
+          const content = await this.loadFile(resolvedPath);
+          context[key] = content;
+        }
+      } catch (err) {
+        console.warn(`⚠️  Could not load context '${key}' from '${pathTemplate}': ${err.message}`);
+      }
+    }
+
+    return context;
+  }
+
+  // Auto-discover: search up the directory tree for context files
+  static async findAndMergeContextFiles(filename, startDir, rootDir) {
+    const contents = [];
+    let currentDir = startDir;
+
+    // Walk up the tree from spec directory to root
+    while (currentDir.startsWith(rootDir)) {
+      const contextPath = join(currentDir, filename);
+      
+      if (existsSync(contextPath)) {
+        try {
+          const content = await this.loadFile(contextPath);
+          contents.unshift(content); // Add to beginning (root context first)
+        } catch (err) {
+          console.warn(`⚠️  Could not load ${filename} from ${contextPath}: ${err.message}`);
+        }
+      }
+      
+      // Move up one directory
+      const parentDir = dirname(currentDir);
+      if (parentDir === currentDir) break; // Reached filesystem root
+      currentDir = parentDir;
+    }
+
+    // Merge all context files (root → specific)
+    if (contents.length === 0) return null;
+    
+    // If all files are strings (markdown), concatenate with separator
+    if (contents.every(c => typeof c === 'string')) {
+      return contents.join('\n\n---\n\n');
+    }
+    
+    // If objects (JSON/JS), merge them
+    if (contents.every(c => typeof c === 'object')) {
+      return Object.assign({}, ...contents);
+    }
+    
+    // Mixed types: return the most specific (last one)
+    return contents[contents.length - 1];
+  }
+
+  static async loadFile(filePath) {
+    const content = readFileSync(filePath, 'utf-8');
+    
+    // Try to parse as JSON
+    if (filePath.endsWith('.json')) {
+      return JSON.parse(content);
+    }
+    
+    // Try to import as JS module
+    if (filePath.endsWith('.js') || filePath.endsWith('.mjs')) {
+      const { pathToFileURL } = await import('url');
+      const module = await import(pathToFileURL(filePath).href);
+      return module.default || module;
+    }
+    
+    // Return raw content (markdown, yaml, txt, etc.)
+    return content;
+  }
+}