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

package/dist/utils/LockfileResolver.d.ts

@@ -7,27 +7,86 @@
  * @module utils/LockfileResolver
  */
 /**
- * Minimal lockfile types (only what kadi-core needs)
+ * Agent Lockfile Types (v0 Structure)
  *
- * These types are a subset of the full lockfile format from kadi-install.
- * We only include fields needed for ability path resolution.
+ * These types define the structure of agent-lock.json files.
+ * The lockfile ensures reproducible installs and tracks exact ability versions.
+ *
+ * **Key Design Decisions:**
+ * - Use `name@version` as keys for future multi-version support
+ * - Track dependencies to enable resolution of transitive dependencies
+ * - Store integrity hashes for verification
+ * - Include metadata for debugging and compatibility checks
+ */
+/**
+ * Metadata about the lockfile generation
+ */
+export interface LockfileMetadata {
+    /** Version of KADI that generated this lockfile */
+    kadiVersion: string;
+    /** ISO 8601 timestamp when lockfile was generated */
+    generated: string;
+}
+/**
+ * Single ability entry in the lockfile
+ *
+ * **Key is**: `name@version` (e.g., "secret-ability@0.0.1")
+ * **Value contains**: All information needed to locate and verify the ability
  */
 export interface LockfileAbilityEntry {
+    /** Semantic version of this ability */
     version: string;
-    kind: 'plugin' | 'ability';
+    /** Type of ability - determines how it's used */
+    kind?: 'plugin' | 'ability';
+    /** Relative path from project root to installed ability directory */
     resolved: string;
+    /** Integrity hash (sha512) of the ability package for verification */
     integrity: string;
-    installStrategy: 'hardlink' | 'clonefile' | 'copyfile' | 'symlink';
-    detached: boolean;
+    /** Strategy used to install this ability on disk */
+    installStrategy?: 'hardlink' | 'clonefile' | 'copyfile' | 'symlink';
+    /**
+     * Dependencies of this ability
+     *
+     * Maps ability name to required version.
+     * When this ability loads a dependency, we verify it gets the correct version.
+     *
+     * Example: { "secret-ability": "0.0.1", "crypto-utils": "1.2.0" }
+     */
+    dependencies?: Record<string, string>;
 }
+/**
+ * Complete agent-lock.json structure (v0)
+ *
+ * **Purpose**: Ensure reproducible ability installations across environments
+ *
+ * **Structure:**
+ * - `lockfileVersion`: Format version for future migrations
+ * - `metadata`: Context about generation
+ * - `agent`: The project/CLI that owns this lockfile
+ * - `abilities`: All installed abilities (direct + transitive dependencies)
+ */
 export interface AgentLockfile {
+    /** Lockfile format version - increment when structure changes */
     lockfileVersion: number;
-    abilities: Record<string, LockfileAbilityEntry>;
+    /** Metadata about lockfile generation */
+    metadata: LockfileMetadata;
+    /** The project or CLI that owns this lockfile */
     agent: {
+        /** Project/CLI name */
         name: string;
+        /** Project/CLI version */
         version: string;
     };
-    generated: string;
+    /**
+     * All installed abilities, indexed by `name@version`
+     *
+     * Includes both:
+     * - Direct dependencies (explicitly installed)
+     * - Transitive dependencies (pulled in by other abilities)
+     *
+     * Example keys: "kadi-secret@0.0.1", "secret-ability@0.0.1"
+     */
+    abilities: Record<string, LockfileAbilityEntry>;
 }
 /**
  * Minimal ability manifest (agent.json)
@@ -39,19 +98,91 @@ export interface AbilityManifest {
     version: string;
     kind?: 'plugin' | 'ability';
     entry?: string;
+    entrypoint?: string;
     description?: string;
+    /**
+     * Lifecycle scripts
+     *
+     * Shell commands for different execution stages.
+     * Primarily used by stdio transport for auto-resolution.
+     */
+    scripts?: {
+        preflight?: string;
+        setup?: string;
+        start?: string;
+        stop?: string;
+        [key: string]: string | undefined;
+    };
     [key: string]: unknown;
 }
 /**
- * Find project root by looking for agent.json
+ * Find ability in global cache
+ *
+ * Checks ~/.kadi/abilities/ for any version of the ability.
+ * Returns the highest version found.
+ *
+ * @param abilityName - Name of the ability to find
+ * @returns Absolute path to the ability or null if not found
+ */
+export declare function findInGlobalCache(abilityName: string): string | null;
+/**
+ * Find sibling abilities directory
  *
- * Walks up directory tree from cwd until finding agent.json
+ * TEMPORARY: This function detects if we're running inside an ability
+ * (e.g., kadi-secret) and finds its sibling abilities.
  *
- * @param startDir - Directory to start search from (defaults to cwd)
- * @returns Absolute path to project root
+ * When kadi-secret loads secret-ability, both are installed in the same
+ * parent abilities/ directory. This function walks up the directory tree
+ * to find the abilities/ folder we're running from.
+ *
+ * Example: If running from:
+ *   /opt/homebrew/.../cli/abilities/kadi-secret/0.0.1/dist/index.js
+ * Returns:
+ *   /opt/homebrew/.../cli/abilities/
+ *
+ * TODO: Replace with config.json approach (see CLI-REVAMP-PLAN.md)
+ * Future: abilities will reference ~/.kadi/config.json for discovery
+ *
+ * @returns Sibling abilities directory path, or null if not running from an ability
+ */
+export declare function findSiblingAbilitiesDir(): string | null;
+/**
+ * Find ability in a specific abilities directory
+ *
+ * Generic function to search for an ability in any abilities folder.
+ * Scans {baseDir}/{abilityName}/ for version directories and returns the highest version.
+ *
+ * @param abilityName - Name of the ability to find
+ * @param baseDir - Base abilities directory to search in
+ * @returns Object with path and version, or null if not found
+ */
+export declare function findInAbilitiesDir(abilityName: string, baseDir: string): {
+    path: string;
+    version: string;
+} | null;
+/**
+ * Find the true project root by intelligently searching for agent.json
+ *
+ * This function distinguishes between:
+ * - **Ability manifests**: agent.json files inside abilities/name/version/
+ * - **Project roots**: agent.json files that represent actual projects (CLI or user projects)
+ *
+ * **Algorithm:**
+ * 1. Walk up directory tree from startPath
+ * 2. For each agent.json found, check if it's inside an abilities/ structure
+ * 3. If inside abilities/ → skip (it's an ability manifest, not a project root)
+ * 4. If NOT inside abilities/ → return (it's a true project root)
+ *
+ * **Example paths:**
+ * - `/opt/homebrew/.../cli/abilities/kadi-secret/0.0.1/agent.json` → SKIP (ability manifest)
+ * - `/opt/homebrew/.../cli/agent.json` → RETURN (CLI root)
+ * - `/Users/alice/my-project/agent.json` → RETURN (user project root)
+ *
+ * @param startPath - File or directory path to start searching from (defaults to cwd)
+ * @returns Absolute path to the true project root
  * @throws {KadiError} If no project root found
  */
-export declare function findProjectRoot(startDir?: string): string;
+export declare function findProjectRoot(startPath?: string): string;
 /**
  * Read agent-lock.json from project root
  *
@@ -78,28 +209,48 @@ export declare function resolveAbilityPath(abilityName: string, projectRoot: str
  */
 export declare function readAbilityManifest(abilityPath: string): AbilityManifest;
 /**
- * Auto-resolve ability configuration for loading
+ * Resolve ability configuration from project root
+ *
+ * **New Explicit Strategy:**
+ * Uses explicit project root instead of inferring from stack traces:
+ * 1. Use provided projectRoot directly (no inference needed)
+ * 2. Look in `{projectRoot}/abilities/{abilityName}/`
+ * 3. If not found → clear error with exact path searched
  *
- * Combines lockfile lookup with manifest reading to provide
- * all information needed to load an ability.
+ * **Why This Works:**
+ * - CLI plugins: Get projectRoot from `ctx.core.getKadiInstallPath()`
+ *   - projectRoot: `/opt/homebrew/.../cli/`
+ *   - Searches: `/opt/homebrew/.../cli/abilities/secret-ability/`
  *
- * @param abilityName - Name of ability
- * @param projectRoot - Project root directory (optional, will search if not provided)
- * @returns Resolved ability configuration
+ * - User projects: Get projectRoot from `process.cwd()` (default)
+ *   - projectRoot: `/Users/alice/my-project/`
+ *   - Searches: `/Users/alice/my-project/abilities/my-ability/`
+ *
+ * **Resolution Strategy:**
+ * 1. Check agent-lock.json (if exists) for exact version
+ * 2. Fall back to scanning abilities/ folder if no lockfile
+ * 3. Return highest version if multiple exist
+ *
+ * @param abilityName - Name of ability to resolve
+ * @param projectRoot - Project root directory (from detectProjectRoot or explicit config)
+ * @returns Resolved ability configuration with path, version, entry point, and manifest
+ *
+ * @throws {KadiError} If ability not found
  *
  * @example
  * ```typescript
- * const config = resolveAbilityConfig('math-lib');
- * // Returns:
- * // {
- * //   path: '/path/to/project/abilities/math-lib@1.0.0',
- * //   version: '1.0.0',
- * //   entry: 'service.js',
- * //   manifest: { ... }
- * // }
+ * // Called from CLI plugin (with explicit project root):
+ * const projectRoot = '/opt/homebrew/.../cli';
+ * const config = resolveAbilityConfig('secret-ability', projectRoot);
+ * // Searches: /opt/homebrew/.../cli/abilities/secret-ability/
+ *
+ * // Called from user project (with default project root):
+ * const projectRoot = process.cwd();
+ * const config = resolveAbilityConfig('my-ability', projectRoot);
+ * // Searches: {cwd}/abilities/my-ability/
  * ```
  */
-export declare function resolveAbilityConfig(abilityName: string, projectRoot?: string): {
+export declare function resolveAbilityConfig(abilityName: string, projectRoot: string): {
     path: string;
     version: string;
     entry: string;

package/dist/utils/LockfileResolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LockfileResolver.d.ts","sourceRoot":"","sources":["../../src/utils/LockfileResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,UAAU,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,CAAC;IACnE,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAChD,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,QAAQ,GAAE,MAAsB,GAAG,MAAM,CA8BxE;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CA2D/D;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,oBAAoB,CAqEtB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,CAkDxE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,WAAW,CAAC,EAAE,MAAM,GACnB;IACD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,eAAe,CAAC;CAC3B,CAmBA"}
+{"version":3,"file":"LockfileResolver.d.ts","sourceRoot":"","sources":["../../src/utils/LockfileResolver.ts"],"names":[],"mappings":"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"}