Output Formatting

Relevant source files

The following files were used as context for generating this wiki page:

• src/cli/mod.rs
• src/main.rs
• specs/002-implement-tdd-green/plan.md
• kitty-specs/002-unquoted-cli-arguments/tasks.md
• specs/006-intelligent-prompt-generation/spec.md
• website/BLOG_STRUCTURE_GUIDE.md

The caro command-line tool provides a flexible output formatting system that allows users to receive the results of command generation in various formats. This system is designed to support both human-readable output for interactive use and machine-parseable formats like JSON and YAML for integration into scripts and automated workflows. The output format is controlled via a command-line argument.

The core of the system is the GeneratedCommand struct, which holds all the data about the generated command. This data is then passed to a specific formatter based on the user's selection. The system is designed to be extensible, with a clear separation of concerns between the CLI interface, the data models, and the output format handlers.

Sources: specs/002-implement-tdd-green/plan.md:120-121, 34-36, specs/002-implement-tdd-green/spec.md:65-68

Architecture and Data Flow

The output formatting process begins after a command has been successfully generated. The main.rs entry point orchestrates the flow, parsing CLI arguments, generating the command, and then passing the resulting GeneratedCommand object to the appropriate output handler.

The following diagram illustrates the data flow for output formatting:

This diagram shows the process from user input to final output, highlighting the selection of the JSON formatter.

The key components involved are:

• main.rs: The binary entry point that orchestrates the entire process.
• src/cli/mod.rs: Defines the CLI structure using clap, including the --format argument.
• src/cli/args.rs: Contains the Clap argument definitions, including the OutputFormat enum.
• src/cli/output.rs: Implements the format handlers for JSON, YAML, and plain text.
• src/models/generated_command.rs: Defines the GeneratedCommand struct that is serialized.

Sources: specs/002-implement-tdd-green/plan.md:117-121, 331-338, src/main.rs, src/cli/mod.rs

CLI Control

Output formatting is controlled by the --format command-line argument. The implementation is planned to be in src/cli/args.rs using clap derive macros.

The planned CLI options are:

Option	Description	OutputFormat Variant
json	Outputs the GeneratedCommand struct as a JSON object.	Json
yaml	Outputs the GeneratedCommand struct as a YAML document.	Yaml
text	Outputs a human-readable, color-coded summary.	Text

This functionality is part of the CliApp interface, which is validated by contract tests.

Sources: specs/002-implement-tdd-green/plan.md:120-121, 335-338, specs/002-implement-tdd-green/spec.md:65-68

OutputFormat Enum

The selection of an output format is managed by the OutputFormat enum, which is defined as part of the clap argument structures.

This diagram shows the variants of the OutputFormat enum.

This enum is used within the CliArgs struct to parse the user's choice and is then passed to the output handling logic.

Sources: specs/002-implement-tdd-green/plan.md:335

Format Handlers

The actual serialization logic is located in src/cli/output.rs. This module contains separate handlers for each format.

• JSON Formatter: Uses serde_json to serialize the GeneratedCommand struct into a JSON string.
• YAML Formatter: Uses serde_yaml to serialize the GeneratedCommand struct into a YAML string.
• Text Formatter: Creates a custom, human-readable string, likely using the colored crate for color-coded output to enhance readability.

Sources: specs/002-implement-tdd-green/plan.md:335-338

Output Data Structure

The data source for all output formats is the GeneratedCommand struct. This ensures consistency across all formats. The fields of this struct are what get serialized into JSON, YAML, or plain text.

The GeneratedCommand struct contains the following fields:

Field	Type	Description
command	String	The generated shell command.
explanation	String	A natural language explanation of the command.
safety_level	RiskLevel	The assessed safety risk of the command (e.g., Safe, Critical).
estimated_impact	String	A description of what the command is expected to do.
alternatives	Vec<String>	A list of alternative commands.
backend_used	String	The name of the LLM backend that generated the command.
generation_time_ms	u64	The time taken for generation in milliseconds.
confidence_score	f64	A score from 0.0 to 1.0 indicating the model's confidence.

Sources: specs/002-implement-tdd-green/plan.md:214-222

Example JSON Output

While not explicitly in the source, a JSON output for a GeneratedCommand would look something like this, based on the struct definition:

{
  "command": "ls -lhS",
  "explanation": "Generated using BSD backend",
  "safety_level": "Safe",
  "estimated_impact": "Lists files in the current directory, sorted by size in human-readable format.",
  "alternatives": [
    "ls -lS",
    "find . -maxdepth 1 -ls | sort -k 7 -n"
  ],
  "backend_used": "MockBackend",
  "generation_time_ms": 150,
  "confidence_score": 0.95
}

Sources: specs/002-implement-tdd-green/plan.md:214-222, specs/006-intelligent-prompt-generation/spec.md:65-69

Non-Interactive Mode

When the prompt is provided via the -p/--prompt flag or piped via stdin, caro is designed to enter a non-interactive mode. In this mode, user confirmation prompts are skipped. This is particularly relevant for output formatting, as it ensures that automated scripts using JSON or YAML output are not blocked by an interactive prompt.

Sources: kitty-specs/002-unquoted-cli-arguments/tasks.md:100-101

Summary

The output formatting system in caro is a key feature for usability and automation. By leveraging clap for argument parsing and serde for serialization, it provides a robust and extensible way to present generated commands. The support for JSON, YAML, and human-readable text makes the tool suitable for a wide range of use cases, from interactive terminal sessions to complex CI/CD pipelines.

Sources: specs/002-implement-tdd-green/plan.md:331-338