@herdctl/core 0.0.1

package/dist/config/loader.js

@@ -0,0 +1,336 @@
+/**
+ * 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, } from "./schema.js";
+import { ConfigError, FileReadError, SchemaValidationError } from "./parser.js";
+import { mergeAgentConfig } from "./merge.js";
+import { interpolateConfig } from "./interpolate.js";
+// =============================================================================
+// Constants
+// =============================================================================
+/**
+ * Default config file names to search for
+ */
+export const CONFIG_FILE_NAMES = ["herdctl.yaml", "herdctl.yml"];
+// =============================================================================
+// Error Classes
+// =============================================================================
+/**
+ * Error thrown when no configuration file is found
+ */
+export class ConfigNotFoundError extends ConfigError {
+    searchedPaths;
+    startDirectory;
+    constructor(startDirectory, searchedPaths) {
+        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 {
+    agentPath;
+    agentName;
+    constructor(agentPath, cause, agentName) {
+        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;
+    }
+}
+// =============================================================================
+// File Discovery
+// =============================================================================
+/**
+ * Check if a file exists and is accessible
+ */
+async function fileExists(filePath) {
+    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) {
+    const searchedPaths = [];
+    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, filePath) {
+    let rawConfig;
+    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, filePath) {
+    let rawConfig;
+    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, fleetConfigDir) {
+    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, options = {}) {
+    const { env = process.env, interpolate = true, mergeDefaults = true, } = options;
+    // Determine the config file path
+    let resolvedConfigPath;
+    let searchedPaths = [];
+    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;
+    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 = [];
+    // 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;
+        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;
+        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, 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, options = {}) {
+    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)),
+        };
+    }
+}
+//# sourceMappingURL=loader.js.map

package/dist/config/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"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"}

package/dist/config/merge.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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, WorkSource, Session, Docker, PermissionMode, BashPermissions } from "./schema.js";
+/**
+ * Permissions input type - all fields optional before Zod applies defaults
+ */
+export interface PermissionsInput {
+    mode?: PermissionMode;
+    allowed_tools?: string[];
+    denied_tools?: string[];
+    bash?: BashPermissions;
+}
+/**
+ * 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 declare function deepMerge<T extends Record<string, unknown>>(base: T | undefined, override: T | undefined): T | undefined;
+/**
+ * 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;
+}
+/**
+ * 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 declare function mergeAgentConfig(defaults: ExtendedDefaults | undefined, agent: AgentConfig): AgentConfig;
+/**
+ * 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 declare function mergeAllAgentConfigs(defaults: ExtendedDefaults | undefined, agents: AgentConfig[]): AgentConfig[];
+//# sourceMappingURL=merge.d.ts.map

package/dist/config/merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../src/config/merge.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,WAAW,EAEX,UAAU,EACV,OAAO,EACP,MAAM,EACN,cAAc,EACd,eAAe,EAChB,MAAM,aAAa,CAAC;AAMrB;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,IAAI,CAAC,EAAE,eAAe,CAAC;CACxB;AAsBD;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzD,IAAI,EAAE,CAAC,GAAG,SAAS,EACnB,QAAQ,EAAE,CAAC,GAAG,SAAS,GACtB,CAAC,GAAG,SAAS,CAyCf;AAMD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,cAAc,CAAC;CAClC;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,SAAS,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,cAAc,CAAC;CAClC;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,gBAAgB,GAAG,SAAS,EACtC,KAAK,EAAE,WAAW,GACjB,WAAW,CAkEb;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,gBAAgB,GAAG,SAAS,EACtC,MAAM,EAAE,WAAW,EAAE,GACpB,WAAW,EAAE,CAEf"}

package/dist/config/merge.js

@@ -0,0 +1,138 @@
+/**
+ * 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
+ */
+// =============================================================================
+// Type Guards
+// =============================================================================
+/**
+ * Check if a value is a plain object (not an array, null, or other type)
+ */
+function isPlainObject(value) {
+    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(base, override) {
+    // 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 };
+    // 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;
+}
+// =============================================================================
+// 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, agent) {
+    // If no defaults, return agent as-is
+    if (!defaults) {
+        return agent;
+    }
+    // Start with the agent config
+    const result = { ...agent };
+    // Merge permissions (deep merge)
+    if (defaults.permissions || agent.permissions) {
+        result.permissions = deepMerge(defaults.permissions, agent.permissions);
+    }
+    // Merge work_source (deep merge)
+    if (defaults.work_source || agent.work_source) {
+        result.work_source = deepMerge(defaults.work_source, agent.work_source);
+    }
+    // Merge session (deep merge)
+    if (defaults.session || agent.session) {
+        result.session = deepMerge(defaults.session, agent.session);
+    }
+    // Merge docker (deep merge)
+    if (defaults.docker || agent.docker) {
+        result.docker = deepMerge(defaults.docker, agent.docker);
+    }
+    // Merge instances (deep merge)
+    if (defaults.instances || agent.instances) {
+        result.instances = deepMerge(defaults.instances, agent.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, agents) {
+    return agents.map((agent) => mergeAgentConfig(defaults, agent));
+}
+//# sourceMappingURL=merge.js.map

package/dist/config/merge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.js","sourceRoot":"","sources":["../../src/config/merge.ts"],"names":[],"mappings":"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"}