@kadi.build/core 0.3.4 → 0.5.0

package/src/lockfile.ts

@@ -0,0 +1,493 @@
+/**
+ * Lock file resolution for kadi-core v0.1.0
+ *
+ * This module handles reading agent-lock.json and resolving ability paths.
+ * The lock file is generated by kadi-install and contains:
+ * - Exact versions of installed abilities
+ * - Paths where abilities are installed
+ * - Integrity hashes for verification
+ *
+ * Flow:
+ * 1. Find project root (where agent.json lives)
+ * 2. Read agent-lock.json from project root
+ * 3. Look up ability by name to get its installed path
+ */
+
+import { readFile } from 'fs/promises';
+import { join, dirname } from 'path';
+import type { AgentLockFile, AbilityLockEntry, ResolvedScript } from './types.js';
+import { KadiError } from './errors.js';
+
+// ═══════════════════════════════════════════════════════════════════════
+// PROJECT ROOT DISCOVERY
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Find the project root by walking up the directory tree.
+ * Looks for agent.json, which marks the root of a KADI project.
+ *
+ * @param startDir - Directory to start searching from (default: process.cwd())
+ * @returns Absolute path to the project root
+ * @throws KadiError if no agent.json is found
+ *
+ * @example
+ * ```typescript
+ * const root = await findProjectRoot();
+ * // '/Users/kassi/my-project'
+ *
+ * const root = await findProjectRoot('/Users/kassi/my-project/src/deep/folder');
+ * // '/Users/kassi/my-project'
+ * ```
+ */
+export async function findProjectRoot(startDir: string = process.cwd()): Promise<string> {
+  let current = startDir;
+
+  // Walk up the directory tree looking for agent.json
+  while (current !== dirname(current)) {
+    const agentJsonPath = join(current, 'agent.json');
+
+    try {
+      // Try to read agent.json - if it exists, this is the project root
+      await readFile(agentJsonPath);
+      return current;
+    } catch {
+      // File doesn't exist, try parent directory
+      current = dirname(current);
+    }
+  }
+
+  // Reached filesystem root without finding agent.json
+  throw new KadiError(
+    'Could not find project root',
+    'PROJECT_ROOT_NOT_FOUND',
+    {
+      searched: startDir,
+      hint: 'Make sure you are in a KADI project directory with an agent.json file',
+    }
+  );
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// LOCK FILE READING
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Read and parse agent-lock.json from a project root.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @returns Parsed lock file contents
+ * @throws KadiError if lock file doesn't exist or is invalid
+ *
+ * @example
+ * ```typescript
+ * const lockFile = await readLockFile('/Users/kassi/my-project');
+ * console.log(lockFile.abilities);
+ * // { 'calculator@1.0.0': { resolved: 'abilities/calculator@1.0.0', ... } }
+ * ```
+ */
+export async function readLockFile(projectRoot: string): Promise<AgentLockFile> {
+  const lockPath = join(projectRoot, 'agent-lock.json');
+
+  let content: string;
+  try {
+    content = await readFile(lockPath, 'utf-8');
+  } catch (error) {
+    throw new KadiError(
+      'agent-lock.json not found',
+      'LOCKFILE_NOT_FOUND',
+      {
+        searched: lockPath,
+        hint: 'Run `kadi install` to generate the lock file',
+        alternative: 'Or specify an explicit path when loading abilities',
+      }
+    );
+  }
+
+  try {
+    return JSON.parse(content) as AgentLockFile;
+  } catch (error) {
+    throw new KadiError(
+      'Failed to parse agent-lock.json',
+      'LOCKFILE_PARSE_ERROR',
+      {
+        path: lockPath,
+        reason: error instanceof Error ? error.message : 'Invalid JSON',
+        hint: 'The lock file may be corrupted. Try running `kadi install` again',
+      }
+    );
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// ABILITY LOOKUP
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Find an ability entry in the lock file by name.
+ * Keys in the lock file are "name@version", this function matches by name only.
+ *
+ * @param lockFile - The parsed lock file
+ * @param name - Ability name to find (without version)
+ * @returns The ability entry, or null if not found
+ *
+ * @example
+ * ```typescript
+ * const entry = findAbilityEntry(lockFile, 'calculator');
+ * // Returns entry for 'calculator@1.0.0' (or whatever version is installed)
+ * ```
+ */
+export function findAbilityEntry(
+  lockFile: AgentLockFile,
+  name: string
+): AbilityLockEntry | null {
+  // Lock file keys are "name@version", we need to match by name only
+  for (const [key, entry] of Object.entries(lockFile.abilities)) {
+    // Find the last @ to split name from version
+    // (handles scoped packages like @kadi.build/ability@1.0.0)
+    const lastAtIndex = key.lastIndexOf('@');
+
+    if (lastAtIndex === -1) {
+      // No @ in key - shouldn't happen, but check anyway
+      if (key === name) {
+        return entry;
+      }
+      continue;
+    }
+
+    const abilityName = key.substring(0, lastAtIndex);
+    if (abilityName === name) {
+      return entry;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Get all installed ability names from the lock file.
+ * Useful for error messages listing available abilities.
+ *
+ * @param lockFile - The parsed lock file
+ * @returns Array of ability names (without versions)
+ */
+export function getInstalledAbilityNames(lockFile: AgentLockFile): string[] {
+  const names: string[] = [];
+
+  for (const key of Object.keys(lockFile.abilities)) {
+    const lastAtIndex = key.lastIndexOf('@');
+    if (lastAtIndex !== -1) {
+      names.push(key.substring(0, lastAtIndex));
+    }
+  }
+
+  return names;
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// PATH RESOLUTION
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Resolve the absolute path to an installed ability.
+ * This is the main function used by loadNative() and loadStdio().
+ *
+ * Flow:
+ * 1. Find project root (if not provided)
+ * 2. Read agent-lock.json
+ * 3. Look up ability by name
+ * 4. Return absolute path to the ability
+ *
+ * @param name - Ability name to resolve
+ * @param projectRoot - Project root (will be auto-detected if not provided)
+ * @returns Absolute path to the ability directory
+ * @throws KadiError if ability not found
+ *
+ * @example
+ * ```typescript
+ * const path = await resolveAbilityPath('calculator');
+ * // '/Users/kassi/my-project/abilities/calculator@1.0.0'
+ * ```
+ */
+export async function resolveAbilityPath(
+  name: string,
+  projectRoot?: string
+): Promise<string> {
+  // Find project root if not provided
+  const root = projectRoot ?? await findProjectRoot();
+
+  // Read lock file
+  const lockFile = await readLockFile(root);
+
+  // Find ability entry
+  const entry = findAbilityEntry(lockFile, name);
+
+  if (!entry) {
+    // Build helpful error message with available abilities
+    const available = getInstalledAbilityNames(lockFile);
+
+    throw new KadiError(
+      `Ability "${name}" not found in agent-lock.json`,
+      'ABILITY_NOT_FOUND',
+      {
+        abilityName: name,
+        searched: join(root, 'agent-lock.json'),
+        available: available.length > 0 ? available : undefined,
+        hint: `Run \`kadi install ${name}\` to install it`,
+        alternative: 'Or specify an explicit path: { path: "./path/to/ability" }',
+      }
+    );
+  }
+
+  // Build absolute path from project root + relative path in lock file
+  return join(root, entry.resolved);
+}
+
+/**
+ * Get full ability entry with resolved path.
+ * Returns more information than resolveAbilityPath() for cases where
+ * you need the version, type, or other metadata.
+ *
+ * @param name - Ability name to resolve
+ * @param projectRoot - Project root (will be auto-detected if not provided)
+ * @returns Ability entry with absolute path added
+ */
+export async function resolveAbilityEntry(
+  name: string,
+  projectRoot?: string
+): Promise<AbilityLockEntry & { absolutePath: string }> {
+  const root = projectRoot ?? await findProjectRoot();
+  const lockFile = await readLockFile(root);
+  const entry = findAbilityEntry(lockFile, name);
+
+  if (!entry) {
+    const available = getInstalledAbilityNames(lockFile);
+
+    throw new KadiError(
+      `Ability "${name}" not found in agent-lock.json`,
+      'ABILITY_NOT_FOUND',
+      {
+        abilityName: name,
+        searched: join(root, 'agent-lock.json'),
+        available: available.length > 0 ? available : undefined,
+        hint: `Run \`kadi install ${name}\` to install it`,
+        alternative: 'Or specify an explicit path: { path: "./path/to/ability" }',
+      }
+    );
+  }
+
+  return {
+    ...entry,
+    absolutePath: join(root, entry.resolved),
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// SCRIPT RESOLUTION (for loadStdio)
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Parsed script command ready for spawning a child process.
+ */
+interface ParsedScript {
+  /** The command to execute (e.g., 'python3', 'node') */
+  command: string;
+
+  /** Arguments to pass to the command */
+  args: string[];
+}
+
+/**
+ * Parse a script string into command and arguments.
+ *
+ * This is a simple parser that splits on whitespace.
+ * For most use cases (e.g., "python3 main.py --debug"), this works fine.
+ *
+ * Note: Does not handle quoted arguments with spaces (e.g., "node 'my file.js'").
+ * For complex cases, users should use explicit command/args.
+ *
+ * @param script - Script string from agent.json (e.g., "python3 main.py --verbose")
+ * @returns Parsed command and arguments
+ *
+ * @example
+ * ```typescript
+ * parseScriptCommand('python3 main.py --debug')
+ * // → { command: 'python3', args: ['main.py', '--debug'] }
+ *
+ * parseScriptCommand('node dist/server.js')
+ * // → { command: 'node', args: ['dist/server.js'] }
+ * ```
+ */
+export function parseScriptCommand(script: string): ParsedScript {
+  // Check for quotes — we can't handle these properly with simple split
+  // Users with complex commands should use explicit command/args
+  if (script.includes("'") || script.includes('"')) {
+    throw new KadiError(
+      'Script contains quotes which are not supported',
+      'INVALID_CONFIG',
+      {
+        script,
+        hint: 'Scripts with quoted arguments cannot be parsed. Provide command and args separately.',
+        example: '{ command: "node", args: ["my file.js"] }',
+      }
+    );
+  }
+
+  // Trim and split on whitespace
+  const parts = script.trim().split(/\s+/);
+
+  // Extract command (first element)
+  const command = parts[0];
+
+  if (!command) {
+    throw new KadiError(
+      'Script is empty',
+      'INVALID_CONFIG',
+      {
+        script,
+        hint: 'The script should contain a command (e.g., "python3 main.py")',
+      }
+    );
+  }
+
+  return {
+    command,
+    args: parts.slice(1),
+  };
+}
+
+/**
+ * Minimal agent.json structure for script resolution.
+ * We only need the scripts section.
+ */
+interface AbilityAgentJson {
+  name?: string;
+  scripts?: Record<string, string>;
+}
+
+/**
+ * Read an ability's agent.json file.
+ *
+ * @param abilityPath - Absolute path to the ability directory
+ * @returns Parsed agent.json contents
+ * @throws KadiError if agent.json doesn't exist or is invalid
+ *
+ * @example
+ * ```typescript
+ * const agentJson = await readAbilityAgentJson('/path/to/ability');
+ * console.log(agentJson.scripts?.start);
+ * // → "python3 main.py"
+ * ```
+ */
+export async function readAbilityAgentJson(abilityPath: string): Promise<AbilityAgentJson> {
+  const agentJsonPath = join(abilityPath, 'agent.json');
+
+  let content: string;
+  try {
+    content = await readFile(agentJsonPath, 'utf-8');
+  } catch (error) {
+    throw new KadiError(
+      `Ability is missing agent.json`,
+      'ABILITY_LOAD_FAILED',
+      {
+        path: agentJsonPath,
+        hint: 'The ability directory must contain an agent.json file with a scripts section',
+      }
+    );
+  }
+
+  try {
+    return JSON.parse(content) as AbilityAgentJson;
+  } catch (error) {
+    throw new KadiError(
+      `Failed to parse ability's agent.json`,
+      'ABILITY_LOAD_FAILED',
+      {
+        path: agentJsonPath,
+        reason: error instanceof Error ? error.message : 'Invalid JSON',
+      }
+    );
+  }
+}
+
+/**
+ * Resolve a script command for an ability.
+ *
+ * This is the main function used by loadStdio() when in script resolution mode.
+ *
+ * Flow:
+ * 1. Resolve ability path from agent-lock.json
+ * 2. Read ability's agent.json
+ * 3. Get the requested script (default: 'start')
+ * 4. Parse the script into command and args
+ * 5. Resolve paths relative to ability directory
+ *
+ * @param name - Ability name to resolve
+ * @param scriptName - Which script to use (default: 'start')
+ * @param projectRoot - Project root (auto-detected if not provided)
+ * @returns Command, args, and working directory for spawning the process
+ *
+ * @example
+ * ```typescript
+ * // Uses scripts.start by default
+ * const { command, args, cwd } = await resolveAbilityScript('image-processor');
+ * // → { command: 'python3', args: ['main.py'], cwd: '/path/to/ability' }
+ *
+ * // Use a specific script
+ * const { command, args, cwd } = await resolveAbilityScript('image-processor', 'dev');
+ * // → { command: 'python3', args: ['main.py', '--debug'], cwd: '/path/to/ability' }
+ * ```
+ */
+export async function resolveAbilityScript(
+  name: string,
+  scriptName: string = 'start',
+  projectRoot?: string
+): Promise<ResolvedScript> {
+  // Step 1: Resolve ability path from agent-lock.json
+  const abilityPath = await resolveAbilityPath(name, projectRoot);
+
+  // Step 2: Read ability's agent.json
+  const agentJson = await readAbilityAgentJson(abilityPath);
+
+  // Step 3: Get the requested script
+  const scripts = agentJson.scripts;
+  if (!scripts) {
+    throw new KadiError(
+      `Ability "${name}" has no scripts section in agent.json`,
+      'INVALID_CONFIG',
+      {
+        abilityName: name,
+        agentJsonPath: join(abilityPath, 'agent.json'),
+        hint: 'Add a "scripts" section with a "start" script to agent.json',
+        example: '{ "scripts": { "start": "python3 main.py" } }',
+      }
+    );
+  }
+
+  const script = scripts[scriptName];
+  if (!script) {
+    // Build helpful error with available scripts
+    const availableScripts = Object.keys(scripts).filter(k => scripts[k]); // Filter out empty scripts
+
+    throw new KadiError(
+      `Script "${scriptName}" not found in ability "${name}"`,
+      'INVALID_CONFIG',
+      {
+        abilityName: name,
+        requestedScript: scriptName,
+        availableScripts: availableScripts.length > 0 ? availableScripts : undefined,
+        hint: availableScripts.length > 0
+          ? `Available scripts: ${availableScripts.join(', ')}`
+          : 'Add scripts to the ability\'s agent.json',
+      }
+    );
+  }
+
+  // Step 4: Parse the script into command and args
+  const parsed = parseScriptCommand(script);
+
+  // Step 5: Return with ability path as working directory
+  return {
+    ...parsed,
+    cwd: abilityPath,
+  };
+}