config

type ApproveStage struct {
	Name string `json:"name"`
}

type BuildCtx struct {
	Refs    *Refs
	Symbols *SymbolTable
	Block   *hcl.Block // for diagnostic ranges when nothing more precise is available
}

type CompiledCredential struct {
	Disambiguators map[string]string
	Credential     *Entity
}

type CompiledEndpoint struct {
	Name        string
	Family      string // "http" | "sql" | "k8s"
	Plugin      *Plugin
	Body        any
	Hosts       []string
	Credentials []*Entity       // credentials globally bound to this endpoint
	Rules       []*CompiledRule // sorted by priority desc

	// Description is the operator-supplied free-text note from the
	// block's `description = "..."` framework attr, or "" if unset.
	// Surfaced in the discovery manifest to orient agents.
	Description string

	// Retention is the raw `retention = "..."` framework attr, or "" if
	// unset. When set it overrides gateway.actions_keep for this
	// endpoint's rows in the action-log sweeper. time.ParseDuration
	// format; "0" / "off" (or any zero-valued duration like "0s") keeps
	// this endpoint's rows forever. Validated at compile.
	Retention string

	// InspectsTruncatable is true when any rule on this endpoint reads a
	// facet whose bytes a wire frontend buffers under a cap (for ssh:
	// ssh.stdin; the http/sql bodies are buffered by their own frontends
	// on a coarser heuristic). The ssh runtime reads it to keep the
	// channel splice byte-for-byte unchanged when no rule needs stdin —
	// inspection is opt-in per endpoint, not paid by every connection.
	// Computed once at compile time from the per-matcher
	// InspectsTruncatableFacet() bool.
	InspectsTruncatable bool

	// Tunnel is the resolved tunnel this endpoint dials through, or
	// nil for endpoints reached over the gateway's plain dialer.
	// Populated from the endpoint plugin's optional EndpointTunnel()
	// accessor.
	Tunnel *CompiledTunnel
}

type CompiledPolicy struct {
	// Policy fallbacks (mirrored from the top-level Gateway fields).
	UnknownHost    string
	LLMFailMode    string
	LLMCacheTTL    int
	HumanTimeout   int
	HumanOnTimeout string

	// DashboardURL mirrors gateway.public_url — the canonical URL where
	// an operator reaches the dashboard to configure device profiles.
	// Surfaced here so the discovery manifest can point an agent (or its
	// human) at the dashboard when its profile grants nothing. Empty when
	// public_url is unset.
	DashboardURL string

	// Profiles indexed by name. Each holds a per-endpoint rule list,
	// already family-tagged and priority-sorted.
	Profiles map[string]*CompiledProfile

	// Endpoints contains every declared endpoint, keyed by name.
	// Useful for callers that don't care about profile scoping
	// (status pages, dashboard listings).
	Endpoints map[string]*CompiledEndpoint

	// Tunnels contains every declared tunnel, keyed by name. The
	// TunnelManager (host-side) walks this on policy reload to diff
	// old vs new tunnels. Endpoints store a *CompiledTunnel pointer
	// in their Tunnel field — same instance as the entry here.
	Tunnels map[string]*CompiledTunnel

	// Approvers / Credentials surface the same entities from the
	// Policy struct under a runtime-friendly typed alias — they're
	// pointers into the same Entity records, no copies.
	Approvers   map[string]*Entity
	Credentials map[string]*Entity
}

type CompiledProfile struct {
	Name                string
	Credentials         []*Entity
	Endpoints           map[string]*CompiledEndpoint
	HostIndex           map[string]*CompiledEndpoint
	HostPatterns        []HostPattern
	EndpointCredentials map[string][]*CompiledCredential
	HITLAsyncGrants     bool
}

type CompiledRule struct {
	Name       string
	Priority   int
	Disabled   bool
	Condition  string
	Credential string
	Matcher    match.Matcher
	Outcome    Outcome
}

type CompiledTunnel struct {
	Name   string
	Plugin *Plugin
	// Body is whatever the tunnel plugin's Build returned — runtime
	// callers type-assert it to TunnelRuntime (the runtime contract)
	// to call Open / Sharing.
	Body any

	// Sharing is the resolved sharing model after applying any
	// `share = ...` HCL override on top of the plugin's default.
	Sharing string

	// Keepalive is the idle window after refcount==0 before the
	// manager calls Close on the tunnel instance. Zero means tear
	// down immediately; KeepaliveAlways means never tear down on
	// idle (the manager pins refcount).
	Keepalive       time.Duration
	KeepaliveAlways bool

	// Via is the underlying tunnel this one chains through, or nil
	// for top-level tunnels. The manager Acquires the via tunnel
	// before opening this one and releases on teardown.
	Via *CompiledTunnel

	// Credential is the resolved credential entity this tunnel
	// drives its auth from, or nil if the HCL didn't declare one.
	// Plugins fetch the secret bytes via SecretStore.Get keyed on
	// Credential.Symbol.Name.
	Credential *Entity

	// Fingerprint is a stable hash of the compiled tunnel definition,
	// including its credential definition and via chain. Runtime
	// managers use it to distinguish same-name tunnels across policy
	// reloads without retaining or logging raw config/secret-bearing
	// fields.
	Fingerprint string `json:"-"`
}

type CredentialDisambiguatorBody interface {
	CredentialDisambiguators() map[string]string
}

type Defaults struct {
	// UnknownHost controls traffic whose destination does not match
	// any endpoint. "passthrough" relays it; "deny" closes it.
	UnknownHost string `hcl:"unknown_host,optional"`

	// LLMFailMode controls requests guarded by LLM approvers when
	// the model call errors or times out. "closed" denies; "open"
	// allows.
	LLMFailMode string `hcl:"llm_fail_mode,optional"`

	// LLMCacheTTL is the LLM decision cache lifetime in seconds.
	LLMCacheTTL int `hcl:"llm_cache_ttl,optional"`

	// HumanTimeout is the default human-approval timeout in seconds.
	HumanTimeout int `hcl:"human_timeout,optional"`

	// HumanOnTimeout is the default outcome when a human approver
	// does not answer before timeout. "deny" or "allow".
	HumanOnTimeout string `hcl:"human_on_timeout,optional"`
}

type Entity struct {
	Symbol *Symbol
	Plugin *Plugin
	Body   any
	Refs   *Refs
	// Framework holds the resolved values of framework-level attrs
	// (the FrameworkAttrSpec entries declared for this kind). The
	// loader extracts these from the block body via
	// body.PartialContent before invoking the plugin's gohcl
	// decode, so plugin authors get cross-cutting features
	// (`tunnel = X` on every endpoint) without per-plugin schema
	// boilerplate.
	Framework FrameworkAttrs
}

type EnvPushdownProvider interface {
	EnvVars() []EnvVar
}

type EnvVar struct {
	Name        string
	Value       string
	Description string // shown as a `# comment` line above the export
}

type FileIncludable interface {
	FileIncludeFields() []FileIncludeField
}

type FileIncludeField struct {
	Get func() string
	Set func(string)
}

type FrameworkAttrSpec struct {
	Name     string
	Kind     Kind // ref kind; "" for primitive string attrs
	Optional bool
	List     bool // when true (and Kind != ""), value is a list of bare names
}

type FrameworkAttrs struct {
	Refs     map[string]string
	RefLists map[string][]string
	Strings  map[string]string
}

type Gateway struct {
	// SchemaVersion is the config grammar this file targets. The
	// gateway accepts a range of versions and rejects anything newer
	// than it understands with an upgrade error. Omitting it loads as
	// legacy grammar (version 0) with a deprecation warning.
	SchemaVersion int `hcl:"schema_version,optional"`

	// Settings carries every operational scalar and the two transport
	// sub-blocks. Required: configs missing the block fail to load.
	Settings *GatewaySettings `hcl:"gateway,block"`

	// Defaults holds the optional `defaults { ... }` block with the
	// policy defaults (unknown_host, llm_*, human_*). nil when the
	// block is absent — every field has a built-in default.
	Defaults *Defaults `hcl:"defaults,block"`

	// Plugins lists every `plugin "<name>" { source = "..." }` block
	// at the top of the file. The loader spawns each subprocess
	// (and registers its declared types) before running pass-1
	// symbol building, so plugin-supplied (kind, type) pairs are
	// available by the time policy blocks are dispatched.
	Plugins []PluginSource `hcl:"plugin,block"`

	// Policy holds the v14-grammar block contents. Populated after
	// the operational decode by Load's pass-1 / pass-2 walk. Set to
	// a non-nil empty value if the file declared no policy blocks.
	Policy *Policy `hcl:"-"`

	// Remain is the part of the file gohcl didn't consume — i.e.
	// every policy block. Pass-2 reads from this. Not exposed in
	// the public API but kept on the struct so gohcl knows to
	// preserve it.
	Remain hcl.Body `hcl:",remain"`
}

type GatewaySettings struct {
	// DashboardListen is the bind address for the dashboard + JSON
	// API HTTP server. Default 127.0.0.1:8080. Set to a routable
	// address to expose the dashboard off-host (the same mux is also
	// served on the WG netstack / tsnet stack at this port).
	DashboardListen string `hcl:"dashboard_listen,optional"`

	// PublicURL is the canonical externally-reachable gateway URL.
	// Used in generated control-plane links such as join targets, OAuth
	// redirect URIs, and (when public_url has a host but wireguard.endpoint
	// doesn't) the host clients dial for WireGuard.
	PublicURL string `hcl:"public_url,optional"`

	// StateDir is the directory holding clawpatrol.db (and anything
	// a plugin persists to disk under it). Defaults to ${HOME}/.clawpatrol.
	StateDir string `hcl:"state_dir,optional"`

	// DashboardSessionTTL is how long a dashboard login session stays
	// valid after the operator types the password. time.ParseDuration
	// format ("24h", "30m"). Default 24h.
	DashboardSessionTTL string `hcl:"dashboard_session_ttl,optional"`

	// DashboardConfigWrites allows authenticated dashboard users to
	// append generated config snippets to the gateway HCL. Default
	// false: config remains read-only and changes happen out-of-band.
	DashboardConfigWrites bool `hcl:"dashboard_config_writes,optional"`

	// Resolver is the DNS resolver address the gateway uses for
	// upstream lookups when the runtime needs an explicit resolver.
	Resolver string `hcl:"resolver,optional"`

	// LogPath is an optional file path for gateway log output.
	LogPath string `hcl:"log_path,optional"`

	// Telemetry opts in/out of the update-checker / anonymous usage
	// ping (doc/telemetry.md). nil = default on; explicit `telemetry
	// = false` silences the goroutine. Env vars CLAWPATROL_TELEMETRY=0
	// and DO_NOT_TRACK=1 also work.
	Telemetry *bool `hcl:"telemetry,optional"`

	// SessionKeep is the hard retention floor for the sessions table.
	// Sessions whose last_at is older than this get deleted by the
	// background sweeper. Default 720h (30d), "0" / "off" disables.
	// time.ParseDuration format.
	SessionKeep string `hcl:"session_keep,optional"`

	// ActionsKeep is the global default retention floor for the actions
	// table (captured request/response logs — the gateway's largest
	// table). Rows whose ts_ns is older than this are deleted by the
	// background sweeper. Each endpoint may override this with its own
	// `retention = "..."`. Default 720h (30d), "0" / "off" disables the
	// default sweep (per-endpoint retention still applies).
	// time.ParseDuration format.
	ActionsKeep string `hcl:"actions_keep,optional"`

	// Limits, if present, overrides the two gateway-wide body-size
	// limits (rules-engine body buffer and persisted action body
	// storage). nil uses the DefaultBody*Limit constants, which match
	// today's hardcoded behavior.
	Limits *LimitsBlock `hcl:"limits,block"`

	// GenAITelemetry, if present, enables export of OpenTelemetry GenAI
	// semantic-convention spans (gen_ai.*) for intercepted LLM
	// requests. Requires the OTLP exporter to be configured
	// (OTEL_EXPORTER_OTLP_ENDPOINT); without it there is nothing to
	// export to. The block is opt-in: when absent, no gen_ai.* spans
	// are emitted and there is no added per-request overhead.
	GenAITelemetry *GenAITelemetryBlock `hcl:"genai_telemetry,block"`

	// WireGuard, if present, enables the embedded userspace WireGuard
	// server. Required block when running WG-mode deployments.
	WireGuard *WireGuardBlock `hcl:"wireguard,block"`

	// Tailscale, if present, enables the embedded tsnet node and the
	// Tailscale control plane (OAuth key minting, exit-node routing).
	// Both transports may be enabled simultaneously.
	Tailscale *TailscaleBlock `hcl:"tailscale,block"`
}

type GenAITelemetryBlock struct {
	// IncludeMessageContent additionally captures and exports the
	// prompt/completion message content via the GenAI content
	// convention (the gen_ai.input.messages, gen_ai.output.messages,
	// and gen_ai.system_instructions span attributes), and enriches
	// gen_ai.tool.definitions with each tool's description and JSON
	// schema. Default false: message content can be large and
	// sensitive, so it is only captured when an operator explicitly
	// opts in. Independent of the base span export — the gen_ai.*
	// attribute span emits regardless of this flag, including
	// gen_ai.tool.definitions with each tool's name and type.
	IncludeMessageContent bool `hcl:"include_message_content,optional"`
}

type HITLAsyncGrantConfig struct {
	// Enabled explicitly opts this approver into async retry-grant mode.
	// The active profile must also set hitl_async_grants = true.
	Enabled bool `hcl:"enabled,optional" json:"enabled,omitempty"`
	// Post-approval retry grant lifetime for the client to retry.
	ApprovedRetryTTL string `hcl:"approved_retry_ttl,optional" json:"approved_retry_ttl,omitempty"`
	// Request-body fingerprinting mode. V1 supports only "raw".
	FingerprintBody string `hcl:"fingerprint_body,optional" json:"fingerprint_body,omitempty"`
	// Maximum request body size eligible for async raw-body fingerprinting.
	MaxBodyBytes *int `hcl:"max_body_bytes,optional" json:"max_body_bytes,omitempty"`
}

type HITLAsyncGrantEnabler interface {
	HITLAsyncGrantEnabled() bool
}

type HostPattern struct {
	Pattern  string
	Endpoint *CompiledEndpoint
}

type JoinConfig struct {
	AuthKey           string
	ControlURL        string
	Hostname          string
	StateDir          string
	OAuthClientID     string
	OAuthClientSecret string
	TailscaleTags     []string
	WGEnabled         bool
	WGInterface       string
	WGEndpoint        string
	WGListenPort      int
	WGServerPub       string
	WGSubnetCIDR      string
	TailscaleEnabled  bool
	// PublicURL is the operator-facing gateway URL. The WG onboarder
	// uses its host as the default client dial target when
	// WGEndpoint's host portion is wildcard / unset.
	PublicURL string
}

type Kind string

type LimitsBlock struct {
	BodyBuffer  string `hcl:"body_buffer,optional"`
	BodyStorage string `hcl:"body_storage,optional"`
}

type NonInjectingCredential interface {
	IsPassthrough() bool
}

type OAuthConfig struct {
	ClientID     string
	ClientSecret string
	AuthURL      string
	TokenURL     string
	DeviceURL    string // used by Flow="device"
	RegisterURL  string // RFC 7591 dynamic client registration (used by Flow="notion_mcp")
	RedirectURI  string
	Scopes       []string
	RefreshToken string // bootstrap; per-owner tokens override
}

type OAuthFlowProvider interface {
	OAuthFlow() *OAuthIntegration
}

type OAuthIntegration struct {
	ID     string
	Type   string
	Header string
	Prefix string
	Flow   string // "auth_code" (default) | "device"
	OAuth  OAuthConfig
	// OptionalScopes is the catalog of opt-in scopes the dashboard
	// shows as a checklist before kicking off the OAuth flow. Plugins
	// that don't surface a picker leave this empty; the connect modal
	// then goes straight to the OAuth start without a picker step.
	OptionalScopes []OptionalScopeGroup
}

type OptionalScope struct {
	ID    string `json:"id"`
	Label string `json:"label"`
}

type OptionalScopeGroup struct {
	Title  string          `json:"title"`
	Scopes []OptionalScope `json:"scopes"`
}

type Outcome struct {
	Verdict string // "allow" | "deny"
	Reason  string
	Approve []ApproveStage
}

type Plugin struct {
	Kind Kind
	Type string

	// New returns a fresh pointer to the plugin's gohcl-tagged config
	// struct. The loader passes the result to gohcl.DecodeBody, unless
	// DecodeBody is set (see below).
	New func() any

	// DecodeBody, when set, replaces the loader's default
	// gohcl.DecodeBody call. External plugins (config/extplugin) use
	// this hook because their schema is only known at runtime — gohcl
	// requires a statically-tagged Go struct, but an external plugin
	// declares its attributes via a Manifest at startup. The hook
	// receives the body that remains after framework-attr extraction
	// and is responsible for populating target with the decoded
	// attributes (typically by stashing a cty.Value). Built-in
	// plugins leave this nil and rely on gohcl.
	DecodeBody func(body hcl.Body, ctx *hcl.EvalContext, target any) hcl.Diagnostics

	// Refs declares which fields on the decoded struct hold bare-name
	// references that must be resolved against the symbol table.
	Refs []RefSpec

	// Family classifies an endpoint's protocol so rule plugins can
	// constrain which endpoints they target. Set on KindEndpoint
	// plugins ("http" | "sql" | "k8s"). KindRule, with a single
	// unified plugin, leaves these empty — family is inferred from
	// the rule's resolved endpoints at validate/build time.
	Family   string
	Families []string

	// Validate runs after gohcl decode and after Refs are resolved.
	// It catches plugin-local invariants gohcl can't express
	// (e.g. exactly-one-of credential / credentials) and may use the
	// symbol table to resolve refs that the standard RefSpec path
	// syntax can't reach (e.g. fields inside a cty.Value attribute).
	Validate func(decoded any, name string, ctx *BuildCtx) hcl.Diagnostics

	// Build returns the canonical in-memory record stored in
	// Policy.Endpoints / .Credentials / etc. The runtime reads from
	// these, never from the raw decoded struct.
	Build func(decoded any, name string, ctx *BuildCtx) (any, hcl.Diagnostics)

	// CompileRule lowers a rule plugin's Build output into a
	// *CompiledRule + the list of endpoint names it attaches to.
	// Only set on rule plugins; nil for other kinds. Defined as a
	// callback so the lowering logic lives next to the rule plugin's
	// schema (rather than in a generic compile pass that needs an
	// interface escape hatch).
	CompileRule func(body any, name string) (*CompiledRule, []string, error)

	// Runtime is type-asserted by callers based on Kind:
	//   KindEndpoint   → runtime.EndpointRuntime
	//   KindCredential → runtime.CredentialRuntime
	//   KindApprover   → runtime.ApproverRuntime
	//   KindRule       → runtime.RuleMatcherFactory
	//   KindTunnel     → runtime.TunnelRuntime
	// nil means "schema-only; runtime not implemented" — request-time
	// dispatch reports a clear diagnostic when it tries to use one.
	Runtime any

	// Emit serializes a built entity back to HCL by populating an
	// hclwrite block body. Required for every plugin — the framework
	// has no generic reverse path that handles bare-name refs,
	// heterogeneous list shapes (credentials with optional
	// placeholders), or per-family match maps. Plugins that decode
	// nothing (zero-attribute credentials) provide a no-op Emit.
	Emit func(body any, name string, hb *hclwrite.Body)

	// Disambiguators names the HCL attrs this credential plugin
	// recognizes as dispatch discriminators when two credentials of
	// the same type bind the same endpoint within a profile. Only
	// meaningful for KindCredential plugins; left empty elsewhere.
	//
	// Each name corresponds to a string-valued attr the operator may
	// set on either the credential block itself or inline in a
	// profile's credentials list (`{ credential = X, <name> = "..." }`);
	// profile-inline values override block-side values for the same
	// `(credential, endpoint)` tuple.
	//
	// Conventional names per protocol family:
	//   - HTTP-auth (bearer_token, header_token, anthropic_*, …): "placeholder"
	//   - postgres_credential:   "user" (postgres routes by user)
	//   - clickhouse_credential: "database", "user" (either or both)
	//   - ssh_credential:        "user"
	//
	// The loader rejects any disambiguator attr (block-side or
	// profile-side) whose name is not in this list — that catches
	// e.g. `placeholder = "..."` set on a postgres credential.
	Disambiguators []string
}

type PluginLoader interface {
	// stateDir is the gateway's resolved state directory (where the
	// secret store lives); the loader refuses a plugin read_paths
	// grant that overlaps it.
	LoadPlugins(specs []PluginSource, stateDir string) hcl.Diagnostics
}

type PluginSource struct {
	Name   string `hcl:"name,label"`
	Source string `hcl:"source"`

	// Version is a semver constraint (hashicorp/go-version syntax,
	// e.g. "~> 1.2", ">= 1.0, < 2.0") applied to a GitHub source's
	// release tags; the newest satisfying tag is selected. Empty
	// selects the newest non-prerelease. It is an error to set Version
	// on a local-path source.
	Version string `hcl:"version,optional"`

	// Provenance controls how a GitHub release's build-provenance
	// attestation is treated. "warn" (the default) verifies an
	// attestation when present and falls back to checksum-only with a
	// warning when absent; "require" refuses a release that carries no
	// (or an invalid) attestation; "off" skips the attestation check
	// (checksum + lockfile pinning still apply). Only valid on a GitHub
	// source. A present-but-invalid attestation always fails closed.
	Provenance string `hcl:"provenance,optional"`

	// Network grants the plugin direct network access. "none" (the
	// default) confines the plugin to its gateway socket — endpoint,
	// credential, and tunnel plugins all reach the network through the
	// gateway's brokered dial (endpoints via the upstream dial, tunnels
	// via the transport dial), so they need no more. "outbound" lets the
	// plugin dial out itself; it's only for the few plugins that can't use
	// the broker — e.g. one that execs helper tools (ssh, kubectl) which
	// open their own connections, or a credential plugin doing its own
	// token exchange.
	Network string `hcl:"network,optional"`

	// Sandbox controls subprocess isolation. "enforce" (the default)
	// runs the plugin inside an OS sandbox — Linux namespaces (or
	// Landlock where user namespaces are unavailable), macOS
	// seatbelt — and fails config load when no sandbox can be
	// established on this host. "off" runs the plugin with the
	// gateway user's full privileges; the gateway's environment is
	// scrubbed either way.
	Sandbox string `hcl:"sandbox,optional"`

	// ReadPaths grants the plugin recursive read-only access to
	// extra host paths (e.g. "~/.ssh" for an SSH tunnel plugin).
	// Paths must be absolute; a leading "~/" expands to the gateway
	// user's home directory. The gateway refuses a path that overlaps
	// the state dir (the secret store). There is deliberately no
	// host-write grant: writing an active location (~/.bashrc, cron,
	// a $PATH dir, ...) is a code-execution-as-the-gateway-user
	// primitive, and no denylist of such locations can be complete.
	// A plugin that genuinely needs host writes runs with
	// sandbox = "off" (the single, explicit full-trust knob);
	// durable plugin storage goes through the gateway's blob store.
	ReadPaths []string `hcl:"read_paths,optional"`
}

type Policy struct {
	Approvers   map[string]*Entity
	Credentials map[string]*Entity
	Endpoints   map[string]*Entity
	Rules       map[string]*Entity
	Tunnels     map[string]*Entity

	Profiles map[string]*Profile

	// Order preserves declaration order across all kinds combined.
	// Useful for dashboard rendering and emit round-tripping.
	Order []string
}

type Profile struct {
	Name            string                       `json:"name"`
	Credentials     []string                     `json:"credentials"`
	Disambiguators  map[string]map[string]string `json:"disambiguators,omitempty"`
	HITLAsyncGrants bool                         `json:"hitl_async_grants,omitempty"`
}

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

type RefSpec struct {
	// Path traverses the decoded struct. Slice elements use [*];
	// nested struct fields use dot. Examples:
	//   "Endpoint"
	//   "Endpoints[*]"
	//   "Credentials[*].Credential"
	Path string

	// Kind the resolved name must belong to.
	Kind Kind

	// FamilyConstraint, when non-empty, requires the resolved entity's
	// Family to be in this set. Used by rule plugins to require
	// endpoints of a matching protocol family. Empty = any family.
	FamilyConstraint []string

	// Optional means an empty/zero value at Path is fine. Required
	// references that resolve to "" emit a diagnostic.
	Optional bool
}

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

type SecretSlot struct {
	Name        string `json:"name"`        // "" for single-slot; field name for multi
	Label       string `json:"label"`       // human label rendered in the modal
	Multiline   bool   `json:"multiline"`   // true for PEM blobs (textarea, not password input)
	Description string `json:"description"` // optional one-liner under the input
}

type SecretSlotsProvider interface {
	SecretSlots() []SecretSlot
}

type Symbol struct {
	Name   string
	Kind   Kind
	Type   string // "" for one-label kinds
	Family string // for endpoints: "http"|"sql"|"k8s"; "" otherwise
	Block  *hcl.Block
}

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

type TailscaleBlock struct {
	// AuthKey is the Tailscale auth key for the embedded tsnet node.
	// Required when the `tailscale` block is present. Falls back to
	// $TS_AUTHKEY if empty.
	AuthKey string `hcl:"authkey,optional"`

	// Hostname is the device name requested for the tsnet node.
	// Default "clawpatrol-gateway".
	Hostname string `hcl:"hostname,optional"`

	// ControlURL is the Tailscale control-plane URL. Empty →
	// Tailscale's hosted control plane.
	ControlURL string `hcl:"control_url,optional"`

	// Tags is the Tailscale device-tag list applied to keys the
	// gateway mints for onboarded clients (`tag:client` etc.). The
	// autoApprovers exit-node ACL must reference these tags.
	Tags []string `hcl:"tags,optional"`

	// Operators allowlists tailnet logins permitted to use the
	// dashboard without typing the root password. Each entry is
	// either an exact login ("alice@example.com") or a domain
	// wildcard ("*@example.com"). Tagged devices (whose whois login
	// is the tag name, not a user email) never match a wildcard
	// entry — agents on the tailnet can never bypass the gate
	// through this path.
	//
	// Empty / unset → tailnet-allowlist auth is disabled. The stored
	// root password is then the only way in. Lives under `tailscale
	// {}` because matching requires the tsnet whois identity; there
	// is no whois without an active tsnet node.
	Operators []string `hcl:"operators,optional"`

	// Funnel enables Tailscale Funnel on :443 so the join bootstrap
	// and credential webhook paths are internet-reachable via the
	// tsnet cert domain. Requires HTTPS enabled for the tailnet; if
	// public_url is unset the gateway derives it from the tsnet
	// cert domain at startup.
	Funnel bool `hcl:"funnel,optional"`

	// OAuthClientID is the OAuth client id used to mint per-device
	// tailnet auth keys at approval time.
	OAuthClientID string `hcl:"oauth_client_id,optional"`

	// OAuthClientSecret is the OAuth client secret paired with
	// OAuthClientID.
	OAuthClientSecret string `hcl:"oauth_client_secret,optional"`
}

type TunnelCommon struct {
	Share      string
	Keepalive  string
	Via        string
	Credential string
}

type TunnelCommonRead interface {
	TunnelCommon() TunnelCommon
}

type WireGuardBlock struct {
	// SubnetCIDR is the private subnet assigned to onboarded clients.
	// Required (e.g. "10.55.0.0/24").
	SubnetCIDR string `hcl:"subnet_cidr,optional"`

	// ListenPort is the UDP port the gateway binds for WG peers.
	// Default 51820.
	ListenPort int `hcl:"listen_port,optional"`

	// HostLoopbackPort is the TCP port the gateway binds on
	// 127.0.0.1 for host-local clients (single-host deployments where
	// clawpatrol-run loops back to the gateway on the same box).
	// Default 8443. Make it operator-controlled so two gateways can
	// coexist on one host (dev/test, blue-green, multi-tenant)
	// without colliding on the loopback landing pad.
	HostLoopbackPort int `hcl:"host_loopback_port,optional"`

	// Endpoint is the host:port advertised in client wg.conf as
	// `Endpoint = ...`. Host defaults to public_url's host; port
	// defaults to listen_port. Set only for split-host deployments
	// (gateway sits behind a different hostname/IP for WG than for
	// the dashboard).
	Endpoint string `hcl:"endpoint,optional"`

	// Interface is the WireGuard interface name the gateway manages.
	// Mostly irrelevant in userspace mode; leave unset.
	Interface string `hcl:"interface,optional"`

	// ServerPub is the WireGuard server public key advertised to
	// clients. Normally derived from gateway state; only set when
	// bootstrapping from an external key.
	ServerPub string `hcl:"server_pub,optional"`
}