@kadi.build/core 0.0.1-alpha.1 → 0.0.1-alpha.11

package/dist/abilities/AbilityLoader.js

@@ -0,0 +1,343 @@
+/**
+ * Ability Loader
+ *
+ * Orchestrates ability loading with excellent developer experience:
+ * - Smart transport inference (auto-detect or explicit)
+ * - Intelligent caching (composite keys)
+ * - Runtime validation (catch issues early)
+ * - Helpful error messages (actionable suggestions)
+ *
+ * @module abilities/AbilityLoader
+ */
+import { KadiError, ErrorCode } from '../types/index.js';
+import { BrokerTransport } from '../transports/BrokerTransport.js';
+import { NativeTransport } from '../transports/NativeTransport.js';
+import { StdioTransport } from '../transports/StdioTransport.js';
+import { AbilityProxy } from './AbilityProxy.js';
+import { AbilityCache } from './AbilityCache.js';
+import { AbilityValidator } from './AbilityValidator.js';
+/**
+ * Ability Loader
+ *
+ * Orchestrates the complete ability loading process:
+ * - Transport inference (smart auto-detection)
+ * - Caching (avoid duplicate loads)
+ * - Transport creation (factory pattern)
+ * - Validation (runtime checks)
+ * - Error handling (helpful messages)
+ *
+ * Single responsibility: Load abilities, nothing else.
+ *
+ * @example
+ * ```typescript
+ * const loader = new AbilityLoader();
+ *
+ * // Auto-detect (recommended)
+ * const calc = await loader.load('calculator', {}, brokerClient);
+ *
+ * // Explicit transport
+ * const remote = await loader.load('service', {
+ *   transport: 'broker',
+ *   networks: ['global']
+ * }, brokerClient);
+ *
+ * // With validation
+ * const typed = await loader.load<CalcAPI>('calc', {
+ *   validate: true
+ * }, brokerClient);
+ * ```
+ */
+export class AbilityLoader {
+    /**
+     * Ability cache with composite key strategy
+     *
+     * Handles complex scenarios:
+     * - Same name, different transports
+     * - Same name, different versions
+     * - Same name, different brokers
+     */
+    cache = new AbilityCache();
+    /**
+     * Load an ability with explicit transport
+     *
+     * **Features:**
+     * - Explicit transport (no magic)
+     * - Smart caching (composite keys)
+     * - Runtime validation (optional)
+     * - Dynamic method access
+     *
+     * @param name - Ability name
+     * @param transport - Transport type (native, stdio, or broker)
+     * @param options - Load options (transport-specific)
+     * @param brokerClient - Broker client interface
+     * @returns Loaded ability with dynamic method access
+     *
+     * @throws {KadiError} If loading fails
+     *
+     * @example
+     * ```typescript
+     * // Broker transport
+     * const remote = await loader.load('service', 'broker', {
+     *   networks: ['global']
+     * }, brokerClient);
+     *
+     * // With runtime validation
+     * const calc = await loader.load('calc', 'broker', {
+     *   validate: true
+     * }, brokerClient);
+     *
+     * // Native transport
+     * const local = await loader.load('local-lib', 'native', {
+     *   path: './abilities/local-lib'
+     * });
+     * ```
+     */
+    async load(name, transport, options = {}, brokerClient) {
+        // Step 1: Check cache first (avoid duplicate loading)
+        const cacheKey = {
+            name,
+            transport,
+            version: options.version,
+            broker: 'broker' in options ? options.broker : undefined
+        };
+        const cached = this.cache.get(cacheKey);
+        if (cached && cached.__isConnected()) {
+            // Cache hit! Return existing ability
+            return cached;
+        }
+        // Step 2: Create appropriate transport
+        const transportInstance = this.createTransport(name, transport, options, brokerClient);
+        // Step 3: Connect to ability
+        await transportInstance.connect();
+        // Step 4: Create proxy for natural method calling
+        const ability = AbilityProxy.create(name, transportInstance, transport);
+        // Step 5: Validate if requested
+        if (options.validate) {
+            AbilityValidator.validate(ability);
+        }
+        // Step 6: Cache for future use
+        this.cache.set(cacheKey, ability);
+        return ability;
+    }
+    /**
+     * Unload all abilities
+     *
+     * Disconnects all transports and clears cache.
+     *
+     * @example
+     * ```typescript
+     * await loader.unloadAll();
+     * ```
+     */
+    async unloadAll() {
+        // Step 1: Get all cached abilities
+        const abilities = this.cache.getAll();
+        // Step 2: Disconnect all transports in parallel
+        const disconnectPromises = abilities.map(ability => ability.__disconnect().catch(() => {
+            // Ignore disconnect errors during cleanup
+        }));
+        await Promise.all(disconnectPromises);
+        // Step 3: Clear cache
+        this.cache.clear();
+    }
+    /**
+     * Get all loaded abilities
+     *
+     * @returns Array of loaded abilities
+     *
+     * @example
+     * ```typescript
+     * const abilities = loader.getAll();
+     * console.log(`Loaded ${abilities.length} abilities`);
+     * ```
+     */
+    getAll() {
+        return this.cache.getAll();
+    }
+    /**
+     * Get cache statistics
+     *
+     * Useful for debugging and monitoring.
+     *
+     * @returns Cache statistics
+     *
+     * @example
+     * ```typescript
+     * const stats = loader.getStats();
+     * console.log(`Cached: ${stats.totalCached}, Connected: ${stats.connected}`);
+     * ```
+     */
+    getStats() {
+        return this.cache.getStats();
+    }
+    /**
+     * Cleanup disconnected abilities
+     *
+     * Removes stale cache entries.
+     *
+     * @returns Number of stale entries removed
+     *
+     * @example
+     * ```typescript
+     * const removed = loader.cleanup();
+     * console.log(`Cleaned up ${removed} disconnected abilities`);
+     * ```
+     */
+    cleanup() {
+        return this.cache.cleanup();
+    }
+    /**
+     * Create appropriate transport instance
+     *
+     * Clean factory pattern - delegates to specialized creation methods.
+     * Each transport type has its own dedicated method with proper validation.
+     *
+     * @param name - Ability name
+     * @param transport - Transport type (from inference)
+     * @param options - Load options
+     * @param brokerClient - Broker client (for broker transport)
+     * @returns Transport instance ready to connect
+     *
+     * @throws {KadiError} If transport creation fails
+     */
+    createTransport(name, transport, options, brokerClient) {
+        // Delegate to appropriate transport creation method
+        switch (transport) {
+            case 'broker':
+                return this.createBrokerTransport(name, options, brokerClient);
+            case 'native':
+                return this.createNativeTransport(name, options);
+            case 'stdio':
+                return this.createStdioTransport(name, options);
+            default:
+                // TypeScript exhaustiveness check ensures this is unreachable
+                const never = transport;
+                throw new KadiError(`Unknown transport type: ${never}`, ErrorCode.INVALID_CONFIG, 400, { abilityName: name });
+        }
+    }
+    /**
+     * Create broker transport with excellent error handling
+     *
+     * Validates broker connection and creates transport with proper configuration.
+     *
+     * @param name - Ability name
+     * @param options - Load options (broker-specific)
+     * @param brokerClient - Broker client interface
+     * @returns Broker transport instance
+     *
+     * @throws {KadiError} If broker client missing or invalid config
+     */
+    createBrokerTransport(name, options, brokerClient) {
+        // Step 1: Validate broker client exists
+        if (!brokerClient) {
+            throw new KadiError('Cannot use broker transport - not connected to broker', ErrorCode.BROKER_NOT_CONNECTED, 503, {
+                abilityName: name,
+                transport: 'broker',
+                reason: 'Broker client not provided to AbilityLoader',
+                suggestion: 'Connect to broker first: await client.connect()',
+                alternatives: [
+                    'Connect to broker before loading abilities',
+                    'Use different transport like native or stdio'
+                ],
+                hint: 'Broker transport requires active broker connection'
+            });
+        }
+        // Step 2: Extract broker-specific options (type-safe!)
+        const brokerOptions = options;
+        // Step 3: Determine networks to search
+        // Priority: explicit options > client networks
+        const networks = brokerOptions.networks ?? brokerClient.networks;
+        // Step 4: Determine which broker to use
+        // Priority: explicit broker > client default
+        const broker = brokerOptions.broker ?? brokerClient.getBrokerManager().getDefaultBrokerName() ?? undefined;
+        // Step 5: Create transport with validated config
+        return new BrokerTransport({
+            abilityName: name,
+            brokerUrl: '', // Not needed - using existing connection
+            brokerName: broker,
+            networks,
+            timeout: options.timeout
+        }, brokerClient);
+    }
+    /**
+     * Create native transport with path validation
+     *
+     * Validates the ability path and creates a NativeTransport instance
+     * for in-process ability loading.
+     *
+     * @param name - Ability name
+     * @param options - Load options (native-specific)
+     * @returns Native transport instance
+     *
+     * @throws {KadiError} If path is missing or invalid
+     */
+    createNativeTransport(name, options) {
+        // Step 1: Extract native-specific options (type-safe!)
+        const nativeOptions = options;
+        // Step 2: Validate path is provided
+        if (!nativeOptions.path) {
+            throw new KadiError('Native transport requires path option', ErrorCode.INVALID_CONFIG, 400, {
+                abilityName: name,
+                transport: 'native',
+                reason: 'Missing required "path" option for native transport',
+                suggestion: 'Provide path to ability module',
+                example: 'await client.load("calculator", "native", { path: "./abilities/calculator" })',
+                alternatives: [
+                    'Relative path: { path: "./abilities/calculator" }',
+                    'Absolute path: { path: "/usr/local/lib/abilities/calculator" }',
+                    'Package name: { path: "@kadi/calculator-ability" }'
+                ]
+            });
+        }
+        // Step 3: Create NativeTransport with validated config
+        return new NativeTransport({
+            abilityName: name,
+            abilityPath: nativeOptions.path,
+            abilityVersion: options.version,
+            timeout: options.timeout
+            // entryPoint defaults to 'index.js' in NativeTransport constructor
+        });
+    }
+    /**
+     * Create stdio transport with command validation
+     *
+     * Validates the command and creates a StdioTransport instance
+     * for spawning the ability as a child process.
+     *
+     * @param name - Ability name
+     * @param options - Load options (stdio-specific)
+     * @returns Stdio transport instance
+     *
+     * @throws {KadiError} If command is missing
+     */
+    createStdioTransport(name, options) {
+        // Step 1: Extract stdio-specific options (type-safe!)
+        const stdioOptions = options;
+        // Step 2: Validate command is provided
+        if (!stdioOptions.command) {
+            throw new KadiError('Stdio transport requires command option', ErrorCode.INVALID_CONFIG, 400, {
+                abilityName: name,
+                transport: 'stdio',
+                reason: 'Missing required "command" option for stdio transport',
+                suggestion: 'Provide command to execute ability process',
+                example: 'await client.load("calculator", "stdio", { command: "node", args: ["./abilities/calculator/index.js"] })',
+                alternatives: [
+                    'Node.js: { command: "node", args: ["./ability.js"] }',
+                    'Python: { command: "python3", args: ["./ability.py"] }',
+                    'Binary: { command: "./ability-binary" }'
+                ]
+            });
+        }
+        // Step 3: Create StdioTransport with validated config
+        return new StdioTransport({
+            abilityName: name,
+            command: stdioOptions.command,
+            args: stdioOptions.args,
+            cwd: stdioOptions.cwd,
+            env: stdioOptions.env,
+            timeout: options.timeout,
+            abilityVersion: options.version
+        });
+    }
+}
+//# sourceMappingURL=AbilityLoader.js.map

package/dist/abilities/AbilityLoader.js.map

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