command

type AdditionalArgsCompleter ¶

type AdditionalArgsCompleter interface {
	CompleteAdditionalArgs(ctx context.Context, r *readline.Readline) []goprompt.Suggest
}

type ArgInfo ¶ added in v0.21.0

type ArgInfo = tree.ArgInfo

ArgInfo describes a single positional argument of a command.

type ArgumentCompleter ¶

type ArgumentCompleter interface {
	CompleteArguments(ctx context.Context, r *readline.Readline) []goprompt.Suggest
}

type Cache ¶

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

func NewCache(l log.Logger, cache cache.Cache) *Cache

func (c *Cache) Complete(ctx context.Context, r *readline.Readline) []goprompt.Suggest

func (c *Cache) Describe(ctx context.Context) CommandInfo

func (c *Cache) Description() string

func (c *Cache) Execute(ctx context.Context, r *readline.Readline) error

func (c *Cache) Help(ctx context.Context, r *readline.Readline) string

func (c *Cache) Name() string

func (c *Cache) Skill(ctx context.Context, name string) string

type CacheGet ¶ added in v0.21.0

type CacheGet struct {
	Namespace string `json:"namespace"`
	Key       string `json:"key"`
	Value     any    `json:"value"`
}

CacheGet is the result of `cache get`. Value is nil when the key is unset.

type CacheList ¶ added in v0.21.0

type CacheList struct {
	Namespaces []CacheNamespace `json:"namespaces"`
}

CacheList is the result of `cache list`.

type CacheNamespace ¶ added in v0.21.0

type CacheNamespace struct {
	Namespace string   `json:"namespace"`
	Keys      []string `json:"keys"`
}

CacheNamespace is a single cache namespace and the keys it holds. Values are deliberately excluded - use `cache get` to read one.

type Check ¶ added in v0.5.4

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

func NewCheck(l log.Logger, checkers ...check.Checker) *Check

func (c *Check) Complete(ctx context.Context, r *readline.Readline) []goprompt.Suggest

func (c *Check) Describe(ctx context.Context) CommandInfo

func (c *Check) Description() string

func (c *Check) Execute(ctx context.Context, r *readline.Readline) error

func (c *Check) Help(ctx context.Context, r *readline.Readline) string

func (c *Check) Name() string

func (c *Check) Skill(ctx context.Context, name string) string

type Command ¶

type Command interface {
	Name() string
	Description() string
	Execute(ctx context.Context, r *readline.Readline) error
}

type CommandInfo ¶ added in v0.21.0

type CommandInfo = tree.CommandInfo

CommandInfo describes one command for the `posh agent catalog` catalog.

func Describe(ctx context.Context, name, description string, v any) CommandInfo

type Commands ¶

type Commands map[string]Command

func (c Commands) Add(commands ...Command)

func (c Commands) Get(name string) Command

func (c Commands) Has(name string) bool

func (c Commands) List() []Command

func (c Commands) Load(paths ...string) error

func (c Commands) MustAdd(command Command, err error)

func (c Commands) TryAdd(command Command, err error) error

type Completer ¶

type Completer interface {
	Complete(ctx context.Context, r *readline.Readline) []goprompt.Suggest
}

type Describer ¶ added in v0.21.0

type Describer interface {
	Describe(ctx context.Context) CommandInfo
}

Describer is an optional Command extension: a command that describes its own structure for `posh agent catalog`, so an AI coding agent gets a machine-readable answer to "what can I run" without parsing help text.

The contract is CommandInfo, not a command tree: a command is free to model its structure however it likes and stays free to change that later. Tree based commands delegate to tree.Root.Describe like any other tree method:

func (c *Cache) Describe(ctx context.Context) command.CommandInfo {
	return c.tree.Describe(ctx)
}

Commands that do not implement it are still listed, just without subcommand detail.

type Env ¶ added in v0.5.0

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

func NewEnv(l log.Logger) *Env

func (c *Env) Complete(ctx context.Context, r *readline.Readline) []goprompt.Suggest

func (c *Env) Describe(ctx context.Context) CommandInfo

func (c *Env) Description() string

func (c *Env) Execute(ctx context.Context, r *readline.Readline) error

func (c *Env) Help(ctx context.Context, r *readline.Readline) string

func (c *Env) Name() string

func (c *Env) Skill(ctx context.Context, name string) string

type EnvGet ¶ added in v0.21.0

type EnvGet struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

EnvGet is the result of `env get`.

type EnvList ¶ added in v0.21.0

type EnvList struct {
	Values []EnvVar `json:"values"`
}

EnvList is the result of `env list`.

type EnvVar ¶ added in v0.21.0

type EnvVar struct {
	Name  string `json:"name"`
	Value string `json:"value,omitempty"`
}

EnvVar is a single environment variable. Value is omitted unless the listing was requested with values.

type Exit ¶

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

func NewExit(l log.Logger) *Exit

func (c *Exit) Description() string

func (c *Exit) Execute(ctx context.Context, args *readline.Readline) error

func (c *Exit) Help(ctx context.Context, r *readline.Readline) string

func (c *Exit) Name() string

type FlagCompleter ¶

type FlagCompleter interface {
	CompleteFlags(ctx context.Context, r *readline.Readline) []goprompt.Suggest
}

type FlagInfo ¶ added in v0.21.0

type FlagInfo = tree.FlagInfo

FlagInfo describes a single flag of a command.

type Help ¶

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

func NewHelp(l log.Logger, commands Commands) *Help

func (c *Help) Complete(ctx context.Context, r *readline.Readline) []goprompt.Suggest

func (c *Help) Describe(ctx context.Context) CommandInfo

func (c *Help) Description() string

func (c *Help) Execute(ctx context.Context, r *readline.Readline) error

func (c *Help) Name() string

func (c *Help) Validate(ctx context.Context, r *readline.Readline) error

type Helper ¶

type Helper interface {
	Help(ctx context.Context, r *readline.Readline) string
}

type History ¶ added in v0.4.0

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

func NewHistory(l log.Logger, history history.History) *History

func (c *History) Description() string

func (c *History) Execute(ctx context.Context, r *readline.Readline) error

func (c *History) Name() string

func (c *History) Skill(ctx context.Context, name string) string

type Option ¶ added in v0.5.4

type Option func(*Check)

type PassThroughFlagsCompleter ¶

type PassThroughFlagsCompleter interface {
	CompletePassTroughFlags(ctx context.Context, r *readline.Readline) []goprompt.Suggest
}

type Shutdowner ¶ added in v0.17.0

type Shutdowner interface {
	Shutdown(ctx context.Context) error
}

type SkillMetadata ¶ added in v0.22.0

type SkillMetadata struct {
	// Name defaults to "posh" for the root skill, "posh-<command>" for a
	// command's own.
	Name string `yaml:"name"`
	// Description defaults to a generic one. A description naming concrete
	// triggering conditions is what makes the skill load at all.
	Description string `yaml:"description"`
	// AllowedTools are granted without a permission prompt for the turn that
	// invokes the skill, e.g. "Bash(posh execute:*)".
	AllowedTools []string `yaml:"allowed-tools,omitempty"`
}

SkillMetadata is the frontmatter of a generated SKILL.md.

The fields are restricted to the Agent Skills spec allowlist (https://agentskills.io) so a generated skill stays valid if it is ever uploaded to claude.ai or the Skills API, both of which reject unknown keys.

func SkillMetadataOf(ctx context.Context, v any, name string) SkillMetadata

type SkillMetadataer ¶ added in v0.22.0

type SkillMetadataer interface {
	SkillMetadata(ctx context.Context, name string) SkillMetadata
}

SkillMetadataer is an optional Command extension supplying the frontmatter of that command's own generated skill.

Unset fields fall back to values derived from the command: the name to "posh-<name>", the description to a generic "Use when running ..." line. The description is the only thing an agent runtime sees when deciding whether to load a skill at all, so a generic one effectively means the skill never triggers - name the conditions that should reach for this command.

name is the registered command name, as for Skiller.

type Skiller ¶ added in v0.21.0

type Skiller interface {
	Skill(ctx context.Context, name string) string
}

Skiller is an optional Command extension: a command that contributes extra markdown to its generated SKILL.md, beyond the structure Describer already provides - extended instructions, worked configuration examples, links to further docs.

The contract is deliberately a free-form string rather than a struct: what is worth telling an agent varies per command, and a fixed shape would constrain that without buying anything, since the destination is markdown either way.

name is the command name the contribution is rendered under, which is not necessarily the command's default one: the same provider can be registered under another name. Write the prose against name rather than hardcoding a literal, or the generated skill tells an agent to run a command that does not exist in this project.

The returned markdown is appended verbatim under the command's heading. Use heading level 4 (####) or deeper - level 3 is the command heading itself.

Commands that do not implement it render as just their paths and descriptions.

type Validator ¶

type Validator interface {
	Validate(ctx context.Context, r *readline.Readline) error
}

type Version ¶ added in v0.21.0

type Version struct {
	Version   string `json:"version"`
	Commit    string `json:"commit,omitempty"`
	BuildTime string `json:"build_time,omitempty"`
}

Version is the result of `posh version`. Commit and BuildTime are only populated at debug level, matching the fields the human output prints there.