@kadi.build/core 0.9.0 → 0.11.0

package/src/agent-json.ts

@@ -0,0 +1,655 @@
+/**
+ * AgentJsonManager for kadi-core
+ *
+ * Provides unified read/write access to agent.json files across the ecosystem.
+ * Three target locations:
+ *
+ * 1. **Project root** — the agent's own config (`/my-agent/agent.json`)
+ * 2. **Installed ability** — an ability's config (`/my-agent/abilities/calculator@1.0.0/agent.json`)
+ * 3. **KADI home** — global CLI config (`~/.kadi/agent.json`)
+ *
+ * @example
+ * ```typescript
+ * import { AgentJsonManager } from '@kadi.build/core';
+ *
+ * const ajm = new AgentJsonManager();
+ *
+ * // Read
+ * const config = await ajm.readProject();
+ * const deploy = await ajm.readProject('deploy.local');
+ * const abilityConfig = await ajm.readAbility('calculator');
+ *
+ * // Write
+ * await ajm.writeProject('deploy.staging', { target: 'akash' });
+ * await ajm.deleteProject('deploy.staging');
+ * ```
+ */
+
+import { readFile, writeFile, rename, mkdir } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+import { randomBytes } from 'crypto';
+import type {
+  AgentJson,
+  AgentJsonManagerOptions,
+  ReadAbilityOptions,
+  AbilityInfo,
+  AgentJsonPaths,
+  AgentLockFile,
+  AbilityLockEntry,
+} from './types.js';
+import { KadiError } from './errors.js';
+import { findProjectRoot, readLockFile, getInstalledAbilityNames } from './lockfile.js';
+import { getByPath, setByPath, deleteByPath } from './utils.js';
+
+// ═══════════════════════════════════════════════════════════════════════
+// CONSTANTS
+// ═══════════════════════════════════════════════════════════════════════
+
+const AGENT_JSON_FILENAME = 'agent.json';
+const DEFAULT_KADI_HOME = join(homedir(), '.kadi');
+
+// ═══════════════════════════════════════════════════════════════════════
+// AGENT JSON MANAGER
+// ═══════════════════════════════════════════════════════════════════════
+
+export class AgentJsonManager {
+  private readonly options: Required<AgentJsonManagerOptions>;
+
+  /** Cached project root (resolved lazily) */
+  private resolvedProjectRoot: string | null = null;
+
+  constructor(options: AgentJsonManagerOptions = {}) {
+    this.options = {
+      projectRoot: options.projectRoot ?? '',
+      kadiHome: options.kadiHome ?? DEFAULT_KADI_HOME,
+      createOnWrite: options.createOnWrite ?? true,
+    };
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // PROJECT ROOT RESOLUTION
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Get the resolved project root path.
+   * Auto-detects if not explicitly set.
+   */
+  private async getProjectRoot(): Promise<string> {
+    if (this.resolvedProjectRoot) {
+      return this.resolvedProjectRoot;
+    }
+
+    if (this.options.projectRoot) {
+      this.resolvedProjectRoot = this.options.projectRoot;
+    } else {
+      this.resolvedProjectRoot = await findProjectRoot();
+    }
+
+    return this.resolvedProjectRoot;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // READ API
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Read the project root agent.json.
+   *
+   * @param field - Optional dot-notation path to a specific field
+   * @returns The full agent.json object, or a specific field value
+   * @throws KadiError with code AGENT_JSON_NOT_FOUND, AGENT_JSON_PARSE_ERROR,
+   *         or AGENT_JSON_FIELD_NOT_FOUND
+   *
+   * @example
+   * ```typescript
+   * const config = await ajm.readProject();                // Full object
+   * const name = await ajm.readProject('name');            // 'my-agent'
+   * const deploy = await ajm.readProject('deploy.local');  // { target: 'docker', ... }
+   * ```
+   */
+  async readProject(field?: string): Promise<unknown> {
+    const root = await this.getProjectRoot();
+    const filePath = join(root, AGENT_JSON_FILENAME);
+    const data = await this.readJsonFile(filePath, 'project');
+
+    if (!field) return data;
+    return this.resolveField(data, field, filePath);
+  }
+
+  /**
+   * Read an installed ability's agent.json.
+   *
+   * Resolution order for version ambiguity:
+   * 1. If `options.version` specified → exact match
+   * 2. Prefer `isTopLevel: true` entries (direct dependencies)
+   * 3. Use highest semver version
+   *
+   * @param name - Ability name (without version)
+   * @param options - Version targeting and field selection
+   * @returns The full agent.json object, or a specific field value
+   *
+   * @example
+   * ```typescript
+   * const config = await ajm.readAbility('calculator');
+   * const scripts = await ajm.readAbility('calculator', { field: 'scripts' });
+   * const specific = await ajm.readAbility('secret-ability', { version: '0.9.0' });
+   * ```
+   */
+  async readAbility(name: string, options: ReadAbilityOptions = {}): Promise<unknown> {
+    const abilityPath = await this.resolveAbilityDir(name, options.version);
+    const filePath = join(abilityPath, AGENT_JSON_FILENAME);
+    const data = await this.readJsonFile(filePath, `ability "${name}"`);
+
+    if (!options.field) return data;
+    return this.resolveField(data, options.field, filePath);
+  }
+
+  /**
+   * Read the global KADI home agent.json (~/.kadi/agent.json).
+   *
+   * @param field - Optional dot-notation path to a specific field
+   * @returns The full agent.json object, or a specific field value
+   *
+   * @example
+   * ```typescript
+   * const global = await ajm.readHome();
+   * const plugins = await ajm.readHome('cliPlugins');
+   * ```
+   */
+  async readHome(field?: string): Promise<unknown> {
+    const filePath = join(this.options.kadiHome, AGENT_JSON_FILENAME);
+    const data = await this.readJsonFile(filePath, 'home (~/.kadi)');
+
+    if (!field) return data;
+    return this.resolveField(data, field, filePath);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // WRITE API
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Write a value to the project root agent.json.
+   *
+   * Uses deep-merge semantics for objects (preserves sibling keys).
+   * Scalars and arrays are directly replaced.
+   *
+   * @param path - Dot-notation path to the field to set
+   * @param value - The value to write
+   *
+   * @example
+   * ```typescript
+   * await ajm.writeProject('version', '2.0.0');
+   * await ajm.writeProject('deploy.staging', { target: 'akash', network: 'mainnet' });
+   * await ajm.writeProject('build.arm64', { from: 'node:22-slim', platform: 'linux/arm64' });
+   * ```
+   */
+  async writeProject(path: string, value: unknown): Promise<void> {
+    const root = await this.getProjectRoot();
+    const filePath = join(root, AGENT_JSON_FILENAME);
+    await this.writeField(filePath, path, value, 'project');
+  }
+
+  /**
+   * Write a value to an installed ability's agent.json.
+   *
+   * @param name - Ability name
+   * @param path - Dot-notation path to the field to set
+   * @param value - The value to write
+   * @param version - Optional specific version to target
+   *
+   * @example
+   * ```typescript
+   * await ajm.writeAbility('calculator', 'scripts.dev', 'node dist/index.js --debug');
+   * ```
+   */
+  async writeAbility(name: string, path: string, value: unknown, version?: string): Promise<void> {
+    const abilityPath = await this.resolveAbilityDir(name, version);
+    const filePath = join(abilityPath, AGENT_JSON_FILENAME);
+    await this.writeField(filePath, path, value, `ability "${name}"`);
+  }
+
+  /**
+   * Write a value to the global KADI home agent.json.
+   *
+   * @param path - Dot-notation path to the field to set
+   * @param value - The value to write
+   *
+   * @example
+   * ```typescript
+   * await ajm.writeHome('cliPlugins.my-plugin', { version: '1.0.0' });
+   * ```
+   */
+  async writeHome(path: string, value: unknown): Promise<void> {
+    const filePath = join(this.options.kadiHome, AGENT_JSON_FILENAME);
+    await this.writeField(filePath, path, value, 'home (~/.kadi)');
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // DELETE API
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Delete a field from the project root agent.json.
+   *
+   * @param path - Dot-notation path to the field to delete
+   * @returns true if the field was found and deleted
+   *
+   * @example
+   * ```typescript
+   * await ajm.deleteProject('deploy.staging');
+   * ```
+   */
+  async deleteProject(path: string): Promise<boolean> {
+    const root = await this.getProjectRoot();
+    const filePath = join(root, AGENT_JSON_FILENAME);
+    return this.deleteField(filePath, path);
+  }
+
+  /**
+   * Delete a field from an ability's agent.json.
+   */
+  async deleteAbility(name: string, path: string, version?: string): Promise<boolean> {
+    const abilityPath = await this.resolveAbilityDir(name, version);
+    const filePath = join(abilityPath, AGENT_JSON_FILENAME);
+    return this.deleteField(filePath, path);
+  }
+
+  /**
+   * Delete a field from the global KADI home agent.json.
+   */
+  async deleteHome(path: string): Promise<boolean> {
+    const filePath = join(this.options.kadiHome, AGENT_JSON_FILENAME);
+    return this.deleteField(filePath, path);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // DISCOVERY API
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * List all installed abilities with their name, version, and path.
+   *
+   * @returns Array of AbilityInfo objects
+   *
+   * @example
+   * ```typescript
+   * const abilities = await ajm.listAbilities();
+   * // [
+   * //   { name: 'calculator', version: '1.0.0', path: '/abs/path/abilities/calculator@1.0.0' },
+   * //   { name: 'secret-ability', version: '0.9.0', path: '/abs/path/abilities/secret-ability@0.9.0' },
+   * // ]
+   * ```
+   */
+  async listAbilities(): Promise<AbilityInfo[]> {
+    const root = await this.getProjectRoot();
+    let lockFile: AgentLockFile;
+
+    try {
+      lockFile = await readLockFile(root);
+    } catch {
+      return []; // No lock file → no installed abilities
+    }
+
+    const abilities: AbilityInfo[] = [];
+
+    for (const [key, entry] of Object.entries(lockFile.abilities)) {
+      const lastAt = key.lastIndexOf('@');
+      const name = lastAt !== -1 ? key.substring(0, lastAt) : key;
+      abilities.push({
+        name,
+        version: entry.version,
+        path: join(root, entry.resolved),
+      });
+    }
+
+    return abilities;
+  }
+
+  /**
+   * Check if a specific ability is installed.
+   *
+   * @param name - Ability name (without version)
+   * @returns true if the ability exists in the lock file
+   */
+  async hasAbility(name: string): Promise<boolean> {
+    const root = await this.getProjectRoot();
+    let lockFile: AgentLockFile;
+
+    try {
+      lockFile = await readLockFile(root);
+    } catch {
+      return false;
+    }
+
+    return this.findAbilityEntries(lockFile, name).length > 0;
+  }
+
+  /**
+   * Get all installed versions of a specific ability.
+   *
+   * @param name - Ability name (without version)
+   * @returns Array of version strings
+   *
+   * @example
+   * ```typescript
+   * const versions = await ajm.getAbilityVersions('secret-ability');
+   * // ['0.7.0', '0.9.0']
+   * ```
+   */
+  async getAbilityVersions(name: string): Promise<string[]> {
+    const root = await this.getProjectRoot();
+    let lockFile: AgentLockFile;
+
+    try {
+      lockFile = await readLockFile(root);
+    } catch {
+      return [];
+    }
+
+    return this.findAbilityEntries(lockFile, name).map(e => e.version);
+  }
+
+  /**
+   * Get resolved paths for all known agent.json files.
+   *
+   * @returns Object with project, home, and abilities paths
+   */
+  async getPaths(): Promise<AgentJsonPaths> {
+    const root = await this.getProjectRoot();
+    const abilities: Record<string, string> = {};
+
+    try {
+      const lockFile = await readLockFile(root);
+      for (const [key, entry] of Object.entries(lockFile.abilities)) {
+        abilities[key] = join(root, entry.resolved, AGENT_JSON_FILENAME);
+      }
+    } catch {
+      // No lock file — abilities stays empty
+    }
+
+    return {
+      project: join(root, AGENT_JSON_FILENAME),
+      home: join(this.options.kadiHome, AGENT_JSON_FILENAME),
+      abilities,
+    };
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // INTERNAL: FILE I/O
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Read and parse a JSON file.
+   */
+  private async readJsonFile(filePath: string, label: string): Promise<AgentJson> {
+    let content: string;
+    try {
+      content = await readFile(filePath, 'utf-8');
+    } catch {
+      throw new KadiError(
+        `${label} agent.json not found`,
+        'AGENT_JSON_NOT_FOUND',
+        {
+          path: filePath,
+          hint: label === 'project'
+            ? 'Make sure you are in a KADI project directory with an agent.json file'
+            : `The ${label} agent.json was expected at: ${filePath}`,
+        },
+      );
+    }
+
+    try {
+      return JSON.parse(content) as AgentJson;
+    } catch {
+      throw new KadiError(
+        `Failed to parse ${label} agent.json`,
+        'AGENT_JSON_PARSE_ERROR',
+        {
+          path: filePath,
+          hint: 'The file contains invalid JSON. Check for syntax errors.',
+        },
+      );
+    }
+  }
+
+  /**
+   * Resolve a field from a parsed agent.json using dot-path notation.
+   */
+  private resolveField(data: AgentJson, field: string, filePath: string): unknown {
+    const value = getByPath(data as Record<string, unknown>, field);
+
+    if (value === undefined) {
+      throw new KadiError(
+        `Field "${field}" not found in agent.json`,
+        'AGENT_JSON_FIELD_NOT_FOUND',
+        {
+          path: filePath,
+          available: Object.keys(data),
+          hint: `Available top-level keys: ${Object.keys(data).join(', ')}`,
+        },
+      );
+    }
+
+    return value;
+  }
+
+  /**
+   * Write a field to a JSON file using dot-path notation.
+   * Atomic write: writes to a temp file then renames.
+   */
+  private async writeField(
+    filePath: string,
+    path: string,
+    value: unknown,
+    label: string,
+  ): Promise<void> {
+    // Read existing or create new
+    let data: Record<string, unknown>;
+
+    try {
+      const content = await readFile(filePath, 'utf-8');
+      data = JSON.parse(content) as Record<string, unknown>;
+    } catch {
+      if (!this.options.createOnWrite) {
+        throw new KadiError(
+          `${label} agent.json not found (createOnWrite is false)`,
+          'AGENT_JSON_NOT_FOUND',
+          { path: filePath },
+        );
+      }
+      data = {};
+    }
+
+    // Apply the change
+    setByPath(data, path, value);
+
+    // Atomic write
+    await this.atomicWriteJson(filePath, data);
+  }
+
+  /**
+   * Delete a field from a JSON file.
+   */
+  private async deleteField(filePath: string, path: string): Promise<boolean> {
+    let content: string;
+    try {
+      content = await readFile(filePath, 'utf-8');
+    } catch {
+      return false;
+    }
+
+    let data: Record<string, unknown>;
+    try {
+      data = JSON.parse(content) as Record<string, unknown>;
+    } catch {
+      return false;
+    }
+
+    const deleted = deleteByPath(data, path);
+    if (deleted) {
+      await this.atomicWriteJson(filePath, data);
+    }
+
+    return deleted;
+  }
+
+  /**
+   * Write JSON to a file atomically (write temp → rename).
+   */
+  private async atomicWriteJson(filePath: string, data: Record<string, unknown>): Promise<void> {
+    const dir = dirname(filePath);
+    const tmpPath = join(dir, `.agent.json.${randomBytes(6).toString('hex')}.tmp`);
+
+    try {
+      // Ensure directory exists
+      if (!existsSync(dir)) {
+        await mkdir(dir, { recursive: true });
+      }
+
+      const json = JSON.stringify(data, null, 2) + '\n';
+      await writeFile(tmpPath, json, 'utf-8');
+      await rename(tmpPath, filePath);
+    } catch (error) {
+      // Attempt cleanup of temp file
+      try {
+        const { unlink } = await import('fs/promises');
+        await unlink(tmpPath);
+      } catch {
+        // Ignore cleanup failure
+      }
+
+      throw new KadiError(
+        'Failed to write agent.json',
+        'AGENT_JSON_WRITE_ERROR',
+        {
+          path: filePath,
+          reason: error instanceof Error ? error.message : String(error),
+        },
+      );
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // INTERNAL: ABILITY RESOLUTION
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Resolve the directory path for an installed ability.
+   * Handles version ambiguity with smart defaults.
+   */
+  private async resolveAbilityDir(name: string, version?: string): Promise<string> {
+    const root = await this.getProjectRoot();
+    const lockFile = await readLockFile(root);
+    const entries = this.findAbilityEntries(lockFile, name);
+
+    if (entries.length === 0) {
+      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`,
+        },
+      );
+    }
+
+    let selected: { entry: AbilityLockEntry; key: string };
+
+    if (version) {
+      // Exact version requested
+      const exact = entries.find(e => e.version === version);
+      if (!exact) {
+        throw new KadiError(
+          `Ability "${name}" version "${version}" not found`,
+          'ABILITY_NOT_FOUND',
+          {
+            abilityName: name,
+            available: entries.map(e => e.version),
+            hint: `Available versions: ${entries.map(e => e.version).join(', ')}`,
+          },
+        );
+      }
+      selected = exact;
+    } else if (entries.length === 1) {
+      // Only one version — no ambiguity
+      selected = entries[0]!;
+    } else {
+      // Multiple versions — prefer isTopLevel
+      const topLevel = entries.filter(e => e.entry.isTopLevel);
+
+      if (topLevel.length === 1) {
+        selected = topLevel[0]!;
+      } else if (topLevel.length > 1) {
+        // Multiple top-level — pick highest semver
+        selected = this.highestVersion(topLevel);
+      } else {
+        // No top-level — ambiguous
+        throw new KadiError(
+          `Multiple versions of "${name}" installed — specify a version`,
+          'AGENT_JSON_VERSION_AMBIGUOUS',
+          {
+            abilityName: name,
+            available: entries.map(e => e.version),
+            hint: `Installed versions: ${entries.map(e => e.version).join(', ')}. Use { version: "x.y.z" } to select one.`,
+          },
+        );
+      }
+    }
+
+    return join(root, selected.entry.resolved);
+  }
+
+  /**
+   * Find all lock file entries matching an ability name.
+   */
+  private findAbilityEntries(
+    lockFile: AgentLockFile,
+    name: string,
+  ): Array<{ entry: AbilityLockEntry; key: string; version: string }> {
+    const results: Array<{ entry: AbilityLockEntry; key: string; version: string }> = [];
+
+    for (const [key, entry] of Object.entries(lockFile.abilities)) {
+      const lastAt = key.lastIndexOf('@');
+      const entryName = lastAt !== -1 ? key.substring(0, lastAt) : key;
+
+      if (entryName === name) {
+        results.push({ entry, key, version: entry.version });
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Pick the entry with the highest semver version.
+   * Simple comparison — splits on dots and compares numerically.
+   */
+  private highestVersion<T extends { version: string }>(entries: T[]): T {
+    return entries.reduce((highest, current) => {
+      return this.compareSemver(current.version, highest.version) > 0
+        ? current
+        : highest;
+    });
+  }
+
+  /**
+   * Compare two semver strings. Returns > 0 if a > b, < 0 if a < b, 0 if equal.
+   */
+  private compareSemver(a: string, b: string): number {
+    const aParts = a.split('.').map(Number);
+    const bParts = b.split('.').map(Number);
+
+    for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) {
+      const aVal = aParts[i] ?? 0;
+      const bVal = bParts[i] ?? 0;
+      if (aVal !== bVal) return aVal - bVal;
+    }
+    return 0;
+  }
+}