toolbelt

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"`
	Requires    []string `json:"requires,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"`
}

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 | ...
}

type AquaFile struct {
	Name string `json:"name" yaml:"name"`
	Src  string `json:"src,omitempty" yaml:"src"` // template; default = Name
}

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"`
}

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"`
}

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"`
}

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"`

	// Generated is the compile timestamp (RFC 3339 UTC), stamped by
	// cmd/toolcatalog (informational).
	Generated string `json:"generated,omitempty"`
	// contains filtered or unexported fields
}

type CatalogEntry struct {
	Aqua        *AquaPackage `json:"aqua,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"`
	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"`
}

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"`
	// 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"`
}

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
}

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().
	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)
	// Logger receives engine-level log lines. Nil means slog.Default().
	Logger *slog.Logger
	// Seed is the manifest written when none exists (fresh volume).
	// 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: the
	// engine fetches the published catalog at Refresh.URL (on the
	// engine-owned schedule when Interval is positive, and 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 (the pre-refresh behavior).
	Refresh *CatalogRefresh
	// CatalogOverlays are consumer overlay JSON files (see
	// ApplyOverlay) applied in order to every catalog the engine
	// loads: the baked file, the refresh cache, and each fetched
	// refresh. This keeps app-specific display patches independent of
	// the published artifact. Entries added by 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
}

type DependentsError struct {
	Dependents []string
}

type Engine struct {
	// contains filtered or unexported fields
}

type InstallSpec struct {
	URL         string
	Format      string // tar.gz | tar.xz | tar.zst | zip | gz | xz | raw
	ChecksumURL string // empty = no verification
	ChecksumAlg string
	Files       []AquaFile
}

type Inventory struct {
	Job    *Job         `json:"job,omitempty"`
	Tools  []ToolInfo   `json:"tools"`
	System []SystemTool `json:"system"`
}

type Job struct {
	ID    string   `json:"id"`
	Kind  string   `json:"kind"`
	State string   `json:"state"`
	Error string   `json:"error,omitempty"`
	Names []string `json:"names,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"`
}

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"`
}

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"`
	// Force permits disabling a tool that enabled entries require,
	// cascading the disable to those dependents (one level, mirroring
	// Remove's force cascade).
	Force bool `json:"force,omitempty"`
}

type ReconcileMode int

type State struct {
	Tools map[string]ToolStatus `json:"tools"`
}

type SystemTool struct {
	Name      string `json:"name"`
	Installed bool   `json:"installed"`
}

type Tool struct {
	// 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 upstream version, exactly as upstream
	// tags it (may or may not carry a leading v). Never a range.
	// 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"`
	// 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"`
	// 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"`
}

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"`
	Requires         []string `json:"requires,omitempty"`
	Pin              bool     `json:"pin,omitempty"`
	Disabled         bool     `json:"disabled,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"`
}

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"`
	// LastError is the failure message of the most recent install
	// attempt; cleared on success.
	LastError string `json:"last_error,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"`
}