@kadi.build/core 0.9.0 → 0.11.0

package/src/types.ts

@@ -1073,3 +1073,280 @@ export interface EmitOptions {
    */
   network?: string;
 }
+
+// ═══════════════════════════════════════════════════════════════════════
+// 9. AGENT.JSON TYPES
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Lifecycle scripts in agent.json.
+ * These are executed by kadi-install and kadi-run at various stages.
+ */
+export interface AgentJsonScripts {
+  /** Run before setup — environment checks, secret retrieval */
+  preflight?: string;
+  /** Install dependencies and build */
+  setup?: string;
+  /** Start the agent/ability */
+  start?: string;
+  /** Stop the agent/ability */
+  stop?: string;
+  /** Development mode start */
+  dev?: string;
+  /** Cleanup generated files */
+  clean?: string;
+  /** Any other custom scripts */
+  [key: string]: string | undefined;
+}
+
+/**
+ * Container build profile in agent.json.
+ */
+export interface AgentJsonBuildProfile {
+  /** Base image (e.g., 'node:22-slim') */
+  from: string;
+  /** Target platform (e.g., 'linux/amd64') */
+  platform?: string;
+  /** KADI CLI version to install in container */
+  cli?: string;
+  /** RUN commands for Dockerfile */
+  run?: string[];
+  /** CMD for the container */
+  cmd?: string[];
+  /** Additional fields */
+  [key: string]: unknown;
+}
+
+/**
+ * Deployment profile in agent.json.
+ */
+export interface AgentJsonDeployProfile {
+  /** Deployment target (e.g., 'local', 'akash') */
+  target: string;
+  /** Container engine for local deployments (e.g., 'docker') */
+  engine?: string;
+  /** Network name for Akash deployments */
+  network?: string;
+  /** Deposit amount for Akash */
+  deposit?: string;
+  /** Service definitions */
+  services?: Record<string, unknown>;
+  /** Secret delivery configuration */
+  secrets?: Record<string, unknown>;
+  /** Additional fields */
+  [key: string]: unknown;
+}
+
+/**
+ * Full agent.json schema — union of all known fields across the ecosystem.
+ *
+ * Agent.json files can exist in three locations:
+ * 1. **Project root** — the agent's own config
+ * 2. **Installed ability** — an ability's config within abilities/
+ * 3. **KADI home** — global CLI config at ~/.kadi/
+ *
+ * @example
+ * ```typescript
+ * const agentJson: AgentJson = {
+ *   name: 'my-agent',
+ *   version: '1.0.0',
+ *   type: 'ability',
+ *   entrypoint: 'dist/index.js',
+ *   abilities: { 'secret-ability': '^0.9.0' },
+ *   scripts: { setup: 'npm install && npm run build', start: 'node dist/index.js' },
+ *   deploy: { local: { target: 'local', engine: 'docker' } },
+ * };
+ * ```
+ */
+export interface AgentJson {
+  /** Name of the agent/ability/plugin (required) */
+  name: string;
+  /** Semver version */
+  version?: string;
+  /** Human-readable description */
+  description?: string;
+  /** License identifier */
+  license?: string;
+  /** Package type */
+  type?: 'ability' | 'plugin' | 'agent';
+  /** Entry point file for native loading */
+  entrypoint?: string;
+  /** Alternate entry field (used in some Python projects) */
+  entry?: string;
+  /** Git repository URL */
+  repo?: string;
+  /** Archive download URL */
+  lib?: string;
+  /** CLI commands this plugin provides */
+  commands?: string[];
+  /** Ability dependencies (name → semver range) */
+  abilities?: Record<string, string>;
+  /** Broker connections (name → URL or BrokerEntry) */
+  brokers?: Record<string, string | { url: string; networks?: string[] }>;
+  /** Lifecycle scripts */
+  scripts?: AgentJsonScripts;
+  /** Container build profiles */
+  build?: Record<string, AgentJsonBuildProfile>;
+  /** Deployment profiles */
+  deploy?: Record<string, AgentJsonDeployProfile>;
+  /** CLI plugin registrations */
+  cliPlugins?: Record<string, unknown>;
+  /** Extensible — any additional fields */
+  [key: string]: unknown;
+}
+
+/**
+ * Options for creating an AgentJsonManager.
+ */
+export interface AgentJsonManagerOptions {
+  /** Explicit project root. If omitted, auto-detected via findProjectRoot(). */
+  projectRoot?: string;
+  /** Custom KADI home path. Default: ~/.kadi */
+  kadiHome?: string;
+  /** If true, creates agent.json files that don't exist on first write. Default: true */
+  createOnWrite?: boolean;
+}
+
+/**
+ * Options for reading an ability's agent.json.
+ */
+export interface ReadAbilityOptions {
+  /** Specific field to read (dot-notation path). */
+  field?: string;
+  /** Specific version to target when multiple versions are installed. */
+  version?: string;
+}
+
+/**
+ * Summary info about an installed ability.
+ */
+export interface AbilityInfo {
+  /** Ability name */
+  name: string;
+  /** Installed version */
+  version: string;
+  /** Absolute path to the ability directory */
+  path: string;
+}
+
+/**
+ * Resolved paths for all known agent.json files.
+ */
+export interface AgentJsonPaths {
+  /** Path to project root agent.json */
+  project: string;
+  /** Path to KADI home agent.json */
+  home: string;
+  /** Map of "name@version" → absolute path to agent.json */
+  abilities: Record<string, string>;
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// 10. PROCESS MANAGER TYPES
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Execution mode for a managed process.
+ *
+ * - **headless**: Fire-and-forget. No communication channel. Best for builds, cleanup.
+ * - **piped**: stdout/stderr are streamed back. Best for monitoring deploys, tailing logs.
+ * - **bridge**: Full JSON-RPC stdio bridge. Best for interactive tools, worker agents.
+ */
+export type ProcessMode = 'headless' | 'piped' | 'bridge';
+
+/**
+ * Lifecycle state of a managed process.
+ */
+export type ProcessState = 'running' | 'exited' | 'killed' | 'errored';
+
+/**
+ * Options for spawning a managed process.
+ */
+export interface SpawnOptions {
+  /** Shell command to execute */
+  command: string;
+  /** Arguments to the command */
+  args?: string[];
+  /** Working directory */
+  cwd?: string;
+  /** Environment variables (merged with process.env) */
+  env?: Record<string, string>;
+  /** Execution mode */
+  mode: ProcessMode;
+  /** Timeout in ms — auto-kills if exceeded. 0 = no timeout. Default: 0 */
+  timeout?: number;
+  /** Grace period before SIGKILL after SIGTERM (ms). Default: 5000 */
+  killGracePeriod?: number;
+  /** Maximum output buffer size in bytes (piped mode). Default: 10MB */
+  maxOutputBuffer?: number;
+}
+
+/**
+ * Information about a managed process.
+ */
+export interface ProcessInfo {
+  /** Unique identifier (the name passed to spawn) */
+  id: string;
+  /** OS process ID */
+  pid: number;
+  /** Current lifecycle state */
+  state: ProcessState;
+  /** Execution mode */
+  mode: ProcessMode;
+  /** When the process was started */
+  startedAt: Date;
+  /** When the process ended (null if still running) */
+  endedAt: Date | null;
+  /** Exit code (null if still running or killed by signal) */
+  exitCode: number | null;
+  /** Signal that killed the process (null if exited normally) */
+  signal: string | null;
+  /** Duration in ms (null if still running) */
+  duration: number | null;
+  /** The command that was run */
+  command: string;
+  /** Arguments passed to the command */
+  args: string[];
+  /** Working directory */
+  cwd: string;
+}
+
+/**
+ * Exit information for a completed process.
+ */
+export interface ProcessExitInfo {
+  /** Exit code (null if killed by signal) */
+  exitCode: number | null;
+  /** Signal that killed the process (null if exited normally) */
+  signal: string | null;
+  /** Duration in ms from start to exit */
+  duration: number;
+}
+
+/**
+ * Buffered output from a piped process.
+ */
+export interface ProcessOutput {
+  /** All captured stdout data */
+  stdout: string;
+  /** All captured stderr data */
+  stderr: string;
+}
+
+/**
+ * Options for listing processes.
+ */
+export interface ProcessListOptions {
+  /** Filter by lifecycle state */
+  state?: ProcessState;
+  /** Filter by execution mode */
+  mode?: ProcessMode;
+}
+
+/**
+ * Options for pruning dead processes.
+ */
+export interface ProcessPruneOptions {
+  /** Remove exited processes older than this many seconds */
+  olderThan?: number;
+}

package/src/utils.ts

@@ -0,0 +1,246 @@
+/**
+ * Dot-path utility functions for kadi-core
+ *
+ * Provides get/set/delete operations on nested objects using dot-notation paths.
+ * Used by AgentJsonManager for field-level reads and writes.
+ *
+ * @example
+ * ```typescript
+ * const obj = { deploy: { local: { target: 'docker' } } };
+ *
+ * getByPath(obj, 'deploy.local.target');
+ * // → 'docker'
+ *
+ * setByPath(obj, 'deploy.staging.target', 'akash');
+ * // obj is now: { deploy: { local: { target: 'docker' }, staging: { target: 'akash' } } }
+ *
+ * deleteByPath(obj, 'deploy.staging');
+ * // obj is now: { deploy: { local: { target: 'docker' } } }
+ * ```
+ */
+
+// ═══════════════════════════════════════════════════════════════════════
+// PATH PARSING
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Split a dot-notation path into segments.
+ *
+ * If the full path exists as a literal key in the object, it takes precedence
+ * over dot-splitting. This handles the (rare) case where a key literally
+ * contains a dot.
+ *
+ * @param path - Dot-notation path (e.g., 'deploy.local.services')
+ * @returns Array of path segments
+ */
+export function splitPath(path: string): string[] {
+  if (!path) return [];
+  return path.split('.');
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// GET
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Get a value from a nested object by dot-notation path.
+ *
+ * @param obj - The object to read from
+ * @param path - Dot-notation path (e.g., 'deploy.local.target')
+ * @returns The value at the path, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const config = { deploy: { local: { target: 'docker' } } };
+ *
+ * getByPath(config, 'deploy.local.target');  // 'docker'
+ * getByPath(config, 'deploy.local');          // { target: 'docker' }
+ * getByPath(config, 'missing');               // undefined
+ * getByPath(config, 'deploy.missing.deep');   // undefined
+ * ```
+ */
+export function getByPath(obj: Record<string, unknown>, path: string): unknown {
+  // Check if the full path exists as a literal key first
+  if (path in obj) {
+    return obj[path];
+  }
+
+  const segments = splitPath(path);
+  let current: unknown = obj;
+
+  for (const segment of segments) {
+    if (current === null || current === undefined || typeof current !== 'object') {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[segment];
+  }
+
+  return current;
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// SET
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Deep merge two objects. Arrays and scalars are replaced, not merged.
+ *
+ * @param target - The object to merge into
+ * @param source - The object to merge from
+ * @returns The merged target object
+ */
+export function deepMerge(
+  target: Record<string, unknown>,
+  source: Record<string, unknown>,
+): Record<string, unknown> {
+  for (const key of Object.keys(source)) {
+    const sourceVal = source[key];
+    const targetVal = target[key];
+
+    if (
+      sourceVal !== null &&
+      typeof sourceVal === 'object' &&
+      !Array.isArray(sourceVal) &&
+      targetVal !== null &&
+      typeof targetVal === 'object' &&
+      !Array.isArray(targetVal)
+    ) {
+      // Both are plain objects — recurse
+      target[key] = deepMerge(
+        targetVal as Record<string, unknown>,
+        sourceVal as Record<string, unknown>,
+      );
+    } else {
+      // Scalar, array, or type mismatch — replace
+      target[key] = sourceVal;
+    }
+  }
+  return target;
+}
+
+/**
+ * Set a value in a nested object by dot-notation path.
+ *
+ * Creates intermediate objects as needed. For object values, performs
+ * a deep merge with existing values (preserving sibling keys).
+ * For scalars and arrays, replaces the value.
+ *
+ * @param obj - The object to modify (mutated in place)
+ * @param path - Dot-notation path (e.g., 'deploy.staging.target')
+ * @param value - The value to set
+ *
+ * @example
+ * ```typescript
+ * const config = { deploy: { local: { target: 'docker', engine: 'docker' } } };
+ *
+ * // Set a scalar — replaces
+ * setByPath(config, 'deploy.local.target', 'akash');
+ * // { deploy: { local: { target: 'akash', engine: 'docker' } } }
+ *
+ * // Set an object — deep merges
+ * setByPath(config, 'deploy.local', { network: 'mainnet' });
+ * // { deploy: { local: { target: 'akash', engine: 'docker', network: 'mainnet' } } }
+ *
+ * // Set on non-existent path — creates intermediates
+ * setByPath(config, 'build.arm64.from', 'node:22-slim');
+ * // { deploy: {...}, build: { arm64: { from: 'node:22-slim' } } }
+ * ```
+ */
+export function setByPath(
+  obj: Record<string, unknown>,
+  path: string,
+  value: unknown,
+): void {
+  const segments = splitPath(path);
+
+  if (segments.length === 0) return;
+
+  // Walk to the parent of the target key, creating intermediates
+  let current: Record<string, unknown> = obj;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const segment = segments[i]!;
+    const next = current[segment];
+
+    if (next === null || next === undefined || typeof next !== 'object' || Array.isArray(next)) {
+      // Create intermediate object
+      const newObj: Record<string, unknown> = {};
+      current[segment] = newObj;
+      current = newObj;
+    } else {
+      current = next as Record<string, unknown>;
+    }
+  }
+
+  const lastSegment = segments[segments.length - 1]!;
+  const existing = current[lastSegment];
+
+  // Deep merge if both existing and new are plain objects
+  if (
+    value !== null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    existing !== null &&
+    typeof existing === 'object' &&
+    !Array.isArray(existing)
+  ) {
+    current[lastSegment] = deepMerge(
+      existing as Record<string, unknown>,
+      value as Record<string, unknown>,
+    );
+  } else {
+    current[lastSegment] = value;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// DELETE
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Delete a key from a nested object by dot-notation path.
+ *
+ * @param obj - The object to modify (mutated in place)
+ * @param path - Dot-notation path to the key to delete
+ * @returns true if the key was found and deleted, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const config = { deploy: { local: { target: 'docker' }, staging: { target: 'akash' } } };
+ *
+ * deleteByPath(config, 'deploy.staging');
+ * // config is now: { deploy: { local: { target: 'docker' } } }
+ * // returns true
+ *
+ * deleteByPath(config, 'missing.key');
+ * // returns false
+ * ```
+ */
+export function deleteByPath(obj: Record<string, unknown>, path: string): boolean {
+  const segments = splitPath(path);
+
+  if (segments.length === 0) return false;
+
+  // Walk to the parent of the target key
+  let current: unknown = obj;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const segment = segments[i]!;
+    if (current === null || current === undefined || typeof current !== 'object') {
+      return false;
+    }
+    current = (current as Record<string, unknown>)[segment];
+  }
+
+  if (current === null || current === undefined || typeof current !== 'object') {
+    return false;
+  }
+
+  const lastSegment = segments[segments.length - 1]!;
+  const parent = current as Record<string, unknown>;
+
+  if (!(lastSegment in parent)) {
+    return false;
+  }
+
+  delete parent[lastSegment];
+  return true;
+}