@kadi.build/core 0.0.1-alpha.12 → 0.0.1-alpha.14

package/dist/abilities/AbilityLoader.d.ts

@@ -53,6 +53,38 @@ export declare class AbilityLoader {
      * - Same name, different brokers
      */
     private cache;
+    /**
+     * Explicit project root (provided by KadiClient)
+     *
+     * This is the directory where KADI will look for abilities.
+     * - If provided: use this directory
+     * - If not provided: default to process.cwd()
+     *
+     * This makes context explicit instead of inferred.
+     */
+    private readonly explicitProjectRoot?;
+    /**
+     * Create an AbilityLoader
+     *
+     * **AbilityLoader** is responsible for finding, loading, and caching abilities.
+     *
+     * @param options - Loader options
+     * @param options.projectRoot - Explicit project root (overrides detection)
+     *
+     * @example
+     * ```typescript
+     * // With explicit project root (CLI plugin)
+     * const loader = new AbilityLoader({
+     *   projectRoot: '/opt/homebrew/lib/node_modules/@kadi.build/cli'
+     * });
+     *
+     * // Without explicit project root (user project)
+     * const loader = new AbilityLoader({});
+     * ```
+     */
+    constructor(options?: {
+        projectRoot?: string;
+    });
     /**
      * Load an ability with explicit transport
      *
@@ -145,16 +177,59 @@ export declare class AbilityLoader {
      * ```
      */
     cleanup(): number;
+    /**
+     * Detect project root directory
+     *
+     * **Strategy** (simple and explicit):
+     * 1. Use explicit override (constructor option or env var)
+     * 2. Fall back to process.cwd() (default behavior, like professor's approach)
+     *
+     * **Why This Approach?**
+     * - **Explicit over implicit**: Plugins tell us where to load from
+     * - **Simple**: No stack parsing, no complex inference
+     * - **Reliable**: Works in all environments (dev, prod, bundlers, etc.)
+     * - **Escape hatch**: Env var for edge cases
+     *
+     * **How It's Used**:
+     * - CLI plugins: Pass `ctx.core.getKadiInstallPath()` via constructor
+     * - User projects: Don't pass anything, uses process.cwd()
+     * - Edge cases: Set KADI_PROJECT_ROOT env var
+     *
+     * @returns Detected project root directory
+     *
+     * @example
+     * ```typescript
+     * // Example 1: CLI plugin (explicit)
+     * const loader = new AbilityLoader({
+     *   projectRoot: '/opt/homebrew/lib/node_modules/@kadi.build/cli'
+     * });
+     * const root = loader.detectProjectRoot();
+     * // Returns: '/opt/homebrew/lib/node_modules/@kadi.build/cli'
+     *
+     * // Example 2: User project (default)
+     * const loader = new AbilityLoader({});
+     * const root = loader.detectProjectRoot();
+     * // Returns: process.cwd() (e.g., '/Users/kassi/Repositories/KADI/gateway-agent')
+     *
+     * // Example 3: Env var override (escape hatch)
+     * process.env.KADI_PROJECT_ROOT = '/app';
+     * const loader = new AbilityLoader({});
+     * const root = loader.detectProjectRoot();
+     * // Returns: '/app'
+     * ```
+     */
+    private detectProjectRoot;
     /**
      * Create appropriate transport instance
      *
-     * Clean factory pattern - delegates to specialized creation methods.
-     * Each transport type has its own dedicated method with proper validation.
+     * Factory pattern that creates the right transport based on type.
+     * Each transport type (native, stdio, broker) has its own creation method.
      *
      * @param name - Ability name
-     * @param transport - Transport type (from inference)
-     * @param options - Load options
+     * @param transport - Transport type (native, stdio, or broker)
+     * @param options - Load options (transport-specific)
      * @param brokerClient - Broker client (for broker transport)
+     * @param projectRoot - Project root directory (where to find abilities)
      * @returns Transport instance ready to connect
      *
      * @throws {KadiError} If transport creation fails
@@ -174,29 +249,78 @@ export declare class AbilityLoader {
      */
     private createBrokerTransport;
     /**
-     * Create native transport with path auto-resolution
+     * Create native transport with project root context
      *
-     * If path is provided, uses it directly (backwards compatible).
-     * If path is NOT provided, auto-resolves from agent-lock.json.
+     * Native transport loads abilities directly from the filesystem.
+     *
+     * Resolution strategy:
+     * 1. If explicit path provided → use it directly
+     * 2. Otherwise → auto-resolve from projectRoot using lockfile
      *
      * @param name - Ability name
      * @param options - Load options (native-specific)
+     * @param projectRoot - Project root directory (from detectProjectRoot)
      * @returns Native transport instance
      *
-     * @throws {KadiError} If path is missing and auto-resolution fails
+     * @throws {KadiError} If path cannot be resolved
      */
     private createNativeTransport;
     /**
-     * Create stdio transport with command auto-resolution
+     * Create stdio transport with context-aware command resolution
+     *
+     * Resolution strategy:
+     * 1. If explicit command provided → use it directly
+     * 2. Otherwise → auto-resolve from caller's project context
      *
-     * If command is provided, uses it directly (backwards compatible).
-     * If command is NOT provided, auto-resolves from agent-lock.json.
+     * **Context-Aware Resolution:**
+     * - Uses callerFilePath to find the correct project root
+     * - CLI plugins resolve from CLI's abilities/
+     * - User projects resolve from project's abilities/
      *
      * @param name - Ability name
      * @param options - Load options (stdio-specific)
+     * @param callerFilePath - File path where load() was called from
      * @returns Stdio transport instance
      *
-     * @throws {KadiError} If command is missing and auto-resolution fails
+     * @throws {KadiError} If command cannot be resolved
+     */
+    /**
+     * Create stdio transport with auto-resolution support
+     *
+     * **Two modes of operation**:
+     *
+     * 1. **Auto-resolution** (no command provided):
+     *    - Resolves ability path using resolveAbilityConfig()
+     *    - Reads ability's agent.json
+     *    - Extracts scripts.start command
+     *    - Spawns child process with shell: true
+     *    - Sets cwd to ability directory
+     *    - Injects KADI_* environment variables
+     *
+     * 2. **Explicit command** (command provided):
+     *    - Uses provided command/args directly
+     *    - Developer has full control
+     *    - Still injects KADI_* environment variables
+     *
+     * @param name - Ability name
+     * @param options - Load options (stdio-specific)
+     * @param projectRoot - Project root directory (from detectProjectRoot)
+     * @returns Stdio transport instance
+     *
+     * @throws {KadiError} If command cannot be resolved or scripts.start missing
+     *
+     * @example
+     * ```typescript
+     * // Auto-resolution mode
+     * const transport = this.createStdioTransport('calculator', {}, '/project/root');
+     * // Resolves path, reads agent.json, uses scripts.start
+     *
+     * // Explicit mode
+     * const transport = this.createStdioTransport('calculator', {
+     *   command: 'node',
+     *   args: ['dist/index.js']
+     * }, '/project/root');
+     * ```
      */
     private createStdioTransport;
 }

package/dist/abilities/AbilityLoader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AbilityLoader.d.ts","sourceRoot":"","sources":["../../src/abilities/AbilityLoader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAuC,MAAM,YAAY,CAAC;AAGlG,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAGvF,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAMrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,aAAa;IACxB;;;;;;;OAOG;IACH,OAAO,CAAC,KAAK,CAAsB;IAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACG,IAAI,CACR,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,aAAa,EACxB,OAAO,GAAE,WAAgB,EACzB,YAAY,CAAC,EAAE,aAAa,GAC3B,OAAO,CAAC,aAAa,CAAC;IAwCzB;;;;;;;;;OASG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBhC;;;;;;;;;;OAUG;IACH,MAAM,IAAI,aAAa,EAAE;IAIzB;;;;;;;;;;;;OAYG;IACH,QAAQ,IAAI;QACV,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;KAC5C;IAID;;;;;;;;;;;;OAYG;IACH,OAAO,IAAI,MAAM;IAIjB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,eAAe;IA6BvB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,qBAAqB;IAiD7B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,qBAAqB;IA4D7B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,oBAAoB;CA8E7B"}
+{"version":3,"file":"AbilityLoader.d.ts","sourceRoot":"","sources":["../../src/abilities/AbilityLoader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAkD,MAAM,YAAY,CAAC;AAG7G,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAGvF,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAOrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,aAAa;IACxB;;;;;;;OAOG;IACH,OAAO,CAAC,KAAK,CAAsB;IAEnC;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAS;IAE9C;;;;;;;;;;;;;;;;;;OAkBG;gBACS,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE;IAY9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACG,IAAI,CACR,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,aAAa,EACxB,OAAO,GAAE,WAAgB,EACzB,YAAY,CAAC,EAAE,aAAa,GAC3B,OAAO,CAAC,aAAa,CAAC;IAwDzB;;;;;;;;;OASG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBhC;;;;;;;;;;OAUG;IACH,MAAM,IAAI,aAAa,EAAE;IAIzB;;;;;;;;;;;;OAYG;IACH,QAAQ,IAAI;QACV,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;KAC5C;IAID;;;;;;;;;;;;OAYG;IACH,OAAO,IAAI,MAAM;IAIjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACH,OAAO,CAAC,iBAAiB;IAmDzB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,eAAe;IAoCvB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,qBAAqB;IAiD7B;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,qBAAqB;IAyF7B;;;;;;;;;;;;;;;;;;OAkBG;IACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACH,OAAO,CAAC,oBAAoB;CAoP7B"}