admin

type APIKeyStore interface {
	List(ctx context.Context) ([]*auth.APIKey, error)
	Create(ctx context.Context, createdBy *uuid.UUID, in *auth.CreateAPIKeyInput) (*auth.APIKeyWithSecret, error)
	Revoke(ctx context.Context, id uuid.UUID, revokedBy *uuid.UUID) error
	Regenerate(ctx context.Context, id uuid.UUID) (string, error)
	Delete(ctx context.Context, id uuid.UUID) error
}

type AddressBanner struct {
	Path                 string
	ChooseHref, KeepHref string
	// KeepLabel is "Keep <address>…".
	KeepLabel string
}

type AddressLock string

type AddressService interface {
	State() AddressState
	// Assess ranks a candidate against the reserved names and the site.
	Assess(ctx context.Context, path string) adminpath.Result
	// Generate returns a new random strong candidate. It stores nothing.
	Generate() string
	// Apply stores req.Path and serves the admin there from now on.
	Apply(ctx context.Context, req ApplyRequest) (ApplyResult, error)
	// Keep records that an owner knowingly accepted the current address.
	Keep(ctx context.Context, by string) error
}

type AddressState struct {
	Path    string
	Level   adminpath.Level
	Reasons []adminpath.Reason
	// SetBy and SetAt are nil for an address the server generated itself and
	// for installs that predate the record.
	SetBy string
	SetAt *time.Time
	// AckBy and AckAt are set when an owner knowingly accepted a weak address.
	AckBy string
	AckAt *time.Time
	Lock  AddressLock
	// Pinned is the environment variable name behind AddressLockedEnv. It is
	// data from the server so no template spells the address or its source.
	Pinned string
}

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

type AgentStats interface {
	agents.StatsStore
	FirstCrawls(ctx context.Context, rg agents.Range, p agents.Page) ([]agents.FirstCrawlRow, int, error)
	FirstCrawlAggregates(ctx context.Context, rg agents.Range) (agents.FirstCrawlAgg, error)
	PublishedPages(ctx context.Context) (int, error)
	FetchesBySchema(ctx context.Context, rg agents.Range) ([]agents.SeriesPoint, error)
	HealthSeries(ctx context.Context, rg agents.Range) ([]agents.HealthDay, error)
	NeverFetchedBySchema(ctx context.Context) ([]agents.SchemaCount, error)
	agents.RobotsStore
}

type ApplyRequest struct {
	Path string
	// By is the display name or email of the owner choosing it.
	By string
	// Ack is true when the owner typed the confirmation for a weak address.
	Ack bool
}

type ApplyResult struct{ Path string }

type Assets struct {
	CSSURL    string
	Importmap template.HTML
	Tokens    []byte
	// contains filtered or unexported fields
}

type AuditEvent struct {
	ActorID, Actor, Action, Target string
	Detail                         map[string]any
}

type AuditReader interface {
	Recent(ctx context.Context, limit, offset int) ([]AuditRow, int, error)
	Latest(ctx context.Context, limit int) ([]AuditRow, error)
}

type AuditRow struct {
	ID                    int64
	At                    time.Time
	Actor, Action, Target string
	Detail                map[string]any
}

type Authenticator interface {
	LoginSession(ctx context.Context, email, password, userAgent, ip string) (*user.User, string, error)
	IssueSession(ctx context.Context, userID uuid.UUID, userAgent, ip string) (string, error)
}

type AuthorStore interface {
	List(ctx context.Context) ([]*person.Person, error)
	Resolve(ctx context.Context, name string) (entity.Byline, error)
}

type BackupInfo struct {
	ID           string
	Kind         string // BackupManual or BackupPreUpdate
	Target       string // the version a pre-update backup was taken for
	State        string // BackupRunning, BackupOK or BackupFailed
	Percent      int
	Error        string
	Created      time.Time
	Size         int64
	Parts        []string // archive members, e.g. core.dump, content.tar.gz
	Plugins      []string
	MediaMissing int // referenced media files that were not on disk
}

type BackupsService interface {
	List(ctx context.Context) (BackupsState, error)
	// Start begins a manual backup in the background and returns its id.
	// It returns ErrBackupRunning when one is already running.
	Start(ctx context.Context, actor string) (string, error)
	// Open returns the archive for download. The caller closes it.
	Open(ctx context.Context, id string) (io.ReadSeekCloser, BackupInfo, error)
	// Delete removes a finished backup; ErrBackupNotFound for an unknown id.
	Delete(ctx context.Context, id string) error
}

type BackupsState struct {
	Rows          []BackupInfo // newest first
	Running       bool
	FreeBytes     uint64 // free space where backups are written; 0 when unknown
	KeepManual    int
	KeepPreUpdate int
}

type ConfirmInfo struct {
	Name                    string
	Downgrade, SignerChange bool
	// WidenedAccess is set when an update can call web addresses the installed
	// version could not; it also clears the plugin's grants.
	WidenedAccess          bool
	NewHosts               []string
	NewFetchAny            bool
	NewIsland              bool
	NewScripts             bool
	OldVersion, NewVersion string
	OldSigner, NewSigner   string
	// Missing are section types the active theme would lose.
	Missing []MissingSection
}

type ContentDeps struct {
	Entities EntityStore
	Terms    TermStore
	Media    MediaStore
	Authors  AuthorStore
	// PublicPath is the public URL path of an entity ("" when unknown).
	PublicPath func(ctx context.Context, e *entity.Entity) string
	// PublicPaths is PublicPath for many entities of one schema at once (one
	// ancestor query for all of rows, none without nested URLs). routable is
	// false, with nil paths, when the schema has no public URL; rows may be nil
	// to ask only that. Nil falls back to PublicPath per entity.
	PublicPaths func(ctx context.Context, sc *entity.EntitySchema, rows []*entity.Entity) (paths []string, routable bool)
	// Theme lists the active theme's section types; nil (or empty) when page
	// rendering is off, which leaves the page editor without "Add section" and
	// without a preview.
	Theme func() []ThemeSection
	// Preview renders unsaved attributes: it answers a POST with the JSON body
	// of /api/v1/render/preview (entity_id, schema, attributes, path, canvas)
	// with the full HTML document. Nil turns the live preview off.
	Preview http.Handler
	// RenderNodes applies builder ops to a draft page doc and renders node
	// fragments for the canvas: it answers a POST with the JSON body of the
	// node render request (the preview body plus ops, render, css, seq).
	// Nil turns the in-place canvas patching off (the editor reloads the frame).
	RenderNodes http.Handler
	// Templates are the section templates; nil hides saving and inserting them.
	Templates TemplateStore
	// Crawlers reads AI-crawler activity for the blog editor's "AI crawlers"
	// card; nil hides the card.
	Crawlers CrawlerStore
	// Recovery keeps the unsaved work of a published post or page per user, so
	// it can be offered back after a closed tab. Nil turns recovery copies
	// off: the routes answer 204 and the editors get no copy.
	Recovery RecoveryStore
}

type CrawlerStore interface {
	EntityActivity(ctx context.Context, entityID uuid.UUID, agentIDs []string, today time.Time) (agents.EntityActivityData, error)
}

type Crumb = ui.Crumb

type CurrentUser struct {
	ID    string
	Name  string
	Email string
	Role  string
}

type Deps struct {
	Logger *slog.Logger
	// Sessions, Users and Site may be nil only in route-table builds: the
	// handlers are never invoked there.
	Sessions SessionStore
	Users    UserReader
	Site     SiteStore
	Nav      *Nav
	Auth     Authenticator
	Tokens   TokenService
	Finder   UserFinder
	Mailer   Mailer
	// BaseURL returns the site address the owner or operator configured
	// (PUBLIC_BASE_URL, else the Site address setting); "" when none is set.
	// Emailed links use only this, never the request's headers.
	BaseURL func(*http.Request) string
	// CookieSecure is ADMIN_COOKIE_SECURE: a floor for the Secure cookie
	// attribute (TLS seen on the request also turns it on).
	CookieSecure bool
	Manager      UserManager
	Passwords    PasswordChanger
	APIKeys      APIKeyStore
	// Webhooks is the outgoing-webhook service behind Settings > Webhooks; nil
	// answers that section with 404. Set it only when non-nil: a typed nil
	// would defeat the check.
	Webhooks WebhookStore
	// WebhookDeliveryOn is true when a job sends queued webhooks; false shows
	// the "delivery is switched off" notice.
	WebhookDeliveryOn bool
	// WebhooksPluginLeft says a plugin named webhooks is still installed (one
	// that was not moved into core); true shows the notice on the webhooks page.
	WebhooksPluginLeft func(context.Context) bool
	// Invalidate clears the rendered-page cache after settings change.
	Invalidate func(context.Context)
	// BuilderTokens reports whether the live theme opted in to the design
	// tokens (theme.json builder.tokens); nil means no.
	BuilderTokens func() bool
	// BuilderParts lists the layout slots (header, footer, single, archive) the
	// live theme renders parts for (theme.json builder.parts); nil means none.
	BuilderParts func() []string
	// PageCache is the rendered-page cache behind Settings > Performance;
	// nil answers that page with 503.
	PageCache PageCacheService
	// Spam is the spam protection settings behind Settings > Forms > Spam
	// protection; nil answers that page with 503.
	Spam SpamService
	// EmailSettings is the SMTP configuration behind Settings > Email and the
	// setup wizard's Email step; nil answers those pages with 503.
	EmailSettings EmailSettingsService
	// Updates is the automatic-update service behind Settings > Updates and
	// the owner banner; nil renders that page as unavailable and no banner.
	// Set it only when non-nil: a typed nil would defeat the check.
	Updates UpdatesService
	// Stats is the opt-in install stats service behind the Install stats card
	// on Settings > Updates, the setup wizard step and the owner banner; nil
	// hides all three. Set it only when non-nil.
	Stats StatsService
	// UpdatesUnavailable is why Updates is nil, shown on the page.
	UpdatesUnavailable string
	// Backups is the backup service behind Settings > Backups; nil answers
	// that page with 503. Set it only when non-nil.
	Backups BackupsService
	// Audit records an owner action in the admin audit log; nil skips it.
	Audit func(ctx context.Context, e AuditEvent)
	// AuditLog reads the audit log back; nil leaves the Audit log page
	// unmounted. Set it only when non-nil.
	AuditLog AuditReader
	Owners   OwnerCreator
	Starter  StarterInstaller
	// SetupCode gates the first owner; nil disables the wizard's first step.
	SetupCode *SetupCode
	// NeedsSetup reports a fresh install (no users yet); /admin/login then
	// sends visitors to the setup wizard. Nil means never.
	NeedsSetup func(context.Context) bool
	// FlashKey signs the flash cookie (derive it from the server secret).
	FlashKey []byte
	// SiteNameFallback is shown until the site config has a name.
	SiteNameFallback string
	// RateLimit wraps the unauthenticated auth screens; nil means none.
	RateLimit func(http.Handler) http.Handler
	// Growth holds the services of the menus, forms, redirects, dashboards,
	// linking and plugins screens (see growth.go).
	Growth GrowthDeps
	// Content holds the services behind the entity, schema, taxonomy and media
	// screens (v1-11).
	Content ContentDeps
	// People is the person behind each user account: the profile pages and
	// the sign-in profile gate. Nil skips the gate.
	People PeopleStore
	// PersonPath is the public path of a person by slug (the person content
	// type's URL pattern); nil or "" falls back to /author/{slug}.
	PersonPath func(ctx context.Context, slug string) string
	// Import runs the WordPress import wizard (importjob.Manager); nil answers 503.
	Import ImportService
	// Dir, when set, replaces the embedded templates/CSS/JS with files from
	// disk and rebuilds them per request (dev loop, HATAMOTO_ADMIN_DIR).
	Dir string
	// PublicAPIPrefix is the extra public API prefix (PUBLIC_API_PREFIX), empty
	// when only /api/v1/public is served. Form addresses shown in the admin use it.
	PublicAPIPrefix string
	// Dev turns on the development-only pages (the styleguide, HATAMOTO_DEV=1).
	Dev bool
	// Demo is the public demo mode (HATAMOTO_DEMO=1): a fixed banner, the
	// public login on the sign-in page and the refusals of config.DemoConfig.
	Demo config.DemoConfig

	// AdminPath is the URL prefix every admin route is served under. Empty
	// means DefaultAdminPath; otherwise it is "/" plus one lowercase [a-z0-9-]
	// segment of 1 to 64 characters, not starting or ending with "-". Reserved
	// names and the spec's length rules come in PR 2. Demo mode requires the
	// default.
	AdminPath string
	// Address is the live admin address: its state, the picker's checks and
	// the change itself. Nil hides the address screens (route-table builds).
	Address AddressService
	// Sudo, when set, holds the sudo grants. The server builds one and passes
	// it to every Admin it swaps in, so an owner keeps sudo across a change.
	// Nil means this Admin keeps its own.
	Sudo *SudoStore
}

type EmailInput struct {
	Provider    string
	SESRegion   string
	Host        string
	Port        int
	Security    email.Security
	Username    string
	Password    string
	FromAddress string
	FromName    string
}

type EmailSettingsService interface {
	Get(ctx context.Context) (EmailSettingsView, error)
	// Check connects and signs in with in without sending a message. A
	// *email.CheckError explains a failure. keepPassword uses the saved
	// password instead of in.Password.
	Check(ctx context.Context, in EmailInput, keepPassword bool) error
	// Save stores in (sealing the password) and applies it at once.
	// keepPassword keeps the saved password instead of in.Password.
	Save(ctx context.Context, in EmailInput, keepPassword bool) error
	// Reset deletes the saved settings so the server's SMTP_* apply again.
	Reset(ctx context.Context) error
}

type EmailSettingsView struct {
	// Saved reports whether a settings row exists. The form fields below are
	// defaults (custom, 587, STARTTLS) when it does not.
	Saved       bool
	Provider    string
	SESRegion   string
	Host        string
	Port        int
	Security    email.Security
	Username    string
	FromAddress string
	FromName    string

	// PasswordSaved: a password is stored and can be read.
	PasswordSaved bool
	// PasswordLost: a password is stored but cannot be read (the server
	// SECRET changed); the owner must type it again.
	PasswordLost bool

	Source EmailSource
	// Configured: the live service can send.
	Configured bool
	// Disabled: EMAIL_DISABLED=true switches all sending off.
	Disabled bool
}

type EmailSource string

type EntityNavEntry struct {
	ID, Href, Label string
	Count           int
	Current         bool
}

type EntityStore interface {
	ListSchemas(ctx context.Context) ([]*entity.EntitySchema, error)
	GetSchema(ctx context.Context, id uuid.UUID) (*entity.EntitySchema, error)
	CreateSchema(ctx context.Context, in *entity.CreateSchemaInput) (*entity.EntitySchema, error)
	UpdateSchema(ctx context.Context, id uuid.UUID, in *entity.UpdateSchemaInput) (*entity.EntitySchema, error)
	DeleteSchema(ctx context.Context, id uuid.UUID) error

	GetEntity(ctx context.Context, id uuid.UUID) (*entity.Entity, error)
	CreateEntity(ctx context.Context, userID *uuid.UUID, in *entity.CreateEntityInput) (*entity.Entity, error)
	UpdateEntity(ctx context.Context, id uuid.UUID, userID *uuid.UUID, in *entity.UpdateEntityInput) (*entity.Entity, error)
	UpdateEntityStatus(ctx context.Context, id uuid.UUID, userID *uuid.UUID, status entity.EntityStatus) (*entity.Entity, error)
	ScheduleEntity(ctx context.Context, id uuid.UUID, userID *uuid.UUID, at time.Time) (*entity.Entity, error)
	DeleteEntity(ctx context.Context, id uuid.UUID) error
	ListEntitiesWithOffset(ctx context.Context, f *entity.ListEntitiesFilter, p *entity.OffsetPage) (*entity.OffsetPagedResult[*entity.Entity], error)
	CountEntitiesBySchemaStatus(ctx context.Context) ([]entity.SchemaStatusCount, error)
	CountEntitiesByParent(ctx context.Context, limit int) ([]entity.ParentCount, error)
	CountEntityChildren(ctx context.Context, parentIDs []uuid.UUID) (map[uuid.UUID]int, error)
	// RefUsers lists what embeds a block (a block's usage list).
	RefUsers(ctx context.Context, blockID uuid.UUID, limit int) (users []entity.RefUser, capped bool, err error)

	ListVersions(ctx context.Context, id uuid.UUID, limit int) ([]*entity.EntityVersion, error)
	GetVersion(ctx context.Context, id uuid.UUID, version int) (*entity.EntityVersion, error)
	RestoreVersion(ctx context.Context, id uuid.UUID, userID *uuid.UUID, version int) (*entity.Entity, error)
}

type Flash struct {
	Kind    string `json:"k"` // success | error | warning | info
	Message string `json:"m"`
	Expires int64  `json:"e"`
	Inline  bool   `json:"-"` // stay beside the form instead of becoming a toast
}

type FormMailer interface {
	Configured() bool
	Forward(ctx context.Context, f *form.Form, sub *form.FormSubmission, to []string, by string) error
}

type FormStore interface {
	ListForms(ctx context.Context, status string) ([]*form.Form, error)
	GetForm(ctx context.Context, id uuid.UUID) (*form.Form, error)
	CreateForm(ctx context.Context, in *form.CreateFormInput) (*form.Form, error)
	UpdateForm(ctx context.Context, id uuid.UUID, in *form.UpdateFormInput) (*form.Form, error)
	DeleteForm(ctx context.Context, id uuid.UUID) error
	ListSubmissions(ctx context.Context, formID uuid.UUID, p *form.ListSubmissionsParams) ([]*form.FormSubmission, int, error)
	GetSubmission(ctx context.Context, id uuid.UUID) (*form.FormSubmission, error)
	UpdateSubmission(ctx context.Context, id uuid.UUID, in *form.UpdateSubmissionInput) (*form.FormSubmission, error)
	DeleteSubmission(ctx context.Context, id uuid.UUID) error
}

type GrowthDeps struct {
	Menus     MenuStore
	Forms     FormStore
	Redirects RedirectStore
	Explain   URLExplainer
	Pickers   Pickers
	Sections  SectionStore
	Agents    AgentStats
	Referrals Referrals
	Linking   LinkingStore
	Plugins   PluginAdmin
	Packages  PackageAdmin
	FormMail  FormMailer
	// AgentRegistry names the crawlers (agents.Default() when nil).
	AgentRegistry *agents.Registry
}

type ImportService interface {
	Begin(ctx context.Context, actor importjob.Actor, src importjob.Source) (uuid.UUID, error)
	Get(ctx context.Context, id uuid.UUID) (*importjob.Run, error)
	Recent(ctx context.Context, limit int) ([]importjob.Run, error)
	Start(ctx context.Context, id uuid.UUID, actor importjob.Actor, host string, o importjob.Options) error
	Resume(ctx context.Context, id uuid.UUID, actor importjob.Actor, host string, cred *importjob.Source) error
	Cancel(ctx context.Context, id uuid.UUID, actor importjob.Actor) error
}

type InsertOutcome struct {
	Inserted   bool
	SkipReason string
}

type LinkingStore interface {
	ListRules(ctx context.Context, f *linkingv2.RuleFilter) (*linkingv2.PaginatedRulesResult, error)
	GetRule(ctx context.Context, id uuid.UUID) (*linkingv2.LinkRule, error)
	CreateRule(ctx context.Context, in *linkingv2.CreateRuleInput) (*linkingv2.LinkRule, error)
	UpdateRule(ctx context.Context, id uuid.UUID, in *linkingv2.UpdateRuleInput) (*linkingv2.LinkRule, error)
	DeleteRules(ctx context.Context, ids []uuid.UUID) (int, error)
	DeleteRulesBySource(ctx context.Context, source string) (int, error)
	DeleteAllRules(ctx context.Context) (int, error)
	PreviewRule(ctx context.Context, phrase string, target uuid.UUID) (linkingv2.RulePreviewResult, error)
	Suggest(ctx context.Context, source uuid.UUID) ([]linkingv2.Suggestion, error)
	Equity(ctx context.Context) (*linkingv2.EquityReport, error)
	Inbound(ctx context.Context, target uuid.UUID) ([]linkingv2.EquityDetailRow, error)
	// EntityName is the display name of an entity, "" when it does not exist.
	EntityName(ctx context.Context, id uuid.UUID) string
	// Insert wraps the first usable mention of anchor in source's content with a
	// link to target (the suggestion panel's "Insert").
	Insert(ctx context.Context, source, target uuid.UUID, anchor string) (InsertOutcome, error)
	// SuggestIn is Suggest against the editor's live (unsaved) content html.
	SuggestIn(ctx context.Context, source uuid.UUID, html string) ([]linkingv2.Suggestion, error)
	// WrapIn links the first usable mention of anchor in html to target and
	// returns the new html. Nothing is stored: the editor saves it as usual.
	WrapIn(ctx context.Context, target uuid.UUID, anchor, html string) (string, InsertOutcome, error)
}

type Mailer interface {
	IsConfigured() bool
	SendPasswordReset(ctx context.Context, to string, data email.ResetMailData) error
	SendInvite(ctx context.Context, to string, data email.InviteMailData) error
	SendTest(ctx context.Context, to, siteName string) error
	SendAdminAddressChanged(ctx context.Context, to string, data email.AdminAddressChangedData) error
	SendAdminAddressSetup(ctx context.Context, to string, data email.AdminAddressSetupData) error
}

type MediaStore interface {
	Upload(ctx context.Context, userID *uuid.UUID, file io.Reader, filename, mimeType string, size int64) (*media.Media, error)
	Get(ctx context.Context, id uuid.UUID) (*media.Media, error)
	List(ctx context.Context, f *media.ListMediaFilter, limit, offset int) (*media.PagedResult, error)
	Update(ctx context.Context, id uuid.UUID, in *media.UpdateMediaInput) (*media.Media, error)
	Delete(ctx context.Context, id uuid.UUID) error
	Usage(ctx context.Context, m *media.Media) ([]media.Usage, error)
	Config() media.Config
}

type MenuStore interface {
	ListMenus(ctx context.Context) ([]*menu.Menu, error)
	GetMenuWithItems(ctx context.Context, id uuid.UUID) (*menu.Menu, error)
	CreateMenu(ctx context.Context, in *menu.CreateMenuInput) (*menu.Menu, error)
	ReplaceMenu(ctx context.Context, id uuid.UUID, fields *menu.UpdateMenuInput, items []menu.ReplaceItem) (*menu.Menu, error)
	DeleteMenu(ctx context.Context, id uuid.UUID) error
}

type MissingSection struct {
	Type string
	Uses int
}

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

type NavEntry struct {
	Label, Href, Icon, Badge string
	Current                  string
	Group                    string
}

type NavGroup struct {
	Label string
	Items []NavEntry
}

type NavItem struct {
	ID, Label, Href, Icon string
	Order                 int
	// Group is the sidebar section title; consecutive items sharing one are
	// listed together, and "" means no title. Items sharing a Group must have
	// adjacent Order, or GroupNav splits them into separate groups.
	Group string
	Roles []string
	// Prefixes are the paths the item covers: it is the current section when
	// the request path equals one or lies below it (at a "/" boundary). Empty
	// means Href alone.
	Prefixes []string
	// Exact limits the item to Href alone: Overview lives at /admin, which is
	// the parent of every other admin path.
	Exact bool
	// Badge is evaluated per render ("" hides it).
	Badge func() string
	// Visible, when set, decides visibility per role instead of Roles.
	Visible func(role string) bool
	// HrefFor, when set, resolves the link per role instead of Href.
	HrefFor func(role string) string
}

type OwnerCreator interface {
	CreateFirstOwner(ctx context.Context, name, email, password string) (*user.User, error)
}

type PackageAdmin interface {
	Registry(ctx context.Context) RegistryView
	// Fetch downloads kind/name from the registry (hash-checked).
	Fetch(ctx context.Context, kind, name string) ([]byte, error)
	// Inspect parses a package for the permission prompt.
	Inspect(ctx context.Context, data []byte) (PackageSummary, error)
	// Install stores and applies the package; grant is the approved permission
	// list (nil keeps the earlier grant); confirm is the owner's yes to a
	// Summary.Confirm. Reasons the owner should read come back as *Refusal.
	Install(ctx context.Context, data []byte, source string, grant []string, confirm bool) error
	SetEnabled(ctx context.Context, name string, on bool) error
	Uninstall(ctx context.Context, kind, name string, dropData bool) error
	AllowUnsigned(ctx context.Context) bool
	SetAllowUnsigned(ctx context.Context, on bool) error

	Themes(ctx context.Context) ([]ThemeInfo, error)
	MissingSections(ctx context.Context, theme string) ([]MissingSection, error)
	// Activate switches the site to the theme ("default" is the built-in one).
	Activate(ctx context.Context, theme string) error
	ThemeSettingsSchema(ctx context.Context, theme string) []byte
	ThemeSettings(ctx context.Context, theme string) (map[string]any, error)
	SaveThemeSettings(ctx context.Context, theme string, values map[string]any) (schemaform.Errors, error)
	// PreviewURL is the public-site URL that starts a preview of the theme.
	PreviewURL(theme string) string

	// UIFile serves a file of the plugin package's ui/ directory; it reports
	// false when the plugin is not loaded or has no such file.
	UIFile(w http.ResponseWriter, r *http.Request, plugin, file, csp, cache string) bool
	// CallRoute runs one of the plugin's own routes as the signed-in user.
	CallRoute(ctx context.Context, plugin, method, path string, query url.Values, body []byte, user CurrentUser) RouteResult
	// CallHost runs one host function of the plugin (its permissions apply);
	// the result is the sdk.CallResponse JSON.
	CallHost(ctx context.Context, plugin, fn string, args json.RawMessage) json.RawMessage
}

type PackageMeta struct {
	Enabled bool
	// WidgetOnly is set for a package that ships widgets and no plugin code:
	// the runtime has no status for it, and that is healthy.
	WidgetOnly bool
	Signed     bool
	Signer     string
	// FirstParty is set when the package is signed by one of the project's own keys
	// (whether that key is still trusted is Blocked's business).
	FirstParty bool
	// WebhooksImported is set (webhooks row only) when the boot step has recorded that
	// the plugin's subscriptions were copied into core.
	WebhooksImported bool
	Source           string
	// Update is the newer version the registry offers ("" when none).
	Update string
	// UpdateNew lists the permissions that update asks for and the installed
	// version does not; empty when Update is, or when it asks for nothing new.
	UpdateNew []string
	// Blocked says why policy keeps the package from loading (a signer that is
	// no longer trusted, a dev package in production); "" when it is not.
	Blocked string
	// ScriptsBlocked is set when the plugin ships browser JavaScript (an
	// assets/plugin.js, or script tags for the page head) that is not loaded
	// because the owner has not granted site.scripts.
	ScriptsBlocked bool
	// MarkupStopped lists the sections and partials that are not registered
	// because they carry scripts and the plugin lacks site.scripts.
	MarkupStopped []string
	// AsksScripts: its manifest lists site.scripts, so the owner can grant it.
	AsksScripts bool
	// Uninstalling is set while an uninstall is unfinished (retry it).
	Uninstalling bool
}

type PackageSummary struct {
	Kind, Name, Version, Description string
	Permissions, AllowedHosts        []string
	Signed                           bool
	Signer                           string
	// Problem says why installing would be refused (untrusted signer, bad
	// signature, unsigned while unsigned packages are off); "" when it would go ahead.
	Problem string
	// Updating is set when a package of that name is installed already.
	Updating         bool
	InstalledVersion string
	Granted          []string
	// Confirm is set when replacing the installed package needs the owner's
	// confirmation (older version, other signer, lost sections).
	Confirm *ConfirmInfo
}

type PageAnswer struct {
	Kind     string // entity | home | archive | ""
	Name     string
	Schema   string
	Path     string // canonical path
	EntityID string
}

type PageCacheService interface {
	Stats(ctx context.Context) PageCacheStats
	Settings(ctx context.Context) (PageCacheSettings, error)
	Save(ctx context.Context, s PageCacheSettings) error
	Clear(ctx context.Context) (pages int, err error)
	PreloadNow(ctx context.Context) (started bool, err error)
	PreloadStatus() PreloadStatus
}

type PageCacheSettings struct {
	Enabled                bool
	TTLSeconds, MaxMB      int
	PreloadEnabled         bool
	PreloadIntervalSeconds int
	// PreloadMode is "missing" (skip cached pages) or "all" (refresh).
	PreloadMode string
	// PreloadAfterChanges schedules a preload shortly after content changes.
	PreloadAfterChanges bool
}

type PageCacheStats struct {
	Pages                int
	Bytes, CapBytes      int64
	EffectiveTTL         time.Duration
	ServerDefaultTTL     time.Duration
	TTLSource            string
	ServerDefaultFromEnv bool
	BaseURLPinned        bool
	SchedulerAvailable   bool
}

type PasswordChanger interface {
	ChangePassword(ctx context.Context, userID uuid.UUID, current, newPassword string, keepSession *uuid.UUID) error
}

type PeopleStore interface {
	// ForUser returns the person a user owns, person.ErrNotFound when none.
	ForUser(ctx context.Context, userID uuid.UUID) (*person.Person, error)
	// Save writes the profile form, making the person from the typed name when
	// the user has none; invalid input is a *person.ValidationError.
	Save(ctx context.Context, userID uuid.UUID, in person.ProfileInput) (*person.Person, error)

	// List returns every person by name.
	List(ctx context.Context) ([]*person.Person, error)
	// PostCounts is the number of published entities credited to each person.
	PostCounts(ctx context.Context) (map[uuid.UUID]int, error)
	// LinkedUsers maps a person to the user that owns it (people without a
	// login are absent).
	LinkedUsers(ctx context.Context) (map[uuid.UUID]uuid.UUID, error)
	// Create makes a person without a login; a bad name is a *person.ValidationError.
	Create(ctx context.Context, by *uuid.UUID, name string) (*person.Person, error)
	// MergePeople folds drop into keep (person.ErrMergeBothLogins when both
	// have a login).
	MergePeople(ctx context.Context, keepID, dropID uuid.UUID) (*person.MergeResult, error)
}

type PickOption struct {
	Value string // entity id, or a term's archive path
	Label string
	Hint  string // schema, slug, kind
	Slug  string // an entity's slug (empty for terms)
}

type Pickers interface {
	SearchEntities(ctx context.Context, q string, limit int) ([]PickOption, error)
	SearchTerms(ctx context.Context, q string, limit int) ([]PickOption, error)
	// EntityName is the display name of an entity, "" when it does not exist.
	EntityName(ctx context.Context, id uuid.UUID) string
}

type PluginAdmin interface {
	Plugins() []PluginInfo
	Grant(ctx context.Context, name string, permissions []string) error
	// Settings is the stored settings with schema defaults merged and write-only
	// values masked.
	Settings(ctx context.Context, name string) (map[string]any, error)
	// StoredSecrets names the writeOnly settings that hold a value; the form
	// says "stored" for them and never shows the value.
	StoredSecrets(ctx context.Context, name string) (map[string]bool, error)
	// SaveSettings validates against the plugin's schema; problems come back as
	// field errors (dotted paths), not as an error.
	SaveSettings(ctx context.Context, name string, values map[string]any) (schemaform.Errors, error)
}

type PluginInfo struct {
	Name, Version, SDK, Description, Error, DataError string
	Loaded                                            bool
	Hooks, Permissions, Granted, AllowedHosts         []string
	// Refused is the part of Permissions this plugin may never be given (a
	// community plugin and its scripts); the page shows them unticked.
	Refused                      []string
	Routes, Cron, Cookies, Funcs []string // one human line each
	SettingsSchema               []byte
	// Package is set for a plugin installed from a package (nil for one loaded
	// from HATAMOTO_PLUGIN_DIR); UI for one that ships an admin page.
	Package *PackageMeta
	UI      *PluginUIInfo
}

type PluginNavEntry struct {
	ID, Href, Label, Marker string
	Muted, Current          bool
}

type PluginUIInfo struct {
	Title string
	// Entry is the HTML file under the package's ui/ directory.
	Entry string
	Roles []string
	// Functions are the host functions its page may call: what its granted
	// permissions allow.
	Functions []string
}

type Preload struct {
	URL       string
	Integrity string
}

type PreloadFailure struct {
	Path, Reason string
}

type PreloadStatus struct {
	Running       bool
	Done, Total   int
	HasResult     bool
	Finished      time.Time
	Pages, Errors int
	Duration      time.Duration
	StoppedEarly  bool
	Reason        string
	Skipped       int // pages already cached and left alone
	Failures      []PreloadFailure
}

type RecoveryCopy = recovery.Copy

type RecoveryStore interface {
	Put(ctx context.Context, user, entity uuid.UUID, c RecoveryCopy) error
	// Get returns nil, nil when there is no copy.
	Get(ctx context.Context, user, entity uuid.UUID) (*RecoveryCopy, error)
	Delete(ctx context.Context, user, entity uuid.UUID) error
}

type RedirectStore interface {
	ListRedirects(ctx context.Context, p redirect.RedirectListParams) ([]*redirect.Redirect, int, error)
	GetRedirect(ctx context.Context, id uuid.UUID) (*redirect.Redirect, error)
	CreateRedirect(ctx context.Context, in *redirect.CreateRedirectInput) (*redirect.Redirect, error)
	UpdateRedirect(ctx context.Context, id uuid.UUID, in *redirect.UpdateRedirectInput) (*redirect.Redirect, error)
	DeleteRedirect(ctx context.Context, id uuid.UUID) error
	List404Entries(ctx context.Context, p redirect.NotFoundListParams) ([]*redirect.NotFoundEntry, int, error)
	ListRecent404Entries(ctx context.Context, since time.Time, limit int) ([]*redirect.NotFoundEntry, error)
	Ignore404Entry(ctx context.Context, id uuid.UUID) error
	Delete404Entry(ctx context.Context, id uuid.UUID) error
}

type Referrals interface {
	AIReferrals(ctx context.Context, from, to time.Time) ([]analytics.ReferralDay, error)
	Pageviews(ctx context.Context, from, to time.Time) ([]analytics.DayCount, error)
}

type Refusal struct{ Msg string }

type RegistryEntry struct {
	Kind, Name, Version, Description, Homepage string
	Permissions                                []string
	Installed                                  bool
	InstalledVersion                           string
	// Update is set when the registry's version is newer than the installed one.
	Update bool
}

type RegistryView struct {
	Entries []RegistryEntry
	// Off means no registry is configured; Err says why a configured one failed.
	Off bool
	Err string
	// Host is the registry's host name, shown in the empty state when Err is set.
	Host string
}

type RouteResult struct {
	Status      int
	ContentType string
	Body        []byte
}

type ScriptTag struct {
	URL       string
	Integrity string
}

type SecondFactor interface {
	// Has reports whether the user enrolled a second factor. Return an error
	// when you cannot tell: sudo then refuses rather than skip the code.
	Has(ctx context.Context, userID uuid.UUID) (bool, error)
	// Verify checks the code the user typed. Return ErrWrongCode (or an error
	// wrapping it) for a wrong code, and any other error when you cannot tell.
	// Core only caps wrong codes per session (a handful per 15 minutes). A
	// provider should also count and lock its own failures per user, because a
	// session cap does not stop an attacker who opens new sessions.
	Verify(ctx context.Context, userID uuid.UUID, code string) error
}

type SectionStore interface {
	List(ctx context.Context, f *sectiontemplate.ListFilter, limit, offset int) (*sectiontemplate.ListResult, error)
	Get(ctx context.Context, id uuid.UUID) (*sectiontemplate.SectionTemplate, error)
	Update(ctx context.Context, id uuid.UUID, in *sectiontemplate.UpdateInput) (*sectiontemplate.SectionTemplate, error)
	Delete(ctx context.Context, id uuid.UUID) error
}

type SessionStore interface {
	Validate(ctx context.Context, token string) (*session.Session, error)
	Revoke(ctx context.Context, id uuid.UUID) error
	RevokeAllForUser(ctx context.Context, userID uuid.UUID) error
}

type SettingsSection struct {
	ID, Label, Icon, Desc, Href string
	// Group is the sidebar heading the section sits under (Site, Content,
	// System); empty for areas that show no headings.
	Group string
	Tabs  []SettingsTab
}

type SettingsTab struct {
	ID, Label, Href string
	Roles           []string
}

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

type SiteStore interface {
	Get(ctx context.Context) (*siteconfig.Config, error)
	Update(ctx context.Context, in siteconfig.UpdateInput) (*siteconfig.Config, error)
}

type SpamService interface {
	Settings(ctx context.Context) (spam.Settings, error)
	Save(ctx context.Context, s spam.Settings) error
	SealSecret(secret string) ([]byte, error)
	// SecretReadable reports whether the saved secret can be opened.
	SecretReadable(s spam.Settings) bool
	// TestSecret checks the saved secret with the provider.
	TestSecret(ctx context.Context, s spam.Settings) (valid bool, detail string, err error)
}

type StarterInstaller interface {
	Install(ctx context.Context, o starter.Options) (starter.Result, error)
}

type StatsBanner struct {
	PreviewHref string // Settings > Updates, at the card that shows what is sent
}

type StatsService interface {
	// View is the stored choice, whether the server configuration forces it
	// off, and the exact payload the daily ping would send.
	View(ctx context.Context) (StatsView, error)
	// Unanswered reports whether the owner still has to answer: the server
	// configuration does not turn stats off and the choice is unset. It must
	// be cheap, the banner asks it on every owner page.
	Unanswered(ctx context.Context) (bool, error)
	// ForcedOff reports HATAMOTO_TELEMETRY=off. It reads no state.
	ForcedOff() bool
	// Choose stores the owner's answer. Yes creates the install ID, No (or
	// switching off) deletes it.
	Choose(ctx context.Context, yes bool) error
	// Reset replaces the install ID with a new one.
	Reset(ctx context.Context) error
}

type StatsView struct {
	Consent     string     // "unset", "yes" or "no"
	ForcedOff   bool       // HATAMOTO_TELEMETRY=off: the owner cannot change it
	PreviewJSON string     // the exact request body
	LastSent    *time.Time // time of the last successful report
}

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

type TemplateStore interface {
	List(ctx context.Context, f *sectiontemplate.ListFilter, limit, offset int) (*sectiontemplate.ListResult, error)
	Get(ctx context.Context, id uuid.UUID) (*sectiontemplate.SectionTemplate, error)
	Create(ctx context.Context, userID *uuid.UUID, in *sectiontemplate.CreateInput) (*sectiontemplate.SectionTemplate, error)
	RecordUsage(ctx context.Context, id uuid.UUID) error
}

type TermStore interface {
	ListTerms(ctx context.Context, kind, search string, page, perPage int) (*taxonomy.TermListResult, error)
	GetTerm(ctx context.Context, id uuid.UUID) (*taxonomy.Term, error)
	CreateTerm(ctx context.Context, in taxonomy.CreateTermInput) (*taxonomy.Term, error)
	UpdateTerm(ctx context.Context, in taxonomy.UpdateTermInput) (*taxonomy.Term, error)
	DeleteTerm(ctx context.Context, id uuid.UUID) error
	MergeTerms(ctx context.Context, from, into uuid.UUID) error
	ListTermsForEntity(ctx context.Context, entityID uuid.UUID) ([]*taxonomy.Term, error)
	ReplaceEntityTerms(ctx context.Context, entityID uuid.UUID, termIDs []uuid.UUID) error
}

type ThemeInfo struct {
	Name, Version, Description string
	Builtin, Active            bool
	Signed                     bool
	Signer, Source             string
	HasSettings                bool
	Update                     string
	// Blocked says why policy keeps an installed theme from running ("" when it is not).
	Blocked string
}

type ThemeSection struct {
	Type, Title, Description string
	Schema                   json.RawMessage
}

type TokenService interface {
	IssueReset(ctx context.Context, userID uuid.UUID) (string, error)
	ResetValid(ctx context.Context, token string) bool
	ConsumeReset(ctx context.Context, token, newPassword string) (*user.User, error)
	PeekInvite(ctx context.Context, token string) (*auth.Invite, error)
	ConsumeInvite(ctx context.Context, token, name, password string) (*user.User, error)
	IssueInvite(ctx context.Context, email string, role user.Role, invitedBy uuid.UUID) (string, *auth.Invite, error)
	ListInvites(ctx context.Context) ([]auth.Invite, error)
	RevokeInvite(ctx context.Context, id uuid.UUID) error
}

type URLExplainer interface {
	ExplainURL(ctx context.Context, path string) (URLExplanation, error)
}

type URLExplanation struct {
	Redirects *redirect.Answer
	// Page is what serves the path when no redirect fires; Kind is "" when
	// nothing does (a 404).
	Page PageAnswer
}

type UpdateBanner struct {
	Kind    string // rolled_back | blocked | backup_failed
	Message string
	Href    string
	Label   string
}

type UpdateChip struct {
	ID      string // the popover's element id
	Version string // "v1.4.2", or "dev build"
	Title   string // "Up to date", "v1.4.3 is ready", "v1.4.3 rolled back"
	Channel string // "Stable channel", "" on a dev build
	Note    string // one sentence under the title (a major release, updates off for 90+ days)
	Name    string // the trigger's accessible name
	Blocks  []UpdateChipBlock
	Rows    []UpdateChipRow
	Href    string
	Label   string
}

type UpdateChipBlock struct {
	Kind string // success | danger | info | neutral
}

type UpdateChipRow struct {
	Text  string // "Updated to v1.4.2"
	When  string
	Badge string // badge kind
}

type UpdatesBannerInput struct {
	Status  UpdatesStatus
	Mode    string
	Running string
	Dev     bool
}

type UpdatesForm struct {
	Mode, Channel          string
	WindowStart, WindowEnd *int
	DeferDays              int
}

type UpdatesGlance struct {
	Running  string
	Dev      bool
	Mode     string
	Channel  string
	Status   UpdatesStatus
	Applying bool // an Update now run is in flight; read live, never cached
	OffSince *time.Time
	History  []UpdatesHistoryRow // newest first, at most 20
}

type UpdatesHistoryRow struct {
	When     time.Time
	From, To string
	Phase    string
	Error    string
}

type UpdatesLocks struct {
	Mode, Channel       bool
	ModeVar, ChannelVar string
}

type UpdatesResult struct {
	Status  UpdatesStatus
	Target  string // Apply: the version being installed
	Started bool   // Apply: a background run was started
	Busy    bool   // another check or update is already running
}

type UpdatesService interface {
	// View is everything the page shows: running version, effective policy,
	// env locks, stored status and history.
	View(ctx context.Context) (UpdatesState, error)
	// Save stores the policy. It returns field errors (keyed by the form
	// element id: mode, channel, window-start, defer) when the updater rejects
	// a value, and ignores locked fields.
	Save(ctx context.Context, in UpdatesForm) (map[string]string, error)
	// Check fetches and decides without downloading anything.
	Check(ctx context.Context) (UpdatesResult, error)
	// Apply starts an update in the background to the target the service
	// derives from its own stored status (ErrNoUpdate when there is none).
	// The caller never names a version.
	Apply(ctx context.Context) (UpdatesResult, error)
	// ApplyWithoutBackup is Apply for an update the pre-update backup
	// stopped: the same run, with the backup skipped for this version only.
	ApplyWithoutBackup(ctx context.Context) (UpdatesResult, error)
	// Unpin clears the stored pin.
	Unpin(ctx context.Context) error
	// Banner is the owner banner, nil when nothing needs attention.
	Banner(ctx context.Context) (*UpdateBanner, error)
	// Glance is the short, cached read behind the top-bar chip and the
	// Overview: it never writes and never costs more than one read per cache
	// window, so every owner page may ask for it.
	Glance(ctx context.Context) (UpdatesGlance, error)
}

type UpdatesState struct {
	Running     string
	Dev         bool // not a release build: updates are disabled
	Mode        string
	Channel     string
	Channels    []string
	WindowStart *int
	WindowEnd   *int
	DeferDays   int
	Pin         string
	Locks       UpdatesLocks
	Status      UpdatesStatus
	Applying    bool // an update started from here is still running
	OffSince    *time.Time
	History     []UpdatesHistoryRow
}

type UpdatesStatus struct {
	LastCheckAt    *time.Time
	LastResult     string // ok | error | skipped | ""
	Decision       string // one of the updater's decisions, "" before the first check
	Reason         string
	Target         string
	AvailableMajor string
}

type UserFinder interface {
	GetByEmail(ctx context.Context, email string) (*user.User, error)
	Count(ctx context.Context) (int, error)
}

type UserManager interface {
	GetByID(ctx context.Context, id uuid.UUID) (*user.User, error)
	List(ctx context.Context, limit, offset int) ([]*user.User, error)
	Create(ctx context.Context, in *user.CreateUserInput, passwordHash string) (*user.User, error)
	Update(ctx context.Context, id uuid.UUID, in *user.UpdateUserInput) (*user.User, error)
	Delete(ctx context.Context, id uuid.UUID) error
}

type UserReader interface {
	GetByID(ctx context.Context, id uuid.UUID) (*user.User, error)
}

type View struct {
	Title    string
	Crumbs   []Crumb
	SiteName string
	// SiteURL is the public site the sidebar's "Open site" button opens.
	SiteURL string
	Lang    string
	Theme   string
	Path    string

	Nonce   string
	CSRF    string
	Assets  *Assets
	Scripts []string // extra vendored scripts, e.g. "sortablejs"
	// AreaCarry is the query the secondary sidebar's links and phone select
	// keep (the analytics range and compare switch); empty elsewhere.
	AreaCarry url.Values
	// Modules are the page's entry modules beyond "@hm/admin", declared by the
	// page template's "modules" block; Render fills them in. The head preloads
	// their static import closure.
	Modules []string
	Flash   *Flash
	User    *CurrentUser
	Nav     []NavEntry // flat; breadcrumbs read it, the sidebar uses NavGroups
	// Section and Tab place the page in the Settings frame (IDs from
	// settingsRegistry); empty means the page is not a Settings page.
	Section, Tab string

	Wide bool // bare layout: wider panel
	// Width is the page column in the shell: "narrow" (one readable form
	// column), "compact" (the same column, kept at that width inside settings),
	// "wide" (tables, grids, charts; the default) or "full"
	// (editors). Render normalises anything else to "wide".
	Width string
	// Refresh, in seconds, reloads the page without JavaScript (a live status
	// page); htmx pages poll instead.
	Refresh int
	// NoSiteAddress asks the owner to set the site address (emails need it).
	NoSiteAddress bool
	// SetupPending reminds the owner that the wizard was not finished.
	SetupPending bool
	// SkipMarkupHooks keeps the markup scan from adding modules: a page whose
	// markup carries hooks it must not load code for (the builder shell, whose
	// no-JS outline sits in <noscript>) declares what it needs itself.
	SkipMarkupHooks bool
	// UpdateBanner is the owner's update notice (nil when nothing needs
	// attention); NewView fills it for owner GET requests off the Updates page.
	UpdateBanner *UpdateBanner
	// UpdateChip is the owner's top-bar update status (nil for editors and
	// sites without an update service); NewView fills it for GET requests.
	UpdateChip *UpdateChip
	// AddressBanner nags the owner about a weak admin address nobody accepted
	// (nil otherwise); NewView fills it for owner GET requests off the Security pages.
	AddressBanner *AddressBanner
	// StatsBanner asks the owner of an existing install about install stats
	// (nil otherwise); NewView fills it for owner GET requests off the Updates page.
	StatsBanner *StatsBanner
	// DemoBanner is the public demo notice ("" outside demo mode).
	DemoBanner string
	Data       any // page-specific data
	// contains filtered or unexported fields
}

type WebhookStore interface {
	List(ctx context.Context) ([]webhook.ListedSubscription, error)
	// Create stores the subscription and returns it with its new signing secret.
	Create(ctx context.Context, in webhook.Subscription) (webhook.Subscription, string, error)
	Get(ctx context.Context, id string) (*webhook.Subscription, error)
	Update(ctx context.Context, id string, p webhook.SubscriptionPatch) error
	SetActive(ctx context.Context, id string, active bool) error
	// RegenerateSecret replaces the signing secret and returns the new one.
	RegenerateSecret(ctx context.Context, id string) (string, error)
	Delete(ctx context.Context, id string) error
	// SendTest sends a test delivery now and returns its recorded outcome.
	SendTest(ctx context.Context, id string) (*webhook.DeliveryRow, error)
	// ListDeliveries is one page of the delivery log (subscriptionID "" = all)
	// and the total row count. Rows never carry the payload.
	ListDeliveries(ctx context.Context, subscriptionID string, limit, offset int) ([]webhook.DeliveryRow, int, error)
	// RetryDelivery re-queues a failed delivery; false means it had not failed.
	RetryDelivery(ctx context.Context, id string) (bool, error)
	// CountFailedSince is how many deliveries queued since the time have failed.
	CountFailedSince(ctx context.Context, since time.Time) (int, error)
}