syncable_cli/agent/tools/
mod.rs

1//! Agent tools using Rig's Tool trait
2//!
3//! These tools wrap existing CLI functionality for the agent to use.
4//!
5//! ## Available Tools
6//!
7//! ### File Operations
8//! - `ReadFileTool` - Read file contents
9//! - `WriteFileTool` - Write single files (Dockerfiles, Terraform, etc.)
10//! - `WriteFilesTool` - Write multiple files (Terraform modules, Helm charts)
11//! - `ListDirectoryTool` - List directory contents
12//!
13//! ### Analysis
14//! - `AnalyzeTool` - Analyze project architecture, dependencies, build commands
15//!
16//! ### Security
17//! - `SecurityScanTool` - Security vulnerability scanning
18//! - `VulnerabilitiesTool` - Dependency vulnerability checking
19//!
20//! ### Linting
21//! - `HadolintTool` - Native Dockerfile linting (best practices, security)
22//! - `DclintTool` - Native Docker Compose linting (best practices, style, security)
23//! - `HelmlintTool` - Native Helm chart structure/template linting
24//! - `KubelintTool` - Native Kubernetes manifest security/best practice linting
25//!
26//! ### Resource Optimization
27//! - `K8sOptimizeTool` - Kubernetes resource right-sizing and cost optimization
28//! - `K8sCostsTool` - Kubernetes workload cost attribution and analysis
29//! - `K8sDriftTool` - Detect configuration drift between manifests and cluster
30//!
31//! ### Prometheus Integration (for live K8s analysis)
32//! - `PrometheusDiscoverTool` - Discover Prometheus services in Kubernetes cluster
33//! - `PrometheusConnectTool` - Establish connection to Prometheus (port-forward or URL)
34//! - `BackgroundProcessManager` - Manage long-running background processes
35//!
36//! ### Helm vs Kubernetes Linting
37//! - **HelmlintTool**: Use for Helm chart development - validates Chart.yaml, values.yaml,
38//!   Go template syntax, and Helm-specific best practices. Works on chart directories.
39//! - **KubelintTool**: Use for K8s security - checks rendered manifests for privileged containers,
40//!   missing probes, RBAC issues, resource limits. Works on YAML files, Helm charts (renders them),
41//!   and Kustomize directories.
42//!
43//! ### Diagnostics
44//! - `DiagnosticsTool` - Check for code errors via IDE/LSP or language-specific commands
45//!
46//! ### Terraform
47//! - `TerraformFmtTool` - Format Terraform configuration files
48//! - `TerraformValidateTool` - Validate Terraform configurations
49//! - `TerraformInstallTool` - Install Terraform CLI (auto-detects OS)
50//!
51//! ### Shell
52//! - `ShellTool` - Execute validation commands (docker build, terraform validate, helm lint)
53//!
54//! ### Planning (Forge-style workflow)
55//! - `PlanCreateTool` - Create structured plan files with task checkboxes
56//! - `PlanNextTool` - Get next pending task and mark it in-progress
57//! - `PlanUpdateTool` - Update task status (done, failed)
58//! - `PlanListTool` - List all available plan files
59//!
60//! ### Web
61//! - `WebFetchTool` - Fetch content from URLs (converts HTML to markdown)
62//!
63//! ## Error Handling Pattern
64//!
65//! Tools use the shared error utilities in `error.rs`:
66//!
67//! 1. Each tool keeps its own error type (e.g., `ReadFileError`, `ShellError`)
68//! 2. Use `ToolErrorContext` trait to add context when propagating errors
69//! 3. Use `format_error_for_llm` for structured JSON error responses to the agent
70//! 4. Error categories help the agent understand and recover from errors
71//!
72//! See `error.rs` for the complete error handling infrastructure.
73//!
74//! ## Response Format Pattern
75//!
76//! Tools use the shared response utilities in `response.rs` for consistent output:
77//!
78//! 1. Use `format_file_content` for file read operations (with truncation metadata)
79//! 2. Use `format_list` for directory listings and search results
80//! 3. Use `format_write_success` for successful write operations
81//! 4. Use `format_cancelled` for user-cancelled operations
82//! 5. Use `ResponseMetadata` to track truncation, compression, and item counts
83//!
84//! For large outputs (analysis, lint results), use `compress_tool_output` or
85//! `compress_analysis_output` from `compression.rs` which store full data
86//! and return a compressed summary with retrieval reference.
87//!
88//! ### Example
89//!
90//! ```ignore
91//! use crate::agent::tools::response::{format_file_content, format_list};
92//!
93//! // File read response
94//! Ok(format_file_content(&path, &content, total_lines, returned_lines, truncated))
95//!
96//! // Directory listing response
97//! Ok(format_list(&path, &entries, total_count, was_truncated))
98//! ```
99//!
100//! See `response.rs` for the complete response formatting infrastructure.
101
102mod analyze;
103pub mod background;
104pub mod compression;
105mod dclint;
106mod diagnostics;
107pub mod error;
108mod fetch;
109mod file_ops;
110mod hadolint;
111mod helmlint;
112mod k8s_costs;
113mod k8s_drift;
114mod k8s_optimize;
115mod kubelint;
116pub mod output_store;
117mod plan;
118mod prometheus_connect;
119mod prometheus_discover;
120pub mod response;
121mod retrieve;
122mod security;
123mod shell;
124mod terraform;
125mod truncation;
126
127pub use truncation::{TruncationLimits, truncate_json_output};
128
129// Smart compression exports
130pub use compression::{CompressionConfig, compress_analysis_output, compress_tool_output};
131pub use retrieve::{ListOutputsTool, RetrieveOutputTool};
132
133// Error handling utilities for tools
134pub use error::{
135    ErrorCategory, ToolErrorContext, detect_error_category, format_error_for_llm,
136    format_error_with_context,
137};
138
139// Response formatting utilities for tools
140pub use response::{
141    ResponseMetadata, ToolResponse, format_cancelled, format_file_content,
142    format_file_content_range, format_list, format_list_with_metadata, format_success,
143    format_success_with_metadata, format_write_success,
144};
145
146pub use analyze::AnalyzeTool;
147pub use background::BackgroundProcessManager;
148pub use dclint::DclintTool;
149pub use diagnostics::DiagnosticsTool;
150pub use fetch::WebFetchTool;
151pub use file_ops::{ListDirectoryTool, ReadFileTool, WriteFileTool, WriteFilesTool};
152pub use hadolint::HadolintTool;
153pub use helmlint::HelmlintTool;
154pub use k8s_costs::K8sCostsTool;
155pub use k8s_drift::K8sDriftTool;
156pub use k8s_optimize::K8sOptimizeTool;
157pub use kubelint::KubelintTool;
158pub use plan::{PlanCreateTool, PlanListTool, PlanNextTool, PlanUpdateTool};
159pub use prometheus_connect::PrometheusConnectTool;
160pub use prometheus_discover::PrometheusDiscoverTool;
161pub use security::{SecurityScanTool, VulnerabilitiesTool};
162pub use shell::ShellTool;
163pub use terraform::{TerraformFmtTool, TerraformInstallTool, TerraformValidateTool};
syncable_cli/agent/tools/mod.rs

syncable_cli/agent/tools/
mod.rs
