@kadi.build/core 0.12.0 → 0.14.0

package/src/config.ts

@@ -0,0 +1,368 @@
+/**
+ * Configuration loader for KADI agents and abilities.
+ *
+ * Provides standardized config.yml discovery with a 2-tier fallback:
+ *   1. **Project-level** — walk up from startDir looking for config.yml
+ *   2. **Global-level** — ~/.kadi/config.yml (shared KADI infrastructure settings)
+ *
+ * Resolution order per-field (highest-priority first):
+ *   1. Environment variables  (PREFIX_KEY)
+ *   2. Project config.yml section
+ *   3. Global  config.yml section (~/.kadi/config.yml)
+ *   4. Built-in defaults
+ *
+ * Secrets (API keys, tokens) should NEVER appear in config.yml.
+ * Use secret-ability / kadi-secret for credentials.
+ *
+ * @example
+ * ```typescript
+ * import { loadConfig } from '@kadi.build/core';
+ *
+ * const { config, configPath, source } = loadConfig({
+ *   section: 'memory',
+ *   envPrefix: 'MEMORY',
+ *   defaults: { database: 'kadi_memory', embedding_model: 'text-embedding-3-small' },
+ * });
+ * ```
+ *
+ * TypeScript equivalent of: kadi-core-py/src/kadi/config.py
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+
+// ═══════════════════════════════════════════════════════════════════════
+// YAML import — optional runtime dependency
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * We lazy-import js-yaml so that kadi-core does NOT require it as a hard
+ * dependency.  Consumers that use loadConfig() need js-yaml installed;
+ * everything else in kadi-core works without it.
+ *
+ * In practice every KADI agent/ability already has js-yaml, so this is
+ * a formality rather than a real constraint.
+ */
+let yaml: { load(content: string): unknown } | null = null;
+let yamlResolved = false;
+
+function requireYaml(): typeof yaml {
+  if (!yamlResolved) {
+    yamlResolved = true;
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      yaml = require('js-yaml') as typeof yaml;
+    } catch {
+      try {
+        // ESM fallback — createRequire for pure-ESM environments
+        const { createRequire } = require('node:module');
+        const localRequire = createRequire(process.cwd() + '/');
+        yaml = localRequire('js-yaml') as typeof yaml;
+      } catch {
+        yaml = null;
+      }
+    }
+  }
+  return yaml;
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Constants
+// ═══════════════════════════════════════════════════════════════════════
+
+/** Default config filename. */
+const DEFAULT_FILENAME = 'config.yml';
+
+/** Global KADI config directory. */
+const GLOBAL_KADI_DIR = path.join(os.homedir(), '.kadi');
+
+// ═══════════════════════════════════════════════════════════════════════
+// Types
+// ═══════════════════════════════════════════════════════════════════════
+
+/** How the config file was discovered. */
+export type ConfigSource = 'project' | 'global' | 'default';
+
+/** Options for {@link loadConfig}. */
+export interface LoadConfigOptions {
+  /**
+   * YAML section key to extract (e.g. `'tunnel'`, `'memory'`, `'kadi_agent'`).
+   * The top-level key in config.yml whose value becomes the config object.
+   */
+  section: string;
+
+  /**
+   * Directory to start the upward walk from.
+   * @default process.cwd()
+   */
+  startDir?: string;
+
+  /**
+   * Config filename to search for.
+   * @default 'config.yml'
+   */
+  filename?: string;
+
+  /**
+   * Environment variable prefix for automatic overrides.
+   *
+   * When set, loadConfig will scan `process.env` for keys starting with
+   * `PREFIX_` and merge them into the config (highest priority).
+   *
+   * Mapping: `PREFIX_KEY_NAME` → config field `key_name` (lowercased).
+   *
+   * @example envPrefix: 'MEMORY' → MEMORY_DATABASE overrides config.database
+   */
+  envPrefix?: string;
+
+  /**
+   * Built-in defaults (lowest priority).
+   * These are used when neither env vars nor config.yml provide a value.
+   */
+  defaults?: Record<string, unknown>;
+}
+
+/** Result of {@link loadConfig}. */
+export interface ConfigResult<T = Record<string, unknown>> {
+  /** Merged config object: env > project config.yml > global config.yml > defaults. */
+  config: T;
+  /** Absolute path to the config.yml that was loaded, or null if none found. */
+  configPath: string | null;
+  /** Where the primary config was found. */
+  source: ConfigSource;
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// File discovery
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Walk up the directory tree looking for a file.
+ *
+ * @param filename - File to search for (default: `'config.yml'`)
+ * @param startDir - Directory to start from (default: `process.cwd()`)
+ * @returns Absolute path if found, `null` otherwise.
+ */
+export function findConfigFile(
+  filename: string = DEFAULT_FILENAME,
+  startDir?: string,
+): string | null {
+  let dir = path.resolve(startDir ?? process.cwd());
+
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const candidate = path.join(dir, filename);
+    try {
+      if (fs.statSync(candidate).isFile()) {
+        return candidate;
+      }
+    } catch {
+      // Not found, keep walking
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break; // Filesystem root
+    dir = parent;
+  }
+
+  return null;
+}
+
+/**
+ * Find the global KADI config file.
+ *
+ * @param filename - Config filename (default: `'config.yml'`)
+ * @returns Absolute path to `~/.kadi/<filename>` if it exists, `null` otherwise.
+ */
+export function findGlobalConfigFile(
+  filename: string = DEFAULT_FILENAME,
+): string | null {
+  const globalPath = path.join(GLOBAL_KADI_DIR, filename);
+  try {
+    if (fs.statSync(globalPath).isFile()) {
+      return globalPath;
+    }
+  } catch {
+    // Not found
+  }
+  return null;
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Section extraction
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Parse a YAML file and extract a top-level section.
+ */
+function readSection(
+  filePath: string,
+  section: string,
+): Record<string, unknown> {
+  const lib = requireYaml();
+  if (!lib) return {};
+
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const parsed = lib.load(content) as Record<string, unknown> | null;
+    if (!parsed || typeof parsed !== 'object') return {};
+    const sectionData = parsed[section];
+    if (!sectionData || typeof sectionData !== 'object') return {};
+    return sectionData as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Environment variable overlay
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Build an overrides object from environment variables matching a prefix.
+ *
+ * `PREFIX_KEY_NAME=value` → `{ key_name: value }`
+ *
+ * Numeric strings are auto-coerced to numbers.
+ * `'true'` / `'false'` are coerced to booleans.
+ */
+function envOverrides(
+  prefix: string,
+  knownKeys?: Set<string>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  const prefixUpper = prefix.toUpperCase() + '_';
+
+  for (const [envKey, envVal] of Object.entries(process.env)) {
+    if (!envKey.startsWith(prefixUpper) || envVal === undefined) continue;
+
+    const configKey = envKey.slice(prefixUpper.length).toLowerCase();
+
+    // Skip if we have a known-keys set and this key isn't in it
+    if (knownKeys && !knownKeys.has(configKey)) continue;
+
+    result[configKey] = coerce(envVal);
+  }
+
+  return result;
+}
+
+/**
+ * Coerce a string environment value to its natural JS type.
+ */
+function coerce(value: string): unknown {
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  if (value === '') return value;
+
+  // Attempt numeric coercion only for things that look numeric
+  const num = Number(value);
+  if (!Number.isNaN(num) && value.trim() !== '') return num;
+
+  return value;
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Main API
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Load configuration for a KADI agent or ability.
+ *
+ * Resolution order per-field (highest-priority first):
+ *   1. Environment variables  (`envPrefix` + `_KEY`)
+ *   2. Project `config.yml` section (walk-up from startDir)
+ *   3. Global `~/.kadi/config.yml` section
+ *   4. Built-in `defaults`
+ *
+ * @typeParam T - The shape of the merged config object.
+ * @param options - Configuration loading options.
+ * @returns Merged config with metadata about where it was found.
+ *
+ * @example
+ * ```typescript
+ * const { config } = loadConfig<TunnelConfig>({
+ *   section: 'tunnel',
+ *   envPrefix: 'KADI_TUNNEL',
+ *   defaults: { default_service: 'kadi', server_port: 7000 },
+ * });
+ * ```
+ */
+export function loadConfig<T = Record<string, unknown>>(
+  options: LoadConfigOptions,
+): ConfigResult<T> {
+  const {
+    section,
+    startDir,
+    filename = DEFAULT_FILENAME,
+    envPrefix,
+    defaults = {},
+  } = options;
+
+  // ── Layer 4: Defaults ──────────────────────────────────────────────
+  let merged: Record<string, unknown> = { ...defaults };
+
+  // ── Layer 3: Global config.yml (~/.kadi/config.yml) ────────────────
+  let configPath: string | null = null;
+  let source: ConfigSource = 'default';
+
+  const globalPath = findGlobalConfigFile(filename);
+  if (globalPath) {
+    const globalSection = readSection(globalPath, section);
+    if (Object.keys(globalSection).length > 0) {
+      merged = shallowMerge(merged, globalSection);
+      configPath = globalPath;
+      source = 'global';
+    }
+  }
+
+  // ── Layer 2: Project config.yml (walk-up) ──────────────────────────
+  const projectPath = findConfigFile(filename, startDir);
+  if (projectPath) {
+    // Only use project config if it's not the same file as global
+    const isDistinct = !globalPath || path.resolve(projectPath) !== path.resolve(globalPath);
+    if (isDistinct) {
+      const projectSection = readSection(projectPath, section);
+      if (Object.keys(projectSection).length > 0) {
+        merged = shallowMerge(merged, projectSection);
+        configPath = projectPath;
+        source = 'project';
+      }
+    }
+  }
+
+  // ── Layer 1: Environment variables (highest priority) ──────────────
+  if (envPrefix) {
+    const env = envOverrides(envPrefix);
+    if (Object.keys(env).length > 0) {
+      merged = shallowMerge(merged, env);
+    }
+  }
+
+  return {
+    config: merged as T,
+    configPath,
+    source,
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Helpers
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Shallow merge — source keys overwrite target keys.
+ * Only copies defined (non-undefined) values.
+ */
+function shallowMerge(
+  target: Record<string, unknown>,
+  source: Record<string, unknown>,
+): Record<string, unknown> {
+  const result = { ...target };
+  for (const [key, val] of Object.entries(source)) {
+    if (val !== undefined) {
+      result[key] = val;
+    }
+  }
+  return result;
+}

package/src/index.ts

@@ -122,6 +122,10 @@ export { ProcessManager, ManagedProcess } from './process-manager.js';
 // Dot-path utilities
 export { getByPath, setByPath, deleteByPath, deepMerge } from './utils.js';
 
+// Config loader (walk-up config.yml + ~/.kadi/ global fallback)
+export { loadConfig, findConfigFile, findGlobalConfigFile } from './config.js';
+export type { LoadConfigOptions, ConfigResult, ConfigSource } from './config.js';
+
 // Stdio framing (for advanced use cases — building custom bridge protocols)
 export { StdioMessageReader, StdioMessageWriter } from './stdio-framing.js';