cmdctx

type CreateBodyFn func(ctx *Ctx) (any, error)

type Ctx struct {
	Context      context.Context
	CancelFn     context.CancelCauseFunc
	Auth         *auth.ResolvedAuth
	Verb         string
	VerbHandler  string // behavioral dispatch verb; defaults to Verb when verb_handler is unset in spec
	Noun         string
	FieldsNoun   string // overrides Noun for field lookup when set (from spec fields_noun)
	Id           string
	ParentId     string            // optional parent-id arg for list commands (e.g. pipeline ID on "list execution")
	MigrateFrom  string            // --from flag value (pair verbs, e.g. migrate: identifies the source endpoint)
	MigrateTo    string            // --to flag value (pair verbs, e.g. migrate: identifies the destination endpoint)
	SetArgs      map[string]string // --set key=value pairs for update verb (when HasSetArg set on spec)
	DelArgs      []string          // --del key targets for update verb (when HasSetArg set on spec)
	Args         []string          // extra positional args beyond [id] (when HasArgs set on spec)
	IdParts      []string          // id split on "/" when id_parts > 1 on spec; length equals the number of actual parts
	Level        string            // scope level: "account", "org", or "project" (empty when flag not present)
	IsPty        bool              // true when stdout is an interactive terminal
	IsCompletion bool              // true when this ctx was built for a shell completion request
	Resolver     Resolver
	GlobalFlags  GlobalFlags
	FormatFlags  FormatFlags
	PagingFlags  PagingFlags
	// FlagValues holds typed flag values for this command, keyed by flag name. It contains:
	//   - all flags declared in the spec (cs.Flags), typed as string/bool/[]string
	//   - "page"         int    (0-indexed) when the spec declares builtin_flags.page
	//   - "format"       string when the flag exists (gates PTY-sensitive expr rendering)
	//   - "columns"      string when the flag exists (list commands)
	//   - "list-columns" bool   when the flag exists (list commands)
	//   - "list-fields"  bool   when the flag exists (get/update commands)
	//   - "profile", "org", "project" string when no_auth: true (the handler owns auth resolution)
	FlagValues map[string]any
	// UIHistory is the --ui back-navigation stack: one UILink pushed per Hop
	// (link/up/view), popped by the "b" key. Session-lifetime only.
	UIHistory []UILink
	// RestoreOffset is the absolute row index to restore when replaying a
	// popped UILink's Offset. It is resolved against the current pageSize
	// (page = RestoreOffset / pageSize, cursor = RestoreOffset % pageSize),
	// since the terminal may have been resized since it was captured.
	RestoreOffset int
	// UIWantBack is read by finishUIExit right after a "view" ui_command's
	// handler returns, to decide whether to pop UIHistory and redraw the caller
	// (true) or quit outright (false, the default). A view handler that wants
	// its screen's own "b" key to behave like the rest of --ui's back
	// navigation must set this to true before returning — it is not automatic.
	UIWantBack bool
}

type DataAccessor interface {
	GetString(path string) string
	GetInt64(path string) int64
	GetBool(path string) bool
	GetTs(path string) string
	GetData() any
	GetSlice(path string) []any
}

type EndpointRequest struct {
	Method      string
	Path        string
	QueryParams map[string]string
	Body        any
	ContentType string
}

type EndpointValidatorFn func(ctx *Ctx, req EndpointRequest) error

type FetchFn func(ctx *Ctx, ep *spec.EndpointSpec, wantStart, wantCount int, cursor any) (*PageResult, error)

type FlagResolveFn func(ctx *Ctx, raw string) (*FlagResolveResult, error)

type FlagResolveResult struct {
	Value    string
	Defaults map[string]string
}

type FollowFn func(ctx *Ctx, result any) error

type FormatFlags struct {
	Format    string
	Columns   string
	Fields    string // --fields: comma-separated field IDs; outputs tab-separated values (get commands only)
	NoHeaders bool
	OutFile   string
	Raw       bool
}

type GlobalFlags struct{}

type ItemFn func(ctx *Ctx) (any, error)

type ListTransformFn func(ctx *Ctx, data any) (items []any, fields []spec.FieldDef, meta PageMeta, err error)

type PageMeta struct {
	Offset   int
	Count    int
	HasTotal bool
	Total    int64
	Notice   string
}

type PageResult struct {
	Raw         any
	Items       []any
	StartOffset int
	Last        bool
	HasTotal    bool
	Total       int64
	NextCursor  any
}

type PagingFlags struct {
	Offset int  // item-level offset (not page-level)
	Limit  int  // max items to return; 0 means use page_size_default
	All    bool // fetch all pages, overrides Offset and Limit
	Count  bool // return total count instead of items; incompatible with Offset/Limit/All
	// OnPage, if set, is invoked once per fetched page with the number of items
	// accumulated so far and the reported grand total (hasTotal is false when the
	// paging strategy does not return one). Used to surface progress on slow,
	// many-page fetches (e.g. thousands of orgs during login).
	OnPage func(fetched int, total int64, hasTotal bool)
}

type QueryParamsFn func(ctx *Ctx) (map[string]string, error)

type RawBody struct {
	ContentType string
	Content     string
}

type Resolver interface {
	ResolveTextFormatter(id string) TextFormatterFn
	ResolveBodyFn(id string) CreateBodyFn
	ResolveQueryParamsFn(id string) QueryParamsFn
	ResolveFlagResolveFn(id string) FlagResolveFn
	ResolveFetchFn(id string) (FetchFn, error)
	ResolveListTransformFn(id string) ListTransformFn
	ResolveItemFn(id string) ItemFn
	ResolveEndpointValidator(id string) EndpointValidatorFn
	GetSpec(verb, noun string) *spec.CommandSpec
	GetNoun(noun string) *spec.NounDef
	// ResolveNounAlias returns the canonical noun name for the given alias, or "" if not an alias.
	ResolveNounAlias(alias string) string
	RunEndpoint(ctx *Ctx, ep *spec.EndpointSpec) (any, error)
	// RunUIHandler dispatches to the registered ui_handler_fn, e.g. from a get
	// command's drilldown detail overlay when the user presses "v".
	RunUIHandler(ctx *Ctx, fnID string) error
	// FormatList renders rows through the standard list formatting pipeline (table/json/csv/tsv).
	// fields declares the available columns; columnIDs sets the default column order (nil = all).
	FormatList(ctx *Ctx, rows []any, fields []spec.FieldDef, columnIDs []string) error
	// FetchItems fetches all items satisfying pf from a paging-enabled list endpoint.
	// Returns raw items as extracted by the endpoint's items_expr — no field unwrapping.
	FetchItems(ctx *Ctx, ep *spec.EndpointSpec, pf PagingFlags) ([]any, error)
	// GetModuleMetas returns metadata for all loaded modules in load order.
	GetModuleMetas() []spec.ModuleMeta
	// GetHiddenModule returns the recorded stub for a module_type: hidden
	// module by name (recorded regardless of enablement), or nil.
	GetHiddenModule(name string) *spec.ModuleMeta
	// GetSpecsForModule returns all registered CommandSpecs belonging to the given module.
	GetSpecsForModule(module string) []*spec.CommandSpec
	// GetAllSpecs returns every registered CommandSpec across all modules.
	GetAllSpecs() []*spec.CommandSpec
	// GetVerbInfos returns display metadata for all verbs that have at least one registered command.
	GetVerbInfos() []spec.VerbInfo
	// ResolveCommandFields returns the effective []FieldDef for a command: noun fields (or
	// fields_noun override), filtered by fields_subset, with fields_extra appended.
	ResolveCommandFields(cs *spec.CommandSpec) []spec.FieldDef
}

type TextFormatterFn func(w io.Writer, d DataAccessor) error

type TimeoutError struct {
	Secs float64
}

type UILink struct {
	Verb, Noun string
	Id         string
	IdParts    []string
	Level      string

	Profile, Org, Project string
	FlagValues            map[string]any

	Screen UIScreenKind
	// Offset is the absolute row index (page*pageSize + cursor row) the user
	// was on when this Link was captured — resize-safe, unlike a raw page
	// number or in-page cursor alone.
	Offset int
}

type UIScreenKind int