modules

Documentation

Index

• func CategoryOrder(category string) int
• func CompileSearchTerms(terms []string) ([]*regexp.Regexp, error)
• func ExtractModuleContent(moduleDir string, module SearchResult, reg any, originPath, roleName string) (*ast.StructLit, error)
• func GetInstalledOrigin(cfg cue.Value, category, name string) string
• func InstallModule(ctx context.Context, client *registry.Client, index *registry.Index, ...) (string, error)
• func InstallRoleDependency(ctx context.Context, client *registry.Client, index *registry.Index, ...) (string, error)
• func ModuleExists(cfg cue.Value, category, name string) bool
• func ModuleFromOrigin(origin string) string
• func ParseSearchPatterns(input string) []string
• func ParseSearchTerms(input string) []string
• func ResolveRoleName(index *registry.Index, depPath string) (name string, entry registry.IndexEntry, found bool)
• func UpdateModuleInConfig(configPath, category, name string, newContent ast.Expr) error
• func ValidateSearchQuery(terms, tags []string) error
• func VersionFromOrigin(origin string) string
• type SearchResult
  • func SearchCategoryEntries(category string, entries map[string]registry.IndexEntry, query string, ...) ([]SearchResult, error)
  • func SearchIndex(index *registry.Index, query string, tags []string) ([]SearchResult, error)
  • func SearchInstalledConfig(cfg cue.Value, cueKey, category, query string, tags []string) ([]SearchResult, error)

Functions

func CategoryOrder

func CategoryOrder(category string) int

CategoryOrder returns the display order for a category.

func CompileSearchTerms

func CompileSearchTerms(terms []string) ([]*regexp.Regexp, error)

CompileSearchTerms compiles search terms into case-insensitive regular expressions. Each term is treated as a regex pattern, allowing operators like ^ $ . + * etc. Returns an error if any term contains an invalid regex pattern.

func ExtractModuleContent

func ExtractModuleContent(moduleDir string, module SearchResult, reg any, originPath, roleName string) (*ast.StructLit, error)

ExtractModuleContent loads the module and extracts its content as a CUE AST struct. originPath is the module path (without version) to store in the origin field. roleName, if non-empty, replaces an inline role struct with a string reference.

func GetInstalledOrigin

func GetInstalledOrigin(cfg cue.Value, category, name string) string

GetInstalledOrigin returns the origin field value for the named module in a loaded CUE config. Returns an empty string if the module is not found or has no origin field.

func InstallModule

func InstallModule(ctx context.Context, client *registry.Client, index *registry.Index, selected SearchResult, configDir string) (string, error)

InstallModule installs a module from the registry to the config directory. It fetches the module, extracts the content, and writes it to the appropriate config file. For tasks with role dependencies, the role is installed as a separate module and the task references it by name. The index parameter enables role dependency resolution; pass nil to skip role dependency handling. If the module is already installed, it is updated in place. Returns the resolved version that was installed (e.g., "v0.1.4"); empty if no version could be parsed from the resolved module path.

func InstallRoleDependency

func InstallRoleDependency(ctx context.Context, client *registry.Client, index *registry.Index, moduleDir, configDir string) (string, error)

InstallRoleDependency checks if a task module has a role dependency and installs it as a separate module if not already present. Returns the role name for use as a string reference in the task config, or empty string if no role dependency exists.

func ModuleExists

func ModuleExists(cfg cue.Value, category, name string) bool

ModuleExists checks if a module with the given name exists in a loaded CUE config. Returns true if the module is found, false otherwise.

func ModuleFromOrigin

func ModuleFromOrigin(origin string) string

ModuleFromOrigin extracts the module path from an origin path. For example, "github.com/test/module@v0.1.1" returns "github.com/test/module". Returns the input unchanged if no version separator is found.

func ParseSearchPatterns

func ParseSearchPatterns(input string) []string

ParseSearchPatterns splits an input string into unique search patterns, preserving original case. Deduplication is case-insensitive but the first occurrence's casing is kept. This avoids corrupting case-sensitive regex escape sequences like \S, \D, \W, and \B. Returns nil if no valid patterns remain.

func ParseSearchTerms

func ParseSearchTerms(input string) []string

ParseSearchTerms splits an input string into unique, lowercased search terms. It splits on both whitespace and commas, removes empty strings and duplicates. Returns nil if no valid terms remain. Use ParseSearchPatterns instead when terms will be compiled as regex patterns.

func ResolveRoleName

func ResolveRoleName(index *registry.Index, depPath string) (name string, entry registry.IndexEntry, found bool)

ResolveRoleName finds a role's module name in the index by matching its module path. The depPath is the dependency key (e.g., "github.com/.../roles/golang/agent@v0") which is matched against index entries' Module field. Returns the role name, its index entry, and whether a match was found.

func UpdateModuleInConfig

func UpdateModuleInConfig(configPath, category, name string, newContent ast.Expr) error

UpdateModuleInConfig replaces an existing module entry in the config file.

func ValidateSearchQuery

func ValidateSearchQuery(terms, tags []string) error

ValidateSearchQuery checks that a search query meets minimum length requirements. When tags are provided, an empty query is allowed (tags-only search). When a query is provided, the total character count must be at least 3.

func VersionFromOrigin

func VersionFromOrigin(origin string) string

VersionFromOrigin extracts the version string from an origin path. For example, "github.com/test/module@v0.1.1" returns "v0.1.1". Returns an empty string if no version is found.

Types

type SearchResult

type SearchResult struct {
	Category   string              `json:"category"`
	Name       string              `json:"name"`
	Entry      registry.IndexEntry `json:"entry"`
	MatchScore int                 `json:"matchScore"`
}

SearchResult holds a matched index entry with its category and name.

func SearchCategoryEntries

func SearchCategoryEntries(category string, entries map[string]registry.IndexEntry, query string, tags []string) ([]SearchResult, error)

SearchCategoryEntries searches a single category's registry entries with scoring. The query is split into terms and all must match (AND semantics). Terms are treated as regex patterns for flexible matching. When tags is non-empty, entries must also match at least one tag. Returns results sorted by score descending, then by name ascending.

func SearchIndex

func SearchIndex(index *registry.Index, query string, tags []string) ([]SearchResult, error)

SearchIndex searches all categories in the index for matching entries. The query is split into terms (by whitespace and commas) and all terms must match for an entry to be included (AND semantics). Terms are treated as regex patterns for flexible matching. When tags is non-empty, entries must also match at least one tag (OR semantics). Tags alone (empty query) return all entries matching any tag.

func SearchInstalledConfig

func SearchInstalledConfig(cfg cue.Value, cueKey, category, query string, tags []string) ([]SearchResult, error)

SearchInstalledConfig searches installed CUE config entries for a category. It iterates entries under the given CUE key (e.g. "agents"), extracts description/tags into IndexEntry structs, applies scoring, and returns scored results. The query is split into terms with AND semantics. Terms are treated as regex patterns for flexible matching. When tags is non-empty, entries must also match at least one tag.