Add config file generation and validation subcommand

[unclesp1d3r]

Summary

Add a `hash-hive-agent config` subcommand that generates a template config file and validates existing ones.

Requirements

• `hash-hive-agent config init` — generate a commented template config file
• `hash-hive-agent config validate --config path` — validate a config file and report issues
• `hash-hive-agent config show` — display the resolved configuration (merged from all sources)
• Template should include all fields with their defaults and descriptions
• Support both YAML and TOML formats

Acceptance Criteria

• `config init` generates a valid template
• `config validate` catches invalid values
• `config show` displays merged configuration
• Generated template is well-commented

Dependencies

None

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

Plan

Observations

• The CLI uses clap 4 with derive macros (src/cli.rs). Currently Cli is a flat struct with no subcommands — the binary always runs the agent.
• Config is loaded via the config crate (AgentConfig::load in src/config/mod.rs), merging defaults → file → env vars. All fields and their defaults are documented in src/config/defaults.rs.
• serde_json is already a dependency; YAML and TOML serialization crates are not yet present — serde_yaml (or serde-yaml) and toml must be added.
• main.rs calls AgentConfig::load unconditionally before dispatching, so the subcommand dispatch must happen before that call.

Approach

Introduce a Commands enum on Cli with a Config variant, add a src/cli/config_cmd.rs module (or src/config/cmd.rs) that implements the three sub-subcommands, and wire dispatch in main.rs before the existing agent startup path. YAML support will be added via the serde_yaml crate and TOML via the toml crate.

---

Implementation Steps

1. Add serialization dependencies to Cargo.toml

Add two new entries under [dependencies]:

• serde_yaml = "0.9" — for YAML template/show output
• toml = { version = "0.8", features = ["display"] } — for TOML template/show output

serde with derive is already present, so AgentConfig can be made Serialize without extra work.

---

2. Make AgentConfig serializable

In file:src/config/mod.rs, add Serialize to the derive list on AgentConfig:

#[derive(Debug, Clone, Deserialize, Serialize)]

The humantime_serde inner module currently only implements deserialize; add a matching serialize function that formats a Duration back to a human-readable string (e.g. "30s", "10m"). This is needed for config show to round-trip correctly.

---

3. Add a ConfigFormat enum and ConfigSubcommand enum in src/cli.rs

Extend file:src/cli.rs:

• Add a ConfigFormat enum with variants Yaml and Toml, implementing clap::ValueEnum.
• Add a ConfigSubcommand enum with three variants:
  • Init { output: Option<PathBuf>, format: ConfigFormat } — writes a template config file (defaults to stdout if no output path given).
  • Validate { config: PathBuf } — validates the given file and reports issues.
  • Show { format: ConfigFormat } — displays the fully resolved config.
• Add a ConfigArgs struct (or inline) with #[command(subcommand)] subcommand: ConfigSubcommand.
• Add a top-level Commands enum to Cli:

  #[derive(Debug, Subcommand)]
  pub enum Commands {
      Config(ConfigArgs),
  }
  

• Add #[command(subcommand)] pub command: Option<Commands> to Cli. Making it Option keeps the existing default behaviour (no subcommand → run agent).

---

4. Create src/cli/config_cmd.rs (or src/config/cmd.rs)

Prefer src/cli/config_cmd.rs to keep CLI logic co-located with cli.rs. Convert src/cli.rs into a module directory (src/cli/mod.rs + src/cli/config_cmd.rs) following the existing self_named_module_files convention enforced by clippy.

Implement a public run_config_subcommand(args: &ConfigArgs, cli: &Cli) -> Result<()> function that matches on args.subcommand:

Init

• Build a AgentConfig with all defaults (call AgentConfig::load(None) with an empty token, or construct directly from defaults::* constants).
• Serialize to the requested format.
• Prepend per-field comments by building the output as a string with comment blocks above each key (since neither serde_yaml nor toml support inline comments natively, generate the template as a hand-crafted string using the constants from defaults.rs and the doc-comments already present on each field).
• Write to the output path or stdout.

Validate

• Call AgentConfig::load(Some(path)) (env vars intentionally excluded for pure file validation — use a fresh config::Config::builder() that only reads the file, no env source).
• On success, print a summary of the resolved values.
• On error, surface the anyhow error chain with field-level context.
• Additionally perform semantic checks (e.g. agent_token must not be empty, server_url must parse as a valid URL using the already-present url crate, durations must be positive).

Show

• Call AgentConfig::load(cli.config.as_deref().and_then(|p| p.to_str())) — the full merge (file + env + defaults), same as the agent path.
• Serialize the resolved AgentConfig to the requested format and print to stdout.
• Redact agent_token (replace with "***") before printing.

---

5. Update main.rs to dispatch subcommands

In file:src/main.rs, after Cli::parse() and init_logging(...), add a match before AgentConfig::load:

if let Some(Commands::Config(args)) = &cli.command {
    return cli::config_cmd::run_config_subcommand(args, &cli);
}

This ensures the config subcommand exits before any agent startup logic (including the mandatory agent_token check).

---

6. Update src/lib.rs

If cli becomes a module directory, no change is needed to lib.rs since pub mod cli already re-exports it. Ensure config_cmd is pub(crate) or pub as needed.

---

Data flow diagram

sequenceDiagram
    participant User
    participant main
    participant Cli
    participant config_cmd
    participant AgentConfig

    User->>main: hash-hive-agent config <sub> [flags]
    main->>Cli: parse()
    main->>main: init_logging()
    main->>Cli: match cli.command
    Cli-->>main: Some(Commands::Config(args))
    main->>config_cmd: run_config_subcommand(args, cli)
    alt init
        config_cmd->>AgentConfig: construct from defaults
        config_cmd-->>User: write commented template (YAML/TOML)
    else validate
        config_cmd->>AgentConfig: load(file only)
        config_cmd->>config_cmd: semantic checks
        config_cmd-->>User: OK or error report
    else show
        config_cmd->>AgentConfig: load(file + env)
        config_cmd->>config_cmd: redact token
        config_cmd-->>User: serialized config (YAML/TOML)
    end

Loading

---

Summary of files to change / create

File	Change
Cargo.toml	Add serde_yaml and toml dependencies
src/cli.rs → src/cli/mod.rs	Add ConfigFormat, ConfigSubcommand, ConfigArgs, Commands, update Cli
src/cli/config_cmd.rs (new)	Implement run_config_subcommand with init, validate, show logic
src/config/mod.rs	Add Serialize derive; add serialize to humantime_serde inner module
src/main.rs	Dispatch Commands::Config before agent startup

Import In IDE

🤖 Prompt for AI Agents

## Observations

- The CLI uses **clap 4 with derive macros** (`src/cli.rs`). Currently `Cli` is a flat struct with no subcommands — the binary always runs the agent.
- Config is loaded via the **`config` crate** (`AgentConfig::load` in `src/config/mod.rs`), merging defaults → file → env vars. All fields and their defaults are documented in `src/config/defaults.rs`.
- `serde_json` is already a dependency; **YAML and TOML** serialization crates are not yet present — `serde_yaml` (or `serde-yaml`) and `toml` must be added.
- `main.rs` calls `AgentConfig::load` unconditionally before dispatching, so the subcommand dispatch must happen before that call.

## Approach

Introduce a `Commands` enum on `Cli` with a `Config` variant, add a `src/cli/config_cmd.rs` module (or `src/config/cmd.rs`) that implements the three sub-subcommands, and wire dispatch in `main.rs` before the existing agent startup path. YAML support will be added via the `serde_yaml` crate and TOML via the `toml` crate.

---

## Implementation Steps

### 1. Add serialization dependencies to `Cargo.toml`

Add two new entries under `[dependencies]`:
- `serde_yaml = "0.9"` — for YAML template/show output
- `toml = { version = "0.8", features = ["display"] }` — for TOML template/show output

`serde` with `derive` is already present, so `AgentConfig` can be made `Serialize` without extra work.

---

### 2. Make `AgentConfig` serializable

In `file:src/config/mod.rs`, add `Serialize` to the derive list on `AgentConfig`:

```
#[derive(Debug, Clone, Deserialize, Serialize)]
```

The `humantime_serde` inner module currently only implements `deserialize`; add a matching `serialize` function that formats a `Duration` back to a human-readable string (e.g. `"30s"`, `"10m"`). This is needed for `config show` to round-trip correctly.

---

### 3. Add a `ConfigFormat` enum and `ConfigSubcommand` enum in `src/cli.rs`

Extend `file:src/cli.rs`:

- Add a `ConfigFormat` enum with variants `Yaml` and `Toml`, implementing `clap::ValueEnum`.
- Add a `ConfigSubcommand` enum with three variants:
  - `Init { output: Option<PathBuf>, format: ConfigFormat }` — writes a template config file (defaults to stdout if no output path given).
  - `Validate { config: PathBuf }` — validates the given file and reports issues.
  - `Show { format: ConfigFormat }` — displays the fully resolved config.
- Add a `ConfigArgs` struct (or inline) with `#[command(subcommand)] subcommand: ConfigSubcommand`.
- Add a top-level `Commands` enum to `Cli`:
  ```
  #[derive(Debug, Subcommand)]
  pub enum Commands {
      Config(ConfigArgs),
  }
  ```
- Add `#[command(subcommand)] pub command: Option<Commands>` to `Cli`. Making it `Option` keeps the existing default behaviour (no subcommand → run agent).

---

### 4. Create `src/cli/config_cmd.rs` (or `src/config/cmd.rs`)

> Prefer `src/cli/config_cmd.rs` to keep CLI logic co-located with `cli.rs`. Convert `src/cli.rs` into a module directory (`src/cli/mod.rs` + `src/cli/config_cmd.rs`) following the existing `self_named_module_files` convention enforced by clippy.

Implement a public `run_config_subcommand(args: &ConfigArgs, cli: &Cli) -> Result<()>` function that matches on `args.subcommand`:

#### `Init`
- Build a `AgentConfig` with all defaults (call `AgentConfig::load(None)` with an empty token, or construct directly from `defaults::*` constants).
- Serialize to the requested format.
- Prepend per-field comments by building the output as a string with comment blocks above each key (since neither `serde_yaml` nor `toml` support inline comments natively, generate the template as a hand-crafted string using the constants from `defaults.rs` and the doc-comments already present on each field).
- Write to the output path or stdout.

#### `Validate`
- Call `AgentConfig::load(Some(path))` (env vars intentionally excluded for pure file validation — use a fresh `config::Config::builder()` that only reads the file, no env source).
- On success, print a summary of the resolved values.
- On error, surface the `anyhow` error chain with field-level context.
- Additionally perform semantic checks (e.g. `agent_token` must not be empty, `server_url` must parse as a valid URL using the already-present `url` crate, durations must be positive).

#### `Show`
- Call `AgentConfig::load(cli.config.as_deref().and_then(|p| p.to_str()))` — the full merge (file + env + defaults), same as the agent path.
- Serialize the resolved `AgentConfig` to the requested format and print to stdout.
- Redact `agent_token` (replace with `"***"`) before printing.

---

### 5. Update `main.rs` to dispatch subcommands

In `file:src/main.rs`, after `Cli::parse()` and `init_logging(...)`, add a match before `AgentConfig::load`:

```
if let Some(Commands::Config(args)) = &cli.command {
    return cli::config_cmd::run_config_subcommand(args, &cli);
}
```

This ensures the config subcommand exits before any agent startup logic (including the mandatory `agent_token` check).

---

### 6. Update `src/lib.rs`

If `cli` becomes a module directory, no change is needed to `lib.rs` since `pub mod cli` already re-exports it. Ensure `config_cmd` is `pub(crate)` or `pub` as needed.

---

## Data flow diagram

```mermaid
sequenceDiagram
    participant User
    participant main
    participant Cli
    participant config_cmd
    participant AgentConfig

    User->>main: hash-hive-agent config <sub> [flags]
    main->>Cli: parse()
    main->>main: init_logging()
    main->>Cli: match cli.command
    Cli-->>main: Some(Commands::Config(args))
    main->>config_cmd: run_config_subcommand(args, cli)
    alt init
        config_cmd->>AgentConfig: construct from defaults
        config_cmd-->>User: write commented template (YAML/TOML)
    else validate
        config_cmd->>AgentConfig: load(file only)
        config_cmd->>config_cmd: semantic checks
        config_cmd-->>User: OK or error report
    else show
        config_cmd->>AgentConfig: load(file + env)
        config_cmd->>config_cmd: redact token
        config_cmd-->>User: serialized config (YAML/TOML)
    end
```

---

## Summary of files to change / create

| File | Change |
|---|---|
| `Cargo.toml` | Add `serde_yaml` and `toml` dependencies |
| `src/cli.rs` → `src/cli/mod.rs` | Add `ConfigFormat`, `ConfigSubcommand`, `ConfigArgs`, `Commands`, update `Cli` |
| `src/cli/config_cmd.rs` _(new)_ | Implement `run_config_subcommand` with `init`, `validate`, `show` logic |
| `src/config/mod.rs` | Add `Serialize` derive; add `serialize` to `humantime_serde` inner module |
| `src/main.rs` | Dispatch `Commands::Config` before agent startup |

---

Execution Information

Branch: main
Commit: 04d0eea

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.