cliadmin

Documentation

Overview

Package cliadmin contains command-line administration primitives that are independent of Sandbar's concrete CLI parser and renderer.

Index

• Variables
• func GenerateCompletion(shell CompletionShell, root CommandSpec) (string, error)
• func Path(scope ConfigScope, explicit string) (string, error)
• func ValidateCommandSpec(root CommandSpec) error
• type ArgumentSpec
• type CheckStatus
• type CommandSpec
• type CompletionShell
• type ConfigScope
• type DoctorCheck
• type DoctorOptions
• type DoctorReport
  • func RunDoctor(ctx context.Context, options DoctorOptions) DoctorReport
  • func (r DoctorReport) Human() string
  • func (r DoctorReport) JSON() ([]byte, error)
• type Field
  • func Get(scope ConfigScope, explicit, key string) (Field, error)
  • func Reset(scope ConfigScope, explicit, key string) (Field, error)
  • func Set(scope ConfigScope, explicit, key, rawValue string) (Field, error)
• type FlagSpec
• type Snapshot
  • func Read(scope ConfigScope, explicit string) (Snapshot, error)
• type ValidationResult
  • func Validate(scope ConfigScope, explicit string) (ValidationResult, error)
• type ValueHint
• type ValueType

Variables

var (
	// ErrCoreMutationUnsupported is returned by Set and Reset for the core
	// configuration. internal/config intentionally has no persistence API, so
	// cliadmin refuses to invent a second writer that could discard comments,
	// environment placeholders, or unknown future fields.
	ErrCoreMutationUnsupported = errors.New("core config is read-only: edit the YAML file directly, then run config validate")
)

Functions

func GenerateCompletion

func GenerateCompletion(shell CompletionShell, root CommandSpec) (string, error)

GenerateCompletion validates a command descriptor and emits a standalone completion script for bash, zsh, or fish.

func Path

func Path(scope ConfigScope, explicit string) (string, error)

Path resolves the configuration file for a scope. explicit follows config.Resolve semantics for the core scope. Client config has one canonical location and does not accept an override because ClientConfig.Save does not.

func ValidateCommandSpec

func ValidateCommandSpec(root CommandSpec) error

ValidateCommandSpec rejects ambiguous command trees and values that cannot be represented consistently by all three generated shell scripts.

Types

type ArgumentSpec

type ArgumentSpec struct {
	Name        string
	Description string
	Choices     []string
	Hint        ValueHint
	Repeatable  bool
}

ArgumentSpec describes a positional argument or a flag's value. Choices are shell-independent literal values; FileHint and DirectoryHint delegate to the shell's native path completer.

type CheckStatus

type CheckStatus string

CheckStatus is the outcome of one doctor probe.

const (
	CheckPass CheckStatus = "pass"
	CheckWarn CheckStatus = "warn"
	CheckFail CheckStatus = "fail"
)

type CommandSpec

type CommandSpec struct {
	Name            string
	Aliases         []string
	Description     string
	Flags           []FlagSpec
	PersistentFlags []FlagSpec
	Arguments       []ArgumentSpec
	Subcommands     []CommandSpec
}

CommandSpec is an abstract command tree. PersistentFlags apply to this command and all descendants. Keeping this descriptor outside the generator lets the executable use the same registry for parsing/help/completions.

type CompletionShell

type CompletionShell string

CompletionShell is a supported completion-script target.

const (
	Bash CompletionShell = "bash"
	Zsh  CompletionShell = "zsh"
	Fish CompletionShell = "fish"
)

type ConfigScope

type ConfigScope string

ConfigScope identifies one of Sandbar's two configuration files.

const (
	CoreConfig   ConfigScope = "core"
	ClientConfig ConfigScope = "client"
)

type DoctorCheck

type DoctorCheck struct {
	Name    string         `json:"name"`
	Status  CheckStatus    `json:"status"`
	Summary string         `json:"summary"`
	Details map[string]any `json:"details,omitempty"`
}

DoctorCheck contains a secret-safe diagnostic result. Details must never contain raw credentials; cliadmin's built-in checks use only presence flags and the redactedValue marker.

type DoctorOptions

type DoctorOptions struct {
	ConfigPath string
	Model      string
	Workspace  string
	Theme      string
	ColorMode  string
	// Version is the CLI build version echoed into the report ("" omits it).
	Version string

	LookupPath func(string) (string, error)
	Stat       func(string) (os.FileInfo, error)
	Getenv     func(string) string
	IsTerminal func(uintptr) bool
	Output     *os.File
	Now        func() time.Time
}

DoctorOptions configures a doctor run. The function fields are optional dependency seams for deterministic tests; normal callers only need the first five fields.

type DoctorReport

type DoctorReport struct {
	GeneratedAt time.Time     `json:"generated_at"`
	Version     string        `json:"version,omitempty"`
	Healthy     bool          `json:"healthy"`
	Checks      []DoctorCheck `json:"checks"`
}

DoctorReport is a complete doctor run in a stable JSON-friendly shape. Version carries the CLI build version passed in by the caller (empty when unknown).

func RunDoctor

func RunDoctor(ctx context.Context, options DoctorOptions) DoctorReport

RunDoctor performs read-only environment checks. The one exception is the existing config.LoadClientConfig behavior: if the client config is absent it creates the documented default file.

func (DoctorReport) Human

func (r DoctorReport) Human() string

Human renders a compact, no-color doctor report suitable for terminals, logs, and NO_COLOR output.

func (DoctorReport) JSON

func (r DoctorReport) JSON() ([]byte, error)

JSON renders an indented machine-readable doctor report.

type Field

type Field struct {
	Scope    ConfigScope `json:"scope"`
	Key      string      `json:"key"`
	Type     ValueType   `json:"type"`
	Value    any         `json:"value"`
	Redacted bool        `json:"redacted"`
	Writable bool        `json:"writable"`
}

Field is a typed and, when necessary, redacted configuration leaf.

func Get

func Get(scope ConfigScope, explicit, key string) (Field, error)

Get returns one effective configuration leaf by dotted YAML path, for example "server.port" or "providers.0.api_key".

func Reset

func Reset(scope ConfigScope, explicit, key string) (Field, error)

Reset restores one client preference to its built-in default and persists it through ClientConfig.Save. Core mutation is intentionally unsupported.

func Set

func Set(scope ConfigScope, explicit, key, rawValue string) (Field, error)

Set parses and persists one typed client preference through the existing ClientConfig.Save API. Core mutation is intentionally unsupported; see ErrCoreMutationUnsupported.

type FlagSpec

type FlagSpec struct {
	Names       []string
	Description string
	Value       *ArgumentSpec
}

FlagSpec describes one logical flag and all accepted spellings, such as []string{"-m", "--model"}. A nil Value denotes a boolean flag.

type Snapshot

type Snapshot struct {
	Scope  ConfigScope `json:"scope"`
	Path   string      `json:"path"`
	Fields []Field     `json:"fields"`
}

Snapshot is the resolved, effective view of a configuration file. Core values include defaults and environment overrides applied by config.Load.

func Read

func Read(scope ConfigScope, explicit string) (Snapshot, error)

Read returns all effective configuration leaves in deterministic key order.

type ValidationResult

type ValidationResult struct {
	Scope   ConfigScope `json:"scope"`
	Path    string      `json:"path"`
	Valid   bool        `json:"valid"`
	Message string      `json:"message"`
}

ValidationResult is suitable for both human and JSON config validate output. Invalid YAML/configuration is represented by Valid=false rather than an operational error so callers can render one consistent result.

func Validate

func Validate(scope ConfigScope, explicit string) (ValidationResult, error)

Validate parses and validates one config without exposing secret values.

type ValueHint

type ValueHint string

ValueHint tells a shell how to complete a flag value or positional argument.

const (
	NoValueHint   ValueHint = ""
	FileHint      ValueHint = "file"
	DirectoryHint ValueHint = "directory"
)

type ValueType

type ValueType string

ValueType is the stable, user-facing type of a configuration value.

const (
	StringValue  ValueType = "string"
	IntegerValue ValueType = "integer"
	NumberValue  ValueType = "number"
	BooleanValue ValueType = "boolean"
	ListValue    ValueType = "list"
	ObjectValue  ValueType = "object"
	NullValue    ValueType = "null"
)