Documentation
¶
Overview ¶
Package extension implements grut's plugin system. Extensions are small programs (Lua scripts, WASM modules, or MCP servers) installed from https:// git URLs or local directories. Each extension declares a manifest (extension.toml) that specifies its runtime, entry point, and required permissions. The Manager handles install, remove, enable/disable, and state persistence.
Index ¶
- Variables
- func CheckPermission(ext *ExtensionInfo, perm Permission) bool
- func ManifestHasPermission(m *Manifest, perm Permission) bool
- func Scaffold(dir, name, templateName string) error
- func ValidPermission(p string) bool
- type ExtensionInfo
- type Manager
- func (m *Manager) Disable(name string) error
- func (m *Manager) Enable(name string) error
- func (m *Manager) Get(name string) (*ExtensionInfo, error)
- func (m *Manager) Install(ctx context.Context, source string) error
- func (m *Manager) List() []ExtensionInfo
- func (m *Manager) LoadAll() error
- func (m *Manager) Remove(name string) error
- func (m *Manager) VerifyIntegrity(ctx context.Context, name string) error
- type Manifest
- type Permission
- type PermissionDeniedError
- type Template
Constants ¶
This section is empty.
Variables ¶
var DefaultAllowedHosts = []string{hostGitHub}
Functions ¶
func CheckPermission ¶
func CheckPermission(ext *ExtensionInfo, perm Permission) bool
CheckPermission reports whether ext has been granted perm.
NOTE(#174): This function correctly checks the manifest declaration, but no runtime call-site currently enforces permissions before executing extension operations. MCP subprocess extensions run with full OS-level user privileges regardless of their declared permissions. See SECURITY.md for roadmap.
func ManifestHasPermission ¶ added in v0.2.0
func ManifestHasPermission(m *Manifest, perm Permission) bool
ManifestHasPermission reports whether m declares perm in its permissions list. This is the manifest-level equivalent of CheckPermission and is used by runtimes that hold a *Manifest rather than a full *ExtensionInfo.
func ValidPermission ¶
ValidPermission reports whether p is a recognised permission name.
Types ¶
type ExtensionInfo ¶
type ExtensionInfo struct {
InstalledAt time.Time `toml:"installed_at"`
Manifest Manifest `toml:"manifest"`
Dir string `toml:"-"`
Enabled bool `toml:"enabled"`
SourceURL string `toml:"source_url,omitempty"`
CommitHash string `toml:"commit_hash,omitempty"`
}
ExtensionInfo holds runtime state for an installed extension.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager handles extension installation, removal, and state tracking.
func NewManager ¶
NewManager creates a Manager rooted at extDir, creating the directory if needed. It uses DefaultAllowedHosts for registry validation. Call LoadAll explicitly to scan for installed extensions.
func NewManagerWithHosts ¶ added in v0.2.0
NewManagerWithHosts creates a Manager with a custom registry allowlist. Pass nil or an empty slice to reject all remote installs.
func (*Manager) Get ¶
func (m *Manager) Get(name string) (*ExtensionInfo, error)
Get returns a single extension by name.
func (*Manager) Install ¶
Install adds an extension from a git URL (https:// only) or local path. Remote URLs are validated against the trusted registry allowlist. After a successful clone the commit hash is recorded for integrity verification. The manifest inside the source is validated before the installation is considered successful.
func (*Manager) List ¶
func (m *Manager) List() []ExtensionInfo
List returns all installed extensions. The returned slice is a snapshot; callers may iterate without holding a lock.
func (*Manager) LoadAll ¶
LoadAll scans extDir for subdirectories containing extension.toml, loads each manifest, and restores persisted enabled/disabled state.
func (*Manager) VerifyIntegrity ¶ added in v0.2.0
VerifyIntegrity checks that the current HEAD of an installed extension's git repo still matches the commit hash recorded at install time. Returns nil if the hashes match, an error describing the mismatch otherwise. Extensions installed from local paths (no recorded hash) always pass.
type Manifest ¶
type Manifest struct {
Name string `toml:"name"`
Version string `toml:"version"`
Description string `toml:"description"`
Author string `toml:"author"`
License string `toml:"license"`
Runtime string `toml:"runtime"`
EntryPoint string `toml:"entry_point"`
MinGrut string `toml:"min_grut"`
Permissions []string `toml:"permissions"`
}
Manifest describes an extension's metadata, loaded from extension.toml.
func LoadManifest ¶
LoadManifest reads extension.toml from dir and returns the parsed manifest.
func ParseManifest ¶
ParseManifest decodes TOML bytes into a Manifest and validates it.
type Permission ¶
type Permission string
Permission represents a capability an extension can request.
const ( PermFileRead Permission = "file_read" PermFileWrite Permission = "file_write" PermGitRead Permission = "git_read" PermGitWrite Permission = "git_write" PermNetwork Permission = "network" PermProcess Permission = "process" PermClipboard Permission = "clipboard" PermNotify Permission = "notify" )
Valid extension permissions.
func AllPermissions ¶
func AllPermissions() []Permission
AllPermissions returns every valid permission value.
type PermissionDeniedError ¶ added in v0.2.0
type PermissionDeniedError struct {
Extension string
Permission Permission
Operation string
}
PermissionDeniedError is returned when an extension attempts an operation that requires a permission it has not declared.
func (*PermissionDeniedError) Error ¶ added in v0.2.0
func (e *PermissionDeniedError) Error() string
type Template ¶
type Template struct {
Files map[string]string // relative path → content (may contain {{.Name}})
Name string
Description string
Runtime string
}
Template describes a scaffold template for creating new extensions.
func ListTemplates ¶
func ListTemplates() []Template
ListTemplates returns all available scaffold templates.
Source Files
Directories