Module config 

Configuration resolution for Ralph, including global and project layers.

Responsibilities:

• Resolve configuration from multiple layers: global config, project config, and defaults.
• Load and parse config files (JSON with JSONC comment support via load_layer).
• Merge configuration layers via ConfigLayer and apply_layer.
• Validate configuration values (version, paths, numeric ranges, runner binaries).
• Resolve queue/done file paths and ID generation settings (prefix, width).
• Discover repository root via .ralph/ directory or .git/.

Not handled here:

• CLI argument parsing (see crate::cli).
• Queue operations like task CRUD (see crate::queue).
• Runner execution or agent invocation (see crate::runner).
• Prompt rendering or template processing (see crate::prompts_internal).
• Lock management (see crate::lock).

Invariants/assumptions:

• Config version must be 1; unsupported versions are rejected.
• Paths are resolved relative to repo root unless absolute.
• Global config resolves from ~/.config/ralph/config.jsonc with .json fallback.
• Project config resolves from .ralph/config.jsonc with .json fallback.
• Config layers are applied in this order: defaults, then global, then project (later layers override earlier ones).
• save_layer creates parent directories automatically if needed.

Structs

ConfigLayer

Resolved

Resolved configuration including computed paths.

Functions

apply_layer

Apply a config layer on top of a base config. Later layers override earlier ones using leaf-wise merge semantics.

find_repo_root

Find the repository root starting from a given path.

git_ref_invalid_reason

Check if a string is a valid git branch name. Returns None if valid, or Some(reason) if invalid. Based on git’s check-ref-format rules:

global_config_path

Get the path to the global config file.

load_layer

Load a config layer from a JSON/JSONC file.

prefer_jsonc_then_json

Resolve a JSON path with .json fallback.

project_config_path

Get the path to the project config file for a given repo root.

resolve_done_path

Resolve the done file path from config.

resolve_from_cwd

Resolve configuration from the current working directory.

resolve_from_cwd_for_doctor

Resolve config for the doctor command, skipping instruction_files validation. This allows doctor to diagnose and warn about missing files without failing early.

resolve_from_cwd_with_profile

Resolve config with an optional profile selection.

resolve_id_prefix

Resolve the queue ID prefix from config.

resolve_id_width

Resolve the queue ID width from config.

resolve_queue_path

Resolve the queue file path from config.

save_layer

Save a config layer to a JSON file. Automatically sets version to 1 if not specified and creates parent directories.

validate_agent_binary_paths

Validate that all configured binary paths are non-empty strings.

validate_agent_patch

Validate an AgentConfig patch (used for base agent and profile agents).

validate_config

Validate the full configuration.

validate_queue_done_file_override

Validate queue.done_file override (if specified, must be non-empty).

validate_queue_file_override

Validate queue.file override (if specified, must be non-empty).

validate_queue_id_prefix_override

Validate queue.id_prefix override (if specified, must be non-empty after trim).

validate_queue_id_width_override

Validate queue.id_width override (if specified, must be greater than 0).

validate_queue_overrides

Validate all queue config overrides in a single call.