plugins

package
v0.0.1 Latest Latest
Warning

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

 Go to latest Published: Feb 20, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package plugins provides the plugin manifest schema and verification system.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DiscoverPlugins 

func DiscoverPlugins() ([]SessionEnricher, []TabEnricher, []WindowEnricher, []ProcessEnricher, error)

DiscoverPlugins finds plugin executables with supported prefixes in PATH and categorizes them Search order (highest to lowest priority):

  1. Directories from PATH environment variable (highest priority)
  2. Directories from IT2_PLUGIN_PATHS (--plugin-path flag, middle priority)
  3. Embedded plugins directory (lowest priority, fallback)

func EnrichSessionsParallel 

func EnrichSessionsParallel(ctx context.Context, sessions []*client.SessionInfo, enrichers []SessionEnricher)

EnrichSessionsParallel runs plugins concurrently for each session and collects results. It limits concurrency to prevent overwhelming the system (max 20 concurrent executions).

func EnrichTabs 

func EnrichTabs(ctx context.Context, tabs []*formatting.TabInfo, enrichers []TabEnricher)

EnrichTabs applies tab enrichers to a list of tabs.

func EnrichWindows 

func EnrichWindows(ctx context.Context, windows []*client.WindowInfo, enrichers []WindowEnricher)

EnrichWindows applies window enrichers to a list of windows.

func MergeAllOverflowFiles 

func MergeAllOverflowFiles() (int, error)

MergeAllOverflowFiles merges overflow files for both global and all session files

func MergeOverflowFiles 

func MergeOverflowFiles(basePath string) (int, error)

MergeOverflowFiles merges overflow files back into the main file Returns number of files merged and any error

func MetricsLookupKey 

func MetricsLookupKey(name string, pluginType PluginType) string

MetricsLookupKey returns the key used to store metrics for a plugin.

func RecordPluginEvent 

func RecordPluginEvent(pluginName, pluginType, sessionID string, duration time.Duration, err error)

RecordPluginEvent appends an event to both global and session-specific files Uses file locking with short timeout (10ms), spills to .overflow/ on contention

func ShouldRunPlugins 

func ShouldRunPlugins(columns []string) bool

ShouldRunPlugins determines if plugins should be executed based on requested columns. Plugins only run when explicitly requested via non-standard columns. This avoids slow plugin discovery/execution on every session list command.

Types

type Binary 

type Binary struct {
	// SHA256 hash of the binary
	SHA256 string `json:"sha256" yaml:"sha256"`

	// Download URL for pre-built binary (optional)
	URL string `json:"url,omitempty" yaml:"url,omitempty"`

	// Code signature info (macOS)
	CodeSignature *CodeSignature `json:"code_signature,omitempty" yaml:"code_signature,omitempty"`
}

Binary describes the compiled binary and its verification info.

type BufferLinesInput 

type BufferLinesInput struct {
	// Number of lines needed (e.g., 1000)
	Lines int `json:"lines" yaml:"lines"`

	// Whether to include escape sequences
	IncludeEscapes bool `json:"include_escapes,omitempty" yaml:"include_escapes,omitempty"`
}

BufferLinesInput specifies requirements for scrollback buffer.

type BuildConfig 

type BuildConfig struct {
	// Go version (e.g., "1.21.5")
	GoVersion string `json:"go_version" yaml:"go_version"`

	// Build flags (e.g., ["-trimpath", "-ldflags=-s -w"])
	Flags []string `json:"flags" yaml:"flags"`

	// Environment variables (e.g., {"CGO_ENABLED": "0", "SOURCE_DATE_EPOCH": "1"})
	Env map[string]string `json:"env" yaml:"env"`

	// Main package path (e.g., "./cmd/plugin")
	MainPackage string `json:"main_package,omitempty" yaml:"main_package,omitempty"`
}

BuildConfig specifies exactly how to build the plugin reproducibly.

type CodeSignature 

type CodeSignature struct {
	// Developer ID (e.g., "Developer ID: Travis Cline (XXXXXXXXXX)")
	DeveloperID string `json:"developer_id" yaml:"developer_id"`

	// Team ID (e.g., "XXXXXXXXXX")
	TeamID string `json:"team_id,omitempty" yaml:"team_id,omitempty"`
}

CodeSignature describes expected code signature (macOS only).

type EventMonitor 

type EventMonitor interface {
	// Name returns the name of the monitor plugin
	Name() string

	// StartMonitoring starts monitoring for events on the given session
	// Returns a channel that will receive events and an error channel
	StartMonitoring(ctx context.Context, sessionID string) (<-chan PluginEvent, <-chan error, error)

	// StopMonitoring stops monitoring (context cancellation should also work)
	StopMonitoring() error
}

EventMonitor is an interface for plugins that can generate events during monitoring

type ExecPlugin 

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

ExecPlugin represents a plugin that runs an external executable

func NewExecPlugin 

func NewExecPlugin(executable string) *ExecPlugin

NewExecPlugin creates a new executable plugin

func (*ExecPlugin) EnrichProcess 

func (p *ExecPlugin) EnrichProcess(ctx context.Context, sessionID string, pid int) (map[string]interface{}, error)

EnrichProcess runs the executable with process information and parses the output

func (*ExecPlugin) EnrichSession 

func (p *ExecPlugin) EnrichSession(ctx context.Context, session *client.SessionInfo) (map[string]interface{}, error)

EnrichSession runs the executable with the session ID and parses the output

func (*ExecPlugin) EnrichTab 

func (p *ExecPlugin) EnrichTab(ctx context.Context, tab *formatting.TabInfo) (map[string]interface{}, error)

EnrichTab runs the executable with tab information and parses the output

func (*ExecPlugin) EnrichWindow 

func (p *ExecPlugin) EnrichWindow(ctx context.Context, window *client.WindowInfo) (map[string]interface{}, error)

EnrichWindow runs the executable with window information and parses the output

func (*ExecPlugin) Name 

func (p *ExecPlugin) Name() string

Name returns the name of the plugin

func (*ExecPlugin) StartMonitoring 

func (p *ExecPlugin) StartMonitoring(ctx context.Context, sessionID string) (<-chan PluginEvent, <-chan error, error)

StartMonitoring starts monitoring for events from the plugin

func (*ExecPlugin) StopMonitoring 

func (p *ExecPlugin) StopMonitoring() error

StopMonitoring stops monitoring (relies on context cancellation)

func (*ExecPlugin) Type 

func (p *ExecPlugin) Type() PluginType

Type reports the plugin type derived from its executable name.

type ExecPreConditionChecker 

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

ExecPreConditionChecker runs an external executable to check conditions

func NewExecPreConditionChecker 

func NewExecPreConditionChecker(executable string) *ExecPreConditionChecker

NewExecPreConditionChecker creates a new executable pre-condition checker

func (*ExecPreConditionChecker) Check 

func (c *ExecPreConditionChecker) Check(ctx context.Context, args []string) (PreConditionResult, error)

Check runs the executable and interprets the result

func (*ExecPreConditionChecker) Description 

func (c *ExecPreConditionChecker) Description() string

Description returns the description of the checker

func (*ExecPreConditionChecker) Name 

func (c *ExecPreConditionChecker) Name() string

Name returns the name of the checker

type FilesystemPermissions 

type FilesystemPermissions struct {
	// Read-only paths (e.g., ["/tmp"])
	ReadOnly []string `json:"read_only,omitempty" yaml:"read_only,omitempty"`

	// Read-write paths (e.g., ["~/.cache/plugin-name"])
	ReadWrite []string `json:"read_write,omitempty" yaml:"read_write,omitempty"`
}

FilesystemPermissions specifies allowed filesystem access.

type Inputs 

type Inputs struct {
	// Session ID (always provided)
	SessionID bool `json:"session_id" yaml:"session_id"`

	// Screen lines (visible terminal content)
	ScreenLines *ScreenLinesInput `json:"screen_lines,omitempty" yaml:"screen_lines,omitempty"`

	// Buffer lines (scrollback history)
	BufferLines *BufferLinesInput `json:"buffer_lines,omitempty" yaml:"buffer_lines,omitempty"`

	// Session metadata (title, working directory, etc.)
	SessionMetadata []string `json:"session_metadata,omitempty" yaml:"session_metadata,omitempty"`

	// Environment variables (specific vars only, not full env)
	EnvironmentVars []string `json:"environment_vars,omitempty" yaml:"environment_vars,omitempty"`
}

Inputs declares what data the plugin needs to function. This implements input minimization - plugins only get what they declare.

type Manifest 

type Manifest struct {
	// Plugin metadata
	Name        string `json:"name" yaml:"name"`
	Version     string `json:"version" yaml:"version"`
	Description string `json:"description" yaml:"description"`
	Author      string `json:"author" yaml:"author"`

	// Source information for reproducible builds
	Source Source `json:"source" yaml:"source"`

	// Binary verification
	Binary Binary `json:"binary" yaml:"binary"`

	// Input requirements (what data the plugin needs)
	Inputs Inputs `json:"inputs" yaml:"inputs"`

	// Permissions (what the plugin can do)
	Permissions Permissions `json:"permissions" yaml:"permissions"`

	// Sandbox configuration
	Sandbox SandboxConfig `json:"sandbox" yaml:"sandbox"`
}

Manifest describes a plugin's metadata, source, permissions, and verification info. This is the source of truth for what a plugin needs and how to verify it.

type MetricsStore 

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

MetricsStore manages plugin execution metrics

func GetMetricsStore 

func GetMetricsStore() *MetricsStore

GetMetricsStore returns the global metrics store singleton

func (*MetricsStore) GetAllMetrics 

func (s *MetricsStore) GetAllMetrics() map[string]*PluginMetrics

GetAllMetrics returns metrics for all plugins

func (*MetricsStore) RecordExecution 

func (s *MetricsStore) RecordExecution(pluginName, pluginType string, duration time.Duration)

RecordExecution records a plugin execution with its duration

func (*MetricsStore) Save 

func (s *MetricsStore) Save() error

Save persists metrics to disk

type Permissions 

type Permissions struct {
	// Filesystem access
	Filesystem *FilesystemPermissions `json:"filesystem,omitempty" yaml:"filesystem,omitempty"`

	// Network access (default: denied)
	Network bool `json:"network,omitempty" yaml:"network,omitempty"`

	// Execute other programs (default: denied)
	Execute []string `json:"execute,omitempty" yaml:"execute,omitempty"`
}

Permissions declares what the plugin is allowed to do. This is used to configure the sandbox.

type PluginEvent 

type PluginEvent struct {
	PluginName string                 `json:"plugin_name"`
	EventType  string                 `json:"event_type"`
	SessionID  string                 `json:"session_id"`
	Timestamp  time.Time              `json:"timestamp"`
	Data       map[string]interface{} `json:"data"`
	Message    string                 `json:"message,omitempty"`
}

PluginEvent represents an event from a plugin

type PluginExecutionEvent 

type PluginExecutionEvent struct {
	Timestamp  time.Time `json:"timestamp"`
	PluginName string    `json:"plugin_name"`
	PluginType string    `json:"plugin_type"`
	SessionID  string    `json:"session_id,omitempty"`
	DurationMs float64   `json:"duration_ms"`
	DurationUs int64     `json:"duration_us"`
	Success    bool      `json:"success"`
	Error      string    `json:"error,omitempty"`
}

PluginExecutionEvent represents a single plugin execution event for metrics.

type PluginInput 

type PluginInput struct {
	SessionID   string   `json:"session_id"`
	SessionName string   `json:"session_name,omitempty"`
	Cwd         string   `json:"cwd,omitempty"`
	BufferLines []string `json:"buffer_lines,omitempty"`
}

PluginInput represents the data passed to a plugin via stdin

type PluginMetadata 

type PluginMetadata struct {
	Name       string
	Type       PluginType
	Path       string
	Source     string // "PATH", "custom", or "embedded"
	SHA256     string
	Duplicates int // Count of other plugins with same name and type
}

PluginMetadata contains detailed information about a discovered plugin

func DiscoverPluginMetadata 

func DiscoverPluginMetadata() ([]PluginMetadata, error)

DiscoverPluginMetadata returns detailed metadata about all discovered plugins

type PluginMetrics 

type PluginMetrics struct {
	Name           string        `json:"name"`
	Type           string        `json:"type,omitempty"`
	ExecutionCount int           `json:"execution_count"`
	TotalDuration  time.Duration `json:"total_duration"`
	Durations      []int64       `json:"durations"` // Microseconds for compact storage
	LastExecuted   time.Time     `json:"last_executed"`
}

PluginMetrics tracks execution statistics for a single plugin

func (*PluginMetrics) CalculateStats 

func (m *PluginMetrics) CalculateStats() (avg, p50, p95, p99 time.Duration)

CalculateStats computes statistics from recorded durations

type PluginType 

type PluginType string

PluginType identifies the scope a plugin enriches. 

const (
	PluginTypeUnknown        PluginType = "unknown"
	PluginTypeSession        PluginType = "session"
	PluginTypeTab            PluginType = "tab"
	PluginTypeWindow         PluginType = "window"
	PluginTypeSessionProcess PluginType = "session-process"
)

type PreConditionChecker 

type PreConditionChecker interface {
	// Check runs the pre-condition check
	Check(ctx context.Context, args []string) (PreConditionResult, error)

	// Name returns the name of the pre-condition checker
	Name() string

	// Description returns a description of what this checker validates
	Description() string
}

PreConditionChecker is an interface for checking pre-conditions

type PreConditionManager 

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

PreConditionManager manages and executes pre-condition checks

func NewPreConditionManager 

func NewPreConditionManager() *PreConditionManager

NewPreConditionManager creates a new pre-condition manager

func (*PreConditionManager) Register 

func (m *PreConditionManager) Register(checker PreConditionChecker)

Register adds a new pre-condition checker

func (*PreConditionManager) RegisterExecutable 

func (m *PreConditionManager) RegisterExecutable(executable string) error

RegisterExecutable registers an executable as a pre-condition checker

func (*PreConditionManager) WaitForCondition 

func (m *PreConditionManager) WaitForCondition(ctx context.Context, conditionName string, args []string, timeout time.Duration, pollInterval time.Duration) (PreConditionResult, error)

WaitForCondition waits for a condition to be met, with retries and timeout

type PreConditionResult 

type PreConditionResult struct {
	Success bool
	Message string
	Error   error
}

PreConditionResult represents the result of a pre-condition check

func WaitForCondition 

func WaitForCondition(ctx context.Context, conditionName string, args []string, timeout time.Duration) (PreConditionResult, error)

WaitForCondition is a convenience function using the global manager

type ProcessEnricher 

type ProcessEnricher interface {
	// Name returns the name of the enricher
	Name() string

	// EnrichProcess adds extra data about a process given its PID and session ID
	EnrichProcess(ctx context.Context, sessionID string, pid int) (map[string]interface{}, error)
}

ProcessEnricher is an interface for plugins that can add extra process data

type Registry 

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

Registry holds discovered plugins

func NewRegistry 

func NewRegistry() *Registry

NewRegistry creates a new plugin registry

func (*Registry) DiscoverAndRegister 

func (r *Registry) DiscoverAndRegister() error

DiscoverAndRegister discovers and registers all plugins

func (*Registry) GetEnrichers 

func (r *Registry) GetEnrichers() []SessionEnricher

GetEnrichers returns all registered session enrichers (backward compatibility)

func (*Registry) GetProcessEnrichers 

func (r *Registry) GetProcessEnrichers() []ProcessEnricher

GetProcessEnrichers returns all registered process enrichers

func (*Registry) GetTabEnrichers 

func (r *Registry) GetTabEnrichers() []TabEnricher

GetTabEnrichers returns all registered tab enrichers

func (*Registry) GetWindowEnrichers 

func (r *Registry) GetWindowEnrichers() []WindowEnricher

GetWindowEnrichers returns all registered window enrichers

type SandboxConfig 

type SandboxConfig struct {
	// Timeout for execution
	Timeout time.Duration `json:"timeout" yaml:"timeout"`

	// Maximum output size in bytes
	MaxOutputBytes int `json:"max_output_bytes" yaml:"max_output_bytes"`

	// Maximum memory in bytes (0 = no limit)
	MaxMemoryBytes int64 `json:"max_memory_bytes,omitempty" yaml:"max_memory_bytes,omitempty"`

	// Maximum CPU time in milliseconds (0 = no limit)
	MaxCPUMillis int64 `json:"max_cpu_millis,omitempty" yaml:"max_cpu_millis,omitempty"`
}

SandboxConfig specifies sandbox constraints.

func DefaultSandboxConfig 

func DefaultSandboxConfig() SandboxConfig

DefaultSandboxConfig returns sensible defaults for sandbox configuration.

func RelaxedSandboxConfig 

func RelaxedSandboxConfig() SandboxConfig

RelaxedSandboxConfig returns looser constraints for verified plugins.

type ScreenLinesInput 

type ScreenLinesInput struct {
	// Number of lines needed (e.g., 50)
	Lines int `json:"lines" yaml:"lines"`

	// Whether to include escape sequences
	IncludeEscapes bool `json:"include_escapes,omitempty" yaml:"include_escapes,omitempty"`
}

ScreenLinesInput specifies requirements for screen content.

type SessionEnricher 

type SessionEnricher interface {
	// Name returns the name of the enricher
	Name() string

	// EnrichSession adds extra data to a session
	EnrichSession(ctx context.Context, session *client.SessionInfo) (map[string]interface{}, error)
}

SessionEnricher is an interface for plugins that can add extra data to session listings

func FilterEnrichers 

func FilterEnrichers(enrichers []SessionEnricher, columns []string) []SessionEnricher

FilterEnrichers filters enrichers based on requested plugin names from columns. If no columns are specified, all enrichers are returned.

func FilterEnrichersByPattern 

func FilterEnrichersByPattern(enrichers []SessionEnricher, pattern *regexp.Regexp) []SessionEnricher

FilterEnrichersByPattern filters enrichers whose names match the provided regexp. If pattern is nil, the original slice is returned.

type Source 

type Source struct {
	// Repository URL (e.g., "github.com/tmc/it2-session-claude-has-modal")
	Repository string `json:"repository" yaml:"repository"`

	// Git commit hash (full SHA)
	Commit string `json:"commit" yaml:"commit"`

	// Git tag (optional, for human readability)
	Tag string `json:"tag,omitempty" yaml:"tag,omitempty"`

	// Build configuration for reproducible builds
	Build BuildConfig `json:"build" yaml:"build"`
}

Source describes where to find the source code for reproducible builds.

type TabEnricher 

type TabEnricher interface {
	// Name returns the name of the enricher
	Name() string

	// EnrichTab adds extra data to a tab
	EnrichTab(ctx context.Context, tab *formatting.TabInfo) (map[string]interface{}, error)
}

TabEnricher is an interface for plugins that can add extra data to tab listings

type WindowEnricher 

type WindowEnricher interface {
	// Name returns the name of the enricher
	Name() string

	// EnrichWindow adds extra data to a window
	EnrichWindow(ctx context.Context, window *client.WindowInfo) (map[string]interface{}, error)
}

WindowEnricher is an interface for plugins that can add extra data to window listings

Source Files

View all Source files

Directories

Path Synopsis
Package verify implements reproducible build verification for it2 plugins.
 Package verify implements reproducible build verification for it2 plugins.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.