@kadi.build/core 0.8.0 → 0.11.0

package/dist/agent-json.d.ts

@@ -0,0 +1,231 @@
+/**
+ * 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 type { AgentJsonManagerOptions, ReadAbilityOptions, AbilityInfo, AgentJsonPaths } from './types.js';
+export declare class AgentJsonManager {
+    private readonly options;
+    /** Cached project root (resolved lazily) */
+    private resolvedProjectRoot;
+    constructor(options?: AgentJsonManagerOptions);
+    /**
+     * Get the resolved project root path.
+     * Auto-detects if not explicitly set.
+     */
+    private getProjectRoot;
+    /**
+     * 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', ... }
+     * ```
+     */
+    readProject(field?: string): Promise<unknown>;
+    /**
+     * 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' });
+     * ```
+     */
+    readAbility(name: string, options?: ReadAbilityOptions): Promise<unknown>;
+    /**
+     * 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');
+     * ```
+     */
+    readHome(field?: string): Promise<unknown>;
+    /**
+     * 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' });
+     * ```
+     */
+    writeProject(path: string, value: unknown): Promise<void>;
+    /**
+     * 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');
+     * ```
+     */
+    writeAbility(name: string, path: string, value: unknown, version?: string): Promise<void>;
+    /**
+     * 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' });
+     * ```
+     */
+    writeHome(path: string, value: unknown): Promise<void>;
+    /**
+     * 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');
+     * ```
+     */
+    deleteProject(path: string): Promise<boolean>;
+    /**
+     * Delete a field from an ability's agent.json.
+     */
+    deleteAbility(name: string, path: string, version?: string): Promise<boolean>;
+    /**
+     * Delete a field from the global KADI home agent.json.
+     */
+    deleteHome(path: string): Promise<boolean>;
+    /**
+     * 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' },
+     * // ]
+     * ```
+     */
+    listAbilities(): Promise<AbilityInfo[]>;
+    /**
+     * Check if a specific ability is installed.
+     *
+     * @param name - Ability name (without version)
+     * @returns true if the ability exists in the lock file
+     */
+    hasAbility(name: string): Promise<boolean>;
+    /**
+     * 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']
+     * ```
+     */
+    getAbilityVersions(name: string): Promise<string[]>;
+    /**
+     * Get resolved paths for all known agent.json files.
+     *
+     * @returns Object with project, home, and abilities paths
+     */
+    getPaths(): Promise<AgentJsonPaths>;
+    /**
+     * Read and parse a JSON file.
+     */
+    private readJsonFile;
+    /**
+     * Resolve a field from a parsed agent.json using dot-path notation.
+     */
+    private resolveField;
+    /**
+     * Write a field to a JSON file using dot-path notation.
+     * Atomic write: writes to a temp file then renames.
+     */
+    private writeField;
+    /**
+     * Delete a field from a JSON file.
+     */
+    private deleteField;
+    /**
+     * Write JSON to a file atomically (write temp → rename).
+     */
+    private atomicWriteJson;
+    /**
+     * Resolve the directory path for an installed ability.
+     * Handles version ambiguity with smart defaults.
+     */
+    private resolveAbilityDir;
+    /**
+     * Find all lock file entries matching an ability name.
+     */
+    private findAbilityEntries;
+    /**
+     * Pick the entry with the highest semver version.
+     * Simple comparison — splits on dots and compares numerically.
+     */
+    private highestVersion;
+    /**
+     * Compare two semver strings. Returns > 0 if a > b, < 0 if a < b, 0 if equal.
+     */
+    private compareSemver;
+}
+//# sourceMappingURL=agent-json.d.ts.map

package/dist/agent-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-json.d.ts","sourceRoot":"","sources":["../src/agent-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAOH,OAAO,KAAK,EAEV,uBAAuB,EACvB,kBAAkB,EAClB,WAAW,EACX,cAAc,EAGf,MAAM,YAAY,CAAC;AAgBpB,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAE5D,4CAA4C;IAC5C,OAAO,CAAC,mBAAmB,CAAuB;gBAEtC,OAAO,GAAE,uBAA4B;IAYjD;;;OAGG;YACW,cAAc;IAkB5B;;;;;;;;;;;;;;OAcG;IACG,WAAW,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASnD;;;;;;;;;;;;;;;;;;OAkBG;IACG,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,OAAO,CAAC;IASnF;;;;;;;;;;;OAWG;IACG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAYhD;;;;;;;;;;;;;;;OAeG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAM/D;;;;;;;;;;;;OAYG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM/F;;;;;;;;;;OAUG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAS5D;;;;;;;;;;OAUG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMnD;;OAEG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMnF;;OAEG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAShD;;;;;;;;;;;;;OAaG;IACG,aAAa,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAyB7C;;;;;OAKG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAahD;;;;;;;;;;;OAWG;IACG,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAazD;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,cAAc,CAAC;IAwBzC;;OAEG;YACW,YAAY;IA+B1B;;OAEG;IACH,OAAO,CAAC,YAAY;IAkBpB;;;OAGG;YACW,UAAU;IA8BxB;;OAEG;YACW,WAAW;IAuBzB;;OAEG;YACW,eAAe;IAqC7B;;;OAGG;YACW,iBAAiB;IAiE/B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAkB1B;;;OAGG;IACH,OAAO,CAAC,cAAc;IAQtB;;OAEG;IACH,OAAO,CAAC,aAAa;CAWtB"}