entity

package
v1.17.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 18, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package entity exposes shared entity types used in the public wick contract (tool/job registration). Most entity types stay in internal/entity — only the bits downstream authors touch live here.

Index

Constants

This section is empty.

Variables

View Source
var DefaultGroupsCollapsed func() bool

DefaultGroupsCollapsed reports the admin setting "config groups start collapsed" (config_groups_collapsed). nil means off. Set once at boot.

Functions

func MapToStruct added in v0.13.0

func MapToStruct(m map[string]string, dst any)

MapToStruct fills dst (pointer to struct) from m using each field's wick tag. key= picks the map key; default= is used when the map value is empty or absent. Fields without a wick tag or key are ignored.

func VisibleWhenMatches added in v0.33.0

func VisibleWhenMatches(predicate string, values map[string]string) bool

VisibleWhenMatches evaluates a "<field>:<a|b|c>" visible_when predicate against the current values map (keyed by config Key). An empty predicate (no visible_when tag) is always visible. The value half is pipe-separated and matched as an OR. Mirrors the manager templ applyVisibility and the FE isVisible helper so a required-but-hidden field is not counted missing.

Single level only — it does not walk a dependency chain. That is enough for the required-completeness check: a field required under condition X is only enforced while X holds; the UI handles the cascading hide.

Types

type Config

type Config struct {
	Owner         string `gorm:"primaryKey;type:varchar(64);default:''"`
	Key           string `gorm:"primaryKey;type:varchar(64)"`
	Value         string `gorm:"type:text"`
	Type          string `gorm:"type:varchar(16);default:'text'"`
	Options       string `gorm:"type:text"`
	IsSecret      bool   `gorm:"default:false"`
	CanRegenerate bool   `gorm:"default:false"`
	Locked        bool   `gorm:"default:false"`
	Required      bool   `gorm:"default:false"`
	Description   string `gorm:"type:text"`
	UpdatedAt     time.Time
	// Hidden is set from the `wick:"hidden"` tag at seed time. Not persisted
	// (gorm:"-") — tells the manager Settings page to skip this row. Hidden
	// configs are still seeded to DB so runtime reads work normally.
	//
	// JSON-exposed (omitempty) so the SPA inspector / workflow editor
	// receives the same presentation hint the templ admin page already
	// uses. Pure UI flag — no secret material here.
	Hidden bool `gorm:"-" json:"hidden,omitempty"`
	// Internal is set from the `wick:"internal"` tag. Not persisted. The row
	// is a value wick writes for itself (e.g. a token expiry) — every config
	// renderer skips it, including dedicated pages that do show Hidden rows,
	// so it never gets a widget or a "required" badge. Code still loads and
	// saves it like any other row.
	Internal bool `gorm:"-" json:"internal,omitempty"`
	// ColOptions holds per-column select options for kvlist rows. Not persisted.
	// Key = column name; Value = pipe-separated "label::value" pairs (or just
	// "value" when label == value). The kvlist component renders a <select>
	// instead of <input> for columns that have options set.
	ColOptions map[string]string `gorm:"-" json:"col_options,omitempty"`
	// VisibleWhen is a "<otherField>:<value>" predicate sourced from the
	// `wick:"visible_when=..."` tag. When set, the admin UI shows this row
	// only while the named field's current value equals <value>. Not
	// persisted — pure presentation hint.
	VisibleWhen string `gorm:"-" json:"visible_when,omitempty"`
	// Group is an optional section heading for the admin Settings page,
	// sourced from the `wick:"group=..."` tag. Simple (non-kvlist,
	// non-picker) rows that share a Group render together under one card
	// titled with the Group name, in first-seen order; rows with no Group
	// fall into the default "Configuration" card. Pure presentation hint —
	// not persisted, JSON-exposed for the SPA inspector.
	Group string `gorm:"-" json:"group,omitempty"`
	// Mode locks the workflow editor's Fixed ⇄ Expression toggle for this
	// field, sourced from the `wick:"mode=fixed"` / `wick:"mode=expression"`
	// tag. Empty = operator chooses freely (toggle enabled, defaults to
	// fixed). "fixed" or "expression" = toggle greyed out, forced to that
	// mode. Pure presentation hint for the SPA workflow inspector — the
	// admin Settings page (templ) does not render a mode toggle. Not
	// persisted.
	Mode string `gorm:"-" json:"mode,omitempty"`
	// EnvOverride names the environment variable currently overriding
	// this row's value. Set by Service.ListOwned when the operator has
	// exported an env var declared in configs.envOverrides — the UI
	// renders a badge + disables the input, and Set() rejects writes
	// while the override is live. Empty when no override is active.
	EnvOverride string `gorm:"-" json:"env_override,omitempty"`
}

Config is one row in the runtime-editable KV config table (legacy name: `app_variables`). Wick reconciles two sources into this table at boot:

  • app-level defaults declared in internal/configs/spec.go (Owner == "", for session_secret / app_url / app_name)
  • per-module Config structs passed to app.RegisterTool. Framework reflects the typed struct + `wick:"..."` tags into rows via StructToConfigs, with Owner == Meta.Key stamped at boot.

The composite primary key (Owner, Key) lets the same Key repeat across scopes without collision (every tool can have its own "api_key", for example).

Type drives which widget the admin UI renders:

text (default), textarea, dropdown, number, checkbox,
email, url, color, date, datetime,
kvlist (editable table; Options = pipe-separated column names)

Options is pipe-separated (`a|b|c`). For "dropdown" it holds option values; for "kvlist" it holds column names (e.g. "id|name"). Value for kvlist rows is a JSON array of string-keyed objects.

func StructToConfigs

func StructToConfigs(cfg any) []Config

StructToConfigs reflects a typed per-module Config struct into a slice of Config rows ready for reconciliation. Each exported field with a non-empty `wick:"..."` tag becomes one row.

Field name → Key: CamelCase → snake_case (InitText → init_text), unless overridden by `key=...` in the tag.

Field type → widget:

bool   → "checkbox"
int*   → "number"
string → "text" (or whatever tag flag says: textarea, dropdown,
                 email, url, color, date, datetime)

Field value → seed Value. Zero values are written as empty string for string fields, "0" for int fields, "false" for bool fields — reconcile then either inserts the row or preserves the existing DB value.

Fields without a `wick` tag are ignored, so Config structs can hold internal state that should not become a row.

func (Config) EffectiveGroup added in v1.16.0

func (c Config) EffectiveGroup() string

EffectiveGroup is Group with that setting applied: a named group with no third segment ("Title" or "Title|Desc") becomes "Title|Desc|collapsed". A group that says so explicitly keeps its own choice — "Title|Desc|open" stays open, "…|collapsed" stays collapsed — and rows with no group (the default "Configuration" card) are never collapsed by the setting.

func (Config) MarshalJSON added in v1.16.0

func (c Config) MarshalJSON() ([]byte, error)

MarshalJSON sends the effective group, so the SPA config form follows the collapsed-by-default setting without knowing about it.

func (Config) TableName

func (Config) TableName() string

type DefaultTag added in v0.26.0

type DefaultTag struct {
	Name        string
	Description string
	IsGroup     bool
	IsFilter    bool
	IsSystem    bool
	SortOrder   int
}

DefaultTag is the spec used by a module's DefaultTags to seed tags on startup. It lives in pkg/entity (a leaf with no UI/templ deps) so that pkg/connector and pkg/job can reference it WITHOUT importing pkg/tool — pkg/tool pulls in the HTML render stack (templ), which has no business in a connector plugin binary. pkg/tool keeps a `DefaultTag = entity.DefaultTag` alias for backward compatibility.

IsSystem marks the tag as code-owned — see Tag godoc for the admin-UI implications (cannot be assigned to users from the picker).

type ToolVisibility

type ToolVisibility string

ToolVisibility controls who can access a tool.

const (
	VisibilityPublic  ToolVisibility = "public"  // no login needed
	VisibilityPrivate ToolVisibility = "private" // login + approved (optionally filtered by tags)
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL