Documentation
¶
Overview ¶
Design: docs/guide/developer-setup.md -- the supported Ubuntu server bootstrap
This file keeps the server bootstrap in the le binary. Paths redirect all filesystem effects into fixtures; downloads, identity lookup, platform values, archive installation, and processes have explicit test seams.
Design: api/proto/ze.proto -- the native protobuf generation path.
Design: api/proto/ze.proto -- explicit json_name options govern generated Go tags.
Design: docs/guide/developer-setup.md -- local web server test workflow.
Index ¶
Constants ¶
const GolangCIVersion = "v2.13.1"
GolangCIVersion is the one release of golangci-lint this repository runs. The linter type-checks with its own copy of go/types, so a release older than the Go directive in go.mod cannot read the export data the ambient toolchain writes and reports every package as a typecheck failure. Raising that directive therefore raises this constant with it.
const KVMGroup = "kvm"
KVMGroup is the group /dev/kvm belongs to.
const LoopbackIPv6 = "fd00::2"
LoopbackIPv6 is the second IPv6 loopback address the suite binds.
const StaticcheckVersion = "2026.2.1"
StaticcheckVersion is the one release of staticcheck this repository runs. A different one on PATH runs and disagrees, which is worse than one that is absent, so probes.go checks the version rather than the presence.
Staticcheck type-checks with its own copy of the unified IR reader, so a release built against an x/tools older than the ambient Go toolchain cannot decode that toolchain's export data and reports every package as an import failure. 2026.1 reads to export data version 2 and Go 1.27 writes version 4, so raising the Go directive in go.mod raises this constant with it.
Variables ¶
This section is empty.
Functions ¶
func Actions ¶
Actions answers the command surface as data, so the listing, the Subs line help renders, and the test that checks them all read one table.
Types ¶
type ClaudeServerEvent ¶
type ClaudeServerEvent struct {
Step string `json:"step"`
Status string `json:"status"`
Detail string `json:"detail,omitempty"`
}
ClaudeServerEvent is one ordered diagnostic in a server setup report.
type ClaudeServerPaths ¶
type ClaudeServerPaths struct {
Home string
GoRoot string
GoArchive string
NodeKey string
NodeSource string
}
ClaudeServerPaths names every path the bootstrap reads or writes.
type Cmd ¶
type Cmd struct {
// Argv is the command and its arguments. Argv[0] is looked up on PATH.
Argv []string
// Dir is the working directory. Empty means this process's own.
Dir string
// Stdin is fed to the command. Nil means an empty stdin, never the
// terminal's: a command that reads a prompt must not find one.
Stdin []byte
// Env replaces the whole environment when it is non-nil, the way
// os/exec reads Cmd.Env.
Env []string
// Timeout bounds the run. Zero means no bound.
Timeout time.Duration
}
Cmd is one command to run, and everything about how to run it.
type Health ¶
type Health string
Health says whether a language server answered, and if not, whose problem it is.
const ( // HealthOK means the server answered. HealthOK Health = "ok" // HealthAbsent means nothing on PATH. A DIFFERENT problem with a different // fix, and the tool table already installs it. HealthAbsent Health = "absent" // HealthBroken means that the server ran but returned no usable result. A // timeout, a non-zero exit, or a reply without an answer causes this state. // A broken module cache, a package that does not build, and a version mismatch // require corrections other than a server reinstall. HealthBroken Health = "broken" // HealthNA means there is nothing here to ask about, so the question does // not apply. HealthNA Health = "na" )
type Installer ¶
type Installer struct {
Manager PackageManager
// contains filtered or unexported fields
}
Installer puts tools on the machine and records what it did during the current run.
Manager is the system package manager. The `go install` and pipx routes do not use it and operate on either platform.
type Outcome ¶
type Outcome struct {
Name string `json:"name"`
State State `json:"state"`
Detail string `json:"detail,omitempty"`
}
Outcome is one step's result: what it was, how it went, and why.
Detail is written for whoever has to fix it, so it names the command, the path, or the complaint rather than restating the state.
type PackageManager ¶
type PackageManager string
PackageManager is the one package manager this host installs system packages with.
const ( // ManagerBrew is Homebrew, on macOS. ManagerBrew PackageManager = "brew" // ManagerApt is apt, on Linux. ManagerApt PackageManager = "apt" // ManagerNone is neither, which is a platform this tool cannot install // for rather than a failure of the tool. ManagerNone PackageManager = "" )
type Privilege ¶
type Privilege string
Privilege is how this process can run a root command right now.
const ( // PrivilegeRoot means already root, so no sudo is used and none needs to // be installed. PrivilegeRoot Privilege = "root" // PrivilegeSudo means sudo acts with no password: NOPASSWD, or a live // timestamp. PrivilegeSudo Privilege = "sudo" // PrivilegePrompt means sudo wants a password and a terminal is attached // to type it on. PrivilegePrompt Privilege = "sudo-prompt" // PrivilegeNone means no route to root that would not block. The caller // records the command instead of running it. PrivilegeNone Privilege = "none" )
type Report ¶
type Report struct {
// Outcomes is the record the verdict is derived from, in the order the
// steps happened.
Outcomes []Outcome
// contains filtered or unexported fields
}
Report contains every outcome of one run and every line that the run would have printed. It also contains the verdict derived from the outcomes.
The code does not calculate totals during the steps. Outcomes is the complete record, and each method below reads it. Therefore, a step cannot be counted in one place but omitted from another.
func (*Report) Add ¶
Add records one outcome and its line. It answers the outcome, for a caller that wants to branch on what it just recorded.
func (*Report) MarshalJSON ¶
MarshalJSON answers the outcomes rather than the struct, so `| json` gives a row set the operators can act on and `| table` renders it.
func (*Report) Note ¶
Note records one line of the transcript that is not an outcome: an install command about to run, a manual fix, a PATH to extend.
type Result ¶
Result is what a command did.
Out and Err are text because every caller wants text, and an invalid UTF-8 complaint is still worth showing.
type Setup ¶
type Setup struct {
// Root is the checkout. The gopls probe runs in it and vendoring writes
// into it.
Root string
// Check probes only: it changes nothing, and answers non-zero when a
// required tool is missing.
Check bool
// Vendor runs `go mod tidy && go mod vendor` at the end of an install run.
Vendor bool
// Shell runs every external command. A nil Shell takes the real route.
Shell *Shell
// GOOS overrides the operating system the platform branches read. Empty
// means this build's own.
GOOS string
// Home overrides where the harness plugin record is looked for. Empty
// means $HOME.
Home string
// UsernsProc overrides the kernel knob the userns state is read from.
UsernsProc string
// KvmDev overrides the device the KVM state is read from.
KvmDev string
// Env answers an environment variable. Nil means the real environment.
Env func(key string) string
// User answers the invoking user's login name.
User func() string
// KvmGroupMember reports whether that user is in the kvm group.
KvmGroupMember func() bool
// Bindable reports whether one address can be bound right now.
Bindable func(addr string) bool
// Gopls answers the gopls probe.
Gopls func() Result
}
Setup is one run: what it was asked for, where it looks, and every seam a test replaces.
func (*Setup) NewInstaller ¶
func (s *Setup) NewInstaller(manager PackageManager, report *Report) *Installer
NewInstaller builds the installer one run uses.
type Shell ¶
type Shell struct {
// Look answers the path to a command on PATH, and whether it is there.
Look func(name string) (string, bool)
// Exec runs one command and answers what it did.
Exec func(ctx context.Context, cmd Cmd) Result
// Euid answers this process's effective user id.
Euid func() int
// Tty reports whether a terminal is attached to answer a password prompt.
Tty func() bool
// Ctx cancels a running command. A nil context means the background one:
// the script had no ceiling either, and each command that can hang
// carries its own Timeout.
Ctx context.Context
}
Shell finds and runs commands. Each field is a test seam that a test can replace. A nil field uses the production implementation.
func (*Shell) Run ¶
Run runs one command and captures its output.
It does not return an error for a command that starts and fails. Instead, it returns a Result with a non-zero code, which each caller must handle. A command that fails to start or exceeds its Timeout also returns a Result. Err contains the reason. Thus, callers examine one Result instead of separate return and failure paths.
type State ¶
type State string
State is what a setup step found, and what that means for the exit code.
The label is what a reader sees and Blocking is what the run is judged by. They travel together because the shell version let them drift apart.
const ( // StatePresent means already there and working. Nothing to do. StatePresent State = "present" // StateInstalled means this run made it so. StateInstalled State = "installed" // StatePending means the machine was changed and a human must finish it: a // PATH to extend, a session to restart. Re-running does not help, so the // run must not report success. StatePending State = "pending" // StateSkipped means nothing to do here and nothing wrong: an optional // tool, or a platform with no package for it. StateSkipped State = "skipped" // StateMissing means required and absent, with no route taken to fix it. // The spelling is upper case because it is the one state a reader must not // skim past. StateMissing State = "MISSING" )
type Tool ¶
type Tool struct {
// Name is what the report calls it.
Name string
// Probe is the executable names to look for.
Probe []string
// ProbeAny says one of those names is enough. Without it every name must
// be found, which is what a package shipping two required binaries needs.
ProbeAny bool
// Brew is the Homebrew formula, when there is one.
Brew string
// Apt is the Debian package, when there is one.
Apt string
// GoInstall is a `go install` target. It works on both platforms, so it
// wins over the system package manager.
GoInstall string
// Required says the run fails without it.
Required bool
// Note is a sentence for a reader who has to decide what to do about it.
Note string
// DoctorCheck is the appliance doctor check that requires this tool.
// An empty value means the tool has no appliance doctor check.
DoctorCheck string
}
Tool is one thing that must be on the machine, and every route to putting it there.
Source Files