packs

Documentation

Overview

Package packs provides the pattern pack system for TW.

Index

• func CategoryOf(id string) string
• func NeedsBacktracking(pattern string) bool
• func ValidateRegex(pattern string) error
• type CompiledRegex
  • func CompileRegex(pattern string) (CompiledRegex, error)
• type DestructiveMatch
• type DestructivePattern
• type LazyRegex
  • func NewLazyRegex(pattern string) *LazyRegex
  • func (lr *LazyRegex) FindIndex(s string) (start, end int, ok bool)
  • func (lr *LazyRegex) IsMatch(s string) bool
  • func (lr *LazyRegex) Pattern() string
• type Pack
  • func (p *Pack) Check(cmd string) *DestructiveMatch
  • func (p *Pack) MatchesDestructive(cmd string) *DestructiveMatch
  • func (p *Pack) MatchesSafe(cmd string) bool
• type PackRegistry
  • func DefaultRegistry() *PackRegistry
  • func NewEmptyRegistry() *PackRegistry
  • func (r *PackRegistry) AllIDs() []string
  • func (r *PackRegistry) Count() int
  • func (r *PackRegistry) ExpandEnabled(ids []string) []string
  • func (r *PackRegistry) Get(id string) *Pack
  • func (r *PackRegistry) LoadFile(path string) error
  • func (r *PackRegistry) LoadFromDir(path string) error
  • func (r *PackRegistry) LoadFromEmbed(fsys embed.FS, pattern string) error
  • func (r *PackRegistry) RegisterPack(pack *Pack, source string) error
  • func (r *PackRegistry) ResolveEnabledSet(enabled, disabled []string) (ids []string, set map[string]bool)
• type PatternSuggestion
• type Platform
  • func ParsePlatform(s string) (Platform, error)
  • func (p Platform) String() string
• type SafePattern
• type Severity
  • func ParseSeverity(s string) (Severity, error)
  • func (s Severity) String() string

Functions

func CategoryOf

func CategoryOf(id string) string

CategoryOf extracts the category from a pack ID (e.g., "database.postgresql" -> "database").

func NeedsBacktracking

func NeedsBacktracking(pattern string) bool

NeedsBacktracking returns true if the pattern uses features that require a backtracking engine (lookahead, lookbehind, atomic groups, possessive quantifiers, or backreferences).

func ValidateRegex

func ValidateRegex(pattern string) error

ValidateRegex checks that a pattern compiles without error. Used at load time to reject invalid regexes eagerly.

Types

type CompiledRegex

type CompiledRegex interface {
	IsMatch(s string) bool
	FindIndex(s string) (start, end int, ok bool)
}

CompiledRegex abstracts over both RE2 and backtracking regex engines.

func CompileRegex

func CompileRegex(pattern string) (CompiledRegex, error)

CompileRegex compiles a pattern, auto-selecting the appropriate engine.

type DestructiveMatch

type DestructiveMatch struct {
	Name        string
	Reason      string
	Severity    Severity
	Explanation string
	Suggestions []PatternSuggestion
	MatchStart  int
	MatchEnd    int
}

DestructiveMatch is the result of a destructive pattern match.

type DestructivePattern

type DestructivePattern struct {
	Name        string
	Regex       *LazyRegex
	Reason      string
	Severity    Severity
	Explanation string
	Suggestions []PatternSuggestion
}

DestructivePattern is a blacklist regex. If matched, the command is denied.

type LazyRegex

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

LazyRegex compiles a regex on first use via sync.Once.

func NewLazyRegex

func NewLazyRegex(pattern string) *LazyRegex

NewLazyRegex creates a LazyRegex that will compile on first use.

func (*LazyRegex) FindIndex

func (lr *LazyRegex) FindIndex(s string) (start, end int, ok bool)

FindIndex returns the byte offsets of the first match. Fail-open on error.

func (*LazyRegex) IsMatch

func (lr *LazyRegex) IsMatch(s string) bool

IsMatch returns true if the pattern matches. Fail-open on compile error.

func (*LazyRegex) Pattern

func (lr *LazyRegex) Pattern() string

Pattern returns the raw pattern string.

type Pack

type Pack struct {
	ID                  string
	Name                string
	Description         string
	Keywords            []string
	SafePatterns        []SafePattern
	DestructivePatterns []DestructivePattern
}

Pack is a named collection of safe and destructive patterns.

func (*Pack) Check

func (p *Pack) Check(cmd string) *DestructiveMatch

Check runs safe patterns then destructive patterns. Returns nil if the command is safe or doesn't match any pattern.

func (*Pack) MatchesDestructive

func (p *Pack) MatchesDestructive(cmd string) *DestructiveMatch

MatchesDestructive returns the first destructive pattern match, or nil.

func (*Pack) MatchesSafe

func (p *Pack) MatchesSafe(cmd string) bool

MatchesSafe returns true if any safe pattern matches the command.

type PackRegistry

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

PackRegistry holds all registered packs and provides lookup/expansion.

func DefaultRegistry

func DefaultRegistry() *PackRegistry

DefaultRegistry returns the singleton registry. Note: It must be initialized (e.g., via allpacks.RegisterAll) before use if you want built-in packs.

func NewEmptyRegistry

func NewEmptyRegistry() *PackRegistry

NewEmptyRegistry builds an empty PackRegistry.

func (*PackRegistry) AllIDs

func (r *PackRegistry) AllIDs() []string

AllIDs returns all registered pack IDs.

func (*PackRegistry) Count

func (r *PackRegistry) Count() int

Count returns the total number of registered packs.

func (*PackRegistry) ExpandEnabled

func (r *PackRegistry) ExpandEnabled(ids []string) []string

ExpandEnabled expands category names (e.g., "database") into all sub-pack IDs (e.g., "database.postgresql", "database.mysql", ...). Non-category IDs are passed through unchanged. Duplicates are removed.

func (*PackRegistry) Get

func (r *PackRegistry) Get(id string) *Pack

Get returns a pack by ID. Returns nil if not found.

func (*PackRegistry) LoadFile

func (r *PackRegistry) LoadFile(path string) error

LoadFile loads one JSON pack file from disk.

func (*PackRegistry) LoadFromDir

func (r *PackRegistry) LoadFromDir(path string) error

LoadFromDir loads every top-level JSON file in a directory. Missing directories are ignored so optional user/project pack roots fail open.

func (*PackRegistry) LoadFromEmbed

func (r *PackRegistry) LoadFromEmbed(fsys embed.FS, pattern string) error

LoadFromEmbed loads pack files from an embedded filesystem glob.

func (*PackRegistry) RegisterPack

func (r *PackRegistry) RegisterPack(pack *Pack, source string) error

RegisterPack registers an already constructed pack while preserving lazy regex compilation inside the pack itself.

func (*PackRegistry) ResolveEnabledSet

func (r *PackRegistry) ResolveEnabledSet(enabled, disabled []string) (ids []string, set map[string]bool)

ResolveEnabledSet expands enabled categories, removes disabled entries, and returns a deduplicated ordered list of active pack IDs plus a set for O(1) lookup.

type PatternSuggestion

type PatternSuggestion struct {
	Command     string
	Description string
	Platform    Platform
}

PatternSuggestion is a safer alternative shown when a command is denied.

type Platform

type Platform int

Platform indicates which OS a suggestion applies to.

const (
	PlatformAll Platform = iota
	PlatformLinux
	PlatformMacOS
	PlatformWindows
	PlatformBSD
)

func ParsePlatform

func ParsePlatform(s string) (Platform, error)

ParsePlatform converts a JSON/string platform to the runtime enum.

func (Platform) String

func (p Platform) String() string

type SafePattern

type SafePattern struct {
	Name  string
	Regex *LazyRegex
}

SafePattern is a whitelist regex. If matched, the command is allowed.

type Severity

type Severity int

Severity indicates how dangerous a destructive pattern is.

const (
	SeverityCritical Severity = iota
	SeverityHigh
	SeverityMedium
	SeverityLow
)

func ParseSeverity

func ParseSeverity(s string) (Severity, error)

ParseSeverity converts a JSON/string severity to the runtime enum.

func (Severity) String

func (s Severity) String() string