plugins

type FailedPlugin struct {
	Name   string `json:"name"`
	Path   string `json:"path"`
	Reason string `json:"reason"`
}

type FieldHandler struct {
	Id      string // qualified: plugin.<name>.<id>
	Label   string
	Handler string // function in the entry file
	// Permission is an optional additive gate on the options endpoint:
	// UseSpaces (space forms drive the fetches) always applies, and a
	// declared gate narrows who may invoke the handler further.
	Permission string `json:"permission,omitempty"` // qualified grant
}

type Handler struct {
	Handler    string `json:"handler"`              // function name or module.function
	Permission string `json:"permission,omitempty"` // qualified grant, as Page; empty: any logged-in user
}

type MCPTool struct {
	Name        string             `json:"name"`                 // MCP tool name; defaults to the handler name
	Description string             `json:"description"`          // shown to MCP clients
	Handler     string             `json:"handler"`              // function in the entry file
	Permission  string             `json:"permission,omitempty"` // qualified grant, as Handler
	Parameters  []MCPToolParameter `json:"parameters,omitempty"` // optional: the tool's input schema
}

type MCPToolParameter struct {
	Name        string `json:"name"`
	Type        string `json:"type"` // string, int, float, bool, list
	Description string `json:"description,omitempty"`
	Default     any    `json:"default,omitempty"`
	Required    bool   `json:"required,omitempty"`
}

type Menu struct {
	PluginName string `json:"plugin,omitempty"`
	Label      string `json:"label"`
	URL        string `json:"url"`
	Permission string `json:"permission,omitempty"`
	Icon       string `json:"icon,omitempty"`
	IconSVG    string `json:"-"`
}

type Page struct {
	PluginName string `json:"plugin,omitempty"`
	Path       string `json:"path"`                 // "/dashboard" — served at /plugins/<name>/dashboard
	Handler    string `json:"handler"`              // function in the entry file ("module.fn" allowed)
	Label      string `json:"label,omitempty"`      // page title
	MenuLabel  string `json:"menu_label,omitempty"` // set: the page also appears in the sidebar under this label
	Permission string `json:"permission,omitempty"` // qualified grant, as Menu
	Icon       string `json:"icon,omitempty"`
	IconSVG    string `json:"-"`
	// Default marks the page as the post-login landing page. At most one
	// takes effect (first plugin by name, then declaration order) — see
	// DefaultPageURL.
	Default bool `json:"default,omitempty"`
}

type Peer struct {
	Name    string `json:"name"`
	Version string `json:"version"`
	Healthy bool   `json:"healthy"`
	Error   string `json:"error,omitempty"`
}

type PermissionDecl struct {
	Id    string `json:"id"`    // fully qualified, e.g. plugin.metrics.read
	Label string `json:"label"` // derived display name, e.g. "read"
}

type Plugin struct {
	Name        string `json:"name"`
	Version     string `json:"version"`
	Description string `json:"description"`
	// APIVersion is the plugin system generation this plugin targets
	// ([tool.knot] api; absent = 1, the only generation today). Breaking
	// changes to the plugin contract — the [tool.knot] shape, the handler
	// request/response contract, the block document — happen only behind a
	// new generation, and a knot that doesn't know a generation rejects the
	// plugin loudly at load rather than mis-parsing it.
	APIVersion int    `json:"api,omitempty"`
	Dir        string `json:"-"`                    // the plugin folder
	EntryFile  string `json:"-"`                    // main.py
	LogoLight  string `json:"logo_light,omitempty"` // relative paths
	LogoDark   string `json:"logo_dark,omitempty"`
	// SiteLogo reports that the plugin's logo pair claims the main page
	// logo (login included) — a declared pair is the claim. At most one
	// plugin's claim takes effect — see SiteLogoURLs.
	SiteLogo      bool             `json:"site_logo,omitempty"`
	Permissions   []PermissionDecl `json:"permissions"`
	Menus         []Menu           `json:"menus"`
	Pages         []Page           `json:"pages"`
	Handlers      []Handler        `json:"handlers"`
	MCPTools      []MCPTool        `json:"mcp_tools"`
	FieldHandlers []FieldHandler   `json:"field_handlers"`
	Libs          []ScriptLib      `json:"libs,omitempty"`

	// ActionIcons maps declared icon asset paths to their sanitized inner
	// SVG markup ([tool.knot] icons). Menus and pages carry their icons
	// statically; row actions are data-driven, so their icons are declared
	// once here, sanitized at load like every other plugin asset, and
	// addressable by path from a handler's action JSON at runtime.
	ActionIcons map[string]string `json:"icons,omitempty"`

	// Assets holds the declared assets a peer served from its own fetcher
	// (an embedded-assets binary plugin), fetched once at load and served
	// from memory. Empty when every asset came from the plugin folder on
	// disk — those keep streaming from disk as before.
	Assets map[string][]byte `json:"-"`

	// RequiredConfig lists the config keys this plugin requires in the
	// server's [plugins.<name>] table, declared as [tool.knot] config — a
	// list of key names. Presence is validated at load: a missing key
	// fails the plugin with a reason on the admin page rather than a
	// handler failing at first use.
	RequiredConfig []string `json:"required_config,omitempty"`

	// Config is the plugin's [plugins.<name>] table from the server
	// configuration, attached at load and injected into every handler
	// request as request["config"] (an empty table when unconfigured).
	Config map[string]any `json:"-"`

	// Exports are the modules declared in [tool.knot] export: scriptling
	// modules materialized in user tool environments as
	// plugin.<name>.<stem> — client SDKs wrapping knot.plugin.call. The
	// first declared module is also aliased as plugin.<name> itself. Each
	// source is read and linted once at load.
	Exports []ScriptExport `json:"exports,omitempty"`

	// EntrySource is the entry file's source, read once at load so request
	// dispatch does not touch the filesystem. Empty for a peer plugin with
	// no main.py.
	EntrySource string `json:"-"`

	// ScriptNamespace is the plugin.<x> library name a pure-script plugin's
	// main.py is registered and addressed under: the folder name sanitized
	// to a scriptling identifier (ScriptNamespace). Empty for a peer plugin
	// with no main.py. This is the "<name>" a bare handler declaration
	// (handler = "status") resolves against.
	ScriptNamespace string `json:"-"`

	// Namespaces are the plugin.<x> library names this plugin's declared
	// handlers resolve under, in the order they must be imported to
	// materialize the plugin.<x> bindings for dispatch. A pure-script
	// plugin contributes its folder name (its main.py registers as
	// plugin.<folder>); a peer plugin contributes each peer's handshake
	// name (the peer registers plugin.<peer>). A plugin with both
	// contributes both.
	Namespaces []string `json:"-"`
	// contains filtered or unexported fields
}

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

type ScriptExport struct {
	Path   string `json:"path"`
	Source string `json:"-"`
}

type ScriptLib struct {
	Name    string `json:"name"`    // from the filename, e.g. libs/calc.py -> "calc"
	Version string `json:"version"` // [tool.knot.lib] version, default "1.0"
	Source  string `json:"-"`
}