kbotctx

Documentation

Overview

Package kbotctx manages named working-directory contexts for kbot.

A context bundles a path to a Total Annihilation install (packed or flattened), the game it represents, and an optional version label. Contexts are persisted to a JSON file at $HOME/.kbot so that every VFS-backed kbot command can pick up the right install without the user having to repeat the path.

The active context is whichever alias is named in the file's "current" field. The KBOT_CONTEXT environment variable overrides it for the current process.

Index

• Constants
• Variables
• func DefaultPath() (string, error)
• func IsKnownGame(g string) bool
• type Config
  • func Load() (*Config, error)
  • func (c *Config) Active() (alias string, ctx Context, source string, ok bool)
  • func (c *Config) Add(alias string, ctx Context, replace bool) error
  • func (c *Config) Aliases() []string
  • func (c *Config) Delete(alias string) error
  • func (c *Config) ForgetWorkspace(path string)
  • func (c *Config) Path() string
  • func (c *Config) RememberWorkspace(ref WorkspaceRef) error
  • func (c *Config) ResolveChain(alias string) ([]string, error)
  • func (c *Config) Save() error
  • func (c *Config) SetParent(alias, parent string) error
  • func (c *Config) Use(alias string) error
• type Context
• type WorkspaceRef

Constants

const (
	GameTotalA     = "totala"
	GameTAKingdoms = "takingdoms"
	GameCustom     = "custom"
)

Game identifies which game an install holds.

const ConfigFileName = ".kbot"

ConfigFileName is the basename used for the kbot config file.

const EnvVar = "KBOT_CONTEXT"

EnvVar is the environment variable that overrides the persisted "current" context for the running process.

Variables

var ValidGames = []string{GameTotalA, GameTAKingdoms, GameCustom}

ValidGames lists the accepted values for Context.Game.

Functions

func DefaultPath

func DefaultPath() (string, error)

DefaultPath returns the path to the kbot config file ($HOME/.kbot). It does not check that the file exists.

func IsKnownGame

func IsKnownGame(g string) bool

IsKnownGame reports whether g is one of the accepted Game values.

Types

type Config

type Config struct {
	Current    string             `json:"current,omitempty"`
	Contexts   map[string]Context `json:"contexts,omitempty"`
	Workspaces []WorkspaceRef     `json:"workspaces,omitempty"`
	// contains filtered or unexported fields
}

Config is the on-disk shape of the kbot config file.

func Load

func Load() (*Config, error)

Load reads the kbot config from $HOME/.kbot. A missing file is treated as an empty config so callers can add the first context without bootstrapping.

func (*Config) Active

func (c *Config) Active() (alias string, ctx Context, source string, ok bool)

Active resolves the context that should be applied to the current process. The KBOT_CONTEXT environment variable wins over the persisted Current field. The returned bool reports whether any context applies; alias is the resolved name, source identifies where the choice came from ("env" or "config").

func (*Config) Add

func (c *Config) Add(alias string, ctx Context, replace bool) error

Add registers a new context. It rejects duplicate aliases unless replace is true.

func (*Config) Aliases

func (c *Config) Aliases() []string

Aliases returns the registered context aliases in sorted order.

func (*Config) Delete

func (c *Config) Delete(alias string) error

Delete removes a context. Returns an error if the alias is unknown or if another context still names it as a parent. If the deleted context was current, Current is cleared.

func (*Config) ForgetWorkspace

func (c *Config) ForgetWorkspace(path string)

ForgetWorkspace removes a workspace from the recents index by path. It is a no-op if the path is not present.

func (*Config) Path

func (c *Config) Path() string

Path returns the on-disk path the config was loaded from.

func (*Config) RememberWorkspace

func (c *Config) RememberWorkspace(ref WorkspaceRef) error

RememberWorkspace records (or refreshes) a workspace in the recents index, moving it to the front. Entries are de-duplicated by absolute path.

func (*Config) ResolveChain

func (c *Config) ResolveChain(alias string) ([]string, error)

ResolveChain returns the context aliases from alias up to its root parent, highest-priority first (alias itself, then its parent, and so on). It fails if a parent is missing, a cycle exists, or the chain mixes incompatible games (e.g. totala under takingdoms; custom is compatible with either).

func (*Config) Save

func (c *Config) Save() error

Save writes the config back to its original path with restrictive permissions (0600) since it stores filesystem locations.

func (*Config) SetParent

func (c *Config) SetParent(alias, parent string) error

SetParent sets (or clears, when parent is "") the parent of alias, validating that the resulting chain is acyclic and game-compatible.

func (*Config) Use

func (c *Config) Use(alias string) error

Use marks alias as the persisted current context.

type Context

type Context struct {
	Path    string `json:"path"`
	Game    string `json:"game"`
	Version string `json:"version,omitempty"`

	// Parent is the alias of another context this one is layered on top of.
	// When set, a VFS built for this context resolves through the parent
	// chain (base game → expansion → mod), with this context overriding its
	// parents. Empty for a root context.
	Parent string `json:"parent,omitempty"`
}

Context describes a single registered install.

type WorkspaceRef

type WorkspaceRef struct {
	Name string `json:"name"`
	Path string `json:"path"`
	Base string `json:"base"`
}

WorkspaceRef is a lightweight pointer to an editing workspace on disk. The authoritative metadata lives in the workspace's manifest; this index just lets tools (e.g. the studio picker) list recently used workspaces.