@kadi.build/core 0.0.1-alpha.0 → 0.0.1-alpha.10

package/dist/config/ConfigLoader.js

@@ -0,0 +1,226 @@
+/**
+ * Configuration Loader
+ *
+ * Loads configuration from various sources:
+ * - Environment variables
+ * - Configuration files (agent.json, kadi.config.json)
+ * - Package.json
+ *
+ * @module config/ConfigLoader
+ */
+import { readFileSync, existsSync } from 'fs';
+import { resolve, dirname } from 'path';
+/**
+ * Configuration Loader
+ *
+ * Handles the actual loading of configuration from files and environment.
+ * Separated from ConfigResolver for testability.
+ *
+ * @example
+ * ```typescript
+ * const loader = new ConfigLoader();
+ *
+ * // Load from environment
+ * const envConfig = loader.loadFromEnvironment();
+ *
+ * // Load from file
+ * const fileConfig = await loader.loadFromFile();
+ * ```
+ */
+export class ConfigLoader {
+    /**
+     * Configuration file names to search for (in order of preference)
+     */
+    configFiles = [
+        'agent.json',
+        'kadi.config.json',
+        '.kadirc.json'
+    ];
+    /**
+     * Load configuration from environment variables
+     *
+     * Reads KADI_* environment variables and returns structured config.
+     *
+     * @returns Environment configuration
+     *
+     * @example
+     * ```typescript
+     * // With environment variables:
+     * // KADI_BROKER_URL=ws://localhost:8080
+     * // KADI_NETWORKS=global,team-alpha
+     *
+     * const config = loader.loadFromEnvironment();
+     * // { KADI_BROKER_URL: 'ws://localhost:8080', KADI_NETWORKS: 'global,team-alpha' }
+     * ```
+     */
+    loadFromEnvironment() {
+        return {
+            KADI_BROKER_URL: process.env.KADI_BROKER_URL,
+            KADI_NETWORKS: process.env.KADI_NETWORKS,
+            KADI_TRANSPORT: this.parseTransport(process.env.KADI_TRANSPORT),
+            KADI_AGENT_NAME: process.env.KADI_AGENT_NAME,
+            KADI_AUTO_CONNECT: process.env.KADI_AUTO_CONNECT
+        };
+    }
+    /**
+     * Load configuration from file
+     *
+     * Searches for configuration files in order of preference:
+     * 1. agent.json
+     * 2. kadi.config.json
+     * 3. .kadirc.json
+     *
+     * Searches from current directory up to root.
+     *
+     * @param startDir - Directory to start searching from (defaults to cwd)
+     * @returns Loaded configuration or null if not found
+     *
+     * @example
+     * ```typescript
+     * const config = await loader.loadFromFile();
+     * if (config) {
+     *   console.log('Loaded from:', config.name);
+     * }
+     * ```
+     */
+    async loadFromFile(startDir) {
+        const searchDir = startDir ?? process.cwd();
+        // Search for config files
+        for (const configFile of this.configFiles) {
+            const filePath = this.findConfigFile(configFile, searchDir);
+            if (filePath) {
+                return this.loadConfigFile(filePath);
+            }
+        }
+        // Also try loading from package.json
+        const packageConfig = this.loadFromPackageJson(searchDir);
+        if (packageConfig) {
+            return packageConfig;
+        }
+        return null;
+    }
+    /**
+     * Find a configuration file by searching up the directory tree
+     *
+     * @param filename - Config filename to search for
+     * @param startDir - Directory to start searching from
+     * @returns Full path to config file or null if not found
+     */
+    findConfigFile(filename, startDir) {
+        let currentDir = resolve(startDir);
+        const root = resolve('/');
+        while (currentDir !== root) {
+            const filePath = resolve(currentDir, filename);
+            if (existsSync(filePath)) {
+                return filePath;
+            }
+            // Move up one directory
+            const parentDir = dirname(currentDir);
+            if (parentDir === currentDir) {
+                break; // Reached root
+            }
+            currentDir = parentDir;
+        }
+        return null;
+    }
+    /**
+     * Load and parse a configuration file
+     *
+     * @param filePath - Path to configuration file
+     * @returns Parsed configuration
+     * @throws If file cannot be read or parsed
+     */
+    loadConfigFile(filePath) {
+        try {
+            const content = readFileSync(filePath, 'utf-8');
+            const config = JSON.parse(content);
+            return config;
+        }
+        catch (error) {
+            console.warn(`Failed to load config file ${filePath}:`, error);
+            throw error;
+        }
+    }
+    /**
+     * Load KADI configuration from package.json
+     *
+     * Looks for a "kadi" field in package.json
+     *
+     * @param startDir - Directory to start searching from
+     * @returns Configuration from package.json or null
+     *
+     * @example
+     * ```json
+     * // package.json
+     * {
+     *   "name": "my-package",
+     *   "kadi": {
+     *     "name": "my-service",
+     *     "brokers": {
+     *       "local": "ws://localhost:8080"
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    loadFromPackageJson(startDir) {
+        const packageJsonPath = this.findConfigFile('package.json', startDir);
+        if (!packageJsonPath) {
+            return null;
+        }
+        try {
+            const content = readFileSync(packageJsonPath, 'utf-8');
+            const packageJson = JSON.parse(content);
+            if (packageJson.kadi) {
+                return packageJson.kadi;
+            }
+        }
+        catch (error) {
+            // Ignore package.json errors - it's optional
+        }
+        return null;
+    }
+    /**
+     * Parse transport string to TransportKind
+     *
+     * @param value - Transport string
+     * @returns TransportKind or undefined
+     */
+    parseTransport(value) {
+        if (!value) {
+            return undefined;
+        }
+        const lower = value.toLowerCase();
+        if (lower === 'native' || lower === 'stdio' || lower === 'broker') {
+            return lower;
+        }
+        return undefined;
+    }
+    /**
+     * Get configuration file path if one exists
+     *
+     * Useful for debugging and logging which config file is being used.
+     *
+     * @param startDir - Directory to start searching from
+     * @returns Path to config file or null
+     *
+     * @example
+     * ```typescript
+     * const configPath = loader.getConfigPath();
+     * if (configPath) {
+     *   console.log('Using config from:', configPath);
+     * }
+     * ```
+     */
+    getConfigPath(startDir) {
+        const searchDir = startDir ?? process.cwd();
+        for (const configFile of this.configFiles) {
+            const filePath = this.findConfigFile(configFile, searchDir);
+            if (filePath) {
+                return filePath;
+            }
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=ConfigLoader.js.map

package/dist/config/ConfigLoader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConfigLoader.js","sourceRoot":"","sources":["../../src/config/ConfigLoader.ts"],"names":[],"mappings":"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"}

package/dist/config/ConfigResolver.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Configuration Resolver
+ *
+ * Resolves configuration from multiple sources with clear precedence:
+ * 1. Code (explicit parameters) - Highest priority
+ * 2. Environment variables
+ * 3. Configuration file (agent.json)
+ * 4. Defaults - Lowest priority
+ *
+ * @module config/ConfigResolver
+ */
+import type { KadiConfig, ResolvedConfig } from '../types/index.js';
+import { ConfigLoader } from './ConfigLoader.js';
+/**
+ * Configuration Resolver
+ *
+ * Handles merging configuration from multiple sources with well-defined precedence.
+ * Makes configuration predictable and debuggable.
+ *
+ * @example
+ * ```typescript
+ * const resolver = new ConfigResolver();
+ *
+ * // Simple string config
+ * const config = await resolver.resolve('ws://localhost:8080');
+ *
+ * // Full config object
+ * const config = await resolver.resolve({
+ *   name: 'my-service',
+ *   brokers: { local: 'ws://localhost:8080' }
+ * });
+ * ```
+ */
+export declare class ConfigResolver {
+    private readonly loader;
+    /**
+     * Create a new ConfigResolver
+     *
+     * @param loader - Optional custom config loader (for testing)
+     */
+    constructor(loader?: ConfigLoader);
+    /**
+     * Resolve complete configuration from multiple sources
+     *
+     * Precedence (highest to lowest):
+     * 1. Explicit code configuration
+     * 2. Environment variables
+     * 3. Configuration file (agent.json)
+     * 4. Default values
+     *
+     * @param config - Configuration string (broker URL) or object
+     * @returns Fully resolved configuration with sources tracked
+     *
+     * @throws {KadiError} If configuration is invalid
+     *
+     * @example
+     * ```typescript
+     * // Simple broker URL
+     * const resolved = await resolver.resolve('ws://localhost:8080');
+     *
+     * // Full configuration
+     * const resolved = await resolver.resolve({
+     *   name: 'calculator',
+     *   brokers: { local: 'ws://localhost:8080' },
+     *   networks: ['global', 'team']
+     * });
+     * ```
+     */
+    resolve(config: KadiConfig): Promise<ResolvedConfig>;
+    /**
+     * Normalize configuration input
+     *
+     * Converts string (broker URL) to object form
+     *
+     * @param config - Configuration input
+     * @returns Normalized configuration object
+     */
+    private normalizeConfig;
+    /**
+     * Resolve a single field with precedence
+     *
+     * @template T - Field value type
+     * @param fieldName - Name of the field being resolved
+     * @param codeValue - Value from code
+     * @param envValue - Value from environment
+     * @param fileValue - Value from file
+     * @param defaultValue - Default value
+     * @param sources - Source tracking object
+     * @returns Resolved value
+     */
+    private resolveField;
+    /**
+     * Resolve broker configuration
+     *
+     * @param codeConfig - Code configuration
+     * @param envConfig - Environment configuration
+     * @param fileConfig - File configuration
+     * @param sources - Source tracking
+     * @returns Resolved brokers
+     */
+    private resolveBrokers;
+    /**
+     * Resolve networks configuration
+     *
+     * @param codeConfig - Code configuration
+     * @param envConfig - Environment configuration
+     * @param fileConfig - File configuration
+     * @param sources - Source tracking
+     * @returns Resolved networks
+     */
+    private resolveNetworks;
+    /**
+     * Resolve advanced configuration
+     *
+     * @param codeConfig - Code configuration
+     * @param sources - Source tracking
+     * @returns Resolved advanced config
+     */
+    private resolveAdvanced;
+    /**
+     * Validate resolved configuration
+     *
+     * @param config - Resolved configuration
+     * @throws {KadiError} If configuration is invalid
+     */
+    private validateConfig;
+    /**
+     * Parse boolean from string
+     *
+     * @param value - String value
+     * @returns Boolean or undefined
+     */
+    private parseBoolean;
+}
+//# sourceMappingURL=ConfigResolver.d.ts.map

package/dist/config/ConfigResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConfigResolver.d.ts","sourceRoot":"","sources":["../../src/config/ConfigResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAEV,UAAU,EACV,cAAc,EAIf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAqBjD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IAEtC;;;;OAIG;gBACS,MAAM,CAAC,EAAE,YAAY;IAIjC;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC;IAmC1D;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe;IAYvB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,YAAY;IAoCpB;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc;IAyBtB;;;;;;;;OAQG;IACH,OAAO,CAAC,eAAe;IAyBvB;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAavB;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAuDtB;;;;;OAKG;IACH,OAAO,CAAC,YAAY;CAerB"}

package/dist/config/ConfigResolver.js

@@ -0,0 +1,282 @@
+/**
+ * Configuration Resolver
+ *
+ * Resolves configuration from multiple sources with clear precedence:
+ * 1. Code (explicit parameters) - Highest priority
+ * 2. Environment variables
+ * 3. Configuration file (agent.json)
+ * 4. Defaults - Lowest priority
+ *
+ * @module config/ConfigResolver
+ */
+import { KadiError, ErrorCode } from '../types/index.js';
+import { ConfigLoader } from './ConfigLoader.js';
+/**
+ * Default configuration values
+ */
+const DEFAULT_CONFIG = {
+    version: '1.0.0',
+    role: 'agent',
+    transport: 'native',
+    networks: ['global'],
+    autoConnect: false,
+    advanced: {
+        heartbeatInterval: 30000,
+        requestTimeout: 30000,
+        connectionTimeout: 10000,
+        autoReconnect: true,
+        maxReconnectAttempts: 5,
+        verbose: false
+    }
+};
+/**
+ * Configuration Resolver
+ *
+ * Handles merging configuration from multiple sources with well-defined precedence.
+ * Makes configuration predictable and debuggable.
+ *
+ * @example
+ * ```typescript
+ * const resolver = new ConfigResolver();
+ *
+ * // Simple string config
+ * const config = await resolver.resolve('ws://localhost:8080');
+ *
+ * // Full config object
+ * const config = await resolver.resolve({
+ *   name: 'my-service',
+ *   brokers: { local: 'ws://localhost:8080' }
+ * });
+ * ```
+ */
+export class ConfigResolver {
+    loader;
+    /**
+     * Create a new ConfigResolver
+     *
+     * @param loader - Optional custom config loader (for testing)
+     */
+    constructor(loader) {
+        this.loader = loader ?? new ConfigLoader();
+    }
+    /**
+     * Resolve complete configuration from multiple sources
+     *
+     * Precedence (highest to lowest):
+     * 1. Explicit code configuration
+     * 2. Environment variables
+     * 3. Configuration file (agent.json)
+     * 4. Default values
+     *
+     * @param config - Configuration string (broker URL) or object
+     * @returns Fully resolved configuration with sources tracked
+     *
+     * @throws {KadiError} If configuration is invalid
+     *
+     * @example
+     * ```typescript
+     * // Simple broker URL
+     * const resolved = await resolver.resolve('ws://localhost:8080');
+     *
+     * // Full configuration
+     * const resolved = await resolver.resolve({
+     *   name: 'calculator',
+     *   brokers: { local: 'ws://localhost:8080' },
+     *   networks: ['global', 'team']
+     * });
+     * ```
+     */
+    async resolve(config) {
+        // Normalize input to object form
+        const codeConfig = this.normalizeConfig(config);
+        // Load configuration from file
+        const fileConfig = await this.loader.loadFromFile();
+        // Load configuration from environment
+        const envConfig = this.loader.loadFromEnvironment();
+        // Track sources for each field
+        const sources = {};
+        // Resolve each field with precedence
+        const resolved = {
+            name: this.resolveField('name', codeConfig.name, envConfig.KADI_AGENT_NAME, fileConfig?.name, undefined, sources),
+            version: this.resolveField('version', codeConfig.version, undefined, fileConfig?.version, DEFAULT_CONFIG.version, sources),
+            description: this.resolveField('description', codeConfig.description, undefined, fileConfig?.description, undefined, sources),
+            role: this.resolveField('role', codeConfig.role, undefined, undefined, DEFAULT_CONFIG.role, sources),
+            transport: this.resolveField('transport', codeConfig.transport, envConfig.KADI_TRANSPORT, undefined, DEFAULT_CONFIG.transport, sources),
+            brokers: this.resolveBrokers(codeConfig, envConfig, fileConfig, sources) ?? {},
+            defaultBroker: this.resolveField('defaultBroker', codeConfig.defaultBroker, undefined, fileConfig?.defaultBroker, undefined, sources),
+            networks: this.resolveNetworks(codeConfig, envConfig, fileConfig, sources),
+            abilityAgentJSON: this.resolveField('abilityAgentJSON', codeConfig.abilityAgentJSON, undefined, undefined, undefined, sources),
+            autoConnect: this.resolveField('autoConnect', codeConfig.autoConnect, this.parseBoolean(envConfig.KADI_AUTO_CONNECT), undefined, DEFAULT_CONFIG.autoConnect, sources),
+            advanced: this.resolveAdvanced(codeConfig, sources),
+            sources
+        };
+        // Validate resolved configuration
+        this.validateConfig(resolved);
+        return resolved;
+    }
+    /**
+     * Normalize configuration input
+     *
+     * Converts string (broker URL) to object form
+     *
+     * @param config - Configuration input
+     * @returns Normalized configuration object
+     */
+    normalizeConfig(config) {
+        if (typeof config === 'string') {
+            // Simple broker URL
+            return {
+                brokers: { default: config },
+                defaultBroker: 'default'
+            };
+        }
+        return config;
+    }
+    /**
+     * Resolve a single field with precedence
+     *
+     * @template T - Field value type
+     * @param fieldName - Name of the field being resolved
+     * @param codeValue - Value from code
+     * @param envValue - Value from environment
+     * @param fileValue - Value from file
+     * @param defaultValue - Default value
+     * @param sources - Source tracking object
+     * @returns Resolved value
+     */
+    resolveField(fieldName, codeValue, envValue, fileValue, defaultValue, sources) {
+        if (codeValue !== undefined) {
+            sources[fieldName] = 'code';
+            return codeValue;
+        }
+        if (envValue !== undefined) {
+            sources[fieldName] = 'environment';
+            return envValue;
+        }
+        if (fileValue !== undefined) {
+            sources[fieldName] = 'file';
+            return fileValue;
+        }
+        if (defaultValue !== undefined) {
+            sources[fieldName] = 'default';
+            return defaultValue;
+        }
+        throw new KadiError(`Required configuration field '${fieldName}' is missing`, ErrorCode.INVALID_CONFIG, 400, { fieldName });
+    }
+    /**
+     * Resolve broker configuration
+     *
+     * @param codeConfig - Code configuration
+     * @param envConfig - Environment configuration
+     * @param fileConfig - File configuration
+     * @param sources - Source tracking
+     * @returns Resolved brokers
+     */
+    resolveBrokers(codeConfig, envConfig, fileConfig, sources) {
+        if (codeConfig.brokers && Object.keys(codeConfig.brokers).length > 0) {
+            sources.brokers = 'code';
+            return codeConfig.brokers;
+        }
+        if (envConfig.KADI_BROKER_URL) {
+            sources.brokers = 'environment';
+            return { default: envConfig.KADI_BROKER_URL };
+        }
+        if (fileConfig?.brokers && Object.keys(fileConfig.brokers).length > 0) {
+            sources.brokers = 'file';
+            return fileConfig.brokers;
+        }
+        // Brokers are optional - may use native/stdio transport
+        return undefined;
+    }
+    /**
+     * Resolve networks configuration
+     *
+     * @param codeConfig - Code configuration
+     * @param envConfig - Environment configuration
+     * @param fileConfig - File configuration
+     * @param sources - Source tracking
+     * @returns Resolved networks
+     */
+    resolveNetworks(codeConfig, envConfig, fileConfig, sources) {
+        if (codeConfig.networks && codeConfig.networks.length > 0) {
+            sources.networks = 'code';
+            return codeConfig.networks;
+        }
+        if (envConfig.KADI_NETWORKS) {
+            sources.networks = 'environment';
+            return envConfig.KADI_NETWORKS.split(',').map(n => n.trim());
+        }
+        if (fileConfig?.networks && fileConfig.networks.length > 0) {
+            sources.networks = 'file';
+            return fileConfig.networks;
+        }
+        sources.networks = 'default';
+        return [...DEFAULT_CONFIG.networks];
+    }
+    /**
+     * Resolve advanced configuration
+     *
+     * @param codeConfig - Code configuration
+     * @param sources - Source tracking
+     * @returns Resolved advanced config
+     */
+    resolveAdvanced(codeConfig, sources) {
+        const advanced = {
+            ...DEFAULT_CONFIG.advanced,
+            ...codeConfig.advanced
+        };
+        sources.advanced = codeConfig.advanced ? 'code' : 'default';
+        return advanced;
+    }
+    /**
+     * Validate resolved configuration
+     *
+     * @param config - Resolved configuration
+     * @throws {KadiError} If configuration is invalid
+     */
+    validateConfig(config) {
+        // Validate name
+        if (!config.name || config.name.trim().length === 0) {
+            throw new KadiError('Agent name is required', ErrorCode.INVALID_CONFIG, 400, { field: 'name' });
+        }
+        // Validate transport
+        const validTransports = ['native', 'stdio', 'broker'];
+        if (!validTransports.includes(config.transport)) {
+            throw new KadiError(`Invalid transport: ${config.transport}. Must be one of: ${validTransports.join(', ')}`, ErrorCode.INVALID_CONFIG, 400, { field: 'transport', value: config.transport });
+        }
+        // Validate broker configuration if using broker transport
+        if (config.transport === 'broker') {
+            if (!config.brokers || Object.keys(config.brokers).length === 0) {
+                throw new KadiError('Broker configuration is required when using broker transport', ErrorCode.INVALID_CONFIG, 400, { field: 'brokers', transport: config.transport });
+            }
+            // Validate default broker exists if specified
+            if (config.defaultBroker && !config.brokers[config.defaultBroker]) {
+                throw new KadiError(`Default broker '${config.defaultBroker}' not found in broker configuration`, ErrorCode.INVALID_CONFIG, 400, { field: 'defaultBroker', value: config.defaultBroker, availableBrokers: Object.keys(config.brokers) });
+            }
+        }
+        // Validate networks
+        if (!Array.isArray(config.networks) || config.networks.length === 0) {
+            throw new KadiError('At least one network is required', ErrorCode.INVALID_CONFIG, 400, { field: 'networks' });
+        }
+    }
+    /**
+     * Parse boolean from string
+     *
+     * @param value - String value
+     * @returns Boolean or undefined
+     */
+    parseBoolean(value) {
+        if (value === undefined) {
+            return undefined;
+        }
+        const lower = value.toLowerCase();
+        if (lower === 'true' || lower === '1' || lower === 'yes') {
+            return true;
+        }
+        if (lower === 'false' || lower === '0' || lower === 'no') {
+            return false;
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=ConfigResolver.js.map

package/dist/config/ConfigResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConfigResolver.js","sourceRoot":"","sources":["../../src/config/ConfigResolver.ts"],"names":[],"mappings":"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"}

package/dist/config/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Configuration Module
+ *
+ * Exports for configuration resolution and loading.
+ */
+export { ConfigResolver } from './ConfigResolver.js';
+export { ConfigLoader } from './ConfigLoader.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/config/index.js

@@ -0,0 +1,8 @@
+/**
+ * Configuration Module
+ *
+ * Exports for configuration resolution and loading.
+ */
+export { ConfigResolver } from './ConfigResolver.js';
+export { ConfigLoader } from './ConfigLoader.js';
+//# sourceMappingURL=index.js.map