registry

type Checker ¶ added in v0.6.0

type Checker interface{ Check() error }

Checker is implemented by an input type that can refuse a value from the input alone: no API, no clock, no configuration. Validate runs it after the strict decode, so the CLI refuses a bad argument before it loads the configuration or starts the credential wrapper (a secret-manager unlock). A check that needs anything else belongs in the tool's run function.

On the command line, Check runs before the binder fills the fields that are read from a file or from standard input, so a rule over loaded text lives in the run function. Such a field must be omitempty (optional in the schema), because Validate runs before it is set.

type ClassCount ¶ added in v0.6.0

type ClassCount struct {
	Class    string
	Count    int
	Expected bool // Tailscale-written constructs: expected, and a drift check may ignore them
}

ClassCount is the number of changes of one class.

type Computes ¶ added in v0.6.0

type Computes interface{ FailOnKinds() []string }

Computes is implemented, with a value receiver, by a Gated result type whose tool fills only some of the counts of Findings. FailOnKinds names the --fail-on tokens the tool computes ("warnings", "tests-reduced", "defaults", "widening", "change"), at least one. The command refuses a token outside the list before anything loads, because a gate on a count that is always 0 never fires and a pipeline that relies on it would stay green for good. A Gated type that does not implement Computes computes all five.

type ComputesOffline ¶ added in v0.6.0

type ComputesOffline interface{ OfflineFailOnKinds() []string }

ComputesOffline is implemented, with a value receiver, by a Computes result type whose tool fills fewer kinds when the command line asks for --offline, where nothing is read from the tailnet and nothing is compared with the live policy. OfflineFailOnKinds names the tokens it fills then, which may be none. The command refuses any other token with --offline, for the reason Computes gives: a gate that cannot fire is a pipeline that stays green. A result type without it computes the same kinds offline as online.

type Credential ¶

type Credential string

Credential is the credential class a tool uses (spec §7.1).

const (
	CredRead Credential = "read"
	CredNone Credential = "none"
	// CredOptional is for a read tool that can also run without a credential, for
	// example on two local files. The input type says when, through OfflineInput.
	CredOptional Credential = "optional"
)

type Env ¶

type Env struct {
	API      *api.Client // nil when no credential is configured; APIErr says why
	APIErr   error
	Local    *local.Runner // nil when no tailscale CLI was found; LocalErr says why
	LocalErr error
	Config   *config.Loaded
	// Privacy names masked values and keys audit-log digests (spec §7.6); nil
	// when no key was provided, and PrivacyErr then says why if one was malformed.
	Privacy    *privacy.Key
	PrivacyErr error
	Now        func() time.Time
}

Env is everything a tool may use at run time.

func (e *Env) Clock() time.Time

func (e *Env) Display(ptr any)

func (e *Env) Masker() sanitize.Masker

func (e *Env) PersonalRefs(s string) []string

func (e *Env) RequireAPI() (*api.Client, error)

func (e *Env) RequireLocal() (*local.Runner, error)

func (e *Env) RequirePrivacy() (*privacy.Key, error)

func (e *Env) ShowPersonalData() bool

func (e *Env) UntrustedRefs(s string) []string

type ExitCoder ¶ added in v0.6.0

type ExitCoder interface{ ExitCode() int }

ExitCoder is implemented by a typed result whose verdict decides the CLI's exit code. ExitCode reads the verdict alone, never message text: 0 for a pass, 1 for an answer that is unknown, 9 for a failed test or invariant, 2 for input that is invalid, rejected or unresolved. The CLI applies the exit policy to it (see Gated), and MCP ignores it: an MCP caller reads the result's status field.

type Fact ¶ added in v0.6.0

type Fact struct {
	Label string
	Text  string
}

Fact is one statement of a Report under its label.

type Finding ¶ added in v0.6.0

type Finding struct {
	// Severity is "error", "warning" or "notice".
	Severity string
	// Source says which input the location is in: "from", "against", "patch" or
	// "invariants" (the flag that named the file), "live" for the live policy, or
	// empty for none. The CLI replaces it with the path the user typed.
	Source       string
	Line, Column int    // 1-based; 0 when unknown
	Pointer      string // a JSON pointer to the element, when the line is not known
	Message      string
	// Untrusted marks Tailscale's own text: the layout prints it behind a notice.
	Untrusted bool
}

Finding is one located problem or note.

type Findings ¶ added in v0.6.0

type Findings struct {
	NewWarnings  int // warnings the proposal adds to the baseline (--fail-on warnings)
	TestsReduced int // tests or SSH tests removed or weakened (tests-reduced)
	Defaults     int // acls, grants or ssh moving between absent, empty and non-empty (defaults)
	Widenings    int // structural widenings (widening)
	Changes      int // any defaults or semantic change, Tailscale-written constructs included unless ignored (change)
}

Findings counts what a result found, in the kinds the CLI's --fail-on names. A tool computes every count over all of its changes, not over the page of them that the result shows, so a gate cannot be passed by paging.

type Gated ¶ added in v0.6.0

type Gated interface{ Findings() Findings }

Gated is implemented by a typed result that --fail-on can gate. A command whose output type implements it takes --fail-on; one that does not has no such flag. A count the tool does not compute is 0 (see Findings), and the command refuses a --fail-on token for it when the result type says which kinds it computes (Computes).

Precedence when several apply: exit 1, then 9, then 2, then 8, then 0. The result's own code (ExitCoder) is 0, 1, 2 or 9; a gate that matches turns an otherwise successful run into exit 8, findings_present, and never hides a code that outranks it.

type Given ¶ added in v0.6.0

type Given map[string]bool

Given says which CLI input flags a command line set, by flag name without the dashes ("from", "against", "patch", "invariants", "no-invariants", "offline"). A flag whose value names the live policy ("--against live") counts as not set. MCP calls have no flags: Given only serves the CLI's decision whether to start the credential wrapper.

type Level ¶ added in v0.6.0

type Level string

Level is how serious a verdict is, for the colour a terminal shows it in.

const (
	LevelOK   Level = "ok"   // the answer is yes
	LevelWarn Level = "warn" // yes, with something to read
	LevelFail Level = "fail" // the answer is no, or no answer
)

type Meta ¶

type Meta struct {
	Name       string
	Area       string // CLI group, e.g. "devices"
	Verb       string // CLI command, e.g. "list"
	Summary    string
	Tier       Tier
	Stage      Stage
	PlanGate   string // documented plan gating; "" means all plans
	Credential Credential
	Scopes     []string // minimal OAuth scopes, companions included
	// PartialScopes means each scope reads part of the result (settings fields,
	// key types): a missing one narrows the result instead of failing the tool.
	PartialScopes bool
	// OptionalScopes each enable one feature of the tool and are not needed for it to
	// run: the tool tries the feature and, on scope_missing, leaves it out and says
	// so. They are never read from the granted list (stale for federated identities).
	OptionalScopes []OptionalScope
	// Title is the name a host shows for the tool. Optional, except for OpenWorld tools.
	Title string
	// OpenWorld marks a tool that sends text the caller supplied (a proposed policy,
	// a test) to Tailscale: MCP advertises openWorldHint true for it, and its
	// description says the input leaves the machine.
	OpenWorld bool
	Notes     string // extra facts for the docs, e.g. an unverified scope
	// Operations are the API operations the tool calls, as "METHOD /path" with the
	// path spelled as Tailscale's OpenAPI document spells it (spec §20).
	Operations []string
	// MaxResultChars raises the result size an MCP host keeps for this tool
	// (Claude Code's anthropic/maxResultSizeChars); 0 leaves the default, which
	// list tools raise to 200,000 characters.
	MaxResultChars int
}

Meta is a tool's declared metadata.

type OfflineInput ¶ added in v0.6.0

type OfflineInput interface{ RunsOffline(g Given) bool }

OfflineInput is implemented by the input type of a tool whose Credential is CredOptional. RunsOffline says, from the flags the command line set, that the call will not touch the API.

type OptionalScope ¶ added in v0.6.0

type OptionalScope struct {
	Scope  string `json:"scope"`
	Reason string `json:"reason"` // what the scope enables, in one line
}

OptionalScope is an OAuth scope that enables one feature of a tool without being needed for the tool to run.

type Prepared ¶ added in v0.6.0

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

Prepared is an input that passed Validate, ready to run.

func (p *Prepared) Input() any

func (p *Prepared) NeedsCredential(g Given) bool

func (p *Prepared) Run(ctx context.Context, env *Env) (out any, err error)

func (p *Prepared) Tool() Tool

type Registry ¶

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

Registry holds tools by name.

func New() *Registry

func (r *Registry) Add(t Tool) error

func (r *Registry) All() []Tool

func (r *Registry) ByCommand(area, verb string) (Tool, bool)

func (r *Registry) Get(name string) (Tool, bool)

func (r *Registry) MustAdd(tools ...Tool)

func (r *Registry) Profile(profile string, enableAlpha bool) ([]Tool, error)

func (r *Registry) ReadScopes() []string

type Report ¶ added in v0.6.0

type Report struct {
	// Verdict is the first line: "VALID · 0 new warnings (3 existing) · 14 tests
	// passed · invariants: none". Empty prints nothing.
	Verdict string
	Level   Level
	// Facts are what the result states about itself, each under its own label ("note",
	// "posture"): tailkeeper's own sentences, never a tailnet's text. They are not
	// NotChecked, which names what the result does not answer.
	Facts []Fact
	// NotChecked names what the result does not answer ("lockout", "downgrades").
	NotChecked []string
	// Classes are the diff counts by class, in the order to show them: defaults,
	// tests reduced and widenings first.
	Classes []ClassCount
	// Findings are the located problems and notes, in the order to show them. (The
	// counts of Gated.Findings are another thing: a count a tool does not compute is
	// 0, and the command refuses the --fail-on token that names it; see Computes.)
	Findings []Finding
}

Report is the human layout of a typed result: the one shape every output format renders. The text layout is for people; every other format prints the same fields.

A tool builds it from its own result; the strings it holds have already been through the registry's escaping, and each formatter escapes again for its own syntax.

type Reporter ¶ added in v0.6.0

type Reporter interface{ Report() Report }

Reporter is implemented by a typed result with a human layout. A command whose output type implements it takes --format.

type Stage ¶

type Stage string

Stage is the documented release stage of the underlying Tailscale feature.

const (
	StageGA    Stage = "ga"
	StageBeta  Stage = "beta"
	StageAlpha Stage = "alpha"
)

type Tier ¶

type Tier string

Tier is a tool's base tier (spec §5).

const (
	TierRead           Tier = "read"
	TierLocal          Tier = "local"
	TierOffline        Tier = "offline"
	TierPrivilegedRead Tier = "privileged_read"
	TierReversible     Tier = "reversible"
	TierEscalation     Tier = "escalation"
	TierIrreversible   Tier = "irreversible"
)

type Tool ¶

type Tool struct {
	Meta            Meta
	InputType       reflect.Type
	OutputType      reflect.Type
	InputSchema     *jsonschema.Schema
	OutputSchema    *jsonschema.Schema
	UntrustedFields []string // JSON paths of untrusted output fields
	PersonalFields  []string // JSON paths of identifiers masked whole unless personalData is "show"
	PlainFields     []string // JSON paths of untrusted fields kept unmasked (configuration such as routes)
	EmailFields     []string // JSON paths of untrusted fields whose email addresses alone are masked
	// contains filtered or unexported fields
}

Tool is a registered tool.

func Define[In, Out any](m Meta, run func(ctx context.Context, env *Env, in In) (Out, error)) Tool

func (t Tool) Call(ctx context.Context, env *Env, raw json.RawMessage) (any, error)

func (t Tool) Validate(raw json.RawMessage) (*Prepared, error)