config

type APIConfig struct {
	Enabled   bool             `yaml:"enabled"` // Enable REST API endpoints (default: false)
	CORS      *CORSConfig      `yaml:"cors,omitempty"`
	RateLimit *RateLimitConfig `yaml:"rate_limit,omitempty"`
	Auth      *AuthConfig      `yaml:"auth,omitempty"`
}

type APIKeyConfig struct {
	Name        string       `yaml:"name"`
	Key         string       `yaml:"key"`
	Permissions []Permission `yaml:"permissions,omitempty"`
}

type Action struct {
	// Describes is a human-readable note about what running this action does. Same
	// role as SourceConfig.Describes: it is what an operator reads when reviewing the
	// privileged operations a generated app performs. See Config.Generation.
	Describes string `yaml:"describes,omitempty"`

	Kind       string              `yaml:"kind"`                 // Action kind: "sql", "http", "exec"
	Source     string              `yaml:"source,omitempty"`     // For sql: source name to execute against
	Statement  string              `yaml:"statement,omitempty"`  // For sql: a single SQL statement with :param placeholders
	Statements []string            `yaml:"statements,omitempty"` // For sql: several statements run atomically in one transaction (mutually exclusive with statement)
	URL        string              `yaml:"url,omitempty"`        // For http: request URL (supports template expressions)
	Method     string              `yaml:"method,omitempty"`     // For http: HTTP method (default: POST)
	Body       string              `yaml:"body,omitempty"`       // For http: request body template
	Cmd        string              `yaml:"cmd,omitempty"`        // For exec: command to run
	Params     map[string]ParamDef `yaml:"params,omitempty"`     // Parameter definitions
	Confirm    string              `yaml:"confirm,omitempty"`    // Confirmation message (triggers dialog)
}

type AuthConfig struct {
	// APIKey is the legacy single API key for authentication (backward compatible).
	// Supports environment variable expansion (e.g., "${API_KEY}" or "$API_KEY").
	// Gets full permissions (read, write, delete) when used.
	APIKey string `yaml:"api_key,omitempty"`
	// HeaderName is the HTTP header name for the API key (default: "X-API-Key")
	// Also supports "Authorization: Bearer <token>" format when set to "Authorization"
	HeaderName string `yaml:"header_name,omitempty"`
	// Keys is a list of named API keys with specific permissions.
	Keys []APIKeyConfig `yaml:"keys,omitempty"`
}

type BlocksConfig struct {
	AutoID          bool   `yaml:"auto_id"`
	IDFormat        string `yaml:"id_format"`
	ShowLineNumbers bool   `yaml:"show_line_numbers"`
}

type CORSConfig struct {
	Origins []string `yaml:"origins,omitempty"` // Allowed origins (e.g., ["http://localhost:3000", "*"])
}

type CacheConfig struct {
	TTL      string `yaml:"ttl,omitempty"`       // Cache TTL (e.g., "5m", "1h"). Default: disabled (empty)
	Strategy string `yaml:"strategy,omitempty"`  // Cache strategy: "simple" or "stale-while-revalidate". Default: "simple"
	MaxRows  int    `yaml:"max_rows,omitempty"`  // Maximum rows to cache (truncates if exceeded). Default: unlimited
	MaxBytes int    `yaml:"max_bytes,omitempty"` // Maximum bytes to cache (truncates if exceeded). Default: unlimited
}

type Config struct {
	Title       string                   `yaml:"title"`
	Description string                   `yaml:"description"`
	Type        string                   `yaml:"type"` // "tutorial" or "site"
	Site        *SiteConfig              `yaml:"site,omitempty"`
	Navigation  []NavSection             `yaml:"navigation,omitempty"`
	Server      ServerConfig             `yaml:"server"`
	Styling     StylingConfig            `yaml:"styling"`
	Blocks      BlocksConfig             `yaml:"blocks"`
	Features    FeaturesConfig           `yaml:"features"`
	Ignore      []string                 `yaml:"ignore"`
	Sources     map[string]SourceConfig  `yaml:"sources,omitempty"`
	Actions     map[string]*Action       `yaml:"actions,omitempty"`
	API         *APIConfig               `yaml:"api,omitempty"`
	Webhooks    map[string]*Webhook      `yaml:"webhooks,omitempty"`
	Outputs     map[string]*OutputConfig `yaml:"outputs,omitempty"`
	Security    SecurityConfig           `yaml:"security,omitempty"`

	// Generation, when present, declares which of this project's sources and actions
	// an LLM is allowed to wire up when generating an app. Its presence is what makes
	// a tinkerdown.yaml a *manifest*; without it nothing here changes and the project
	// behaves exactly as before.
	Generation *GenerationConfig `yaml:"generation,omitempty"`

	// VersionPrefix, when non-empty, becomes a URL path segment that is
	// stripped from incoming requests before route resolution. Routes serve
	// equivalently with or without the prefix; the prefix exists so that a
	// future multi-version deployment can mount several site builds under
	// distinct prefixes (e.g. /v0/, /latest/) without collision.
	VersionPrefix string `yaml:"version_prefix,omitempty"`

	// Routes declares custom URL routes that bypass the markdown page
	// resolver. Each entry binds a request-path pattern to an upstream
	// destination. Currently only `type: proxy` is supported, which
	// reverse-proxies the request (including WebSocket upgrades) to the
	// configured upstream host. The full request path is forwarded
	// unchanged — the upstream is responsible for its own URL structure.
	Routes []RouteEntry `yaml:"routes,omitempty"`
}

type DocumentRefs struct {
	Sources         []string
	Actions         []string
	DeclaredSources []string
	DeclaredActions []string
}

type FeaturesConfig struct {
	HotReload bool `yaml:"hot_reload"`
	Sidebar   bool `yaml:"sidebar"`  // Show navigation sidebar (default: false)
	Headless  bool `yaml:"headless"` // Run without web UI, only API/webhooks/schedules

	// PrerenderDiagrams enables server-side mermaid pre-rendering via
	// Kroki. When true, “`mermaid blocks are converted to inline SVG at
	// parse time and the ~3.3MB client-side mermaid runtime is skipped on
	// pages where ALL blocks pre-rendered successfully. Blocks that fail
	// to render fall back to the client-side runtime. Default: false.
	PrerenderDiagrams bool `yaml:"prerender_diagrams,omitempty"`

	// KrokiURL overrides the Kroki base URL used for diagram pre-render
	// (default: https://kroki.io public instance). Point this at a
	// self-hosted Kroki container for production deployments where the
	// public instance's rate limits or terms are not acceptable.
	KrokiURL string `yaml:"kroki_url,omitempty"`
}

type GenerationConfig struct {
	// Sources names the sources a generated app may bind to. Each must exist in
	// Config.Sources; naming an undefined source is a config error, not a silent skip.
	Sources []string `yaml:"sources,omitempty"`

	// Actions names the actions a generated app may invoke. Each must exist in
	// Config.Actions.
	Actions []string `yaml:"actions,omitempty"`

	// StyleGuide optionally points at a markdown file describing house style — tone,
	// layout conventions, which components to prefer, what to avoid — injected into
	// the generation context so output conforms by construction. Optional: without it
	// generation falls back to the project theme and PicoCSS semantic defaults.
	StyleGuide string `yaml:"style_guide,omitempty"`
}

type NavPage struct {
	Title     string    `yaml:"title"`               // Page or group title (e.g., "Installation", "Forms & Editing")
	Path      string    `yaml:"path,omitempty"`      // Page path (e.g., "getting-started/installation.md"); empty for a pure group
	Collapsed bool      `yaml:"collapsed,omitempty"` // For groups: whether collapsed by default
	Pages     []NavPage `yaml:"pages,omitempty"`     // Sub-pages; presence makes this a group
}

type NavSection struct {
	Title     string    `yaml:"title"`           // Section title (e.g., "Getting Started")
	Path      string    `yaml:"path"`            // Section path (e.g., "getting-started")
	Collapsed bool      `yaml:"collapsed"`       // Whether section is collapsed by default
	Pages     []NavPage `yaml:"pages,omitempty"` // Pages in this section
}

type Operation struct {
	Kind      string `json:"kind"`                // "source" or "action"
	Name      string `json:"name"`                //
	Type      string `json:"type"`                // source type, or action kind
	Describes string `json:"describes,omitempty"` // the manifest's human-readable note
	Execs     bool   `json:"execs,omitempty"`     // runs a shell command
	Writes    bool   `json:"writes,omitempty"`    // mutates stored data
	Network   bool   `json:"network,omitempty"`   // talks to something off-host
}

type OperationSummary struct {
	Privileged bool        `json:"privileged"`
	Operations []Operation `json:"operations"`
}

type OutputConfig struct {
	// Type is the output type: "slack" or "email"
	Type string `yaml:"type"`

	// Channel is the Slack channel (for slack type), e.g., "#team-updates"
	// Environment variable expansion is supported (e.g., "${SLACK_CHANNEL}")
	Channel string `yaml:"channel,omitempty"`

	// To is the email recipient address (for email type)
	// Environment variable expansion is supported (e.g., "${ALERT_EMAIL}")
	To string `yaml:"to,omitempty"`

	// Subject is the email subject line (for email type)
	// Defaults to "Notification from Tinkerdown"
	Subject string `yaml:"subject,omitempty"`
}

type ParamDef struct {
	Type     string `yaml:"type,omitempty"`     // Parameter type: "string", "number", "date", "bool"
	Required bool   `yaml:"required,omitempty"` // Whether the parameter is required
	Default  string `yaml:"default,omitempty"`  // Default value
}

type Permission string

type PolicyViolation struct {
	Kind    string // "source" or "action"
	Name    string // the offending name
	Reason  string // what is wrong
	Hint    string // what to do instead
	Shadows bool   // the name is approved, and the document tried to redefine it
}

type RateLimitConfig struct {
	RequestsPerSecond float64 `yaml:"requests_per_second,omitempty"` // Rate limit in requests per second (default: 10)
	Burst             int     `yaml:"burst,omitempty"`               // Burst size (default: 20)
	MaxTrackedIPs     int     `yaml:"max_tracked_ips,omitempty"`     // Maximum unique IPs to track (default: 10000)
}

type RetryConfig struct {
	MaxRetries int    `yaml:"max_retries,omitempty"` // Maximum retry attempts (default: 3)
	BaseDelay  string `yaml:"base_delay,omitempty"`  // Initial delay (e.g., "100ms"). Default: 100ms
	MaxDelay   string `yaml:"max_delay,omitempty"`   // Maximum delay (e.g., "5s"). Default: 5s
}

type RouteEntry struct {
	Pattern  string `yaml:"pattern"`
	Type     string `yaml:"type"`
	Upstream string `yaml:"upstream"`
}

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

type SecurityConfig struct {
	// FrameSrc lists origins appended to the CSP frame-src directive,
	// in addition to the implicit 'self'. Set this when the site embeds
	// cross-origin iframes (e.g., a separately-deployed app loaded as a
	// live demo on a docs page). Validate() rejects entries that contain
	// CSP/header-injection characters or that don't parse as a URI. Use
	// scheme + host (e.g., "https://lt-landing-demo.fly.dev"). When the
	// list is empty no frame-src directive is emitted, falling back to
	// default-src 'self' which blocks cross-origin frames.
	FrameSrc []string `yaml:"frame_src,omitempty"`
}

type ServerConfig struct {
	Port  int    `yaml:"port"`
	Host  string `yaml:"host"`
	Debug bool   `yaml:"debug"`
}

type SiteConfig struct {
	Home       string `yaml:"home"`       // Homepage markdown file (e.g., "index.md")
	Logo       string `yaml:"logo"`       // Logo path (e.g., "/assets/logo.svg")
	Repository string `yaml:"repository"` // GitHub repository URL

	// URL is the canonical absolute base URL of the deployed site
	// (e.g., "https://livetemplate.fly.dev"), with NO trailing slash.
	// When set, sitemap.xml emits absolute URLs and OpenGraph meta tags
	// include og:url. When empty, sitemap entries use relative paths and
	// og:url is omitted.
	URL string `yaml:"url,omitempty"`
}

type SourceConfig struct {
	// Describes is a human-readable note about what this source touches — the
	// dataset, its scope, its sensitivity. It carries no runtime behavior; it exists
	// so an operator reviewing what a generated app does sees "the pending PII access
	// requests queue" rather than a table name. See Config.Generation.
	Describes string `yaml:"describes,omitempty"`

	Type        string                 `yaml:"type"`                   // "exec", "pg", "rest", "csv", "json", "markdown", "sqlite", "wasm", "graphql"
	Cmd         string                 `yaml:"cmd,omitempty"`          // For exec: command to run
	Query       string                 `yaml:"query,omitempty"`        // For pg: SQL query
	From        string                 `yaml:"from,omitempty"`         // For rest/graphql: API endpoint URL
	File        string                 `yaml:"file,omitempty"`         // For csv/json/markdown: file path
	Anchor      string                 `yaml:"anchor,omitempty"`       // For markdown: section anchor (e.g., "#todos")
	DB          string                 `yaml:"db,omitempty"`           // For sqlite: database file path (default: ./tinkerdown.db)
	Table       string                 `yaml:"table,omitempty"`        // For sqlite: table name
	Path        string                 `yaml:"path,omitempty"`         // For wasm: path to .wasm file
	QueryFile   string                 `yaml:"query_file,omitempty"`   // For graphql: path to .graphql file
	Variables   map[string]interface{} `yaml:"variables,omitempty"`    // For graphql: query variables
	Headers     map[string]string      `yaml:"headers,omitempty"`      // For rest/graphql: HTTP headers (env vars expanded)
	QueryParams map[string]string      `yaml:"query_params,omitempty"` // For rest: URL query parameters (env vars expanded)
	ResultPath  string                 `yaml:"result_path,omitempty"`  // For rest/graphql: dot-path to extract array (e.g., "data.items")
	Readonly    *bool                  `yaml:"readonly,omitempty"`     // For markdown/sqlite: read-only mode (default: true, set to false for writes)
	Options     map[string]string      `yaml:"options,omitempty"`      // Type-specific options (also used for wasm init config)
	Manual      bool                   `yaml:"manual,omitempty"`       // For exec: require Run button click
	Format      string                 `yaml:"format,omitempty"`       // For exec: output format (json, lines, csv). Default: json
	Delimiter   string                 `yaml:"delimiter,omitempty"`    // For exec CSV: field delimiter. Default: ","
	Env         map[string]string      `yaml:"env,omitempty"`          // For exec: environment variables (env vars expanded)
	Timeout     string                 `yaml:"timeout,omitempty"`      // Request timeout (e.g., "30s", "1m"). Default: 10s
	Retry       *RetryConfig           `yaml:"retry,omitempty"`        // Retry configuration
	Cache       *CacheConfig           `yaml:"cache,omitempty"`        // Cache configuration
	AutoBind    *bool                  `yaml:"auto_bind,omitempty"`    // Set to false to exclude from auto-table matching

	// For computed sources: derive data from another source
	GroupBy   string            `yaml:"group_by,omitempty"`  // Field to group by (e.g., "category")
	Aggregate map[string]string `yaml:"aggregate,omitempty"` // Field → aggregation expression (e.g., "total": "sum(amount)")
	Filter    string            `yaml:"filter,omitempty"`    // Optional filter expression (e.g., "status = active")
}

type StylingConfig struct {
	Theme        string `yaml:"theme"`
	PrimaryColor string `yaml:"primary_color"`
	Font         string `yaml:"font"`
	// CustomCSS is a site-relative path (e.g. "assets/landing.css") served
	// from <rootDir>/assets and injected as a <link> in the <head> of pages
	// using `layout: landing`. Lets a site carry bespoke styling for its
	// marketing/landing pages without touching the default docs shell.
	CustomCSS string `yaml:"custom_css,omitempty"`
	// SiteCSS is a site-relative path served from <rootDir>/assets and injected
	// as a <link> in the <head> of EVERY page (both the default docs shell and
	// `layout: landing`). Use it for shared brand primitives — self-hosted
	// @font-face declarations, base tokens — that should reach the calm docs
	// shell too, while CustomCSS stays quarantined to landing pages. On landing
	// pages SiteCSS loads before CustomCSS so the landing layer can override it.
	SiteCSS string `yaml:"site_css,omitempty"`
	// Tokens overrides individual design tokens — the on-brand palette — declaratively,
	// so a team sets its brand without writing raw CSS. Keys are the snake_case names
	// in KnownStyleTokens (e.g. "accent", "bg_primary", "card_bg"); each drives the
	// matching CSS custom property (--accent, --bg-primary, …) in the page's :root,
	// overriding the built-in default via the same mechanism primary_color uses for
	// --accent. Overriding a token skins the generated (semantic) HTML on-brand by
	// construction. An unknown key is a config error (ValidateStyleTokens). Absent,
	// the built-in defaults apply.
	Tokens map[string]string `yaml:"tokens,omitempty"`
}

type Webhook struct {
	// Action is the name of the action to execute when this webhook is triggered
	Action string `yaml:"action"`
	// Secret is the shared secret for validation (supports env var expansion)
	// Used for X-Webhook-Secret header or ?secret= query param validation
	Secret string `yaml:"secret,omitempty"`
	// SignatureSecret is the secret used for HMAC signature validation (supports env var expansion)
	// When set, validates X-Webhook-Signature header in format "sha256=<hex>"
	// This provides stronger security than plain secret validation
	SignatureSecret string `yaml:"signature_secret,omitempty"`
	// ValidateTimestamp enables replay attack prevention by validating X-Webhook-Timestamp
	// Requests older than TimestampTolerance seconds are rejected
	ValidateTimestamp bool `yaml:"validate_timestamp,omitempty"`
	// TimestampTolerance is the maximum age in seconds for timestamp validation (default: 300 = 5 minutes)
	TimestampTolerance int `yaml:"timestamp_tolerance,omitempty"`
}