doctor

package
v0.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 7, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Overview

Package doctor implements `vegaload doctor`: a set of small, independent checks that answer "will VegaLoad work from here?" for the CLI, for each agent host (Cursor, Claude Code, Claude Desktop), and for a target.

Every check returns pass, warn, fail, or skip with a one-line message and, for problems, a fix. Checks that can be repaired safely carry a fix function that `--fix` runs. Nothing changes on disk unless the caller asks for fixes, and nothing is sent to Harness unless it asks for the harness checks (NFR-05).

The package knows nothing about the engine, protocols, or reporting. Host-specific file locations come from internal/hosts, the same source `vegaload init` writes from.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func WriteJSON

func WriteJSON(w io.Writer, rep Report, home string) error

WriteJSON prints the whole report as one JSON document (FR-CLI-05).

func WriteJSONL

func WriteJSONL(w io.Writer, rep Report, home string) error

WriteJSONL prints one JSON object per line: a "check" line per result, then one "summary" line (FR-CLI-05's streaming mode).

func WriteText

func WriteText(w io.Writer, rep Report, home string, verbose bool)

WriteText prints the human-readable report.

Types

type Check

type Check struct {
	ID       string
	Category string
	Name     string
	Run      func(ctx context.Context) Result
}

Check is one named, independent check.

type Env

type Env struct {
	Version string
	Exe     string // the running vegaload binary
	OS      string
	Arch    string
	Home    string
	Dir     string

	Getenv      func(string) string
	LookPath    func(string) (string, error)
	DirExists   func(string) bool // nil means the real file system
	LookupHost  func(ctx context.Context, host string) ([]string, error)
	DialContext func(ctx context.Context, network, addr string) (net.Conn, error)
	HTTPClient  *http.Client
	// RunCmd runs a command and returns its combined output, trimmed.
	RunCmd func(ctx context.Context, name string, args ...string) (string, error)
	// Probe starts an MCP server command and lists its tools.
	Probe func(ctx context.Context, c mcpprobe.Command) (mcpprobe.Info, error)
}

Env is everything the checks read from the machine. Tests replace the pieces they care about; DefaultEnv fills in the real ones.

func DefaultEnv

func DefaultEnv(version string) (Env, error)

DefaultEnv returns an Env wired to the real machine.

type FixFunc

type FixFunc func(ctx context.Context, dryRun bool) (string, error)

FixFunc repairs one problem. With dryRun set it changes nothing and returns what it would do. Otherwise it returns what it did.

type Options

type Options struct {
	Dir          string   // project directory; empty means Env.Dir
	Hosts        []string // "auto" (default), "all", "none", or host IDs
	MCPConfig    string   // an extra MCP config file to check (host "custom")
	Target       string   // target URL or host:port to check
	AllowTargets []string // extra allowlisted hosts, as for `run -allow-target`
	Smoke        bool     // run a one-user, one-second test against Target
	Harness      bool     // verify Harness RT access (the only network call to Harness)
	Fix          bool     // repair what can be repaired safely
	DryRun       bool     // with Fix: report planned repairs, change nothing
	Only         []string // run only these check IDs or prefixes
	Skip         []string // skip these check IDs or prefixes
	Timeout      time.Duration
}

Options selects and tunes the checks.

type Report

type Report struct {
	Version string    `json:"version"`
	OS      string    `json:"os"`
	Arch    string    `json:"arch"`
	Dir     string    `json:"dir"`
	Summary Summary   `json:"summary"`
	Results []Result  `json:"results"`
	Started time.Time `json:"-"`
}

Report is a complete doctor run.

func Run

func Run(ctx context.Context, env Env, opt Options) (Report, error)

Run builds the plan, runs the checks, and, when asked, applies fixes and re-checks what it fixed.

func (Report) ExitCode

func (r Report) ExitCode(strict bool) int

ExitCode maps a report to the process exit code: 1 when any check failed (or warned, under strict), else 0.

type Result

type Result struct {
	ID         string   `json:"id"`
	Category   string   `json:"category"`
	Name       string   `json:"name"`
	Status     Status   `json:"status"`
	Message    string   `json:"message"`
	Detail     []string `json:"detail,omitempty"`
	Fix        string   `json:"fix,omitempty"`
	Fixable    bool     `json:"fixable,omitempty"`
	FixPlan    string   `json:"fix_plan,omitempty"`  // set by --fix -dry-run
	Fixed      bool     `json:"fixed,omitempty"`     // set when --fix repaired it
	FixError   string   `json:"fix_error,omitempty"` // set when --fix failed
	DurationMS int64    `json:"duration_ms"`
	// contains filtered or unexported fields
}

Result is one check's outcome. The JSON form is the stable output contract of `vegaload doctor -output json` (FR-CLI-05).

type Status

type Status string

Status is the outcome of one check.

const (
	Pass Status = "pass"
	Warn Status = "warn"
	Fail Status = "fail"
	Skip Status = "skip"
)

The four outcomes. Pass and skip never affect the exit code, warn only does under strict mode, and fail always does.

type Summary

type Summary struct {
	Pass  int `json:"pass"`
	Warn  int `json:"warn"`
	Fail  int `json:"fail"`
	Skip  int `json:"skip"`
	Fixed int `json:"fixed"`
}

Summary counts results by status.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL