Files
yxxhero 9b943adc9e feat: add helmfile doctor command for AI-assisted diff analysis (#2660)
* feat: add `helmfile doctor` command for AI-assisted diff analysis

`helmfile doctor` runs `helmfile diff` and asks an OpenAI-compatible LLM to
summarize the changes and flag risks (data loss, security exposure, breaking
changes, downtime, performance, best-practice issues).

Key design decisions:
- When no LLM is configured, doctor is equivalent to `helmfile diff` with
  one exception: --show-secrets is always forced off (secrets never reach
  stdout, even without an LLM).
- Secrets are ALWAYS redacted via two layers: (1) ShowSecrets() forced to
  false so helm-diff emits <REDACTED> placeholders; (2) a defense-in-depth
  text redactor strips residual secret-looking content (Secret YAML blocks,
  sensitive key/value lines, base64 blobs, JWT tokens) before LLM transmission.
- LLM configuration precedence: env (HELMFILE_LLM_*) < helmfile.yaml (llm:)
  < CLI flags (--llm-*).
- Supports any OpenAI-compatible backend (OpenAI, Azure, One-API, LiteLLM,
  Ollama, etc.) with automatic response_format fallback for backends that
  don't support JSON mode.
- Prompt injection defense: release names and environment values are
  JSON-encoded before insertion into the LLM prompt.
- Exit codes: 0 (success/low-risk), 2 (high-risk gate, bypass with --force),
  1 (other errors). Helm-diff's 'detected changes' exit-2 is swallowed.

New packages:
- pkg/agent/llm: OpenAI-compatible client with JSON response parsing, mock
  client for testing, prompt builder with injection defense.
- pkg/agent/doctor: secret redactor (state machine + regex), report renderer
  (markdown + JSON), config resolver (env < yaml < flag merge).

Testing: 70+ unit tests covering redaction patterns, prompt injection,
response_format fallback, JSON parsing, yaml roundtrip, concurrency safety,
panic recovery, and error propagation. go test -race passes.

Documentation: full doctor section in docs/cli.md, llm: block reference in
docs/configuration.md, updated skills/helmfile for AI agents.

Signed-off-by: yxxhero <aiopsclub@163.com>

* docs: fix doctor equivalence wording per PR review

Per review feedback (PR #2660): the docs claimed doctor is 'equivalent to
helmfile diff — same flags, same output, same exit codes' in the unconfigured
path, but this over-promises because:

  1. doctor --output is the report format (not helm-diff's output format)
  2. helm-diff's --output is exposed as --diff-output in doctor
  3. --show-secrets is silently ignored

Updated all three locations (cli.md, cmd/doctor.go Long + godoc, pkg/app/doctor.go
godoc) to say 'falls back to helmfile diff with --show-secrets forced off' and
explicitly note the --output / --diff-output flag difference.

Signed-off-by: yxxhero <aiopsclub@163.com>

---------

Signed-off-by: yxxhero <aiopsclub@163.com>
2026-06-22 16:52:35 +08:00

64 lines
1.7 KiB
Go

package llm
import (
goContext "context"
"sync"
)
// MockClient is a test-only Client returning a canned Analysis or error.
//
// Concurrent-safe: Analyze calls are mutex-serialized so LastCall() recordings
// stay consistent under `go test -parallel`. For per-call isolation, create a
// fresh MockClient per case rather than relying on the mutex.
type MockClient struct {
mu sync.Mutex
Analysis Analysis
Err error
lastDiff string
lastInput AnalyzeInput
}
// NewMockClient returns a MockClient that responds with the given Analysis.
func NewMockClient(a Analysis) *MockClient {
return &MockClient{Analysis: a}
}
// Analyze implements Client. The returned Analysis is a deep copy so test
// mutations on the returned value do not corrupt canned state for the next
// caller.
func (m *MockClient) Analyze(_ goContext.Context, diff string, in AnalyzeInput) (Analysis, error) {
m.mu.Lock()
defer m.mu.Unlock()
m.lastDiff = diff
m.lastInput = in
if m.Err != nil {
return Analysis{}, m.Err
}
return cloneAnalysis(m.Analysis), nil
}
// LastCall returns the most recent (diff, input) handed to Analyze. Safe to
// call from a different goroutine than Analyze.
func (m *MockClient) LastCall() (string, AnalyzeInput) {
m.mu.Lock()
defer m.mu.Unlock()
return m.lastDiff, m.lastInput
}
// cloneAnalysis returns a deep-enough copy of a for MockClient use: a test
// that does `out, _ := c.Analyze(...); out.Risks[0].Level = "high"` must not
// change what the NEXT Analyze() returns.
func cloneAnalysis(a Analysis) Analysis {
out := a
if a.Risks != nil {
out.Risks = append([]Risk(nil), a.Risks...)
}
if a.AffectedResources != nil {
out.AffectedResources = append([]string(nil), a.AffectedResources...)
}
return out
}