entity

type AccessControl struct {
	Read   string // List + Get
	Create string
	Update string
	Delete string
}

type AccessDeclaration struct {
	Read   string `json:"read,omitempty"`
	Create string `json:"create,omitempty"`
	Update string `json:"update,omitempty"`
	Delete string `json:"delete,omitempty"`
}

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

type CardFields struct {
	Title    string   `json:"title,omitempty"`
	Subtitle string   `json:"subtitle,omitempty"`
	Badge    string   `json:"badge,omitempty"`
	Meta     []string `json:"meta,omitempty"`
}

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

type DisplayConfig struct {
	Singular string `json:"singular,omitempty"`
	Plural   string `json:"plural,omitempty"`
	// TitleFields name a record in lists, drawers, pickers and
	// breadcrumbs: their values joined with " · ". A Relation field
	// contributes the related record's own title, so a subscription
	// titled by customer_id and plan_id reads "Ada Lovelace · Pro". The
	// first carries the list's record link.
	TitleFields []string `json:"title_fields,omitempty"`
	Description string   `json:"description,omitempty"`
	Columns     []string `json:"columns,omitempty"`

	// Nav places the entity in the sidebar. Hide drops it from nav and the
	// dashboard; it never changes what the admin exposes.
	Nav    *EntityNav  `json:"nav,omitempty"`
	Views  []ListView  `json:"views,omitempty"`
	Facets []string    `json:"facets,omitempty"`
	Form   *EntityForm `json:"form,omitempty"`
	Card   *CardFields `json:"card,omitempty"`

	// Fields holds per-field screen hints keyed by field name.
	Fields map[string]FieldDisplay `json:"fields,omitempty"`

	// PageSizes lists the choices the page-size menu offers. Each entry must
	// be positive and within Pagination.MaxListLimit when that is set.
	PageSizes []int `json:"page_sizes,omitempty"`

	// NoDuplicate and NoBulk turn off the Duplicate row action, or every
	// bulk action, for this entity. The No prefix matches NoQuery.
	NoDuplicate bool `json:"no_duplicate,omitempty"`
	NoBulk      bool `json:"no_bulk,omitempty"`
}

type Endpoint struct {
	Method       string          `json:"method"`
	Path         string          `json:"path"`
	Name         string          `json:"name,omitempty"`
	Description  string          `json:"description,omitempty"`
	MCP          bool            `json:"mcp,omitempty"`
	InputSchema  []schema.Field  `json:"inputSchema,omitempty"`
	OutputSchema []schema.Field  `json:"outputSchema,omitempty"`
	Handler      http.Handler    `json:"-"`
	MCPHandler   mcp.ToolHandler `json:"-"`

	// MCPGate is an optional per-caller precondition for the MCP twin. It
	// runs before MCPHandler on every tools/call, and decides whether the
	// tool is visible to that caller in tools/list.
	//
	// It exists because the two front doors of one Endpoint do not get the
	// same protection for free: Handler inherits the route's middleware
	// chain, while MCPHandler is registered straight onto the MCP server and
	// sees none of it. An endpoint behind auth.RequireRole("editor") was
	// therefore role-checked over HTTP and ungated over MCP.
	//
	// When unset, the twin defaults to requiring an authenticated caller
	// (framework.MCPRequireUser). Set MCPPublic to opt out of that default;
	// set this to something stricter, e.g. auth.MCPRole("editor").
	MCPGate func(ctx context.Context) error `json:"-"`

	// MCPPublic opts the MCP twin out of the default authenticated-caller
	// gate, for an endpoint that really is anonymous over HTTP too. Ignored
	// when MCPGate is set.
	MCPPublic bool `json:"mcpPublic,omitempty"`
}

type Entity struct {
	Config     EntityConfig
	DB         *sql.DB
	PrimaryKey string // defaults to "id"

	// Version identifies the API version this entity is mounted under, when
	// registered via App.GroupEntity. It is the route group's full prefix
	// (e.g. "/api/v1"). Empty for entities registered via App.Entity, those
	// keep the historical single-version behaviour. The registry keys on
	// (Config.Name, Version) so the same entity name can coexist under
	// different versions; callers that don't care about version resolve the
	// unversioned or sole entity via Registry.Get.
	Version string

	// OpenAPITag is the tag applied to this entity's operations in the
	// generated OpenAPI document. Set from the route group's OpenAPITag
	// when registered via App.GroupEntity; empty for App.Entity (the tag
	// defaults to the entity name in that case).
	OpenAPITag string
	// contains filtered or unexported fields
}

type EntityConfig struct {
	Name       string            // entity name (e.g. "users")
	Table      string            // DB table name (defaults to snake_case of Name)
	Fields     []schema.Field    // typed field definitions
	Relations  []Relation        // entity relationships
	Endpoints  []Endpoint        // custom HTTP endpoints for this entity
	Scope      *ScopeConfig      // ownership, tenancy, and soft-delete behavior
	Pagination *PaginationConfig // list limits and keyset cursor shape
	Exposure   *ExposureConfig   // generated HTTP/MCP and access posture
	Timestamps *bool             // add created_at / updated_at columns; nil defaults to true
	Indices    []Index           // additional CREATE INDEX statements emitted by AutoMigrate
	Unmanaged  bool              // when true, the migration system never emits DDL for this object (it is created elsewhere, e.g. a view, an FTS virtual table, or a legacy/external table). The ORM still queries it.

	// Properties holds caller-owned metadata. The framework does not
	// interpret any key; generators, plugins, and apps define their own keys.
	Properties map[string]any

	// SearchFields names the DB columns that ?q= free-text search operates
	// on (e.g. []string{"title","body"}). When non-empty, a List request
	// carrying ?q=<term> tokenizes the term on whitespace (deduped, capped
	// at filter.MaxSearchTerms) and AND-composes one LOWER(col) LIKE
	// pattern per token across the listed fields. Matching is
	// ASCII-case-insensitive everywhere (Unicode-folding on Postgres).
	// Leave nil to keep pre-existing behaviour (?q= is ignored). Column
	// names must be known, non-Hidden, and String/Text-typed; Define panics
	// otherwise. An entity WITHOUT SearchFields ignores ?q= exactly as
	// before (back-compat).
	SearchFields []string

	// Seed runs once per entity after AutoMigrate creates the table. The
	// framework tracks completion in the _gofastr_seeded ledger; subsequent
	// App.Start() calls skip the entity. Errors abort App.Start.
	//
	// Go-only: function values cannot be expressed in a blueprint
	// declaration. Apps whose entities come from a gofastr.yml blueprint
	// must wire seeding from Go.
	//
	// Concurrency: RunSeeds is NOT safe for concurrent invocation across
	// multiple processes. The framework assumes serialized startup (one
	// process / replica calls App.Start at a time). For HA setups, gate
	// seeding behind an external mechanism (init container, one-shot
	// job, advisory lock). Seed implementations should be idempotent
	// (INSERT … ON CONFLICT DO NOTHING) so accidental re-runs cannot
	// duplicate data.
	Seed func(ctx context.Context, db *sql.DB) error

	// SeedFS is an optional fs.FS (typically a //go:embed embed.FS) that
	// the framework attaches to the Seed function's context. Use with
	// SeedPath to point at a single file within the FS.
	//
	// Go-only: like Seed itself, an fs.FS cannot be expressed in JSON
	// entity declarations.
	SeedFS fs.FS

	// SeedPath is the path within SeedFS that Seed should consume.
	// Ignored when SeedFS is nil.
	SeedPath string

	// LenientFilters opts the entity's auto-CRUD List endpoint OUT of strict
	// filter parsing. By default an unknown top-level filter key (a typo like
	// ?stauts=active) is REJECTED with a 400 rather than silently dropped,
	// silently dropping it returns an UNFILTERED result set, which is a
	// data-exposure and broken-client hazard. Set true only as a migration
	// escape hatch for an endpoint that must tolerate arbitrary extra query
	// params (e.g. legacy tracking params); prefer fixing the caller.
	// Default false (strict).
	LenientFilters bool

	// AllowedFilterParams declares extra query-param keys that are NOT entity
	// columns but are legitimately consumed elsewhere on the List request,
	// typically read by a BeforeList hook or custom middleware (e.g. a
	// bespoke "?region=eu" scope param). Strict filter parsing skips these
	// instead of rejecting them, so the endpoint keeps typo-protection for
	// real fields without falling back to LenientFilters (which disables it
	// entirely). Reserved list controls are always allowed and need not be
	// listed here.
	AllowedFilterParams []string

	// Display holds the screen hints for this entity: names, columns,
	// views, form layout, nav placement and per-field drawing hints. It is
	// a pointer config like Scope: nil means every default, and Define
	// copies it deeply so a caller that edits its value afterwards changes
	// nothing the app checked or serves. It never widens what the API
	// accepts; see DisplayConfig for the boot check over every name it
	// holds and where the query strings inside it are parsed.
	Display *DisplayConfig
	// States names the Enum field holding the record's state and the
	// moves that change it. Unless Advisory is set the CRUD handler
	// refuses any write that changes the field or a stamp outside a move;
	// see StatesConfig. Nil means no states. Define copies it deeply.
	States *StatesConfig
	// Renames declares column renames (old name → new name) so the schema
	// diff emits a non-destructive ALTER TABLE … RENAME COLUMN instead of a
	// data-losing DROP of the old column + ADD of the new one. Rename is
	// otherwise indistinguishable from drop+add, so it requires this explicit
	// declaration; auto-detection is unsafe. A rename only fires when the old
	// column is present in the live schema and the new name is declared on the
	// entity. Declare it in Go or under an entity's `renames:` key in a
	// blueprint.
	Renames map[string]string
}

type EntityDeclaration struct {
	Name         string                 `json:"name"`
	Table        string                 `json:"table,omitempty"`
	Fields       []FieldDeclaration     `json:"fields"`
	Relations    []Relation             `json:"relations,omitempty"`
	Endpoints    []Endpoint             `json:"endpoints,omitempty"`
	Scope        *ScopeDeclaration      `json:"scope,omitempty"`
	Pagination   *PaginationDeclaration `json:"pagination,omitempty"`
	Exposure     *ExposureDeclaration   `json:"exposure,omitempty"`
	SearchFields []string               `json:"search_fields,omitempty"`
	Timestamps   *bool                  `json:"timestamps,omitempty"`
	Indices      []Index                `json:"indices,omitempty"`
	Properties   map[string]any         `json:"properties,omitempty"`
	Renames      map[string]string      `json:"renames,omitempty"`
	// Display is the declaration mirror of EntityConfig.Display, spelled
	// `display` under an entity with the snake_case keys documented on
	// DisplayConfig. Unlike the other groups it has no flat shorthand:
	// every key lives under display. Unknown keys inside it are refused.
	Display *DisplayConfig `json:"display,omitempty"`
	// States is the declaration mirror of EntityConfig.States, spelled
	// `states` with the keys documented on StatesConfig. Unknown keys
	// inside it are refused.
	States *StatesConfig `json:"states,omitempty"`
}

type EntityForm struct {
	Main []FormItem `json:"main,omitempty"`
	Side []FormItem `json:"side,omitempty"`
}

type EntityNav struct {
	Group     string `json:"group,omitempty"`
	Icon      string `json:"icon,omitempty"`
	Order     int    `json:"order,omitempty"`
	Hide      bool   `json:"hide,omitempty"`
	HideCount bool   `json:"hide_count,omitempty"`
}

type EnumColumn[T ~string] struct {
	// contains filtered or unexported fields
}

type ExposureConfig struct {
	CRUD      *bool            // nil or true generates CRUD routes
	MCP       bool             // register MCP CRUD tools
	Public    bool             // allow anonymous CRUD when no scope or access rule applies
	Access    AccessControl    // per-operation permissions
	ReadScope *ReadScopeConfig // narrows which rows a caller may read; nil = no row filtering
}

type ExposureDeclaration struct {
	CRUD      *bool                 `json:"crud,omitempty"`
	MCP       bool                  `json:"mcp,omitempty"`
	Public    bool                  `json:"public,omitempty"`
	Access    *AccessDeclaration    `json:"access,omitempty"`
	ReadScope *ReadScopeDeclaration `json:"read_scope,omitempty"`
}

type FieldDeclaration struct {
	Name         string   `json:"name"`
	Type         string   `json:"type"`
	Required     bool     `json:"required,omitempty"`
	Unique       bool     `json:"unique,omitempty"`
	Default      any      `json:"default,omitempty"`
	AutoGenerate string   `json:"auto_generate,omitempty"`
	ReadOnly     bool     `json:"read_only,omitempty"`
	Hidden       bool     `json:"hidden,omitempty"`
	NoQuery      bool     `json:"no_query,omitempty"`
	Max          *float64 `json:"max,omitempty"`
	Min          *float64 `json:"min,omitempty"`
	Pattern      string   `json:"pattern,omitempty"`
	Values       []string `json:"values,omitempty"`
	To           string   `json:"to,omitempty"`
	Many         bool     `json:"many,omitempty"`
}

type FieldDisplay struct {
	Label       string `json:"label,omitempty"`
	Help        string `json:"help,omitempty"`
	Placeholder string `json:"placeholder,omitempty"`

	// Locked draws the field read-only on screens. The screens' save
	// path drops a Locked key before the write; the API may still write
	// it. Refused at registration on a Required field with no Default:
	// the value never submits on create, so no form could create the
	// record.
	Locked bool `json:"locked,omitempty"`

	// Omit leaves the field out of forms and columns on purpose. Unlike
	// Hidden, the API still returns it. Refused at registration on a
	// Required field with no Default: no form could create the record.
	Omit bool `json:"omit,omitempty"`

	// ShowWhen shows the field only while `field = value` or
	// `field in [...]` holds on an editable Enum or Bool field. Parsed
	// with the query DSL when App.Entity registers the entity; any
	// other shape is refused there. A hidden region's controls are
	// disabled, so they never submit — refused at registration on a
	// Required field with no Default, like Omit.
	ShowWhen string `json:"show_when,omitempty"`

	// Input picks a different input and cell for the same storage: a
	// built-in kind (email, url, color, markdown, code) or one the app
	// registers in entityui.Extensions.Kinds. A key here; whether the
	// kind exists is checked when entityui.New builds the app's UI.
	Input string `json:"input,omitempty"`
}

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

type FormItem struct {
	Field     string     `json:"-"`
	Row       []string   `json:"row,omitempty"`
	Section   string     `json:"section,omitempty"`
	Help      string     `json:"help,omitempty"`
	Collapsed bool       `json:"collapsed,omitempty"`
	Items     []FormItem `json:"items,omitempty"`
}

type Index struct {
	Name       string   `json:"name,omitempty"`
	Columns    []string `json:"columns,omitempty"`
	Unique     bool     `json:"unique,omitempty"`
	Expression string   `json:"expression,omitempty"`
}

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

type ListView struct {
	Key     string `json:"key"`
	Label   string `json:"label,omitempty"`
	Where   string `json:"where,omitempty"`
	Sort    string `json:"sort,omitempty"`
	As      string `json:"as,omitempty"`
	Default bool   `json:"default,omitempty"`
}

type OnDeleteAction string

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

type PaginationConfig struct {
	CursorField  string
	CursorFields []string
	MaxListLimit int
}

type PaginationDeclaration struct {
	CursorField  string   `json:"cursor_field,omitempty"`
	CursorFields []string `json:"cursor_fields,omitempty"`
	MaxListLimit int      `json:"max_list_limit,omitempty"`
}

type ReadScopeConfig struct {
	Filter       []RowPredicate
	Unrestricted string
}

type ReadScopeDeclaration struct {
	Filter       []RowPredicateDeclaration `json:"filter,omitempty"`
	Unrestricted string                    `json:"unrestricted,omitempty"`
}

type Registry interface {
	// All returns a snapshot of every registered entity keyed by name.
	// Map iteration order is randomised by Go; for stable iteration use
	// AllSorted().
	All() map[string]*Entity

	// AllSorted returns every registered entity in alphabetical order
	// by name. Use this when emitting bytes whose ordering matters
	// (OpenAPI, generated code, golden-file tests, ETag-cached
	// responses).
	AllSorted() []*Entity

	// Get retrieves one entity by name, or an error when no such entity
	// is registered. When multiple versions of the name exist and none is
	// unversioned, Get returns an ambiguity error.
	//
	// Get is NOT safe for resolving a relation target: it prefers the
	// unversioned entity, so a v1 relation would resolve an unversioned
	// declaration with different Hidden columns and different scopes. Use
	// ResolveTarget for anything that drives visibility or scoping.
	Get(name string) (*Entity, error)
}

type Relation struct {
	Type             RelationType   `json:"type"`
	Name             string         `json:"name"`                // logical name for this relation (e.g. "author", "comments")
	Entity           string         `json:"entity"`              // target entity/table name
	ForeignKey       string         `json:"foreign_key"`         // FK column name
	Through          string         `json:"through,omitempty"`   // pivot table name (ManyToMany only)
	LocalKey         string         `json:"local_key,omitempty"` // column on the local side of a ManyToMany pivot
	ForeignKeyTarget string         `json:"foreign_key_target,omitempty"`
	OnDelete         OnDeleteAction `json:"on_delete,omitempty"`     // referential action on delete (CASCADE, SET NULL, RESTRICT, NO ACTION)
	CascadeWrite     bool           `json:"cascade_write,omitempty"` // allows atomic parent-child creation/updates
}

type RelationType int

type RowPredicate struct {
	Field  string   // column name, exactly as declared on the entity
	Op     string   // "eq", "neq", "in", "not_in"; empty means "eq"
	Value  string   // single-value ops
	Values []string // "in" / "not_in"
}

type RowPredicateDeclaration struct {
	Field  string   `json:"field"`
	Op     string   `json:"op,omitempty"`
	Value  string   `json:"value,omitempty"`
	Values []string `json:"values,omitempty"`
}

type ScopeConfig struct {
	SoftDelete     bool   // add deleted_at and hide deleted rows by default
	MultiTenant    bool   // scope rows to the tenant in the request context
	TenantField    string // tenant column; empty uses tenant_id
	OwnerField     string // owner column stamped and scoped by auto-CRUD
	CrossOwnerRead string // permission that lifts owner scoping for reads only
}

type ScopeDeclaration struct {
	SoftDelete     bool   `json:"soft_delete,omitempty"`
	MultiTenant    bool   `json:"multi_tenant,omitempty"`
	TenantField    string `json:"tenant_field,omitempty"`
	OwnerField     string `json:"owner_field,omitempty"`
	CrossOwnerRead string `json:"cross_owner_read,omitempty"`
}

type StatesConfig struct {
	// Field is the Enum field holding the state.
	Field string `json:"field"`
	// Initial lists the values a create may set. Empty means the field's
	// Default alone; a field with neither is refused at boot.
	Initial []string `json:"initial,omitempty"`
	// Transitions are the moves, in the order screens draw them.
	Transitions []Transition `json:"transitions,omitempty"`
	// Advisory releases the state field and the stamps to direct writes,
	// today's behaviour, and keeps the moves as calls and buttons. For an
	// entity whose status is not a business rule.
	Advisory bool `json:"advisory,omitempty"`
}

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

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

type Transition struct {
	// Key names the move in its route (POST <api>/<entity>/<id>/transitions/<key>)
	// and its MCP tool: lowercase segments joined by single underscores
	// (see transitionKeyGrammar), unique on the entity, and not one of the
	// names a generated surface already uses (reservedTransitionKeys).
	Key string `json:"key"`
	// Label is the button text. Empty draws the key.
	Label string `json:"label,omitempty"`
	// From lists the values the move starts from; never empty.
	From []string `json:"from"`
	// To is the value the move writes.
	To string `json:"to"`
	// Stamp names a Date or Timestamp field the move sets to the server's
	// current UTC date or time. The client never supplies it.
	Stamp string `json:"stamp,omitempty"`
	// Variant is the button variant screens draw the move with
	// (ui.ParseButtonVariant spellings). Empty is the screen's default.
	Variant string `json:"variant,omitempty"`
	// Permission, when set, is required on top of the entity's update
	// access. Empty means update access alone.
	Permission string `json:"permission,omitempty"`
	// System moves get no route, button or MCP tool; only Go code calls
	// RunTransition for them (a job marking invoices past due).
	System bool `json:"system,omitempty"`
}

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

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

type ValidatorFunc func(ctx context.Context, data map[string]any) map[string]string

type VersionedRegistry interface {
	// GetVersioned retrieves the entity registered under name at exactly
	// version (the route-group prefix it was mounted at; "" for the
	// unversioned App.Entity registration).
	GetVersioned(name, version string) (*Entity, error)
}