Documentation
¶
Overview ¶
Package toolbelt provisions developer tools onto a persistent volume, declaratively. A manifest (tools.json) records intent; a compiled catalog carries install knowledge; the Engine reconciles installed state against intent through a single-flight job queue, never touching unmanaged files.
<ConfigDir>/tools.json — user intent, re-read every operation. <ConfigDir>/tools-state.json — engine-owned machine state. <ToolsDir>/opt/<name>/<ver>/ — versioned install trees. <ToolsDir>/bin — the single PATH dir (symlinks).
CatalogPath (compiled by cmd/toolcatalog) is read-only; a missing catalog degrades to manual and ecosystem sources only. Install sources: aqua-registry, npm, pip (via uv), cargo, go install, and a manual bash escape hatch.
Index ¶
- Constants
- Variables
- func ApplyOverlay(c *Catalog, data []byte, resolveAqua func(ref string) (*AquaPackage, error)) error
- func AptAvailable() bool
- func CompareRank(a, b Rank) int
- func DefaultBackends() map[string]string
- func ParseCatalogRefresh(raw RefreshEnv, name RefreshEnvName) time.Duration
- func ParseRequireList(raw string) []string
- func VerifyCatalog(c *Catalog, require []string) []error
- func WriteManifest(configDir string, content []byte) error
- type AddRequest
- type AptHit
- type AptPackage
- type AptState
- type AquaChecksum
- type AquaFile
- type AquaOverride
- type AquaPackage
- type AquaVersionOverride
- type CancelCause
- type Catalog
- type CatalogEntry
- type CatalogInfo
- type CatalogRefresh
- type Config
- type DependentsError
- type Engine
- func (e *Engine) Add(ctx context.Context, req *AddRequest) (*Job, error)
- func (e *Engine) CancelJob(id string) bool
- func (e *Engine) CatalogInfo() CatalogInfo
- func (e *Engine) Close()
- func (e *Engine) EnsureInstalled(ctx context.Context, name string) error
- func (e *Engine) Install(name string) (*Job, error)
- func (e *Engine) Inventory() (*Inventory, error)
- func (e *Engine) Jobs() (active *Job, recent []*Job)
- func (e *Engine) Patch(name string, req PatchRequest) (*Job, error)
- func (e *Engine) Reconcile(mode ReconcileMode) (jv *Job, enqueued bool, err error)
- func (e *Engine) RefreshCatalog() (*Job, error)
- func (e *Engine) Remove(name string) (*Job, []string, error)
- func (e *Engine) RemoveWithDependents(name string) (*Job, []string, error)
- func (e *Engine) ReplaceManifest(content []byte, check func(current []byte) error) error
- func (e *Engine) Search(query string) []CatalogEntry
- func (e *Engine) SearchApt(query string) ([]AptHit, bool)
- func (e *Engine) SearchUnavailable(query string) []CatalogEntry
- func (e *Engine) SearchWithCounts(query string) SearchCounts
- func (e *Engine) SyncManifest(seen []byte, kind SeenKind) (changed bool, err error)
- func (e *Engine) Update(names ...string) (*Job, error)
- func (e *Engine) Wait(ctx context.Context, jobID string) (*Job, error)
- type GitHubRateLimit
- type GitHubRateLimitError
- type InstallSpec
- type Inventory
- type Job
- type Manifest
- type MatchKind
- type PatchRequest
- type Rank
- type ReconcileMode
- type RefreshEnv
- type RefreshEnvName
- type ReleaseHints
- type RootIntegrityError
- type RootIntegrityFinding
- type SearchCounts
- type SeenKind
- type State
- type SystemTool
- type Tool
- type ToolInfo
- type ToolStatus
Constants ¶
const ( DefaultCatalogRefresh = 24 * time.Hour MinCatalogRefresh = time.Hour MaxCatalogRefresh = 30 * 24 * time.Hour )
Canonical catalog refresh cadence policy, shared by every consumer. The published artifact moves at most a few times per day, so the default matches that cadence and the floor keeps an interval typo from hammering the publisher; the ceiling keeps a fat-fingered unit from silently freezing refreshes for months.
const ( CatalogSourceNone = "none" // no catalog available (degraded) CatalogSourceBaked = "baked" // Config.CatalogPath (image-baked) CatalogSourceCached = "cached" // last fetched copy, reloaded from ConfigDir CatalogSourceRemote = "remote" // fetched this process lifetime )
Catalog sources reported by CatalogInfo.
const ( SourceAqua = "aqua" // aqua:owner/repo — evaluated aqua-registry definition SourceNpm = "npm" // npm:package SourcePip = "pip" // pip:package (installed via uv) SourceCargo = "cargo" // cargo:crate SourceGo = "go" // go:package/path (what go install builds) SourceApt = "apt" // apt:package — Debian package, container layer SourceRelease = "release" // release:<github|gitlab>/owner/repo — forge release asset SourceManual = "manual" // user-provided install command )
Source prefixes for Tool.Source. A source is "<kind>:<ref>" except SourceManual which stands alone.
const ( JobQueued = "queued" JobRunning = "running" JobDone = "done" JobFailed = "failed" JobCancelled = "cancelled" )
Job states.
const ( JobKindInstall = "install" JobKindUninstall = "uninstall" // Remove: footprint removed, entry deleted JobKindDisable = "disable" // Patch disabled:true: footprint removed, entry kept JobKindUpdate = "update" JobKindReconcile = "reconcile" // converge disk to intent (install missing + disable extras) JobKindCatalogRefresh = "catalog-refresh" // fetch + verify + swap the published catalog )
Job kinds.
const DefaultCatalogURL = "https://github.com/cplieger/tool-catalog/releases/latest/download/tool-catalog.json"
DefaultCatalogURL is the published compiled catalog's stable latest-download URL (the cplieger/tool-catalog release artifact). The consumer contract lives here so every app defaults to the same publisher and a publisher move is a one-line change; apps expose an env override for forks and mirrors.
const DefaultKeepVersions = 1
DefaultKeepVersions is how many superseded versions of a tool the engine retains when Config.KeepVersions is unset, the count retain.Keep(0) returns: one, so a bad update always has a previous tree under <ToolsDir>/opt/<name>/ to fall back to instead of only a re-download.
const ErrorCodeGitHubRateLimited = "github_rate_limited"
ErrorCodeGitHubRateLimited is Job.ErrorCode for a job GitHub's API rate limit failed; Job.RateLimit then carries the detail.
const ManifestVersion = 2
ManifestVersion is the manifest schema version this engine reads and writes — the only version it accepts. A manifest with any other version (or one that fails to parse) is an error at engine start.
Variables ¶
var ( // ErrNotFound marks an operation on a tool the manifest doesn't have. ErrNotFound = errors.New("tool not found") // ErrHasDependents marks a refused remove/disable: enabled entries // still require the tool (directly or as an implied backend). ErrHasDependents = errors.New("tool has dependents") // ErrEssential marks a refused remove: the consumer's bundled-tools // file declares this tool necessary (CatalogEntry.Essential). // Disabling it is still allowed — see that field for why only deletion // is refused. ErrEssential = errors.New("tool is essential to this application") // ErrDisabled marks an install attempt on a disabled template. // Enabling is an explicit state change (Patch Disabled=false), never // a side effect of a retry. ErrDisabled = errors.New("tool is disabled") // ErrUnknownJob marks a Wait on a job id the queue does not know: // never enqueued, or the job ended before the Wait began and its // result has since been dropped from the retained history. ErrUnknownJob = errors.New("unknown job") // ErrRootIntegrity marks a New refused by the opt-in root-integrity // check (Config.VerifyRootIntegrity): a managed root is a symlink, // is not a directory, is owned or writable by another account (itself // or a directory above it), cannot be inspected, or resolves outside // the tool tree. *RootIntegrityError names each one. ErrRootIntegrity = errors.New("managed root failed the integrity check") // ErrQueueFull marks a job refused because the queue already holds its // cap of waiting jobs. Transient: the request may be retried, and a // refused Add, Patch or Remove has not written the manifest. ErrQueueFull = errors.New("too many queued tool jobs") // ErrShuttingDown marks a job refused because Close has begun. ErrShuttingDown = errors.New("engine shutting down") )
Sentinel errors. Compare with errors.Is; *DependentsError additionally carries the dependent names and *RootIntegrityError the offending roots (errors.As).
ErrAptUnavailable marks an apt operation attempted where apt cannot work: a non-Debian host, or a process that is not root.
var ErrGitHubRateLimited = errors.New("GitHub API rate limit reached")
ErrGitHubRateLimited classifies a request GitHub's API refused for a rate limit. errors.As with a *GitHubRateLimitError (the pointer) reads the detail; Add, EnsureInstalled and a failed Job's Err return it wrapped.
var ErrManifestInvalid = errors.New("toolbelt: invalid manifest")
ErrManifestInvalid is wrapped by every refusal of a tools.json document: ParseManifest's, New's, WriteManifest's, ReplaceManifest's and SyncManifest's. The refusals' error texts do not name it.
var ErrRefreshNotConfigured = errors.New("catalog refresh not configured")
ErrRefreshNotConfigured marks RefreshCatalog on an engine constructed without Config.Refresh.
Functions ¶
func ApplyOverlay ¶
func ApplyOverlay(c *Catalog, data []byte, resolveAqua func(ref string) (*AquaPackage, error)) error
ApplyOverlay merges one overlay JSON document into the catalog, ignoring one leading UTF-8 byte-order mark.
resolveAqua, when non-nil, loads an aqua install definition for a source-bearing `aqua:` entry that does not embed one — the compile case, where cmd/toolcatalog passes a registry-checkout loader. At runtime there is no registry checkout: pass nil, and source-bearing aqua entries must carry their definition inline (display-field patches, the common runtime overlay, need no definition at all).
func AptAvailable ¶ added in v3.1.0
func AptAvailable() bool
AptAvailable reports whether this process can install apt packages: euid 0, and apt-get present per resolveSystemBin, so this gate and the spawn it guards answer about one file. Consumers surface it rather than offering an install that always fails, and the engine's own converge skips apt when it is false.
Root is required because apt writes to /usr and the dpkg database. There is no sudo path here by design: the two consumers of this library run as root deliberately, and a library that shells out to sudo would be inventing a privilege escalation its caller did not ask for.
func CompareRank ¶ added in v3.2.0
CompareRank orders two scored hits: score descending, then name length ascending, then name ascending.
Exported because THREE corpora order by it — the catalog, the Debian package list, and the merged response a consumer renders — and a merged list sorted by a different rule than the two lists feeding it is sorted by neither.
The length tie-break is load-bearing rather than cosmetic. Every prefix match scores alike, so with a name-ascending tie-break alone a short near-exact name loses to every alphabetically-earlier longer one that shares its prefix. Measured over Debian trixie's 68,799 package names, `python3` ranked 909th of 6,607 hits for "python" (behind python-acme-doc and 907 siblings) and `nodejs` ranked 1,701st for "node"; with the length tie-break they rank 1st and 3rd.
func DefaultBackends ¶ added in v3.1.0
DefaultBackends returns the source-kind-to-backend-tool map a compiled catalog should carry: npm needs node, pip needs uv, cargo needs rust, go needs go.
Exported for the catalog compiler, which stamps it into every artifact so the answer travels as DATA rather than living only in this package's source. A consumer that provides a different backend edits the field in its own bundled-tools file; nothing has to reach a Go map. Returns a fresh copy on every call.
func ParseCatalogRefresh ¶
func ParseCatalogRefresh(raw RefreshEnv, name RefreshEnvName) time.Duration
ParseCatalogRefresh interprets a consumer's refresh env value into the CatalogRefresh.Interval duration under the canonical policy: empty or unparseable falls back to DefaultCatalogRefresh, positive durations clamp to [MinCatalogRefresh, MaxCatalogRefresh], and "off"/"disabled"/"0" return zero (schedule disabled; on-demand refresh stays available).
Call it with both arguments converted at the call site, which is what makes the direction readable:
toolbelt.ParseCatalogRefresh(toolbelt.RefreshEnv(os.Getenv(name)), toolbelt.RefreshEnvName(name))
func ParseRequireList ¶
ParseRequireList extracts tool names from a requirements list: one name per line, # comments and blank lines ignored — the shape required-tools.txt files use across the cplieger repos (cmd/toolcatalog verify reads the same format). Shared here so consumers embedding their list for CatalogRefresh.Require parse it identically to the build gate.
func VerifyCatalog ¶
VerifyCatalog checks that every required name resolves in the catalog to install knowledge the engine can act on, offline: a non-empty source; for aqua sources an embedded definition that parses its templates and claims linux support on both amd64 and arm64; for manual sources an install command. One error per failing name; nil means the catalog satisfies the requirement set. Consumers run this at image build (cmd/toolcatalog verify) over their required names so a registry drift fails the build instead of a boot job.
func WriteManifest ¶ added in v3.15.0
WriteManifest validates content as the engine reads tools.json and writes it verbatim to configDir's tools.json with the engine's file mode, atomically. It is for a consumer with no engine running on configDir (use Engine.ReplaceManifest otherwise) and checks no catalog, so it cannot refuse a document that drops an essential row. A write that landed but could not be fsynced is not an error, as for the engine's own manifest writes.
Types ¶
type AddRequest ¶
type AddRequest struct {
Name string `json:"name"`
Source string `json:"source,omitempty"` // optional when the catalog knows the name
Version string `json:"version,omitempty"` // optional: resolve latest
Description string `json:"description,omitempty"`
Origin string `json:"origin,omitempty"`
Install string `json:"install,omitempty"`
Uninstall string `json:"uninstall,omitempty"`
Probe string `json:"probe,omitempty"`
Python string `json:"python,omitempty"` // pip: only; see Tool.Python
Requires []string `json:"requires,omitempty"`
// VersionArgs sets Tool.VersionArgs; empty takes the catalog's.
VersionArgs []string `json:"version_args,omitempty"`
Pin bool `json:"pin,omitempty"`
// Disabled adds the entry as a template: recorded, not installed,
// no job enqueued (Add then returns a nil Job).
Disabled bool `json:"disabled,omitempty"`
}
AddRequest is the Add call's body: intent for a new tool. Every field except Name is optional when the catalog knows the name.
type AptHit ¶ added in v3.1.0
type AptHit struct {
Name string
Description string
// Candidate is the version apt would install, filled in by the
// engine for the hits it returns rather than by the index (it costs
// one apt-cache invocation per package, so it is resolved for the
// capped result set only).
Candidate string
}
AptHit is one package-list search result.
type AptPackage ¶ added in v3.1.0
AptPackage is one installed Debian package this engine does not manage: something a user or an agent installed in the shell. Read-only, with no manifest row behind it. Reported so a consumer's tools surface can answer "what is on this box" without pretending the engine installed it.
type AptState ¶ added in v3.4.0
type AptState string
AptState says what one search could learn from the Debian package corpus. It splits the false half of the bool Engine.SearchApt returns, which covers two facts that mean opposite things to a reader: a host where apt cannot be used at all, and a host whose index has not been read yet.
The zero value states nothing, so a consumer decoding a reply from an engine that predates this falls back to the bool.
const ( // [AptAvailable]), so no search will answer from the corpus. AptStateUnavailable AptState = "unavailable" // AptStateIndexing means apt is usable and no package index is // loaded. The first search starts the load and answers without it, so // a later search answers from the corpus — a consumer says it is // checking rather than asserting an absence it cannot support. AptStateIndexing AptState = "indexing" // AptStateAvailable means the corpus answered this query, so an empty // Apt block means nothing matched. AptStateAvailable AptState = "available" )
The states, ordered by how much the corpus can ever say. There is no name for the zero value: no search returns it, and it exists on the wire only as the absence a consumer reads from an older engine.
type AquaChecksum ¶
type AquaChecksum struct {
Enabled *bool `json:"enabled,omitempty" yaml:"enabled"`
Type string `json:"type,omitempty" yaml:"type"` // github_release | http
Asset string `json:"asset,omitempty" yaml:"asset"`
URL string `json:"url,omitempty" yaml:"url"`
Algorithm string `json:"algorithm,omitempty" yaml:"algorithm"` // sha256 | sha512 | ...
}
AquaChecksum describes where the artifact's checksum lives.
type AquaFile ¶
type AquaFile struct {
Name string `json:"name" yaml:"name"`
Src string `json:"src,omitempty" yaml:"src"` // template; default = Name
}
AquaFile names one binary inside the extracted artifact.
type AquaOverride ¶
type AquaOverride struct {
Replacements map[string]string `json:"replacements,omitempty" yaml:"replacements"`
Checksum *AquaChecksum `json:"checksum,omitempty" yaml:"checksum"`
GOOS string `json:"goos,omitempty" yaml:"goos"`
GOArch string `json:"goarch,omitempty" yaml:"goarch"`
Asset string `json:"asset,omitempty" yaml:"asset"`
URL string `json:"url,omitempty" yaml:"url"`
Format string `json:"format,omitempty" yaml:"format"`
Files []AquaFile `json:"files,omitempty" yaml:"files"`
}
AquaOverride adjusts fields for a specific GOOS/GOARCH.
type AquaPackage ¶
type AquaPackage struct {
Replacements map[string]string `json:"replacements,omitempty" yaml:"replacements"`
Checksum *AquaChecksum `json:"checksum,omitempty" yaml:"checksum"`
VersionConstr string `json:"version_constraint,omitempty" yaml:"version_constraint"`
VersionSource string `json:"version_source,omitempty" yaml:"version_source"`
Asset string `json:"asset,omitempty" yaml:"asset"`
URL string `json:"url,omitempty" yaml:"url"`
Path string `json:"path,omitempty" yaml:"path"`
Format string `json:"format,omitempty" yaml:"format"`
RepoOwner string `json:"repo_owner,omitempty" yaml:"repo_owner"`
RepoName string `json:"repo_name,omitempty" yaml:"repo_name"`
VersionPrefix string `json:"version_prefix,omitempty" yaml:"version_prefix"`
Description string `json:"description,omitempty" yaml:"description"`
Type string `json:"type" yaml:"type"`
VersionFilter string `json:"version_filter,omitempty" yaml:"version_filter"`
VersionOverrides []AquaVersionOverride `json:"version_overrides,omitempty" yaml:"version_overrides"`
SupportedEnvs []string `json:"supported_envs,omitempty" yaml:"supported_envs"`
Overrides []AquaOverride `json:"overrides,omitempty" yaml:"overrides"`
Files []AquaFile `json:"files,omitempty" yaml:"files"`
NoAsset bool `json:"no_asset,omitempty" yaml:"no_asset"`
}
AquaPackage is the subset of an aqua-registry package definition the engine evaluates. Field names mirror the upstream YAML/JSON schema (https://aquaproj.github.io/docs/reference/registry-config), which the catalog compiler (cmd/toolcatalog) relies on to unmarshal registry files directly. Windows- and darwin-only concerns (rosetta2, windows_arm_emulation, complete_windows_ext) are intentionally absent: the engine resolves for linux only, and the evaluator resolves everything for linux/GOARCH.
func (*AquaPackage) CheckTemplates ¶
func (p *AquaPackage) CheckTemplates() error
CheckTemplates parses (without executing) every Go template the definition carries — asset, url, path, checksum asset/url, file srcs, across version overrides — so catalog verification can catch template syntax drift offline. Returns the first parse error.
func (*AquaPackage) ResolveSpec ¶
func (p *AquaPackage) ResolveSpec(version string) (*InstallSpec, error)
ResolveSpec evaluates the package definition for the given version on linux/GOARCH and returns the download plan. version is the upstream tag (with any version_prefix still attached).
func (*AquaPackage) SupportsLinux ¶
func (p *AquaPackage) SupportsLinux(goarch string) bool
SupportsLinux reports whether the definition claims support for linux/goarch at the root level (supported_envs; empty = everywhere). A static, offline check — no version rendering. Used by catalog verification.
type AquaVersionOverride ¶
type AquaVersionOverride struct {
Asset *string `json:"asset,omitempty" yaml:"asset"`
URL *string `json:"url,omitempty" yaml:"url"`
Format *string `json:"format,omitempty" yaml:"format"`
Replacements *map[string]string `json:"replacements,omitempty" yaml:"replacements"`
Checksum *AquaChecksum `json:"checksum,omitempty" yaml:"checksum"`
NoAsset *bool `json:"no_asset,omitempty" yaml:"no_asset"`
VersionPrefix *string `json:"version_prefix,omitempty" yaml:"version_prefix"`
VersionConstr string `json:"version_constraint,omitempty" yaml:"version_constraint"`
Files []AquaFile `json:"files,omitempty" yaml:"files"`
Overrides []AquaOverride `json:"overrides,omitempty" yaml:"overrides"`
SupportedEnvs []string `json:"supported_envs,omitempty" yaml:"supported_envs"`
}
AquaVersionOverride switches definition fields per version range. A nil pointer field means "inherit from the package root".
type CancelCause ¶
type CancelCause string
CancelCause identifies WHO cancelled a job: a shutdown cancellation is routine, a caller cancellation is a deliberate act a consumer may want to alert on. Meaningful only for a job whose State is JobCancelled — a job that finished, failed, or timed out always carries CancelUnknown, even if a cancellation was requested and lost the race.
const ( // CancelUnknown is the zero value: no cause was recorded. A // cancelled job carrying it was stopped through a path that names no // cause. Deliberately NOT equal to CancelShutdown or CancelCaller, // so a cancellation path added later cannot be silently read as // either one. CancelUnknown CancelCause = "" // CancelShutdown is cancellation initiated by Engine.Close: the // running job's context is cancelled and queued jobs are drained // because the engine is shutting down. Routine. CancelShutdown CancelCause = "shutdown" // CancelCaller is cancellation initiated through Engine.CancelJob — // the httpapi POST {prefix}/jobs/{id}/cancel route, or product code // calling it directly. Deliberate. CancelCaller CancelCause = "caller" )
func (CancelCause) String ¶
func (c CancelCause) String() string
String renders a cause for logs, naming the zero value instead of printing an empty string.
type Catalog ¶
type Catalog struct {
// Refs records the upstream registry refs this catalog was
// compiled from (informational).
Refs map[string]string `json:"refs,omitempty"`
// Licenses carries the upstream registries' license texts, keyed by
// registry name (mise, aqua-registry). The compiled catalog embeds
// data derived from both (MIT), and MIT requires the copyright +
// permission notice to travel with copies — embedding the texts
// makes every copy (baked, cached, fetched) self-contained.
Licenses map[string]string `json:"licenses,omitempty"`
Entries map[string]CatalogEntry `json:"entries"`
// (mise core:/vfox:/conda:/gem:/spm: backends, uncovered aqua types),
// each carrying a Reason. A SEPARATE map, not a state field on
// Entries: a sourceless row inside Entries would reach an older
// engine's Search and fail Add on a row its UI had offered, where an
// unknown top-level key is instead ignored wholesale by old engines.
// The two key sets are disjoint (compile-time asserted); membership
// is architecture-INDEPENDENT — "no source exists" is a registry
// fact, "no asset for your arch" is the install job's own answer.
Unavailable map[string]CatalogEntry `json:"unavailable,omitempty"`
// Backends names the tool each source kind needs installed first:
// npm needs node, pip needs uv (see backendFor). DATA rather than an
// engine map, because which catalog entry provides npm is a fact
// about the catalog, not the mechanism — a consumer bundling a
// different provider says so here. Absent/partial falls back to
// defaultBackends, so an older compiled catalog keeps working.
Backends map[string]string `json:"backends,omitempty"`
// Generated is the compile timestamp (RFC 3339 UTC), stamped by
// cmd/toolcatalog (informational).
Generated string `json:"generated,omitempty"`
// contains filtered or unexported fields
}
Catalog is the compiled tool-catalog.json document.
func (*Catalog) Featured ¶
func (c *Catalog) Featured() []CatalogEntry
Featured returns the curated starter set (empty-state content), sorted by name.
The returned entries alias the catalog: do not mutate their slice fields (see CatalogEntry).
func (*Catalog) Lookup ¶
func (c *Catalog) Lookup(name string) (CatalogEntry, bool)
Lookup finds a catalog entry by name or alias.
The returned entry aliases the catalog: do not mutate its slice fields (see CatalogEntry).
func (*Catalog) Search ¶
func (c *Catalog) Search(query string) []CatalogEntry
Search ranks catalog entries against a query: exact name, name prefix, alias, name substring, then description substring. Empty query returns the featured set.
The returned entries alias the catalog: do not mutate their slice fields (see CatalogEntry).
func (*Catalog) SearchUnavailable ¶ added in v3.1.0
func (c *Catalog) SearchUnavailable(query string) []CatalogEntry
SearchUnavailable ranks the entries no install source exists for (see Catalog.Unavailable) with the same scoring Search uses, so a consumer can tell a user that a tool is known and why it cannot be installed instead of showing an empty result. An empty query returns nothing: the unavailable set has no featured members and listing 200 uninstallable tools is not a browse surface.
The returned entries alias the catalog: do not mutate their slice fields (see CatalogEntry).
type CatalogEntry ¶
type CatalogEntry struct {
Aqua *AquaPackage `json:"aqua,omitempty"`
// Release carries the registry's install hints for a release-backed
// entry (see ReleaseHints). Absent for every other source.
Release *ReleaseHints `json:"release,omitempty"`
// Reason is set only on Catalog.Unavailable entries: the registry
// backend the compiler could not use, e.g. "core:python" or
// "vfox:mise-plugins/vfox-postgres". It is the whole explanation a
// consumer can show for a tool it knows about and cannot install.
Reason string `json:"reason,omitempty"`
Name string `json:"name"`
Description string `json:"description,omitempty"`
Source string `json:"source"`
// Version is the default pinned version for entries without an
// upstream version source (manual installs).
Version string `json:"version,omitempty"`
Install string `json:"install,omitempty"` // manual-source entries
Uninstall string `json:"uninstall,omitempty"` // manual-source entries
Probe string `json:"probe,omitempty"` // manual-source entries
Aliases []string `json:"aliases,omitempty"`
// VersionArgs declares the tool's version-reporting shape, e.g.
// ["--version"] or ["version"]. Hydrated onto manifest entries, it
// upgrades the install probe from "the binary runs" to "the binary
// reports the recorded version" (see Tool.VersionArgs).
VersionArgs []string `json:"version_args,omitempty"`
Requires []string `json:"requires,omitempty"`
Featured bool `json:"featured,omitempty"`
// Lsp marks language-server entries; drives the consumers'
// no-LSP-enabled warning and UI badges.
Lsp bool `json:"lsp,omitempty"`
// Essential marks a tool the PRODUCT depends on: removing it breaks a
// feature the user did not ask to lose, so the engine refuses (
// ErrEssential). Declared by a consumer's BUNDLED TOOLS file, never
// by registry data: "this app needs X" is a fact about the app, not
// about X. Not a lock on version or install state: an essential tool can
// still be updated or DISABLED, only deletion is refused. Companion
// to Featured: Essential is NECESSARY, Featured is RECOMMENDED.
Essential bool `json:"essential,omitempty"`
}
CatalogEntry is one tool in the compiled catalog: the mise-registry name/description joined with the preferred install source and, for aqua sources, the embedded aqua package definition. Overlay entries (curated) may add requires/manual install commands and the lsp marker. Its slice fields (Aliases, Requires, VersionArgs) and its Aqua pointer alias the shared catalog, which is never edited in place: writing through them corrupts it for every other caller, so copy what you intend to change.
type CatalogInfo ¶
type CatalogInfo struct {
// Refs are the upstream registry refs the catalog was compiled
// from; Generated its compile timestamp (RFC 3339 UTC). Both are
// informational pass-throughs of the catalog document.
Refs map[string]string `json:"refs,omitempty"`
Generated string `json:"generated,omitempty"`
// Source is where the live catalog came from: baked (the image
// file), cached (the refresh cache, reloaded at boot), remote
// (fetched this process lifetime), or none (degraded, no catalog).
Source string `json:"source"`
// URL is the configured refresh source (empty when refresh is not
// configured).
URL string `json:"url,omitempty"`
// LastError is the most recent refresh failure ("" after a
// successful refresh).
LastError string `json:"last_error,omitempty"`
Entries int `json:"entries"`
// install. Beside Entries it is the operator's read on whether a
// registry bump changed what is reachable: a jump in this number with
// Entries falling is upstream moving tools onto a backend the
// compiler does not support.
Unavailable int `json:"unavailable"`
// FetchedAt is the last successful refresh (Unix milliseconds; 0
// before the first).
FetchedAt int64 `json:"fetched_at,omitempty"`
// Scheduled reports whether the engine-owned background refresh
// loop is running.
Scheduled bool `json:"scheduled"`
}
CatalogInfo reports the live catalog's provenance and freshness (the Engine.CatalogInfo return and the httpapi GET catalog body).
type CatalogRefresh ¶
type CatalogRefresh struct {
// URL of the published compiled catalog (e.g. a GitHub release's
// latest-download URL). Fetched with the engine's hardened HTTP
// client: SSRF-validated on every hop, HTTPS on 443 only.
URL string
// Require lists tool names a fetched catalog must resolve (the
// same offline checks as cmd/toolcatalog verify) before it
// replaces the current one. The consumer's required set; empty
// skips the name check (the structural floor still applies).
Require []string
// Interval between background refreshes. Positive starts the
// engine-owned schedule (one refresh per interval, with jitter;
// deliberately no fire-on-start — consumers trigger the boot
// fetch via RefreshCatalog once their boot work is enqueued);
// zero disables the schedule while keeping on-demand refresh
// (RefreshCatalog / the httpapi route) available.
Interval time.Duration
}
CatalogRefresh configures the runtime catalog refresh: the engine periodically fetches a published compiled catalog, verifies it, and swaps it in atomically. The catalog is DATA on a daily upstream cadence; refreshing it at runtime decouples catalog freshness from consumer image rebuilds. The last good catalog always stands: a failed fetch, parse, overlay, or verify fails the refresh job and changes nothing.
type Config ¶
type Config struct {
// OnJobChanged, when non-nil, receives every job state transition
// (queued, running, done, failed, cancelled). Views carry no output
// tail; stream output via OnJobOutput or poll Jobs(). It runs under the
// job queue's lock, so it must not block or call the Engine.
OnJobChanged func(*Job)
// OnJobOutput, when non-nil, receives coalesced batches of a running
// job's output lines (~150 ms cadence).
OnJobOutput func(jobID string, lines []string)
// GitHubToken, when non-nil, is called once per api.github.com request
// (version checks, release listings) and for no other host, so a rotated
// token reaches the next request. "" sends that request anonymously. An
// error fails it with no anonymous retry; where the engine returns that
// failure (Add, for example), errors.Is and errors.As reach the error.
// Nil means every GitHub API request is anonymous. Must be safe for
// concurrent use.
GitHubToken func(ctx context.Context) (string, error)
// Logger receives engine-level log lines. Nil means slog.Default().
Logger *slog.Logger
// Seed is the manifest written when none exists: by New on a fresh
// volume, and by SyncManifest when it adopts a removed tools.json.
// Nil seeds an empty manifest. See DefaultSeed.
Seed *Manifest
// ConfigDir holds tools.json + tools-state.json (the persistent
// config volume root).
ConfigDir string
// ToolsDir is the install tree root (bin/, opt/, npm/, python/).
ToolsDir string
// CatalogPath is the compiled catalog baked into the consumer's
// image (optional; missing = degraded search + named install errors
// for catalog-dependent entries). With Refresh configured this is
// the first-boot/offline fallback: a valid refresh cache under
// ConfigDir takes precedence at construction.
CatalogPath string
// Refresh, when non-nil, enables runtime catalog refresh: fetches
// the published catalog at Refresh.URL (on the engine-owned
// schedule, or on demand via RefreshCatalog), verifies it against
// Refresh.Require, caches it under ConfigDir, and swaps it in
// atomically. The last good catalog stands on any failure. Nil
// keeps the baked catalog static for the process lifetime.
Refresh *CatalogRefresh
// CatalogOverlays are consumer overlay JSON files (see
// ApplyOverlay) applied to every catalog the engine loads, keeping
// app-specific display patches independent of the published
// artifact. A runtime overlay must embed any aqua definition inline
// — there is no registry checkout to resolve from at runtime.
CatalogOverlays []string
// System names image-baked binaries surfaced read-only in
// Inventory's System group (informational; not managed).
System []string
// TrustedUIDs lists users, beside root and this process's uid, whose
// ownership of, or write access to, a managed root or a directory above
// it VerifyRootIntegrity accepts: an account the operator knows is
// already privileged on the host. New rejects a negative entry.
TrustedUIDs []int
// KeepVersions is how many SUPERSEDED versions of a tool to retain
// under <ToolsDir>/opt/<name>/ (the current version is always kept),
// so a bad update can be rolled back. 0 means DefaultKeepVersions; a
// negative value keeps none.
KeepVersions int
// VerifyRootIntegrity makes New REFUSE to construct an Engine over
// managed roots it cannot safely execute from (see rootintegrity.go).
// Off by default; turn it on when the tool tree lives on an
// operator-controlled volume and the process runs privileged. New
// checks before it writes anything and again after it creates
// ConfigDir and bin/. A failure returns ErrRootIntegrity as a
// *RootIntegrityError (errors.As), logged at Error before New returns.
VerifyRootIntegrity bool
}
Config wires an Engine. ConfigDir and ToolsDir are required, with no ".." component.
type DependentsError ¶
type DependentsError struct {
Dependents []string
}
DependentsError is the ErrHasDependents shape that names the enabled entries blocking a remove/disable, directly or through another entry.
func (*DependentsError) Error ¶
func (e *DependentsError) Error() string
func (*DependentsError) Is ¶
func (*DependentsError) Is(target error) bool
Is makes errors.Is(err, ErrHasDependents) match.
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine is the tools subsystem: the single owner of the manifest and install tree, the job queue, and the catalog. Construct with New.
The manifest store's single-writer guarantee is an in-process lock: every other process (a CLI, an agent) must go through the consumer's server rather than linking toolbelt against the same data dirs.
func New ¶
New constructs and starts an Engine: initializes the manifest files (seeding when absent; another schema version is an error), refuses a ConfigDir that fails a probe write, and launches the job worker.
With Config.VerifyRootIntegrity set (that field says when it checks), an unfit managed root refuses construction with ErrRootIntegrity. New is the seam because Inventory and EnsureInstalled probe synchronously too.
func (*Engine) Add ¶
Add records a new tool in the manifest and, unless the request marks it disabled, enqueues its install. Present-and-enabled is the default intent: adding means "have this installed".
func (*Engine) CancelJob ¶
CancelJob aborts a queued or running job. The cancellation is attributed to the caller: the job's CancelCause reports CancelCaller, distinguishing a deliberate cancel (this call, including the httpapi cancel route) from the CancelShutdown cancellations Close produces.
func (*Engine) CatalogInfo ¶
func (e *Engine) CatalogInfo() CatalogInfo
CatalogInfo reports the live catalog's provenance and freshness: what is loaded (refs, generation timestamp, entry count), where it came from (baked file, refresh cache, live fetch), the last refresh error, and whether the background schedule is running.
func (*Engine) Close ¶
func (e *Engine) Close()
Close stops the catalog-refresh schedule and any apt-index refresh a search started, then the job worker (cancelling any running job and draining the queued ones), and returns once those three have exited. Every job it cancels reports CancelShutdown as its CancelCause, so a consumer can tell an ordinary shutdown from an operator's deliberate cancel.
func (*Engine) EnsureInstalled ¶
EnsureInstalled synchronously guarantees a tool: present in the manifest (created from the catalog when missing), enabled, installed with its dependencies as Reconcile would leave them, and on PATH. This is the programmatic "a product action needs this binary now" path (a forge login installing gh, an MCP flow installing node); unlike Install it DOES enable a disabled template, because the user explicitly invoked the feature that needs the tool.
func (*Engine) Install ¶
Install re-enqueues an install for an existing, enabled tool (retry / install-missing). Installing a disabled template is refused with ErrDisabled: install is policy-neutral, enabling rides Patch.
func (*Engine) Inventory ¶
Inventory assembles the full read-side snapshot: every manifest entry joined with install state, the system group, and the active job.
func (*Engine) Patch ¶
func (e *Engine) Patch(name string, req PatchRequest) (*Job, error)
Patch merges fields into an existing tool and enqueues the job the transition needs: enable → install (when missing); disable → footprint uninstall (template kept); on an enabled tool, a version or python change → reinstall, an apt: pin change where apt is available → install (applies the dpkg hold), a requires change naming a dependency with no enabled row → install (adopts or enables it). Returns nil when no job is needed.
func (*Engine) Reconcile ¶
func (e *Engine) Reconcile(mode ReconcileMode) (jv *Job, enqueued bool, err error)
Reconcile enqueues the convergence job (see ReconcileMissing and ReconcileFull). A queued reconcile is returned rather than duplicated and a full queue never refuses one, so err means a manifest read failure or shutdown.
enqueued is false, with a nil job and a nil error, when the manifest is empty and no state row exists; a readiness gate branches on enqueued first.
func (*Engine) RefreshCatalog ¶
RefreshCatalog enqueues a catalog-refresh job: fetch the published catalog, verify it, persist it to the refresh cache, and swap it in. Returns ErrRefreshNotConfigured when Config.Refresh is nil. The returned job is observable like any other (jobs API, callbacks); Wait on it to gate on completion.
func (*Engine) Remove ¶
Remove uninstalls a tool and deletes its template. A tool that enabled entries require is REFUSED with *DependentsError, and the dependents are returned so a caller can name them; RemoveWithDependents is the cascading sibling that removes them too. The removed manifest entries travel on the uninstall job so source-specific cleanup (npm/pip uninstalls, manual uninstall commands) still knows the sources after the manifest rows are gone.
Two methods rather than one force flag, on the os.Remove / os.RemoveAll precedent: at a call site `Remove(name, true)` said nothing about what the second argument widened, and the wider operation deletes OTHER tools the caller never named.
func (*Engine) RemoveWithDependents ¶
RemoveWithDependents uninstalls a tool together with every enabled entry that needs it, directly or through another entry (disabled or not) or a catalog tool their install would add, and deletes their entries; a disabled entry between them stays. The returned job carries every removed name and dependents reports which rode along. With A requiring B and B requiring name, it removes all three. Prefer Remove unless the caller has already established that removing the dependents is intended; nothing here re-checks that.
func (*Engine) ReplaceManifest ¶ added in v3.15.0
ReplaceManifest writes content verbatim as tools.json under the store lock, then enqueues a ReconcileMissing pass. It writes nothing and returns the refusal when check (nil accepts) refuses the bytes on disk (nil when the file is absent or not a regular file), when check is set and a file there cannot be read (the read's error), when ParseManifest refuses content, or when content drops a row the current manifest holds and the live catalog marks essential (ErrEssential, naming the tool).
func (*Engine) Search ¶
func (e *Engine) Search(query string) []CatalogEntry
Search queries the catalog (empty query = featured set), hiding entries already in the manifest.
The returned entries alias the catalog: do not mutate their slice fields (see CatalogEntry).
func (*Engine) SearchApt ¶ added in v3.1.0
SearchApt ranks Debian packages against a query.
ok=false means no package list is available. A consumer must render that differently from an empty result, because "apt search is unavailable" and "no package matches" look identical and mean opposite things. Which of the two reasons it was is AptState, on SearchCounts; a consumer that tells a reader anything about apt wants that rather than this bool.
The first call triggers a background refresh and returns whatever is loaded, which on a cold engine is nothing. That is deliberate: a search request must not block on a network round trip, and the refresh is lazy precisely so a headless consumer that never searches never pays for the index at all.
func (*Engine) SearchUnavailable ¶ added in v3.1.0
func (e *Engine) SearchUnavailable(query string) []CatalogEntry
SearchUnavailable ranks the catalog entries no install source exists for (see Catalog.Unavailable), filtered like Search so a name the user already has by some other route is not offered as uninstallable.
The returned entries alias the catalog: do not mutate their slice fields (see CatalogEntry).
func (*Engine) SearchWithCounts ¶ added in v3.3.0
func (e *Engine) SearchWithCounts(query string) SearchCounts
SearchWithCounts answers one query from every corpus at once. It is what a consumer building one reply calls, so the per-package work behind Apt (see aptHitsWithCandidate) runs once per request; Engine.Search, Engine.SearchUnavailable and Engine.SearchApt are its projections.
func (*Engine) SyncManifest ¶ added in v3.15.0
SyncManifest adopts tools.json as the caller read it: seen holds a regular file's bytes (non-nil, possibly empty) and is nil otherwise. It does nothing and reports false when the file no longer holds that read. A valid file the engine did not write, or one an engine write folded a hand edit into, is applied; an absent one becomes the seed, written back. Both report true and enqueue a ReconcileMissing pass. A failed seed write returns its error and adopts nothing, so the caller's next read retries it. An unreadable file is refused and its error returned. A polling caller passes an absent or unreadable read only once two consecutive polls saw it; until then reads keep the applied manifest.
func (*Engine) Update ¶
Update enqueues an update job over every unpinned, enabled tool (or the given names).
type GitHubRateLimit ¶ added in v3.7.0
type GitHubRateLimit struct {
// ResetAt is when GitHub allows the next request, in Unix
// milliseconds: a minute after the refusal for a secondary limit
// that names no time, absent for a primary one that names none.
ResetAt int64 `json:"reset_at,omitempty"`
// Limit is X-RateLimit-Limit, absent when GitHub did not send it.
Limit int `json:"limit,omitempty"`
Authenticated bool `json:"authenticated"`
Secondary bool `json:"secondary,omitempty"`
}
GitHubRateLimit is the wire form of a GitHubRateLimitError.
type GitHubRateLimitError ¶ added in v3.7.0
type GitHubRateLimitError struct {
// Reset is the earliest time GitHub allows another request: a minute
// after the refusal for a secondary limit that names no time, zero
// for a primary one that names none.
Reset time.Time
// Limit is the X-RateLimit-Limit quota, 0 when GitHub did not send it.
Limit int
// Authenticated reports whether the refused request carried a token.
Authenticated bool
// Secondary marks GitHub's secondary (abuse) limit, not the hourly quota.
Secondary bool
}
GitHubRateLimitError is the ErrGitHubRateLimited shape. The engine neither retries nor waits on it. Until Reset, and for at least a minute, a GitHub API request with the refused credential (the same token, or no token after an anonymous refusal) gets a copy of it without being sent.
func (*GitHubRateLimitError) Error ¶ added in v3.7.0
func (e *GitHubRateLimitError) Error() string
func (*GitHubRateLimitError) Is ¶ added in v3.7.0
func (*GitHubRateLimitError) Is(target error) bool
Is makes errors.Is(err, ErrGitHubRateLimited) match.
func (*GitHubRateLimitError) Wire ¶ added in v3.7.0
func (e *GitHubRateLimitError) Wire() GitHubRateLimit
Wire returns e in the form Job.RateLimit carries.
type InstallSpec ¶
type InstallSpec struct {
URL string
// Format is the canonical aqua format name (tar.gz, zip, gz, raw, ...):
// the definition's own when it declares one, a short spelling such as
// tgz mapped onto its long name (canonicalFormat), else read off the
// asset name's extension (splitAssetFormat). Never empty.
Format string
ChecksumURL string // empty = nothing to fetch; see ChecksumDeclared
ChecksumAlg string
Files []AquaFile
// SearchFiles marks the Files paths as GUESSES: when one is missing,
// the install dir is searched for a same-named file instead of
// failing. Only the release source sets it — an aqua definition is
// authored against the artifact, so a missing declared path there is
// a registry bug that searching would bury; a release publishes no
// content manifest at all, so nothing was authored to search against.
SearchFiles bool
// ChecksumDeclared records that the definition DECLARES checksum
// verification for this version (a checksum block that upstream did
// not disable). It travels separately from ChecksumURL so the
// install path can tell "this artifact is not meant to be verified"
// from "verification was declared and we failed to obtain it" — the
// second must refuse the install, never install unverified.
ChecksumDeclared bool
}
InstallSpec is the fully resolved plan for downloading one tool version on this machine: a URL, an archive format, the binaries to link, and an optional checksum source.
type Inventory ¶
type Inventory struct {
Job *Job `json:"job,omitempty"`
Tools []ToolInfo `json:"tools"`
System []SystemTool `json:"system"`
// AptPackages are installed Debian packages with no manifest row: the
// ones a user or an agent installed themselves. Absent when apt is not
// this host's package manager, or when the enumeration failed — an
// inventory that cannot answer says nothing rather than reporting an
// empty box as a fact.
AptPackages []AptPackage `json:"apt_packages,omitempty"`
}
Inventory is the full read-side snapshot: every manifest entry joined with state, the system group, and the active job.
type Job ¶
type Job struct {
// RateLimit is set alongside ErrorCode github_rate_limited.
RateLimit *GitHubRateLimit `json:"rate_limit,omitempty"`
ID string `json:"id"`
Kind string `json:"kind"`
State string `json:"state"`
Error string `json:"error,omitempty"`
// ErrorCode classifies Error for a client; empty when the failure has
// no code (ErrorCodeGitHubRateLimited is the one defined).
ErrorCode string `json:"error_code,omitempty"`
Names []string `json:"names,omitempty"`
// CancelCause names who cancelled the job (State JobCancelled only).
// Additive on the wire: omitted whenever the cause is unknown, so a
// consumer that ignores the field sees exactly the payload it saw
// before — JobCancelled keeps its meaning and value.
CancelCause CancelCause `json:"cancel_cause,omitempty"`
// OutputTail carries the job's most recent output lines; populated
// by Jobs() snapshots only (live output streams via the
// Config.OnJobOutput callback).
OutputTail []string `json:"output_tail,omitempty"`
// Timestamps are Unix milliseconds.
CreatedAt int64 `json:"created_at"`
StartedAt int64 `json:"started_at,omitempty"`
EndedAt int64 `json:"ended_at,omitempty"`
// contains filtered or unexported fields
}
Job is one queued/running/finished unit of engine work.
func (*Job) Err ¶ added in v3.7.0
Err returns the error that failed the job: nil unless State is JobFailed, and nil for a timeout, which Error alone describes. errors.As reaches a *GitHubRateLimitError through it. Err is not on the wire; a client reads ErrorCode and RateLimit.
type Manifest ¶
type Manifest struct {
Tools map[string]Tool `json:"tools"`
// Comment is a single reserved documentation key preserved across
// engine rewrites (seed how-to text). Other unknown JSON keys are
// NOT preserved; the manifest is not a general round-tripping
// document.
Comment []string `json:"_comment,omitempty"`
Version int `json:"version"`
}
Manifest is the tools.json document (schema ManifestVersion).
func DefaultSeed ¶
func DefaultSeed() *Manifest
DefaultSeed returns a fresh copy of the shared starter manifest: the officially supported language servers for Go, TypeScript, Python and Rust, all disabled. Nothing downloads until enabled; install knowledge hydrates from the catalog at enable time.
Backend runtimes and required packages are deliberately NOT seeded: the engine adopts a missing dependency at install time, so a seeded row would only be a second place for its version to drift.
func ParseManifest ¶ added in v3.8.0
ParseManifest decodes and validates a tools.json document exactly as the engine reads the file, ignoring one leading UTF-8 byte-order mark. A JSON parse error, a version other than ManifestVersion, an invalid tool name, a version its source's grammar refuses, or a python request that is not a bare version or sits on a non-pip: source is an error. A consumer that writes tools.json on a user's behalf calls it first, because a document it refuses fails New at the next start. Every error matches ErrManifestInvalid.
type MatchKind ¶ added in v3.2.0
type MatchKind string
MatchKind names WHICH field a search query hit. It is the one ranking fact a client cannot re-derive: aliases do not travel on the wire, so from the outside a hit on `rg` is indistinguishable from a description match on ripgrep's summary.
It exists because a description hit is both the weakest kind and by far the most numerous — "python" appears in the description of every tool written in Python — so a consumer that groups, labels or filters results needs to tell it from the rest.
const ( // MatchNone is the zero value: the query hit nothing, or there was // no query to hit anything with. MatchNone MatchKind = "" // MatchName is a hit on the entry's own name. MatchName MatchKind = "name" // MatchAlias is a hit on one of the entry's aliases. MatchAlias MatchKind = "alias" // MatchDescription is a hit on the description only. MatchDescription MatchKind = "description" )
The kinds, ordered by how strongly they answer the query.
func Match ¶ added in v3.2.0
Match reports how query hits an entry, and how strongly, on one scale every corpus this package searches shares.
ONE function rather than one per corpus. The catalog and the Debian package list carried byte-identical tier tables that differed only in that a package has no aliases, and two copies of a ranking rule is how a merged response ends up ordered by neither of them. Pass a nil alias slice for a corpus that has none.
Score 0 means no match and pairs with MatchNone; every other score is strictly ordered, so a caller merging two corpora sorts on it directly (see CompareRank). An empty query scores 0: it selects the featured set rather than matching anything, and that set carries its own order.
type PatchRequest ¶
type PatchRequest struct {
Version *string `json:"version,omitempty"`
Pin *bool `json:"pin,omitempty"`
Disabled *bool `json:"disabled,omitempty"`
Description *string `json:"description,omitempty"`
Requires *[]string `json:"requires,omitempty"`
Install *string `json:"install,omitempty"`
Uninstall *string `json:"uninstall,omitempty"`
// Python sets Tool.Python; "" clears it. A change on an enabled entry
// reinstalls it.
Python *string `json:"python,omitempty"`
// VersionArgs sets Tool.VersionArgs, taking effect at the next probe with
// no job. An empty list clears them, so the probe only requires an answer
// to --version (a source-less template takes the catalog's when hydrated).
VersionArgs *[]string `json:"version_args,omitempty"`
// Force permits disabling a tool that enabled entries require,
// cascading the disable to every enabled entry that needs it, directly
// or through another (the set RemoveWithDependents takes).
Force bool `json:"force,omitempty"`
}
PatchRequest edits an existing tool. Pointer fields distinguish "absent" from zero values. Disabled is the enable/disable toggle: false→true uninstalls the engine-owned footprint and keeps the template; true→false installs.
type Rank ¶ added in v3.2.0
Rank is a scored hit's ordering key: what CompareRank needs and nothing else, so the same comparison serves corpora with different hit types.
type ReconcileMode ¶
type ReconcileMode int
ReconcileMode selects how much a Reconcile job does.
const ( // ReconcileMissing converges intent without network: installs // missing enabled entries, those installed at another version than // the manifest names or, for apt:, than dpkg reports when pinned or // after a failed install, and dependencies with no enabled entry, // sets each apt: entry's dpkg hold to its pin, uninstalls the // engine-owned footprint of disabled entries and orphaned state rows // no install needs. Zero fetches when already converged. ReconcileMissing ReconcileMode = iota // ReconcileFull is ReconcileMissing plus an update pass over // unpinned entries (enqueued as a separate update job). ReconcileFull )
type RefreshEnv ¶
type RefreshEnv string
RefreshEnv is the RAW VALUE a consumer read from its catalog-refresh env variable — "24h", "off", or "" when the variable is unset.
It is a distinct type from RefreshEnvName because ParseCatalogRefresh takes both: as two adjacent strings, a transposed call would parse the variable's NAME as a duration and silently fall back to DefaultCatalogRefresh while the warning named the value.
type RefreshEnvName ¶
type RefreshEnvName string
RefreshEnvName is the NAME of that env variable ("TOOLS_CATALOG_REFRESH"). It is carried for one reason only: so a fallback or clamp warning can tell the operator which variable to fix.
type ReleaseHints ¶ added in v3.1.0
type ReleaseHints struct {
// Matching narrows the candidate set by substring BEFORE the heuristic
// runs. It is the one selection hint that matters: the restate
// repository publishes restate-server, restate-cli and restatectl, and
// these are three separate tools whose assets no file-name heuristic
// can attribute.
Matching string `json:"matching,omitempty"`
// Bin and BinPath name the executable INSIDE the artifact: Bin a file
// name that differs from the published one, BinPath a directory to
// look in. helm-diff is the case both exist for — the archive holds
// `diff/bin/diff` and the tool is published as `helm-diff`.
Bin string `json:"bin,omitempty"`
BinPath string `json:"bin_path,omitempty"`
// Bins are the names this tool publishes on PATH, carried only when
// they differ from the tool's own name (40 of 158 entries) — a
// release ships whatever upstream's build produced: `qdns` is the
// registry's name for `natesales/q`, whose binary is `q`.
//
// A set rather than one name because 14 of those 40 publish several
// (kotlin ships six kotlinc variants). An absent one is skipped
// rather than fatal, since a stale list must still install what IS
// there.
Bins []string `json:"bins,omitempty"`
}
ReleaseHints are the install hints a registry entry carries for a release-backed tool, compiled into the catalog rather than guessed: the four fields (of 26 hint-bearing entries) that state something the heuristic cannot derive from a file name alone — which of several binaries in one repository is this tool, and where the executable sits inside the artifact.
The registry's `asset_pattern` is deliberately NOT among them (least-mechanism, not omission): its 8 users write three different template dialects, and the heuristic already picks the right asset for all 8 against their real release file lists, so a template evaluator would buy nothing.
func (*ReleaseHints) IsZero ¶ added in v3.1.0
func (h *ReleaseHints) IsZero() bool
IsZero reports whether the hints carry nothing, so a catalog entry can omit the object entirely rather than emitting an empty one.
Exported because the catalog COMPILER is the only caller: it decides per entry whether there is a hint worth writing, and duplicating the field list there is how a fifth hint gets added to one side and not the other.
type RootIntegrityError ¶
type RootIntegrityError struct {
// Findings is every offending path with its reason, sorted by path
// then reason so the same bad volume always reports identically.
Findings []RootIntegrityFinding
}
RootIntegrityError is the ErrRootIntegrity shape that names every offending root. Compare with errors.Is(err, ErrRootIntegrity) to classify the failure; recover it with errors.As to read the individual findings (a consumer that warns and runs tool-less needs the detail; a consumer that treats the class as fatal does not).
func (*RootIntegrityError) Error ¶
func (e *RootIntegrityError) Error() string
func (*RootIntegrityError) Is ¶
func (*RootIntegrityError) Is(target error) bool
Is makes errors.Is(err, ErrRootIntegrity) match.
type RootIntegrityFinding ¶
type RootIntegrityFinding struct {
// Path is the offending directory as the check inspected it:
// ConfigDir, ToolsDir, or one of the directories beneath ToolsDir.
Path string
// Reason states the first thing that disqualified it, in operator
// terms ("is a symlink", "is not under this process's exclusive
// control: /tools, mode 0775, can be modified by gid 1001").
Reason string
}
RootIntegrityFinding is one managed root that failed the integrity check, and why.
type SearchCounts ¶ added in v3.3.0
type SearchCounts struct {
// AptState says WHY the package list did or did not answer; see
// [AptState]. AptAvailable is the same verdict narrowed to a bool.
// It leads the struct because govet's fieldalignment wants the
// smaller pointer-bearing field ahead of the slices.
AptState AptState
// Installable is what [Engine.Search] returns: catalog entries with
// an install source, minus those already in the manifest.
Installable []CatalogEntry
Unavailable []CatalogEntry
// Apt is what [Engine.SearchApt] returns; empty when AptAvailable is
// false.
Apt []AptHit
// InstallableMatched is how many entries Installable would hold had
// nothing cut it.
InstallableMatched int
// nothing cut it.
UnavailableMatched int
// AptMatched is how many packages Apt would hold had nothing cut it.
AptMatched int
// AptAvailable is the bool [Engine.SearchApt] returns: false means
// the package list could not be consulted, which a consumer must
// render differently from an empty Apt.
AptAvailable bool
}
SearchCounts is one query answered from every corpus the engine searches, each block cut to its cap beside the count it had before the cut. A block is cut iff its Matched count exceeds its length; nothing else reports a cut.
The catalog entries alias the catalog: do not mutate their slice fields (see CatalogEntry).
type SeenKind ¶ added in v3.15.0
type SeenKind uint8
SeenKind is what a caller's read of tools.json found.
type State ¶
type State struct {
Tools map[string]ToolStatus `json:"tools"`
}
State is the tools-state.json document.
type SystemTool ¶
SystemTool is one image-baked binary surfaced read-only (Config.System).
type Tool ¶
type Tool struct {
// Release carries the registry's install hints for a release-backed
// tool (see ReleaseHints). Hydrated from the catalog; a user editing
// the manifest by hand needs none of it, because the matcher's
// heuristic is what runs without one.
Release *ReleaseHints `json:"release,omitempty"`
// Source locates the install definition: "aqua:cli/cli",
// "npm:pyright", "pip:x", "cargo:x", "go:golang.org/x/tools/gopls",
// or "manual". Empty = hydrate from the catalog.
Source string `json:"source,omitempty"`
// Version is the concrete version exactly as its source spells it —
// a forge tag or registry semver for most kinds, a Debian version
// (epoch and all) for apt:, a PEP 440 version for pip:. Never a
// range; the legal alphabet per source is versionpolicy.go.
// Empty = resolve latest when the tool is actively installed.
Version string `json:"version,omitempty"`
// Description is display text (catalog-provided or user-written).
Description string `json:"description,omitempty"`
// Origin records provenance for linked entries, e.g. "mcp:<name>"
// for a tool created from an MCP add flow.
Origin string `json:"origin,omitempty"`
// Install is the shell command for Source == "manual". It runs via
// bash with VERSION, BIN, TOOLS, OPT and ARCH_* in the environment.
Install string `json:"install,omitempty"`
// Uninstall optionally overrides cleanup for Source == "manual".
Uninstall string `json:"uninstall,omitempty"`
// Probe is the bin name whose presence marks the tool installed
// (manual installs only; other sources derive it). Defaults to the
// tool name.
Probe string `json:"probe,omitempty"`
// Python is the uv interpreter request for a pip: entry, a bare
// version such as "3.14", passed as `uv tool install --python`. Empty
// builds on the newest engine-managed interpreter (or uv's newest
// download). Only a pip: or not-yet-hydrated entry may carry one.
Python string `json:"python,omitempty"`
// Requires lists other manifest/catalog tool names that must be
// installed before (or alongside) this one, e.g. jdtls -> java.
// Backend-level needs (npm->node, pip->uv, cargo->rust, go->go)
// are implied and need not be listed.
Requires []string `json:"requires,omitempty"`
// VersionArgs are the arguments that make this tool print its
// version, e.g. ["--version"] or ["version"]. Declaring them makes
// the install probe verify the ANSWER: the tool is executed and its
// output must contain the recorded version, so a binary that is
// present but is the wrong version counts as not installed and is
// reinstalled. Empty means the probe runs the tool with --version
// and only requires that it answers at all (the version stays
// unproven). Hydrated from the catalog when unset.
VersionArgs []string `json:"version_args,omitempty"`
// Pin freezes the version: update runs skip this tool.
Pin bool `json:"pin,omitempty"`
// Disabled marks the entry a template: recorded intent whose
// install is explicitly bypassed. The reconciler uninstalls a
// disabled tool's engine-owned footprint and keeps the entry.
// Absent (false) means enabled — presence in the manifest is
// intent to have the tool installed.
Disabled bool `json:"disabled,omitempty"`
}
Tool is one manifest entry: the user's intent for a single tool. Every field except the map key (the tool name) is optional; empty Source/Version/Requires hydrate from the catalog when the tool is installed or updated.
type ToolInfo ¶
type ToolInfo struct {
Name string `json:"name"`
Source string `json:"source,omitempty"`
Version string `json:"version,omitempty"`
Description string `json:"description,omitempty"`
Origin string `json:"origin,omitempty"`
InstalledVersion string `json:"installed_version,omitempty"`
Latest string `json:"latest,omitempty"`
LastError string `json:"last_error,omitempty"`
// Checksum reports how the INSTALLED artifact's integrity was
// established (copied from ToolStatus.Checksum): "verified" or
// "unverified" per the definition's declared checksum source, empty
// when the question does not apply (not installed, or a source with
// no artifact to checksum). A "no checksum" badge reads THIS, not
// the source kind — 252 of the catalog's aqua entries declare no
// checksum while the other 402 do.
Checksum string `json:"checksum,omitempty"`
Requires []string `json:"requires,omitempty"`
// Commands names what an installed row puts on PATH, sorted: the bin
// names the engine linked for it or, for an apt: row, the entries dpkg
// records it placing directly in /usr/bin, /usr/sbin, /bin or /sbin.
// Empty when the row is not installed or ships no command (a library).
Commands []string `json:"commands,omitempty"`
// Dependents names the ENABLED entries that need this tool, directly
// (Requires or the implied backend of their source kind) or through
// another entry, disabled or not, or a catalog tool their install would
// add: the set a 409 names and a forced disable or remove takes, for a
// consumer to show BEFORE sending one. Advisory
// only: the engine re-derives the set under the manifest lock, so a
// stale inventory is still refused.
Dependents []string `json:"dependents,omitempty"`
Pin bool `json:"pin,omitempty"`
Disabled bool `json:"disabled,omitempty"`
// Essential marks a tool this application NEEDS: the engine
// refuses to remove it (ErrEssential), so a consumer renders it apart
// from the tools a user chose and offers no delete control. Disable
// remains available, which is the honest escape hatch.
Essential bool `json:"essential,omitempty"`
// Lsp marks a language-server entry (catalog knowledge); consumers
// use it for the no-LSP-enabled warning and UI badges.
Lsp bool `json:"lsp,omitempty"`
Installed bool `json:"installed"`
Installing bool `json:"installing"`
}
ToolInfo is one tool row in Inventory: the manifest entry joined with the engine's install state.
type ToolStatus ¶
type ToolStatus struct {
// UpdatedAt is when this status last changed.
UpdatedAt time.Time `json:"updated_at"`
// InstalledVersion is the version last installed successfully.
InstalledVersion string `json:"installed_version,omitempty"`
// Python is the Tool.Python request the installed venv was built
// with; a manifest request that differs makes the next install rebuild it.
Python string `json:"python,omitempty"`
// LastError is the failure message of the most recent install
// attempt; cleared on success.
LastError string `json:"last_error,omitempty"`
// Checksum records how the installed artifact's integrity was
// established: "verified" (the definition declared a checksum
// source and the digest matched) or "unverified" (it declared
// none). Empty for sources without artifact checksums (npm, pip,
// cargo, go, manual). This is the durable answer to "was this tool
// installed unverified?".
Checksum string `json:"checksum,omitempty"`
// Bins are the names this tool owns in the bin dir (symlinks),
// removed on uninstall.
Bins []string `json:"bins,omitempty"`
// PMBins are package-manager bin names discovered by diffing the
// pm's bin dir (npm/pip), symlinked into the bin dir.
PMBins []string `json:"pm_bins,omitempty"`
}
ToolStatus is the engine-owned per-tool machine state.
Source Files
¶
- apt.go
- aptcommands.go
- aptdiscover.go
- aptindex.go
- aqua.go
- catalog.go
- catalogrefresh.go
- durability.go
- engine.go
- extract.go
- githubapi.go
- install.go
- jobs.go
- layout.go
- manifest.go
- manifest_owner.go
- pathcomponent.go
- probe.go
- release.go
- releaseinstall.go
- rootintegrity.go
- systembin.go
- toolbelt.go
- versionpolicy.go
- versions.go
- wire.go
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
toolcatalog
command
Command toolcatalog compiles a toolbelt tool catalog from registry data (the mise + aqua-registry projects, both MIT) into one tool-catalog.json an Engine loads read-only, and verifies a compiled catalog against a consumer's required tool set.
|
Command toolcatalog compiles a toolbelt tool catalog from registry data (the mise + aqua-registry projects, both MIT) into one tool-catalog.json an Engine loads read-only, and verifies a compiled catalog against a consumer's required tool set. |
|
Package httpapi is the HTTP projection of a toolbelt Engine: one REST route per Engine method, JSON in and out, no auth and no SSE.
|
Package httpapi is the HTTP projection of a toolbelt Engine: one REST route per Engine method, JSON in and out, no auth and no SSE. |
|
internal
|
|
|
custody
Package custody judges whether a directory is under this process's exclusive control: it and every directory on the way to it, through every symlink, belong to this uid or root and nobody else can write them, by mode or by POSIX.1e or NFSv4 access-control list.
|
Package custody judges whether a directory is under this process's exclusive control: it and every directory on the way to it, through every symlink, belong to this uid or root and nobody else can write them, by mode or by POSIX.1e or NFSv4 access-control list. |
|
retain
Package retain is the install engine's retention rule and version-directory order: keep the active version and the keep most recently activated predecessors that could serve.
|
Package retain is the install engine's retention rule and version-directory order: keep the active version and the keep most recently activated predecessors that could serve. |
|
unpack
Package unpack extracts a verified archive through an os.Root.
|
Package unpack extracts a verified archive through an os.Root. |
|
Package pin installs, activates and maintains one digest-pinned upstream release under <Root>/<Name>-versions/<version>/: populated only from a verified archive, published by one same-filesystem rename and marked by a ".complete" sentinel written last, so an interrupted install is never a selection candidate.
|
Package pin installs, activates and maintains one digest-pinned upstream release under <Root>/<Name>-versions/<version>/: populated only from a verified archive, published by one same-filesystem rename and marked by a ".complete" sentinel written last, so an interrupted install is never a selection candidate. |