cms

type AdminSection = admin.Section

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

type CaptchaConfig = captcha.Config

type Config struct {
	// DB is the database connection pool. Required. All CMS tables are
	// prefixed cms_, so the pool may point at a database shared with the
	// host application.
	//
	// Open it with a driver matching Dialect: "pgx" (from
	// github.com/jackc/pgx/v5/stdlib) for Postgres, "mysql" (from
	// github.com/go-sql-driver/mysql) for MySQL or MariaDB. A host that
	// already holds a *pgxpool.Pool can convert it with
	// stdlib.OpenDBFromPool.
	DB *sql.DB

	// Dialect selects the SQL the CMS generates: "postgres" (the default),
	// or "mysql" for both MySQL 8.0.31+ and MariaDB 10.6+. It must match the
	// driver DB was opened with — database/sql does not expose that, so it
	// cannot be detected.
	//
	// MySQL DSNs must set parseTime=true so timestamps scan into time.Time;
	// the CMS sets the session time zone to UTC itself.
	Dialect string

	// Locales lists the content locales the site supports, e.g.
	// []string{"en", "fr"}. The first entry is the default. Defaults to
	// []string{"en"}.
	Locales []string

	// AdminPath is the URL prefix the host application mounts Admin()
	// under, used when the admin UI generates links. Defaults to "/admin".
	AdminPath string

	// SiteURL is the site's canonical public base URL, e.g.
	// "https://example.com" — scheme and host, no trailing slash and no
	// path. It is what the CMS uses wherever a link has to work outside
	// this request: the media library's "Copy link" buttons, RSS feed
	// links, hreflang alternates, and password-reset emails.
	//
	// Optional for the first three, which are looked at by the person
	// who asked for them: when empty, each request's own scheme and Host
	// header are used instead, which is right for development and for a
	// site served under one name.
	//
	// Required in production for the fourth. A reset link is read by
	// somebody other than whoever asked for it, so a base taken from the
	// request would let an attacker post the forgot-password form with a
	// Host header of their choosing and have the CMS mail a victim a
	// working reset link pointing at the attacker. Rather than do that,
	// a site with no SiteURL sends no reset email at all and logs why —
	// except when it is being reached over loopback, which is a
	// developer on their own machine. Everything else is unaffected.
	//
	// Set it, too, when the request's host would simply be wrong —
	// behind a proxy that rewrites Host, or when the admin is reached by
	// a different name than the public site.
	//
	// A value with no scheme is assumed to be https.
	SiteURL string

	// LockOverride forces the site lock on or off from configuration,
	// ignoring the stored setting — the escape hatch for a site locked
	// by mistake, or one that has to come up closed. nil, the default,
	// leaves the switch where the admin left it.
	//
	// Set it from the environment with CMS_SITE_LOCKED; see
	// ConfigFromEnv. A false override is the one to reach for in an
	// emergency: it opens the site without a working admin to click
	// through, and clears itself the moment the variable comes back out.
	// Note that the override does not change what is stored, so a site
	// unlocked this way closes again when the variable is removed.
	LockOverride *bool

	// LockedHandler answers requests refused by Lockdown — the page a
	// visitor sees while the site is closed. nil, the default, serves a
	// plain built-in notice.
	//
	// Whatever it writes, Lockdown has already set the status to 503 and
	// the headers that go with it; a handler that writes its own status
	// overrides that, which is almost always a mistake — a closed site
	// answering 200 is a closed site being indexed.
	LockedHandler http.Handler

	// SessionLifetime is how long a login session lasts. Defaults to 24h.
	SessionLifetime time.Duration

	// RememberFor is how long a session lasts when the user ticks
	// "Remember me" at login: the cookie survives browser restarts and
	// the session deadline is extended to this duration. Without the
	// tick, the cookie dies when the browser closes (SessionLifetime
	// still bounds it server-side). Defaults to 30 days.
	RememberFor time.Duration

	// SecureCookies marks the session cookie Secure, so a browser only
	// ever sends it over HTTPS. Setting it forces the flag on.
	//
	// Leaving it alone does not mean "off": a site whose SiteURL is an
	// https:// address is served over HTTPS by the host's own account, so
	// its session cookie is marked Secure whatever this says. That
	// derivation exists because this is the setting whose absence is
	// silent — nothing looks wrong, the site works, and the admin session
	// cookie is one plaintext request away from being readable. A site
	// that has told the CMS it lives at an https:// address should not
	// also have to remember this.
	//
	// So set it only for the case the derivation cannot see: HTTPS in
	// front of an install that leaves SiteURL empty. There is no way to
	// turn it off for an https:// SiteURL, and nothing legitimate wants
	// to — Secure describes the browser's connection to the edge, not the
	// edge's connection to this process, so terminating TLS at a proxy is
	// not a reason to drop it.
	SecureCookies bool

	// ClientIPHeader names the header a trusted reverse proxy sets to the
	// address the request really came from — "X-Forwarded-For",
	// "CF-Connecting-IP", "True-Client-IP". Empty, the default, takes the
	// address off the connection, which is right when the app is reached
	// directly.
	//
	// The login throttle is what reads it, and it is wrong in both
	// directions if this does not match the deployment. Left unset behind
	// a proxy, every visitor arrives from the same address, so the
	// per-source counter stops separating anyone: a few deliberate
	// failures against a known address shut that account for everybody.
	// Set without a proxy that overwrites the header, the value is one
	// the client chooses, and an attacker varies it to draw a fresh
	// allowance for every request.
	//
	// So set it exactly when every request reaches the app through a
	// proxy you control, and that proxy replaces the header rather than
	// appending to whatever arrived. For X-Forwarded-For the rightmost
	// entry is used — the one the nearest proxy appended, and the only
	// one it vouches for.
	ClientIPHeader string

	// Redis moves session storage from the cms_sessions table to Redis.
	// When set, sessions live under cms_session: keys — the prefix keeps
	// them distinct in an instance shared with the host application — and
	// Redis's own key expiry replaces the hourly cleanup sweep. When nil,
	// the default, sessions stay in the database.
	//
	// Nothing else moves: users, content, and settings remain in DB, so
	// Redis here is purely a performance/locality choice for the
	// per-request session lookup. Set it from the environment with
	// CMS_SESSION_REDIS_ADDR; see ConfigFromEnv. Like DB, the connection
	// is not dialed or verified by New; a wrong address surfaces on the
	// first request that touches a session.
	Redis *RedisConfig

	// TemplateFS holds the host application's page templates (often an
	// embed.FS). If nil, the public Pages handler serves a placeholder.
	TemplateFS fs.FS

	// SharedTemplates are glob patterns within TemplateFS for layouts and
	// partials parsed into every page's template set, e.g.
	// []string{"templates/base.gohtml", "templates/partials/*.gohtml"}.
	SharedTemplates []string

	// PageTemplates lists the templates editors may choose for a page.
	// Each entry's File is parsed together with SharedTemplates into its
	// own set, so different pages may define the same block names.
	// An entry with Unlisted set is offered only to superadmins when
	// creating a page — for one-off templates that back a single page.
	PageTemplates []PageTemplate

	// PostsPerPage is how many posts a paginated listing shows on one
	// page — {{cmsFeed "blog"}} and the ?page= links it builds. Zero, the
	// default, uses render.DefaultPostsPerPage (10); negative values are
	// invalid. A listing template can override it per feed with
	// {{cmsFeed "blog" 6}}, and {{cmsPosts}} ignores it entirely, being
	// the unpaginated "newest N" func. Set it from the environment with
	// CMS_POSTS_PER_PAGE; see ConfigFromEnv.
	PostsPerPage int

	// AdminPerPage is how many rows a paginated admin list shows on one
	// page — Blog & News, and Pages. Zero, the default, uses
	// admin.DefaultPerPage (25); negative values are invalid. Set it from
	// the environment with CMS_ADMIN_PER_PAGE; see ConfigFromEnv.
	//
	// It is deliberately separate from PostsPerPage: that one sizes the
	// public listing, where the number is a design decision about the
	// site, and an editor's table wants far more rows than a blog page
	// does. Tuning one must not disturb the other.
	AdminPerPage int

	// AdminMaxRequestBytes caps the body of an unsafe admin request from a
	// signed-in user. Zero, the default, is sized from the media manager's
	// limits; negative values are invalid.
	//
	// Raise it when the admin accepts an upload larger than that — a
	// host section taking many files in one multipart post is the usual
	// reason, since the cap covers the whole body rather than any one
	// file. Requests carrying no session are held to a much smaller fixed
	// ceiling whatever this says, so raising it does not widen what a
	// signed-out caller can send.
	AdminMaxRequestBytes int64

	// PageVersionsKept bounds each page's history: publishing records what
	// went live, and the oldest editions beyond this many are dropped.
	// Zero, the default, keeps content.DefaultVersionsKept of them.
	//
	// A version holds a whole page's published content, so the number is a
	// question about the database rather than about the site — raise it
	// where storage is cheap and an editor may want to reach a long way
	// back, lower it on a site whose pages are large and republished
	// constantly.
	PageVersionsKept int

	// PostTemplate is the page template blog and news posts render with.
	// A post is an ordinary page underneath — its slug lives under blog/
	// or news/ and its body is edited in place like any page, sections
	// and snippets included — so this is parsed like a PageTemplate, but
	// offered only through the Blog & News admin, never in the page
	// template choosers. The template's dot gets a non-nil .Post
	// (render.PostInfo) carrying the post's date, author, and images,
	// and any template may list posts with {{cmsPosts "blog" 10}}. The
	// zero value disables blog & news.
	PostTemplate PageTemplate

	// SearchTemplate is the page template site search results render
	// with, and setting it is what turns site search on: the CMS then
	// answers at SearchPath, and the in-place editor offers the site
	// setting that puts a magnifying glass in {{cmsNav}}.
	//
	// Like PostTemplate it is parsed as a PageTemplate but kept out of
	// the page template choosers — it backs one address, not a page
	// anyone creates. It is handed a synthesized page rather than a
	// stored one, so it should call {{cmsSearch}} for the results,
	// {{cmsSearchForm}} for the box, and {{cmsPagination}} for the rest,
	// and should not declare editable regions: there is no page behind
	// it for an editor to save them to.
	//
	// The zero value disables site search. Content is indexed either way
	// — an index kept only while the feature is on would be wrong the
	// moment it was switched back on — so turning it on later costs
	// nothing but the template.
	SearchTemplate PageTemplate

	// SearchPath is where results are served, as a slug without slashes
	// around it. "" uses DefaultSearchPath ("search"). A page with this
	// slug wins: the CMS answers here only when no page does, so an
	// install that already has a hand-built search page keeps it.
	SearchPath string

	// SearchPerPage is how many results one page of a search shows.
	// Zero, the default, uses render.DefaultSearchPerPage (10).
	SearchPerPage int

	// S3 configures the object store for image uploads. If nil, the
	// media library is disabled.
	S3 *S3Config

	// ObjectStore overrides the S3 object store with a custom
	// implementation (e.g. local disk for development). When set, S3 is
	// ignored.
	ObjectStore media.ObjectStore

	// MediaWebPQuality is the lossy WebP quality, in (0, 1], for the web
	// and thumbnail variants of uploaded images. Zero — the default —
	// uses 0.3, tuned for fast page loads; the untouched original is
	// always stored alongside. Other values are invalid.
	MediaWebPQuality float64

	// MediaMaxVideoMB caps video uploads, in megabytes. Zero — the
	// default — allows 512 MB; negative values are invalid. Images and
	// documents have a fixed 25 MB cap. Videos are stored exactly as
	// uploaded (no transcoding), so the practical ceiling is what
	// visitors' connections can stream.
	MediaMaxVideoMB int

	// MediaAdopt controls whether Migrate rebuilds the media library from
	// the bucket. Every upload writes a manifest describing it, so a
	// bucket carries everything needed to recreate the cms_media rows —
	// filenames, alt text, folders, dimensions and all.
	//
	// The zero value, MediaAdoptWhenEmpty, adopts a bucket's media when
	// the database has none: point a fresh deployment at a bucket that
	// already holds content and the library comes back. That is the case
	// worth having for disaster recovery, and for a staging environment
	// pointed at a copy of production's bucket. Set MediaAdoptReconcile to
	// check on every startup instead, or MediaAdoptOff to never look.
	//
	// Adoption only ever inserts. It will not delete rows whose objects
	// have gone, because every way listing a bucket can fail looks exactly
	// like that.
	MediaAdopt MediaAdoptMode

	// TemplateFuncs are the host application's own template functions,
	// callable from page templates alongside the cms* funcs. Register as
	// many as the site needs; the usual reason is to reach data the CMS
	// does not own — a product catalogue, a vehicle table — from inside a
	// CMS-managed page:
	//
	//	TemplateFuncs: template.FuncMap{
	//	    "featuredVehicles": func(n int) []Vehicle { ... },
	//	    "vehicleCount":     func() int { ... },
	//	}
	//
	// and then, in a page template:
	//
	//	{{range featuredVehicles 3}}<h3>{{.Name}}</h3>{{end}}
	//
	// Templates parse against this map, so it must name every function
	// they call. Names inside the reserved cms* namespace are refused, so
	// a later CMS release can add funcs without breaking a host.
	//
	// The implementations here are used as-is unless RequestFuncs
	// replaces them per request — which is what a function that queries a
	// database usually wants, for the request's context. A function
	// registered only here is shared by every render and must be safe for
	// concurrent use.
	//
	// These functions run inside the page template with the host's full
	// trust: one returning template.HTML bypasses the editor's content
	// sanitizer entirely, so never interpolate untrusted input into it.
	TemplateFuncs template.FuncMap

	// RequestFuncs binds TemplateFuncs to a request. It is called once
	// per page render, and whatever it returns replaces the matching
	// entries in TemplateFuncs for that render alone; names it omits keep
	// their declared implementation. This is where a function gets the
	// request's context for a query it must not outlive, or the URL it
	// needs to read a query parameter:
	//
	//	RequestFuncs: func(r *http.Request) template.FuncMap {
	//	    return template.FuncMap{
	//	        "featuredVehicles": func(n int) []Vehicle {
	//	            return store.Featured(r.Context(), n)
	//	        },
	//	    }
	//	}
	//
	// Only names TemplateFuncs declared can be called — page templates
	// were parsed against that set — so this needs TemplateFuncs to be
	// set, and New refuses the combination that isn't.
	RequestFuncs func(*http.Request) template.FuncMap

	// EditorStyles populates the in-place editor's Styles menu — named,
	// on-brand text styles that apply CSS classes. Nil gets the
	// Tailwind-first defaults (render.DefaultEditorStyles); an empty
	// non-nil slice disables the menu. Classes used here must exist in
	// the site's CSS — with Tailwind, safelist them, since editor
	// content lives in the database where the source scanner can't see
	// it.
	EditorStyles []EditorStyle

	// Snippets are the host application's pre-written HTML blocks for
	// the editor's palette (per-customer components, versioned with the
	// code). Admins can add more in the admin UI; the palette shows
	// both. A snippet with Settings is a section preset — a one-click
	// starting point in the "Add a section" chooser (see
	// snippets.Snippet). An empty non-nil slice ships none. Snippet
	// classes need safelisting like editor styles do.
	//
	// Nil gets everything the module ships (snippets.All), and so does
	// building on top of snippets.All — which is the recommended way to
	// customize, because a release that adds blocks then delivers them
	// on the next rebuild. Nothing here is stored in the database, so
	// there is no seed to re-run and nothing an upgrade can overwrite:
	//
	//	cfg.Snippets = append(snippets.All(), mySnippets()...)
	//
	// Composing from the individual constructors (DefaultSnippets,
	// LibrarySnippets, DefaultSectionPresets, LibrarySectionPresets)
	// still works and is the way to take a deliberate subset — but such
	// a list is a snapshot, and blocks added to a constructor it does
	// not name will not appear.
	Snippets []Snippet

	// SectionStyles are the curated background, width, and rounded-corner
	// options for sections regions ({{cmsSections "name"}}). Nil gets the
	// Tailwind-first defaults (render.DefaultSectionStyles); a config with
	// a nil Corners list gets the default corner options (an empty non-nil
	// slice ships none and hides the setting). The classes need
	// safelisting like editor styles do.
	SectionStyles *SectionStyles

	// Tailwind, when set, makes the CMS rebuild a supplemental
	// stylesheet whenever stored content's class set changes, by running
	// the host's Tailwind CLI over a synthetic file of those classes.
	// Pages then link the result as /cms/content-<hash>.css via
	// {{cmsHead}}, so classes typed into content (e.g. by superadmins in
	// the HTML source view) get real CSS without a site redeploy. Nil
	// disables the feature; see TailwindConfig.
	Tailwind *TailwindConfig

	// Captcha, when set, protects the admin login form with a
	// proof-of-work CAPTCHA verified against a self-hosted Cap server
	// (docker image tiago2/cap). The challenge is solved invisibly in
	// the background by default; set CaptchaConfig.Visible for Cap's
	// checkbox widget. Nil disables the CAPTCHA; the built-in login
	// throttle and honeypot still apply.
	Captcha *CaptchaConfig

	// Mailer, when set, delivers the email the CMS itself originates —
	// today only the password reset the login page's "Forgot your
	// password?" flow sends. The CMS authors the message (subject and
	// both bodies); the host supplies only the transport, which is where
	// delivery policy — SMTP or an API, which From address, a
	// development mail sink — already lives.
	//
	// Nil turns the feature off entirely: the login page shows no
	// forgot-password link and the reset routes answer 404. That is the
	// honest failure mode — a reset form that could never send its link
	// would look broken rather than be off. A host that wants the flow
	// without real delivery (development, tests) can pass a Mailer that
	// logs.
	Mailer Mailer

	// AdminSections are deployment-specific admin pages: each is an
	// http.Handler mounted at {AdminPath}/x/{Path}, behind the admin's
	// login, session, and CSRF middleware, with an optional link in the
	// admin nav. The /x/ namespace guarantees no collision with built-in
	// admin routes, now or after upgrades.
	AdminSections []AdminSection

	// AdminStylesheets are extra stylesheet URLs the admin links on every
	// one of its pages, after its own. A host that registers
	// AdminSections needs this to style the chrome those sections appear
	// in — the count beside their nav link, say — which the admin's
	// strict Content-Security-Policy makes impossible to do inline, and
	// which a stylesheet linked from a section's own page cannot reach,
	// since it is not loaded on the other pages the nav appears on.
	//
	// Each entry is a URL the host serves. An admin section's own asset
	// route is the natural place:
	//
	//	AdminStylesheets: []string{"/admin/x/registrations/adminassets/nav.css"},
	//
	// They are linked last, so their rules win at equal specificity.
	// Nothing validates them beyond the layout escaping the attribute:
	// they are the host's own URLs, not user input.
	AdminStylesheets []string

	// Permissions declares deployment-specific permissions beyond the
	// built-ins (blogs, news, pages, users), for functionality the host
	// gates itself with auth.User.Can — e.g. in-place editing of its own
	// records. Each appears as a grant checkbox on the admin's user form.
	// An AdminSection with a Permission set is declared automatically
	// (labelled with its NavLabel); list it here only to override the
	// label. Grants live in the cms_user_permissions table; admin and
	// superadmin roles hold every permission implicitly.
	Permissions []PermissionDef

	// Logger receives operational log output. Defaults to slog.Default().
	Logger *slog.Logger
}

type DashboardCard = admin.DashboardCard

type EditorStyle = render.EditorStyle

type Mailer = admin.Mailer

type MediaAdoptMode = media.AdoptMode

type PageTemplate = render.PageTemplate

type PermissionDef = admin.PermissionDef

type RedisConfig struct {
	// Addr is the server address, host:port, e.g. "localhost:6379".
	Addr string

	// Password authenticates to the server. Leave empty when the server
	// has no AUTH configured.
	Password string

	// DB is the logical database number. The default, 0, is right unless
	// the instance is shared and sessions should live in their own
	// database.
	DB int
}

type S3Config = media.S3Config

type SectionOption = render.SectionOption

type SectionStyles = render.SectionStyles

type Snippet = snippets.Snippet

type TailwindConfig struct {
	// Command is the argv that runs the Tailwind CLI. Two placeholders
	// are replaced before running: {content} becomes the path of a
	// synthetic HTML file holding every class token found in stored
	// content, and {output} the path the command must write CSS to.
	// Both must appear somewhere in the argv. Example, using the
	// standalone binary with a v3 config:
	//
	//	Command: []string{"tailwindcss", "-i", "assets/input.css",
	//	    "-o", "{output}", "--content", "{content}"}
	//
	// Setups whose CLI can't point at an ad-hoc content file (e.g.
	// Tailwind v4 auto-detection) can target a wrapper script that
	// copies {content} where their build expects it.
	Command []string

	// Dir is the working directory for Command — typically where the
	// site's Tailwind config and input stylesheet live. Empty means the
	// process's working directory.
	Dir string

	// Sources fingerprints the files the Tailwind build reads on its own
	// account — page templates, the input stylesheet, a theme file —
	// rather than through {content}.
	//
	// It exists because those files are build inputs the CMS cannot
	// otherwise see. A rebuild is skipped when the class set is
	// unchanged, so without this a template edit that adds a class
	// produces no rebuild at all: the generated stylesheet keeps
	// whatever it had, and because it is linked *after* the site's own
	// stylesheet, the utilities it does carry outrank the ones it does
	// not. The symptom is a responsive class that silently stops
	// applying — a lg: rule losing to the sm: rule the stale artifact
	// still holds — which looks like a CSS bug and is really a cache
	// bug.
	//
	// Nil defaults to Config.TemplateFS, which is right whenever the
	// build scans the same templates the CMS renders — the usual
	// arrangement. Set it explicitly to cover more (an input.css that
	// changes, a theme file) or to opt out with an empty FS.
	//
	// Only the file contents matter, not their paths on disk, so an
	// embed.FS and an os.DirFS both work.
	Sources fs.FS

	// Timeout bounds one rebuild. Zero means 60 seconds.
	Timeout time.Duration
}