@herdctl/core 0.0.1

package/src/config/loader.ts

@@ -0,0 +1,472 @@
+/**
+ * Configuration loader for herdctl
+ *
+ * Provides a single entry point to load and resolve all configuration:
+ * - Auto-discovers herdctl.yaml by walking up the directory tree
+ * - Loads fleet config and all referenced agent configs
+ * - Merges fleet defaults into agent configs
+ * - Interpolates environment variables
+ * - Validates the entire configuration tree
+ */
+
+import { readFile, access } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { parse as parseYaml, YAMLParseError } from "yaml";
+import { ZodError } from "zod";
+import {
+  FleetConfigSchema,
+  AgentConfigSchema,
+  type FleetConfig,
+  type AgentConfig,
+} from "./schema.js";
+import { ConfigError, FileReadError, SchemaValidationError } from "./parser.js";
+import { mergeAgentConfig, type ExtendedDefaults } from "./merge.js";
+import { interpolateConfig, type InterpolateOptions } from "./interpolate.js";
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/**
+ * Default config file names to search for
+ */
+export const CONFIG_FILE_NAMES = ["herdctl.yaml", "herdctl.yml"] as const;
+
+// =============================================================================
+// Error Classes
+// =============================================================================
+
+/**
+ * Error thrown when no configuration file is found
+ */
+export class ConfigNotFoundError extends ConfigError {
+  public readonly searchedPaths: string[];
+  public readonly startDirectory: string;
+
+  constructor(startDirectory: string, searchedPaths: string[]) {
+    super(
+      `No herdctl configuration file found. ` +
+        `Searched from '${startDirectory}' up to filesystem root. ` +
+        `Create a herdctl.yaml file to get started.`
+    );
+    this.name = "ConfigNotFoundError";
+    this.searchedPaths = searchedPaths;
+    this.startDirectory = startDirectory;
+  }
+}
+
+/**
+ * Error thrown when agent loading fails
+ */
+export class AgentLoadError extends ConfigError {
+  public readonly agentPath: string;
+  public readonly agentName?: string;
+
+  constructor(agentPath: string, cause: Error, agentName?: string) {
+    const nameInfo = agentName ? ` (${agentName})` : "";
+    super(`Failed to load agent '${agentPath}'${nameInfo}: ${cause.message}`);
+    this.name = "AgentLoadError";
+    this.agentPath = agentPath;
+    this.agentName = agentName;
+    this.cause = cause;
+  }
+}
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * A fully resolved agent configuration with computed properties
+ */
+export interface ResolvedAgent extends AgentConfig {
+  /**
+   * The absolute path to the agent configuration file
+   */
+  configPath: string;
+}
+
+/**
+ * A fully resolved configuration with all agents loaded and merged
+ */
+export interface ResolvedConfig {
+  /**
+   * The parsed and validated fleet configuration
+   */
+  fleet: FleetConfig;
+
+  /**
+   * All agent configurations, fully resolved with defaults merged
+   */
+  agents: ResolvedAgent[];
+
+  /**
+   * The absolute path to the fleet configuration file
+   */
+  configPath: string;
+
+  /**
+   * The directory containing the fleet configuration
+   */
+  configDir: string;
+}
+
+/**
+ * Options for the loadConfig function
+ */
+export interface LoadConfigOptions {
+  /**
+   * Custom environment variables for interpolation
+   * Defaults to process.env
+   */
+  env?: Record<string, string | undefined>;
+
+  /**
+   * Whether to interpolate environment variables
+   * Defaults to true
+   */
+  interpolate?: boolean;
+
+  /**
+   * Whether to merge fleet defaults into agent configs
+   * Defaults to true
+   */
+  mergeDefaults?: boolean;
+}
+
+// =============================================================================
+// File Discovery
+// =============================================================================
+
+/**
+ * Check if a file exists and is accessible
+ */
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Find a configuration file by walking up the directory tree
+ *
+ * Searches for herdctl.yaml or herdctl.yml starting from the given directory
+ * and walking up to the filesystem root (similar to how git finds .git).
+ *
+ * @param startDir - The directory to start searching from
+ * @returns The absolute path to the config file, or null if not found
+ */
+export async function findConfigFile(
+  startDir: string
+): Promise<{ path: string; searchedPaths: string[] } | null> {
+  const searchedPaths: string[] = [];
+  let currentDir = resolve(startDir);
+
+  while (true) {
+    // Check for each possible config file name
+    for (const fileName of CONFIG_FILE_NAMES) {
+      const configPath = join(currentDir, fileName);
+      searchedPaths.push(configPath);
+
+      if (await fileExists(configPath)) {
+        return { path: configPath, searchedPaths };
+      }
+    }
+
+    // Move up to parent directory
+    const parentDir = dirname(currentDir);
+
+    // Stop if we've reached the root
+    if (parentDir === currentDir) {
+      return null;
+    }
+
+    currentDir = parentDir;
+  }
+}
+
+// =============================================================================
+// Internal Parsing Functions
+// =============================================================================
+
+/**
+ * Parse and validate fleet config from YAML content
+ */
+function parseFleetYaml(content: string, filePath: string): FleetConfig {
+  let rawConfig: unknown;
+  try {
+    rawConfig = parseYaml(content);
+  } catch (error) {
+    if (error instanceof YAMLParseError) {
+      const position = error.linePos?.[0];
+      const locationInfo = position
+        ? ` at line ${position.line}, column ${position.col}`
+        : "";
+      throw new ConfigError(
+        `Invalid YAML syntax in '${filePath}'${locationInfo}: ${error.message}`
+      );
+    }
+    throw error;
+  }
+
+  // Handle empty files
+  if (rawConfig === null || rawConfig === undefined) {
+    rawConfig = {};
+  }
+
+  try {
+    return FleetConfigSchema.parse(rawConfig);
+  } catch (error) {
+    if (error instanceof ZodError) {
+      throw new SchemaValidationError(error);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Parse and validate agent config from YAML content
+ */
+function parseAgentYaml(content: string, filePath: string): AgentConfig {
+  let rawConfig: unknown;
+  try {
+    rawConfig = parseYaml(content);
+  } catch (error) {
+    if (error instanceof YAMLParseError) {
+      const position = error.linePos?.[0];
+      const locationInfo = position
+        ? ` at line ${position.line}, column ${position.col}`
+        : "";
+      throw new ConfigError(
+        `Invalid YAML syntax in '${filePath}'${locationInfo}: ${error.message}`
+      );
+    }
+    throw error;
+  }
+
+  // Handle empty files
+  if (rawConfig === null || rawConfig === undefined) {
+    rawConfig = {};
+  }
+
+  try {
+    return AgentConfigSchema.parse(rawConfig);
+  } catch (error) {
+    if (error instanceof ZodError) {
+      const issues = error.issues.map((issue) => ({
+        path: issue.path.join(".") || "(root)",
+        message: issue.message,
+      }));
+      const issueMessages = issues
+        .map((i) => `  - ${i.path}: ${i.message}`)
+        .join("\n");
+      throw new ConfigError(
+        `Agent configuration validation failed in '${filePath}':\n${issueMessages}`
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * Resolve an agent path relative to the fleet config directory
+ */
+function resolveAgentPath(agentPath: string, fleetConfigDir: string): string {
+  if (agentPath.startsWith("/")) {
+    return agentPath;
+  }
+  return resolve(fleetConfigDir, agentPath);
+}
+
+// =============================================================================
+// Main Loading Function
+// =============================================================================
+
+/**
+ * Load complete configuration from a file path or by auto-discovery
+ *
+ * This function:
+ * 1. Finds the config file (if not provided, searches up directory tree)
+ * 2. Parses and validates the fleet configuration
+ * 3. Loads and validates all referenced agent configurations
+ * 4. Interpolates environment variables (optional)
+ * 5. Merges fleet defaults into agent configs (optional)
+ * 6. Returns a fully resolved configuration object
+ *
+ * @param configPath - Path to herdctl.yaml, or directory to search from.
+ *                     If not provided, searches from current working directory.
+ * @param options - Loading options
+ * @returns A fully resolved configuration
+ * @throws {ConfigNotFoundError} If no config file is found
+ * @throws {FileReadError} If a config file cannot be read
+ * @throws {ConfigError} If YAML syntax is invalid
+ * @throws {SchemaValidationError} If configuration fails validation
+ * @throws {AgentLoadError} If an agent configuration fails to load
+ *
+ * @example
+ * ```typescript
+ * // Auto-discover config file
+ * const config = await loadConfig();
+ *
+ * // Load from specific path
+ * const config = await loadConfig("./my-project/herdctl.yaml");
+ *
+ * // Load from specific directory
+ * const config = await loadConfig("./my-project");
+ *
+ * // Load without environment interpolation
+ * const config = await loadConfig(undefined, { interpolate: false });
+ * ```
+ */
+export async function loadConfig(
+  configPath?: string,
+  options: LoadConfigOptions = {}
+): Promise<ResolvedConfig> {
+  const {
+    env = process.env,
+    interpolate = true,
+    mergeDefaults = true,
+  } = options;
+
+  // Determine the config file path
+  let resolvedConfigPath: string;
+  let searchedPaths: string[] = [];
+
+  if (configPath) {
+    // Check if it's a file or directory
+    const isYamlFile =
+      configPath.endsWith(".yaml") || configPath.endsWith(".yml");
+
+    if (isYamlFile) {
+      // Treat as direct file path
+      resolvedConfigPath = resolve(configPath);
+    } else {
+      // Treat as directory - search from there
+      const found = await findConfigFile(configPath);
+      if (!found) {
+        throw new ConfigNotFoundError(configPath, searchedPaths);
+      }
+      resolvedConfigPath = found.path;
+      searchedPaths = found.searchedPaths;
+    }
+  } else {
+    // Auto-discover from current working directory
+    const found = await findConfigFile(process.cwd());
+    if (!found) {
+      throw new ConfigNotFoundError(process.cwd(), searchedPaths);
+    }
+    resolvedConfigPath = found.path;
+    searchedPaths = found.searchedPaths;
+  }
+
+  // Read the fleet config file
+  let fleetContent: string;
+  try {
+    fleetContent = await readFile(resolvedConfigPath, "utf-8");
+  } catch (error) {
+    throw new FileReadError(
+      resolvedConfigPath,
+      error instanceof Error ? error : undefined
+    );
+  }
+
+  // Parse the fleet config
+  let fleetConfig = parseFleetYaml(fleetContent, resolvedConfigPath);
+
+  // Interpolate environment variables in fleet config
+  if (interpolate) {
+    fleetConfig = interpolateConfig(fleetConfig, { env });
+  }
+
+  const configDir = dirname(resolvedConfigPath);
+
+  // Load all agent configs
+  const agents: ResolvedAgent[] = [];
+
+  // FleetConfigSchema has default of [], so agents is always defined
+  const agentRefs = fleetConfig.agents;
+
+  for (const agentRef of agentRefs) {
+    const agentPath = resolveAgentPath(agentRef.path, configDir);
+
+    // Read agent config file
+    let agentContent: string;
+    try {
+      agentContent = await readFile(agentPath, "utf-8");
+    } catch (error) {
+      throw new AgentLoadError(
+        agentRef.path,
+        new FileReadError(agentPath, error instanceof Error ? error : undefined)
+      );
+    }
+
+    // Parse and validate agent config
+    let agentConfig: AgentConfig;
+    try {
+      agentConfig = parseAgentYaml(agentContent, agentPath);
+    } catch (error) {
+      throw new AgentLoadError(
+        agentRef.path,
+        error instanceof Error ? error : new Error(String(error))
+      );
+    }
+
+    // Interpolate environment variables in agent config
+    if (interpolate) {
+      agentConfig = interpolateConfig(agentConfig, { env });
+    }
+
+    // Merge fleet defaults into agent config
+    if (mergeDefaults && fleetConfig.defaults) {
+      agentConfig = mergeAgentConfig(
+        fleetConfig.defaults as ExtendedDefaults,
+        agentConfig
+      );
+    }
+
+    agents.push({
+      ...agentConfig,
+      configPath: agentPath,
+    });
+  }
+
+  return {
+    fleet: fleetConfig,
+    agents,
+    configPath: resolvedConfigPath,
+    configDir,
+  };
+}
+
+/**
+ * Load configuration without throwing on errors
+ *
+ * @param configPath - Path to herdctl.yaml or directory to search from
+ * @param options - Loading options
+ * @returns Success result with config, or failure result with error
+ */
+export async function safeLoadConfig(
+  configPath?: string,
+  options: LoadConfigOptions = {}
+): Promise<
+  | { success: true; data: ResolvedConfig }
+  | { success: false; error: ConfigError }
+> {
+  try {
+    const config = await loadConfig(configPath, options);
+    return { success: true, data: config };
+  } catch (error) {
+    if (error instanceof ConfigError) {
+      return { success: false, error };
+    }
+    return {
+      success: false,
+      error: new ConfigError(
+        error instanceof Error ? error.message : String(error)
+      ),
+    };
+  }
+}

package/src/config/merge.ts

@@ -0,0 +1,246 @@
+/**
+ * Deep merge utilities for herdctl configuration
+ *
+ * Provides functions to merge fleet-level defaults with agent-specific overrides.
+ * - Nested objects merge recursively
+ * - Arrays are replaced, not merged (agent's array replaces defaults)
+ * - Agent-specific values override fleet defaults
+ */
+
+import type {
+  AgentConfig,
+  Defaults,
+  WorkSource,
+  Session,
+  Docker,
+  PermissionMode,
+  BashPermissions,
+} from "./schema.js";
+
+// =============================================================================
+// Input Types (for merging - fields are optional before Zod applies defaults)
+// =============================================================================
+
+/**
+ * Permissions input type - all fields optional before Zod applies defaults
+ */
+export interface PermissionsInput {
+  mode?: PermissionMode;
+  allowed_tools?: string[];
+  denied_tools?: string[];
+  bash?: BashPermissions;
+}
+
+// =============================================================================
+// Type Guards
+// =============================================================================
+
+/**
+ * Check if a value is a plain object (not an array, null, or other type)
+ */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.prototype.toString.call(value) === "[object Object]"
+  );
+}
+
+// =============================================================================
+// Deep Merge
+// =============================================================================
+
+/**
+ * Deep merge two objects. The override object's values take precedence.
+ * Arrays are replaced entirely (not merged).
+ * Objects are merged recursively.
+ *
+ * @param base - The base object (defaults)
+ * @param override - The override object (agent-specific)
+ * @returns A new merged object
+ */
+export function deepMerge<T extends Record<string, unknown>>(
+  base: T | undefined,
+  override: T | undefined
+): T | undefined {
+  // If base is undefined, return override
+  if (base === undefined) {
+    return override;
+  }
+
+  // If override is undefined, return base
+  if (override === undefined) {
+    return base;
+  }
+
+  // Create a new object to hold the result
+  const result = { ...base } as Record<string, unknown>;
+
+  // Iterate over the override object
+  for (const key of Object.keys(override)) {
+    const baseValue = base[key];
+    const overrideValue = override[key];
+
+    // If the override value is undefined, skip it (keep base value)
+    if (overrideValue === undefined) {
+      continue;
+    }
+
+    // If the override value is an array, replace entirely
+    if (Array.isArray(overrideValue)) {
+      result[key] = overrideValue;
+      continue;
+    }
+
+    // If both values are plain objects, merge recursively
+    if (isPlainObject(baseValue) && isPlainObject(overrideValue)) {
+      result[key] = deepMerge(baseValue, overrideValue);
+      continue;
+    }
+
+    // Otherwise, override value takes precedence
+    result[key] = overrideValue;
+  }
+
+  return result as T;
+}
+
+// =============================================================================
+// Agent Config Merge Types
+// =============================================================================
+
+/**
+ * The fields from fleet defaults that can be merged into agent config
+ */
+export interface MergeableDefaults {
+  permissions?: PermissionsInput;
+  work_source?: WorkSource;
+  session?: Session;
+  docker?: Docker;
+  model?: string;
+  max_turns?: number;
+  permission_mode?: PermissionMode;
+}
+
+/**
+ * Extended defaults schema that includes all mergeable fields.
+ * Uses input types (with optional fields) since these are pre-validation values.
+ */
+export interface ExtendedDefaults {
+  docker?: Docker;
+  permissions?: PermissionsInput;
+  work_source?: WorkSource;
+  instances?: { max_concurrent?: number };
+  session?: Session;
+  model?: string;
+  max_turns?: number;
+  permission_mode?: PermissionMode;
+}
+
+// =============================================================================
+// Agent Config Merge
+// =============================================================================
+
+/**
+ * Merge fleet defaults into an agent configuration.
+ *
+ * The merge applies to the following fields:
+ * - permissions: Deep merged (agent overrides fleet defaults)
+ * - work_source: Deep merged
+ * - session: Deep merged
+ * - docker: Deep merged
+ * - model: Agent value overrides default
+ * - max_turns: Agent value overrides default
+ * - permission_mode: Agent value overrides default
+ *
+ * Arrays within these objects (e.g., allowed_tools) are replaced, not merged.
+ *
+ * @param defaults - The fleet-level defaults
+ * @param agent - The agent-specific configuration
+ * @returns A new agent configuration with defaults merged in
+ */
+export function mergeAgentConfig(
+  defaults: ExtendedDefaults | undefined,
+  agent: AgentConfig
+): AgentConfig {
+  // If no defaults, return agent as-is
+  if (!defaults) {
+    return agent;
+  }
+
+  // Start with the agent config
+  const result: AgentConfig = { ...agent };
+
+  // Merge permissions (deep merge)
+  if (defaults.permissions || agent.permissions) {
+    result.permissions = deepMerge(
+      defaults.permissions as Record<string, unknown> | undefined,
+      agent.permissions as Record<string, unknown> | undefined
+    ) as AgentConfig["permissions"];
+  }
+
+  // Merge work_source (deep merge)
+  if (defaults.work_source || agent.work_source) {
+    result.work_source = deepMerge(
+      defaults.work_source as Record<string, unknown> | undefined,
+      agent.work_source as Record<string, unknown> | undefined
+    ) as AgentConfig["work_source"];
+  }
+
+  // Merge session (deep merge)
+  if (defaults.session || agent.session) {
+    result.session = deepMerge(
+      defaults.session as Record<string, unknown> | undefined,
+      agent.session as Record<string, unknown> | undefined
+    ) as AgentConfig["session"];
+  }
+
+  // Merge docker (deep merge)
+  if (defaults.docker || agent.docker) {
+    result.docker = deepMerge(
+      defaults.docker as Record<string, unknown> | undefined,
+      agent.docker as Record<string, unknown> | undefined
+    ) as AgentConfig["docker"];
+  }
+
+  // Merge instances (deep merge)
+  if (defaults.instances || agent.instances) {
+    result.instances = deepMerge(
+      defaults.instances as Record<string, unknown> | undefined,
+      agent.instances as Record<string, unknown> | undefined
+    ) as AgentConfig["instances"];
+  }
+
+  // Merge scalar values (agent takes precedence if defined)
+  if (defaults.model !== undefined && result.model === undefined) {
+    result.model = defaults.model;
+  }
+
+  if (defaults.max_turns !== undefined && result.max_turns === undefined) {
+    result.max_turns = defaults.max_turns;
+  }
+
+  if (
+    defaults.permission_mode !== undefined &&
+    result.permission_mode === undefined
+  ) {
+    result.permission_mode = defaults.permission_mode;
+  }
+
+  return result;
+}
+
+/**
+ * Merge fleet defaults into multiple agent configurations.
+ *
+ * @param defaults - The fleet-level defaults
+ * @param agents - Array of agent configurations
+ * @returns Array of merged agent configurations
+ */
+export function mergeAllAgentConfigs(
+  defaults: ExtendedDefaults | undefined,
+  agents: AgentConfig[]
+): AgentConfig[] {
+  return agents.map((agent) => mergeAgentConfig(defaults, agent));
+}