command

type AliasTable interface {
	Get(name string) (string, bool)
	Set(name, value string)
	Unset(name string) bool
	Clear()
	Names() []string
	All() map[string]string
}

type Command interface {
	// Name returns the canonical lookup key for the command. The
	// registry uses this value as the map key, so it must not change
	// across calls.
	Name() Name

	// Execute runs the command. ctx is the parent execution context
	// (cancellation propagates through it). args is the full argv —
	// args[0] is the command name as invoked by the script, args[1:]
	// are the positional arguments. c carries the dispatch state.
	Execute(ctx context.Context, args []string, c *Context) Result

	// Trusted reports whether the command may run inside a Phase 17+
	// sandbox. It is metadata only; no Phase 8–16 code paths inspect
	// it. Built-ins constructed via Define default to true.
	Trusted() bool
}

type Context struct {
	// FS is the virtual filesystem backing every script-side file
	// operation. Commands MUST route I/O through this field — never
	// through host os.* helpers — to preserve the sandbox contract.
	FS gbfs.FileSystem

	// Cwd is the working directory at dispatch time, resolved through
	// the VFS (not the host disk). Commands that perform relative
	// path resolution should join against this value.
	Cwd string

	// Env is the effective environment at dispatch time. Commands may
	// mutate this map; the runtime decides whether to persist the
	// mutation
	Env map[string]string

	// Stdin, Stdout, Stderr are the streams plumbed through from the
	// runner's current redirection state. Commands write structured
	// output here; they should NOT populate Result.Stdout/Stderr in
	// the same call (the runtime treats those as a fallback when the
	// writers are not consulted, e.g. for early returns).
	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer

	// Registry is a back-reference to the dispatch registry so
	// commands that delegate to peers (e.g. a future `which`) can
	// look them up without a global state lookup.
	Registry *Registry

	// Fetch is the network Doer made available to commands like
	// `curl` (Phase 10). It is nil when the host did not configure
	// BashOptions.Network or BashOptions.Fetch — commands that need
	// network MUST check for nil and produce a `network disabled`
	// diagnostic rather than panicking. Phase 9 plumbs this field;
	// Phase 10 wires it to its first real consumer.
	Fetch network.Doer

	// Sleep is the host-supplied sleep hook used by Phase 10's
	// `sleep` builtin. When nil, the builtin uses a real time.Sleep
	// guarded by ctx. Tests override this to elide wall-clock waits.
	Sleep SleepFunc

	// Trace is the host-supplied trace hook. Wave A built-ins do not
	// emit events; the field is plumbed today so later waves can
	// instrument hot paths without a follow-up Context surface bump.
	Trace TraceFunc

	// Limits is the resolved execution-limit set for the current
	// Exec. Wave A built-ins ignore it; Wave D's awk/sed/jq and the
	// optional runtimes (sqlite/python/js) consume the iteration and
	// timeout caps.
	Limits Limits

	// ExportedEnv is the per-dispatch exported-environment view used
	// by env/printenv/export (Phase 10 Wave G). Wave A does not
	// consume it; the field is plumbed today as a landing zone so
	// later waves do not require a Context surface bump.
	ExportedEnv map[string]string

	// Aliases is the per-Bash alias table consulted and mutated by
	// the `alias` / `unalias` built-ins (Phase 10 Wave G). Aliases
	// only expand at parse time when `shopt expand_aliases` is on;
	// the parse-side wiring lands in Phase 11. nil is treated as an
	// empty table.
	Aliases AliasTable

	// History is the per-Bash command history ring (Phase 10 Wave G).
	// The `history` built-in reads and mutates this ring. The runtime
	// itself does NOT currently push commands into the ring — Phase 19
	// will wire automatic recording at parse time. Hosts can populate
	// it manually via Bash.History() until then.
	History HistoryRing

	// Exec is the sub-shell invocation hook used by the Phase 10
	// Wave G `bash` / `sh` / `timeout` built-ins (which would
	// otherwise need to recurse into the runtime). The spec reserves
	// this field for Phase 11 (source / eval / .); Wave G needs it
	// earlier. nil means sub-shell features are unavailable; consumers
	// MUST nil-check and produce a clean diagnostic.
	Exec SubExecFunc

	// SourceDepth tracks recursive sub-shell / source / . / eval
	// invocations against Limits.MaxSourceDepth (Phase 11). The
	// runtime supplies the current depth at dispatch time; built-ins
	// that delegate to c.Exec must bump it by 1 in the
	// SubExecOptions they forward (the runtime then reads it back
	// when constructing the next dispatch Context). A value at or
	// above Limits.MaxSourceDepth means the call must be rejected
	// with a clean diagnostic.
	SourceDepth int

	// Shopt is the per-Bash shell-option table (`shopt`). The
	// `shopt` builtin reads and mutates it; the alias-expansion path
	// (Phase 11) consults `expand_aliases` at parse time. Nil-safe:
	// a nil table reports every option as off and silently drops
	// writes.
	Shopt ShoptTable
}

type HistoryRing interface {
	Add(cmd string)
	Clear()
	List() (seqs []int, cmds []string)
	Len() int
}

type InvokeToolFunc = func(ctx context.Context, path, argsJSON string) (string, error)

type Limits struct {
	MaxCallDepth             int
	MaxCommandCount          int
	MaxLoopIterations        int
	MaxAwkIterations         int
	MaxSedIterations         int
	MaxJqIterations          int
	MaxSqliteTimeout         time.Duration
	MaxPythonTimeout         time.Duration
	MaxJsTimeout             time.Duration
	MaxGlobOperations        int
	MaxStringLength          int
	MaxArrayElements         int
	MaxHeredocSize           int
	MaxSubstitutionDepth     int
	MaxBraceExpansionResults int
	MaxOutputSize            int
	MaxFileDescriptors       int
	MaxSourceDepth           int
}

type Name string

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

type Result struct {
	Stdout   string
	Stderr   string
	ExitCode int
}

type ShoptTable interface {
	IsSet(name string) bool
	Set(name string, on bool)
	Names() []string
}

type SleepFunc = func(ctx context.Context, d time.Duration) error

type SubExecFunc = func(ctx context.Context, script string, opts SubExecOptions) (Result, error)

type SubExecOptions struct {
	Env        map[string]string
	ReplaceEnv bool
	Cwd        string
	Stdin      io.Reader
	Stdout     io.Writer
	Stderr     io.Writer
	Args       []string

	// SourceDepth, when non-zero, is the depth the sub-shell should
	// start at. The Phase 11 source / eval / . / bash / sh / timeout
	// builtins set this to parent.SourceDepth + 1 so MaxSourceDepth
	// trips cleanly across nested invocations.
	SourceDepth int
}

type TraceEvent struct {
	Category string
	Name     string
	Duration time.Duration
	Details  map[string]any
}

type TraceFunc = func(TraceEvent)