entity

type ActionFlags interface {
	ClickyActionFlags()
}

type ActionInfo struct {
	Name     string
	Short    string
	Method   string
	DataFunc func(flags map[string]string, args []string) (any, error)
	// ContextDataFunc, when set, is preferred over DataFunc by both the CLI run
	// path (fed cmd.Context()) and the RPC executor (fed r.Context()), mirroring
	// the entity CRUD seam. Lets an action resolve request-scoped state instead
	// of process globals.
	ContextDataFunc ContextDataFunc
	// FlagsType, if non-nil, is the struct type whose `flag:"..."` tagged
	// fields are registered as cobra flags on the generated action command
	// and populated into the flag map passed to DataFunc.
	FlagsType    reflect.Type
	ResponseType reflect.Type
	// OptionalID, when true, makes the positional <id> argument optional on
	// the generated action command — the action is invokable with no
	// argument (and the `id` passed to the run func is empty). Use for
	// actions whose target is supplied entirely through flags.
	OptionalID bool
	// ToolGroup overrides the entity's tool group for this action only. Empty
	// means the action inherits the entity's group.
	ToolGroup string
}

type ActionSpec[R any] struct {
	// contains filtered or unexported fields
}

type BulkActionInfo struct {
	Name              string
	Short             string
	DataFunc          func(flags map[string]string, args []string) (any, error)
	FilterFunc        func(flags map[string]string, args []string) (any, error)
	LookupFunc        func(flags map[string]string, args []string) (any, error)
	ContextLookupFunc ContextLookupFunc
	ListType          reflect.Type
	BindCompletions   func(cmd *cobra.Command)
	ResponseType      reflect.Type
}

type BulkActionSpec[R any] struct {
	// contains filtered or unexported fields
}

type ClickyOperationMeta struct {
	SurfaceID          string   `json:"-"`
	Command            string   `json:"command,omitempty"`
	Surface            string   `json:"surface,omitempty"`
	Entity             string   `json:"-"`
	Parent             string   `json:"-"`
	Aliases            []string `json:"-"`
	Admin              bool     `json:"-"`
	Icon               string   `json:"-"`
	Title              string   `json:"-"`
	Verb               string   `json:"verb,omitempty"`
	Scope              string   `json:"scope,omitempty"`
	ActionName         string   `json:"actionName,omitempty"`
	IDParam            string   `json:"idParam,omitempty"`
	SupportsLookup     bool     `json:"supportsLookup,omitempty"`
	SupportsFilterMode bool     `json:"supportsFilterMode,omitempty"`
	Group              string   `json:"group,omitempty"`
	Order              int      `json:"-"`
}

type ClickySpecMeta struct {
	Surfaces []ClickySurface `json:"surfaces,omitempty"`
}

type ClickySurface struct {
	Key         string `json:"key"`
	Entity      string `json:"entity"`
	Title       string `json:"title"`
	Parent      string `json:"parent,omitempty"`
	Admin       bool   `json:"admin,omitempty"`
	Description string `json:"description,omitempty"`
	// Icon is an opaque UI icon name (e.g. "database") the frontend resolves to
	// a glyph. Emitted verbatim from the entity's x-clicky-icon annotation.
	Icon  string `json:"icon,omitempty"`
	Order int    `json:"-"`
}

type CommandOpenAPIMeta struct {
	Entity  string
	Parent  string
	Aliases []string
	Admin   bool
	// Icon is an opaque UI icon name (e.g. "database"); clicky never interprets
	// it — it is emitted verbatim on the surface for the frontend to resolve.
	Icon string
	// Title overrides the auto-generated surface title when non-empty.
	Title              string
	Verb               string
	Method             string
	Scope              string
	ActionName         string
	IDParam            string
	SupportsLookup     bool
	SupportsFilterMode bool
	// OptionalID is true when the operation's positional id is optional
	// (WithOptionalID). Such operations are invocable without an id, so the
	// generated REST path must NOT carry an {id} segment — otherwise the no-id
	// call collides with the entity's get-by-id route.
	OptionalID bool
	// ToolGroup names the group an operation belongs to. It is set on the entity
	// and inherited by every operation (a per-action override may replace it).
	// AI tool-preference layers use it to enable/disable a set of related tools
	// as one unit.
	ToolGroup string
}

type Config struct {
	// DefaultMethod is the default HTTP method for operations.
	DefaultMethod string
	// PathPrefix is the path prefix for REST APIs.
	PathPrefix string
	// AutoGeneratePaths controls whether REST paths are generated from the
	// command hierarchy.
	AutoGeneratePaths bool
	// DefaultTags are applied to all operations.
	DefaultTags []string
}

type ContextDataFunc = func(ctx context.Context, flags map[string]string, args []string) (any, error)

type ContextFilter[ListOpts any] interface {
	OptionsWithContext(ctx context.Context, opts ListOpts) map[string]api.Textable
}

type ContextLookupFunc = func(ctx context.Context, flags map[string]string, args []string) (any, error)

type ContextSearchableFilter[ListOpts any] interface {
	OptionsWithQueryAndContext(ctx context.Context, opts ListOpts, query string, limit int) (options map[string]api.Textable, total int)
}

type DataFunc func(flags map[string]string, args []string) (any, error)

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

type DynamicEntitySpec struct {
	Name    string
	Parent  string
	Aliases []string
	// Icon is an opaque UI icon name emitted on the surface (x-clicky.surfaces[].icon).
	Icon string
	// Title overrides the auto-generated surface title when non-empty.
	Title    string
	ListType reflect.Type // generated struct type: flag binding + OpenAPI params
	ItemType reflect.Type // generated item struct type for the response schema
	List     ContextDataFunc
	Get      ContextDataFunc
	Filters  []DynamicFilter
	// FilterRefs maps a filter key to the reusable named filter backing it, so
	// the OpenAPI layer can emit an x-clicky-lookup $ref (see EntityInfo.FilterRefs).
	FilterRefs map[string]string
}

type DynamicFilter struct {
	Key        string
	Label      string
	Type       string
	Multi      bool
	Searchable bool
	// Options returns the head set (query == "") or search matches, plus the true
	// total behind the head. Required.
	Options func(ctx context.Context, flags map[string]string, query string, limit int) (map[string]api.Textable, int)
	// Selected labels the currently-selected value(s) of this filter's key.
	// Optional; nil means "no selection rendering".
	Selected func(ctx context.Context, flags map[string]string) map[string]api.Textable
}

type DynamicGetFunc func(ctx context.Context, id string) (map[string]any, error)

type DynamicListFunc func(ctx context.Context, opts map[string]string) ([]map[string]any, error)

type Entity[T EntityItem, ListOpts any, R any] struct {
	Name string
	// Parent, when set, nests the entity's command under a parent cobra command
	// with that name. The parent command is created lazily by GenerateCLI if it
	// does not already exist.
	Parent string
	// Aliases applied to the generated entity cobra command.
	Aliases []string
	List    func(opts ListOpts) ([]T, error)
	Get     func(id string) (R, error)
	// ListWithContext / GetWithContext / GetWithFlagsAndContext are context-aware
	// variants of List / Get / GetWithFlags. When set they take precedence over
	// their non-context counterparts and receive the request-scoped
	// context.Context (r.Context() over HTTP, cmd.Context() on the CLI). Use them
	// to resolve per-request state (e.g. a database/config bundle) instead of
	// reaching for process globals.
	ListWithContext        func(ctx context.Context, opts ListOpts) ([]T, error)
	ListPaged              func(opts ListOpts) (PagedResult[T], error)
	ListPagedWithContext   func(ctx context.Context, opts ListOpts) (PagedResult[T], error)
	GetWithContext         func(ctx context.Context, id string) (R, error)
	GetWithFlagsAndContext func(ctx context.Context, id string, flags map[string]string) (R, error)
	// GetFlags, when non-nil, is a zero-value struct value implementing
	// ActionFlags whose `flag:"..."` tagged fields are registered as
	// CLI flags on the generated `get` subcommand. The parsed values are
	// passed into GetWithFlags.
	//
	// GetWithFlags is mutually exclusive with Get: when both are set,
	// GetWithFlags wins. Set GetFlags to declare the flag schema and
	// GetWithFlags to receive the typed values.
	GetFlags     ActionFlags
	GetWithFlags func(id string, flags map[string]string) (R, error)
	Create       func(body map[string]any) (R, error)
	Update       func(id string, body map[string]any) (R, error)
	Delete       func(id string) error
	// CreateWithContext / UpdateWithContext / DeleteWithContext are context-aware
	// variants of Create / Update / Delete, mirroring the read-side seam above.
	// When set they take precedence and receive the request-scoped context, so
	// writes target the request's environment rather than a process global.
	CreateWithContext func(ctx context.Context, body map[string]any) (R, error)
	UpdateWithContext func(ctx context.Context, id string, body map[string]any) (R, error)
	DeleteWithContext func(ctx context.Context, id string) error
	Filters           []Filter[ListOpts]

	Actions     []EntityAction
	BulkActions []EntityBulkAction

	// Admin groups admin-only operations (inspect, configure, etc.)
	// that produce different views/columns from the main CRUD operations.
	// Generates subcommands under an "admin" subgroup and routes like /entity/admin/{verb}.
	Admin *Entity[T, ListOpts, R]

	// ValidArgs provides shell completion for the ID argument.
	ValidArgs func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)

	// ToolGroup names the group all of this entity's operations belong to. It is
	// inherited by every generated operation; an action may override it via
	// WithToolGroup. AI tool-preference layers use it to toggle related tools
	// together.
	ToolGroup string
}

type EntityAction interface {
	// contains filtered or unexported methods
}

type EntityBuilder[T EntityItem, ListOpts any, R any] struct {
	// contains filtered or unexported fields
}

type EntityBulkAction interface {
	// contains filtered or unexported methods
}

type EntityInfo struct {
	Name    string
	Parent  string
	Aliases []string
	// Icon is an opaque UI icon name carried through to the OpenAPI surface
	// (x-clicky.surfaces[].icon). Empty for entities that declare no icon.
	Icon string
	// Title overrides the auto-generated surface title when non-empty.
	Title       string
	Type        reflect.Type
	ListType    reflect.Type
	Operations  []EntityOperation
	Actions     []ActionInfo
	BulkActions []BulkActionInfo
	ValidArgs   func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)
	IsAdmin     bool
	// FilterRefs maps a list filter's flag key to the name of the reusable named
	// filter backing it (when the filter was attached via the entity package's
	// Use/As helper). The OpenAPI layer uses it to emit an x-clicky-lookup $ref
	// to the shared filter definition. Nil when no filters reference a named one.
	FilterRefs map[string]string
	// ToolGroup names the group all of this entity's operations belong to. It is
	// inherited by every generated operation (an action may override it) and is
	// used by AI tool-preference layers to toggle related tools together.
	ToolGroup string
}

type EntityItem interface {
	GetID() string
	GetName() string
}

type EntityOperation struct {
	Verb     string // "list", "get", "create", "update", "delete"
	Method   string // Optional explicit HTTP method for generated RPC/OpenAPI routes.
	DataFunc func(flags map[string]string, args []string) (any, error)
	// ContextDataFunc, when set, is preferred over DataFunc by both the CLI run
	// path (fed cmd.Context()) and the RPC executor (fed r.Context()). Lets the
	// operation resolve request-scoped state instead of process globals.
	ContextDataFunc ContextDataFunc
	// FlagsType, when non-nil, binds typed flags from the given struct type
	// onto the generated cobra command and collects their values into the
	// flag map passed to DataFunc. Used by actions that implement
	// ActionFlags; ignored for the built-in CRUD verbs.
	FlagsType  reflect.Type
	LookupFunc func(flags map[string]string, args []string) (any, error)
	// ContextLookupFunc, when set, is the context-aware filter lookup closure.
	// The RPC converter wires it onto RPCOperation.ContextLookupFunc and the
	// executor prefers it over LookupFunc, feeding the request context.
	ContextLookupFunc ContextLookupFunc
	BindCompletions   func(cmd *cobra.Command)
	ResponseType      reflect.Type
	ResponseArray     bool
	ResponsePaged     bool
	ResponseEntityID  bool
}

type ExecutableCommand interface {
	// Execute runs the command with the given options, capturing everything
	// written to os.Stdout / os.Stderr (including direct writes, not just the
	// cobra writers). It is safe for concurrent callers: implementations that
	// swap process-global file descriptors serialize internally.
	Execute(ctx context.Context, opts ExecuteOptions) (stdout, stderr string, err error)

	// Path is the full space-joined command path ("user create").
	Path() string
	// Name is the leaf command name ("create").
	Name() string
	// RootName is the top-level application command name ("xero-cli"), used for
	// the MCP tool title.
	RootName() string

	// Runnable reports whether the command has a Run/RunE (not a pure group).
	Runnable() bool
	// Hidden reports whether the command is hidden from help/listing.
	Hidden() bool

	// IsBoolFlag reports whether the named flag is a boolean flag. Used by the
	// CLI-string reconstruction to render "--flag" vs "--flag=value".
	IsBoolFlag(name string) bool
}

type ExecuteOptions struct {
	// Args are the positional arguments.
	Args []string
	// Flags maps flag name -> string value. A flag absent on the command is
	// silently skipped (path params and other non-flag keys may appear here);
	// a present flag whose value fails to parse returns an error.
	Flags map[string]string
	// FormatOverrides are best-effort flag values applied before execution
	// (e.g. {"format":"markdown","no-color":"true"}). A flag absent on the
	// command is silently skipped. Used by the MCP server's format forcing.
	FormatOverrides map[string]string
}

type Filter[ListOpts any] interface {
	Key() string
	Label() string
	Lookup(opts *ListOpts) (map[string]api.Textable, error)
	Options(opts ListOpts) map[string]api.Textable
}

type FilterContext struct {
	// Context is the request context (HTTP request or CLI command). It may be
	// nil when a source is invoked outside a request (e.g. shell completion).
	Context context.Context
	// Key is the bound flag/field name this filter resolves on the current
	// entity (e.g. "owner" when a "users" filter is attached via .As("owner")).
	Key string
	// Params holds the current values of every flag/filter on the entity, so a
	// source can narrow its options against sibling selections (cascading).
	Params map[string]string
}

type FilterSource interface {
	// Options returns the available options, optionally narrowed by query, and
	// the true total count behind the (possibly capped) returned set. An empty
	// query means "the head set". A non-positive limit means "no cap".
	Options(fc FilterContext, query string, limit int) (options map[string]api.Textable, total int, err error)
	// Resolve labels the currently-selected raw value(s) for display. A value
	// with no known label is echoed back as plain text.
	Resolve(fc FilterContext, values []string) (map[string]api.Textable, error)
}

type FilterSourceSpec struct {
	Kind string `json:"kind" yaml:"kind"`
	// Options is the value→label map for a static source.
	Options map[string]string `json:"options,omitempty" yaml:"options,omitempty"`
	// Entity is the source entity name for an entity source.
	Entity string `json:"entity,omitempty" yaml:"entity,omitempty"`
}

type FilterSpec struct {
	Name   string           `json:"name" yaml:"name"`
	Label  string           `json:"label,omitempty" yaml:"label,omitempty"`
	Type   string           `json:"type,omitempty" yaml:"type,omitempty"`
	Multi  bool             `json:"multi,omitempty" yaml:"multi,omitempty"`
	Source FilterSourceSpec `json:"source" yaml:"source"`
}

type Filterable[T any] interface {
	Filters() []Filter[T]
}

type Help interface {
	Help() api.Textable
}

type MultiFilter []string

type Name interface {
	GetName() string
}

type NamedFilter struct {
	// Name is the unique registry key.
	Name string
	// Label is the human-facing control label. Defaults to Name when empty.
	Label string
	// Type is the UI control type: "select" (default), "multi-select", "date",
	// "from", or "to".
	Type string
	// Multi reports whether the control accepts multiple selections.
	Multi bool
	// Source resolves the filter's options.
	Source FilterSource
}

type PageInfo struct {
	Limit  int   `json:"limit"`
	Offset int   `json:"offset"`
	Total  int64 `json:"total"`
}

type Paged interface {
	PageMetadata() PageInfo
	PageRows() any
}

type PagedResult[T any] struct {
	Data []T      `json:"data"`
	Page PageInfo `json:"page"`
}

type Property struct {
	Type        string      `json:"type"`
	Description string      `json:"description"`
	Enum        []string    `json:"enum,omitempty"`
	Default     interface{} `json:"default,omitempty"`
}

type RPCOperation struct {
	Name              string               `json:"name"`
	Description       string               `json:"description"`
	Parameters        []RPCParameter       `json:"parameters"`
	Schema            Schema               `json:"schema"`
	Command           ExecutableCommand    `json:"-"`                // Transport-neutral handle to the original command
	Path              string               `json:"path,omitempty"`   // For REST APIs
	Method            string               `json:"method,omitempty"` // HTTP method
	Tags              []string             `json:"tags,omitempty"`   // OpenAPI tags (auto-derived from the parent command)
	Group             string               `json:"group,omitempty"`  // tool-group this operation belongs to (clicky/tool-group)
	DataFunc          DataFunc             `json:"-"`                // Direct data provider, bypasses stdout capture
	ContextDataFunc   ContextDataFunc      `json:"-"`                // Context-aware data provider; preferred over DataFunc when set
	LookupFunc        DataFunc             `json:"-"`                // Direct filter metadata provider
	ContextLookupFunc ContextLookupFunc    `json:"-"`                // Context-aware filter metadata provider; preferred over LookupFunc when set
	Clicky            *ClickyOperationMeta `json:"-"`                // Entity semantics used for OpenAPI extensions
	ResponseType      reflect.Type         `json:"-"`                // Static response type for OpenAPI generation
	ResponseArray     bool                 `json:"-"`                // Response body is an array of ResponseType
	ResponsePaged     bool                 `json:"-"`                // Response body is a paged envelope around ResponseType rows
	ResponseEntityID  bool                 `json:"-"`                // Array item schema should include Clicky _id metadata
}

type RPCParameter struct {
	Name        string      `json:"name"`
	Type        string      `json:"type"`
	Description string      `json:"description"`
	Required    bool        `json:"required"`
	Default     interface{} `json:"default,omitempty"`
	In          string      `json:"in,omitempty"` // "query", "path", "header" for REST
}

type RPCService struct {
	Name        string         `json:"name"`
	Version     string         `json:"version"`
	Description string         `json:"description"`
	Operations  []RPCOperation `json:"operations"`
}

type ResponseOpenAPIMeta struct {
	Type     reflect.Type
	Array    bool
	Paged    bool
	EntityID bool
}

type Schema struct {
	Type       string              `json:"type"`
	Properties map[string]Property `json:"properties"`
	Required   []string            `json:"required"`
}

type SearchableFilter[ListOpts any] interface {
	OptionsWithQuery(opts ListOpts, query string, limit int) (options map[string]api.Textable, total int)
}

type TypedFilter[ListOpts any] interface {
	LookupType() string
}