cli

Documentation

Overview

Package cli wires the kong grammar, the runtime, and the exit-code mapping. main() does nothing but os.Exit(cli.Run(...)) so every path is testable in-process.

Index

• func Run(args []string, stdin io.Reader, stdout, stderr io.Writer) int
• type AgentCmd
  • func (c *AgentCmd) Run(rt *Runtime) error
• type AuthCmd
• type AuthStatusCmd
  • func (c *AuthStatusCmd) Run(rt *Runtime) error
• type CLI
• type DoctorCmd
  • func (c *DoctorCmd) Run(rt *Runtime) error
• type InventoryCheckCmd
  • func (c *InventoryCheckCmd) Run(rt *Runtime) error
• type InventoryCmd
• type InventoryWarehouseCmd
  • func (c *InventoryWarehouseCmd) Run(rt *Runtime) error
• type LotteryCheckCmd
  • func (c *LotteryCheckCmd) Run(rt *Runtime) error
• type LotteryCmd
• type ProductCmd
• type ProductGetCmd
  • func (c *ProductGetCmd) Run(rt *Runtime) error
• type ProductSearchCmd
  • func (c *ProductSearchCmd) Run(rt *Runtime) error
• type Runtime
  • func (rt *Runtime) Guard(op string) error
• type SchemaCmd
  • func (c *SchemaCmd) Run(rt *Runtime) error
• type StoreCmd
• type StoreGetCmd
  • func (c *StoreGetCmd) Run(rt *Runtime) error
• type StoreListCmd
  • func (c *StoreListCmd) Run(rt *Runtime) error
• type StoreNearCmd
  • func (c *StoreNearCmd) Run(rt *Runtime) error
• type VersionCmd
  • func (c *VersionCmd) Run(rt *Runtime) error

Functions

func Run

func Run(args []string, stdin io.Reader, stdout, stderr io.Writer) int

Run parses args and dispatches, returning the process exit code.

Types

type AgentCmd

type AgentCmd struct{}

func (*AgentCmd) Run

func (c *AgentCmd) Run(rt *Runtime) error

type AuthCmd

type AuthCmd struct {
	Status AuthStatusCmd `cmd:"" help:"Show authentication status (none required)."`
}

type AuthStatusCmd

type AuthStatusCmd struct{}

func (*AuthStatusCmd) Run

func (c *AuthStatusCmd) Run(rt *Runtime) error

type CLI

type CLI struct {
	// Output (contract §1, §6)
	Format   string `enum:"json,plain,tsv" default:"plain" help:"Output format: json, plain, or tsv."`
	JSON     bool   `help:"Shorthand for --format=json."`
	NoColor  bool   `help:"Disable colored output."`
	Limit    int    `default:"50" help:"Maximum items to return for list operations."`
	Select   string `help:"Comma-separated dot-path field projection, e.g. productCode,name."`
	Concise  bool   `help:"Terser output (default)."`
	Detailed bool   `help:"Richer output."`

	// Prompt-injection hardening (contract §8). Free text from the target (lottery
	// event titles) is fenced as untrusted by default so a downstream agent does not
	// execute instructions embedded in fetched content.
	WrapUntrusted bool `negatable:"" default:"true" help:"Fence untrusted target text with markers (default on)."`

	// Safety (contract §2). Inert here — present for uniformity; vabc is read-only.
	AllowMutations bool `help:"Permit state-changing operations (no-op: vabc is read-only)."`
	DryRun         bool `help:"Print intended mutations without performing them (no-op: vabc is read-only)."`
	Yes            bool `help:"Assume yes for confirmations (no-op: vabc is read-only)."`
	Force          bool `help:"Bypass safety checks (no-op: vabc is read-only)."`
	NoInput        bool `help:"Never prompt; fail with exit 13 instead."`

	// Backend etiquette (contract §12). Live calls fail fast on a throttle block by
	// default so an agent loop never deadlocks; --wait opts into waiting it out.
	Wait    bool          `help:"Wait out throttle/backoff instead of failing fast."`
	MaxWait time.Duration `default:"30s" help:"Maximum time to wait when --wait is set."`

	// Commands
	Product   ProductCmd   `cmd:"" help:"Search and look up products (live web catalog)."`
	Inventory InventoryCmd `cmd:"" help:"Check live per-store and warehouse inventory."`
	Store     StoreCmd     `cmd:"" help:"List and locate Virginia ABC stores."`
	Lottery   LotteryCmd   `cmd:"" help:"Check limited-availability / allocated releases."`
	Auth      AuthCmd      `cmd:"" help:"Authentication status (none required for Virginia ABC)."`
	Doctor    DoctorCmd    `cmd:"" help:"Diagnose setup and report fixes."`
	Schema    SchemaCmd    `cmd:"" help:"Print the machine-readable command schema (JSON)."`
	Agent     AgentCmd     `cmd:"" help:"Print the bundled agent SKILL.md."`
	Version   VersionCmd   `cmd:"" help:"Print the version."`
}

CLI is the kong grammar. Global flags are the universal agent-CLI contract surface; subcommands follow noun-verb grammar. vabc is read-only: the mutation flags below are present for contract uniformity but inert (no command mutates Virginia ABC).

type DoctorCmd

type DoctorCmd struct {
	Online bool `help:"Also probe live endpoint reachability (makes network requests)."`
}

func (*DoctorCmd) Run

func (c *DoctorCmd) Run(rt *Runtime) error

type InventoryCheckCmd

type InventoryCheckCmd struct {
	Code  string `arg:"" help:"6-digit product code (e.g. 010807)."`
	Store int    `help:"Anchor store number (e.g. 219)."`
	Near  string `help:"Resolve the nearest store from a ZIP, street address, or \"lat,lng\" instead of --store."`
}

func (*InventoryCheckCmd) Run

func (c *InventoryCheckCmd) Run(rt *Runtime) error

type InventoryCmd

type InventoryCmd struct {
	Check     InventoryCheckCmd     `cmd:"" help:"Live per-store availability of a product, with nearby stores."`
	Warehouse InventoryWarehouseCmd `cmd:"" help:"Statewide central-warehouse stock of a product."`
}

InventoryCmd groups live inventory reads against Virginia ABC.

type InventoryWarehouseCmd

type InventoryWarehouseCmd struct {
	Code string `arg:"" help:"6-digit product code."`
}

func (*InventoryWarehouseCmd) Run

func (c *InventoryWarehouseCmd) Run(rt *Runtime) error

type LotteryCheckCmd

type LotteryCheckCmd struct {
	Code string `arg:"" help:"6-digit product code."`
}

func (*LotteryCheckCmd) Run

func (c *LotteryCheckCmd) Run(rt *Runtime) error

type LotteryCmd

type LotteryCmd struct {
	Check LotteryCheckCmd `cmd:"" help:"Check active limited-availability events for a product."`
}

LotteryCmd groups limited-availability ("lottery" / allocated) reads.

type ProductCmd

type ProductCmd struct {
	Search ProductSearchCmd `cmd:"" help:"Search products by keyword (live web catalog)."`
	Get    ProductGetCmd    `cmd:"" help:"Get one product by 6-digit product code."`
}

ProductCmd groups product reads. Search/get query the live web catalog (the site's Coveo index) — full coverage and current, including new/online-only SKUs.

type ProductGetCmd

type ProductGetCmd struct {
	Code string `arg:"" help:"6-digit product code (e.g. 010807)."`
}

func (*ProductGetCmd) Run

func (c *ProductGetCmd) Run(rt *Runtime) error

type ProductSearchCmd

type ProductSearchCmd struct {
	Query     string `arg:"" optional:"" help:"Keyword matched against product name (omit to browse)."`
	Type      string `help:"Filter by product category/type, e.g. bourbon, gin."`
	Allocated bool   `help:"Only allocated / limited-availability products."`
}

func (*ProductSearchCmd) Run

func (c *ProductSearchCmd) Run(rt *Runtime) error

type Runtime

type Runtime struct {
	Cfg    *CLI
	Out    *output.Writer
	Client vabc.Client // live Virginia ABC API
	Stdin  io.Reader
	Ctx    context.Context // cancelled on SIGINT/SIGTERM
}

Runtime is the per-invocation context bound into every command's Run method.

func (*Runtime) Guard

func (rt *Runtime) Guard(op string) error

Guard enforces the read-only-by-default mutation gate (contract §2). vabc exposes no mutating commands, so nothing calls this today; it is kept for contract uniformity and tested directly, so adding a mutation later is gated automatically.

type SchemaCmd

type SchemaCmd struct{}

func (*SchemaCmd) Run

func (c *SchemaCmd) Run(rt *Runtime) error

type StoreCmd

type StoreCmd struct {
	List StoreListCmd `cmd:"" help:"List all Virginia ABC stores."`
	Get  StoreGetCmd  `cmd:"" help:"Get one store by store number."`
	Near StoreNearCmd `cmd:"" help:"Find stores nearest a location."`
}

StoreCmd groups Virginia ABC store-locator reads (ArcGIS-backed).

type StoreGetCmd

type StoreGetCmd struct {
	Number int `arg:"" help:"ABC store number (e.g. 219)."`
}

func (*StoreGetCmd) Run

func (c *StoreGetCmd) Run(rt *Runtime) error

type StoreListCmd

type StoreListCmd struct{}

func (*StoreListCmd) Run

func (c *StoreListCmd) Run(rt *Runtime) error

type StoreNearCmd

type StoreNearCmd struct {
	Location string `arg:"" help:"A 5-digit ZIP, a street address, or \"lat,lng\" to search near."`
}

func (*StoreNearCmd) Run

func (c *StoreNearCmd) Run(rt *Runtime) error

type VersionCmd

type VersionCmd struct {
	Check bool `help:"Check for a newer release (network, short timeout, fail-silent)."`
}

func (*VersionCmd) Run

func (c *VersionCmd) Run(rt *Runtime) error