Documentation
¶
Overview ¶
Package doctor provides a diagnostic command that validates configuration, checks environment health, and reports runtime details.
Index ¶
- Variables
- func NewCmdDoctor(props *p.Props, options ...CmdOption) *setup.Command
- func NewCmdReport(props *p.Props) *cobra.Command
- func PrintBundle(w io.Writer, b *SupportBundle)
- func PrintReport(w io.Writer, report *DoctorReport)
- type CheckFunc
- type CheckResult
- type CheckStatus
- type CmdOption
- type DoctorReport
- type FailThreshold
- type FeatureFlag
- type PathsSection
- type RuntimeSection
- type SupportBundle
- type ToolSection
Constants ¶
This section is empty.
Variables ¶
var ErrDoctorFoundProblems = errorhandling.WithOutcome( errors.NewSentinel("gtb.doctor.problems", "health checks reported problems"), errorhandling.Outcome{Code: 1, Level: slog.LevelWarn}, )
ErrDoctorFoundProblems reports a health run that crossed its threshold.
The disposition travels with the error rather than being an os.Exit in the command: nothing in the error path exits the process, and pkg/cmd/root's Execute owns termination. Reported at WARN because the report itself has already been printed in full — a second, louder rendering of "something is wrong" adds nothing a reader does not already have on screen.
Functions ¶
func NewCmdDoctor ¶
NewCmdDoctor creates the doctor command.
func NewCmdReport ¶ added in v0.22.0
NewCmdReport returns the `doctor report` subcommand: it prints a single, secret-redacted, paste-ready support bundle. It is gated implicitly by being a child of the DoctorCmd-gated `doctor` command.
func PrintBundle ¶ added in v0.22.0
func PrintBundle(w io.Writer, b *SupportBundle)
PrintBundle renders the human-readable bundle: a header, then labelled sections, reusing PrintReport for the checks for visual consistency.
func PrintReport ¶
func PrintReport(w io.Writer, report *DoctorReport)
PrintReport writes a human-readable report to the given writer.
Types ¶
type CheckFunc ¶
CheckFunc is an alias for the registry's CheckFunc type.
func DefaultChecks ¶
DefaultChecks returns the standard set of diagnostic checks, tailored to the tool's enabled features. The always-on checks validate state every tool has (the Go runtime, configuration presence, credential hygiene, config-dir permissions). Feature-specific checks are only included when their feature is enabled, so a default-features tool does not, for example, warn "no AI provider API keys configured" when the AI feature is switched off.
Git availability is deliberately NOT a built-in check: it is only meaningful to a tool with a git-consuming feature, so such tools register their own via setup.RegisterChecks rather than every tool warning about a missing git.
type CheckResult ¶
type CheckResult = setup.CheckResult
CheckResult is an alias for the registry's CheckResult type.
type CheckStatus ¶
type CheckStatus = string
CheckStatus is the outcome of a diagnostic check.
const ( CheckPass CheckStatus = "pass" CheckWarn CheckStatus = "warn" CheckFail CheckStatus = "fail" CheckSkip CheckStatus = "skip" )
type CmdOption ¶ added in v0.38.0
type CmdOption func(*cmdSettings)
CmdOption configures NewCmdDoctor.
type DoctorReport ¶
type DoctorReport struct {
Tool string `json:"tool"`
Version string `json:"version"`
Checks []CheckResult `json:"checks"`
}
DoctorReport contains all check results.
type FailThreshold ¶ added in v0.38.0
type FailThreshold string
FailThreshold is the worst check status a run tolerates before it reports a non-zero exit.
const ( // FailOnNone never fails the run. The escape hatch for a pipeline that is // not ready to be gated yet. FailOnNone FailThreshold = "none" // FailOnFail fails only on a check that outright failed. FailOnFail FailThreshold = "fail" // FailOnWarn additionally fails on a GATING warning — one a check has // marked as a policy violation, such as deprecated credential storage. // Advisory warnings never fail a run at any threshold. FailOnWarn FailThreshold = "warn" )
func DefaultFailThreshold ¶ added in v0.38.0
func DefaultFailThreshold(ci bool) FailThreshold
DefaultFailThreshold is the threshold used when the operator has not chosen one.
Under CI a warning fails the run: deprecated credential storage reports as a warning, and R3 exists so a pipeline can stop that becoming permanent instead of printing something nobody reads. Interactively it takes FailOnFail, so a developer's terminal is not broken by a warning on upgrade — but a check that genuinely FAILED still produces a non-zero exit, which it never did before (spec 0189 G2: doctor returned success unconditionally, so no script could tell a clean run from a broken one).
The CI fact is a parameter rather than something read here, because a rule that reads the world is a rule whose tests pass on one machine and fail on another. That is not hypothetical: it is how !400 went red.
func ParseFailThreshold ¶ added in v0.38.0
func ParseFailThreshold(v string) (FailThreshold, error)
ParseFailThreshold validates an operator-supplied threshold.
func (FailThreshold) Exceeded ¶ added in v0.38.0
func (t FailThreshold) Exceeded(report *DoctorReport) bool
Exceeded reports whether a report crosses the threshold.
CheckSkip never counts. A check that could not run has not found a problem, and failing a pipeline because something was unavailable would make the gate untrustworthy — which is the fastest way to have it turned off.
Neither does an ADVISORY warning. Keying the exit code on severity alone made "no AI provider API keys configured" fail the pipeline of any tool that does not use AI — it turned a diagnostic into a tripwire. Only a warning a check has marked Gating counts, so a check author opts into being able to stop a build rather than inheriting it from a status string.
type FeatureFlag ¶ added in v0.22.0
FeatureFlag is one built-in feature's enabled/disabled state.
type PathsSection ¶ added in v0.22.0
type PathsSection struct {
ConfigDir string `json:"config_dir,omitempty"`
ConfigFile string `json:"config_file,omitempty"`
}
PathsSection holds the resolved config locations (no cache dir — GTB has no cache subsystem).
type RuntimeSection ¶ added in v0.22.0
type RuntimeSection struct {
Go string `json:"go"`
OS string `json:"os"`
Arch string `json:"arch"`
}
RuntimeSection holds the Go runtime and host OS/arch.
type SupportBundle ¶ added in v0.22.0
type SupportBundle struct {
Tool ToolSection `json:"tool"`
Runtime RuntimeSection `json:"runtime"`
Paths PathsSection `json:"paths"`
Features []FeatureFlag `json:"features"`
Config map[string]any `json:"config"` // redacted, key-name-preserving
Doctor *DoctorReport `json:"doctor,omitempty"`
}
SupportBundle is the fully-collected, already-redacted output of `doctor report`. Every string field and every value in Config has passed through pkg/redact before CollectBundle returns it. It subsumes a plain `doctor` run by embedding the DoctorReport.
func CollectBundle ¶ added in v0.22.0
func CollectBundle(ctx context.Context, props *p.Props) *SupportBundle
CollectBundle gathers the support bundle and applies the redaction perimeter. It is total: nil Config or nil Version yield empty/omitted sections, never a panic.
Source Files