Documentation
¶
Overview ¶
Package installer provides installation management for skill dependencies.
The installer package handles the installation and verification of external dependencies required by SKILL.md-defined skills. It supports multiple package managers and provides a unified interface for dependency resolution.
Manager ¶
Manager is the primary type for handling installations:
mgr := installer.NewManager()
// Check if required binaries are available
missing := mgr.VerifyBinaries([]string{"notcrawl", "jq"})
if len(missing) > 0 {
// Install missing dependencies
for _, step := range skill.GetInstallSteps() {
if err := mgr.Install(ctx, step); err != nil {
return err
}
}
}
Supported Package Managers ¶
The manager includes built-in installers for common package managers:
- go: Go modules (go install github.com/user/pkg@version)
- npm: Node.js packages (npm install -g package)
- pip: Python packages (pip install package)
- docker: Docker images (docker pull image)
- brew: Homebrew packages (brew install package)
Custom Installers ¶
Register custom installers for additional package managers:
mgr.RegisterInstaller("cargo", func(ctx context.Context, step loader.InstallStep) error {
return exec.CommandContext(ctx, "cargo", "install", step.Module).Run()
})
Requirement Sources ¶
The installer package also provides Source implementations for fetching skills from external sources:
- [GitHubSource]: Fetch skills from GitHub repositories
- ClawHubSource: Fetch skills from the ClawHub marketplace
GitHub Source ¶
src := installer.NewGitHubSource() skill, err := src.Fetch(ctx, "owner/repo", "skills/myskill")
ClawHub Source ¶
src := installer.NewClawHubSource("https://clawhub.example.com")
skill, err := src.Fetch(ctx, "skill-name", "1.0.0")
Configuration ¶
Manager options include:
- Timeout: Maximum time for install commands (default: 5 minutes)
- Env: Additional environment variables for install commands
- DryRun: Report what would be installed without executing
- Verbose: Enable detailed output
Package installer provides installation management for skill dependencies.
The installer package handles the installation and verification of external dependencies required by SKILL.md-defined skills. It supports multiple package managers and provides a unified interface for dependency resolution.
Index ¶
- func DefaultGlobalDir() string
- func DefaultSkillsDir() string
- func IsClawHubRef(ref string) bool
- func NormalizeClawHubRef(ref string) string
- func ParseGitHubRef(ref string) (owner, repo, tag string, err error)
- type ClawHubSource
- func (s *ClawHubSource) GetSkillInfo(ctx context.Context, name string) (*clawhub.SkillInfo, error)
- func (s *ClawHubSource) InstallFromHub(ctx context.Context, ref string, installer *SkillInstaller) (*InstalledSkill, error)
- func (s *ClawHubSource) SearchHub(ctx context.Context, query string) (*clawhub.SearchResult, error)
- type ConstraintType
- type GitHubFetcher
- func (f *GitHubFetcher) DownloadAndExtract(ctx context.Context, release *GitHubRelease, targetDir string) error
- func (f *GitHubFetcher) GetLatestRelease(ctx context.Context, owner, repo string) (*GitHubRelease, error)
- func (f *GitHubFetcher) GetRelease(ctx context.Context, owner, repo, tag string) (*GitHubRelease, error)
- func (f *GitHubFetcher) WithToken(token string) *GitHubFetcher
- type GitHubRelease
- type InstallResult
- type InstalledSkill
- type InstallerFunc
- type LockFile
- type LockedEntry
- type Manager
- func (m *Manager) Install(ctx context.Context, steps []loader.InstallStep) error
- func (m *Manager) InstallMissing(ctx context.Context, steps []loader.InstallStep) error
- func (m *Manager) InstallStep(ctx context.Context, step loader.InstallStep) error
- func (m *Manager) InstallWithResults(ctx context.Context, steps []loader.InstallStep) []InstallResult
- func (m *Manager) RegisterInstaller(kind string, fn InstallerFunc)
- func (m *Manager) VerifyBinaries(bins []string) (missing []string)
- type PinnedSource
- type SemVer
- type SkillInstaller
- func (i *SkillInstaller) Install(ctx context.Context, sourceStr string) (*InstalledSkill, error)
- func (i *SkillInstaller) InstallGit(ctx context.Context, source *Source) (*InstalledSkill, error)
- func (i *SkillInstaller) InstallLocal(ctx context.Context, source *Source) (*InstalledSkill, error)
- func (i *SkillInstaller) List() ([]*InstalledSkill, error)
- func (i *SkillInstaller) TargetDir() string
- func (i *SkillInstaller) Uninstall(name string) error
- type Source
- type SourceType
- type VersionConstraint
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefaultGlobalDir ¶
func DefaultGlobalDir() string
DefaultGlobalDir returns the default global skills directory.
func DefaultSkillsDir ¶
func DefaultSkillsDir() string
DefaultSkillsDir returns the default local skills directory.
func IsClawHubRef ¶ added in v0.9.0
Helper to determine if a reference is a ClawHub reference.
func NormalizeClawHubRef ¶ added in v0.9.0
NormalizeClawHubRef normalizes a ClawHub reference.
func ParseGitHubRef ¶ added in v0.9.0
ParseGitHubRef parses a GitHub repository reference. Formats:
- github.com/owner/repo
- github.com/owner/repo@tag
- owner/repo
- owner/repo@tag
Types ¶
type ClawHubSource ¶ added in v0.9.0
type ClawHubSource struct {
// contains filtered or unexported fields
}
ClawHubSource provides skill packages from the ClawHub marketplace.
func NewClawHubSource ¶ added in v0.9.0
func NewClawHubSource(hub *clawhub.Hub) *ClawHubSource
NewClawHubSource creates a new ClawHub source.
func (*ClawHubSource) GetSkillInfo ¶ added in v0.9.0
GetSkillInfo gets information about a skill from ClawHub.
func (*ClawHubSource) InstallFromHub ¶ added in v0.9.0
func (s *ClawHubSource) InstallFromHub(ctx context.Context, ref string, installer *SkillInstaller) (*InstalledSkill, error)
InstallFromHub installs a skill from ClawHub.
func (*ClawHubSource) SearchHub ¶ added in v0.9.0
func (s *ClawHubSource) SearchHub(ctx context.Context, query string) (*clawhub.SearchResult, error)
SearchHub searches for skills in ClawHub.
type ConstraintType ¶ added in v0.11.0
type ConstraintType string
ConstraintType identifies the type of version constraint.
const ( // ConstraintExact matches a specific version. ConstraintExact ConstraintType = "exact" // ConstraintRange matches versions in a range. ConstraintRange ConstraintType = "range" // ConstraintCaret matches compatible versions (^). ConstraintCaret ConstraintType = "caret" // ConstraintTilde matches patch versions (~). ConstraintTilde ConstraintType = "tilde" // ConstraintLatest matches the latest version. ConstraintLatest ConstraintType = "latest" )
type GitHubFetcher ¶ added in v0.9.0
type GitHubFetcher struct {
// contains filtered or unexported fields
}
GitHubFetcher fetches skill packages from GitHub releases.
func NewGitHubFetcher ¶ added in v0.9.0
func NewGitHubFetcher() *GitHubFetcher
NewGitHubFetcher creates a new GitHub fetcher.
func (*GitHubFetcher) DownloadAndExtract ¶ added in v0.9.0
func (f *GitHubFetcher) DownloadAndExtract(ctx context.Context, release *GitHubRelease, targetDir string) error
DownloadAndExtract downloads a release tarball and extracts it to the target directory.
func (*GitHubFetcher) GetLatestRelease ¶ added in v0.9.0
func (f *GitHubFetcher) GetLatestRelease(ctx context.Context, owner, repo string) (*GitHubRelease, error)
GetLatestRelease gets the latest release for a repository.
func (*GitHubFetcher) GetRelease ¶ added in v0.9.0
func (f *GitHubFetcher) GetRelease(ctx context.Context, owner, repo, tag string) (*GitHubRelease, error)
GetRelease gets a specific release by tag.
func (*GitHubFetcher) WithToken ¶ added in v0.9.0
func (f *GitHubFetcher) WithToken(token string) *GitHubFetcher
WithToken sets the GitHub token for authenticated requests.
type GitHubRelease ¶ added in v0.9.0
type GitHubRelease struct {
TagName string `json:"tag_name"`
Name string `json:"name"`
TarballURL string `json:"tarball_url"`
ZipballURL string `json:"zipball_url"`
Draft bool `json:"draft"`
Prerelease bool `json:"prerelease"`
}
GitHubRelease represents a GitHub release.
type InstallResult ¶
type InstallResult struct {
// Step is the installation step that was executed.
Step loader.InstallStep
// Success indicates if the installation succeeded.
Success bool
// Error contains any error that occurred.
Error error
// Duration is how long the installation took.
Duration time.Duration
}
InstallResult contains the result of an installation attempt.
type InstalledSkill ¶
type InstalledSkill struct {
// Name is the skill name (directory name).
Name string
// Path is the installed path.
Path string
// Source is the original source location.
Source *Source
// SourceType is git or local.
SourceType SourceType
// Global indicates if installed to global directory.
Global bool
// Symlinked indicates if the skill is symlinked (local installs).
Symlinked bool
}
InstalledSkill contains information about an installed skill.
type InstallerFunc ¶
type InstallerFunc func(ctx context.Context, step loader.InstallStep) error
InstallerFunc is a function that installs a dependency.
type LockFile ¶ added in v0.11.0
type LockFile struct {
// Version is the lock file format version.
Version int `json:"version"`
// Generated is when the lock file was created.
Generated string `json:"generated"`
// Locked maps source URLs to pinned versions.
Locked map[string]LockedEntry `json:"locked"`
}
LockFile represents a version lock file for reproducible installs.
type LockedEntry ¶ added in v0.11.0
type LockedEntry struct {
// Version is the pinned version.
Version string `json:"version"`
// Constraint is the original constraint.
Constraint string `json:"constraint,omitempty"`
// Checksum is the integrity hash.
Checksum string `json:"checksum,omitempty"`
}
LockedEntry is a single locked dependency.
type Manager ¶
type Manager struct {
// Timeout is the maximum time for an installation command.
// Zero means use default (5 minutes).
Timeout time.Duration
// Env contains additional environment variables for install commands.
Env []string
// DryRun when true, only reports what would be installed.
DryRun bool
// Verbose enables detailed output.
Verbose bool
// contains filtered or unexported fields
}
Manager handles installation of skill dependencies.
Manager provides methods to verify, install, and manage external dependencies defined in SKILL.md files. It supports multiple installation methods including Go modules, npm packages, and pip.
func NewManager ¶
func NewManager() *Manager
NewManager creates a new installation manager with default installers.
func (*Manager) InstallMissing ¶
InstallMissing installs only the dependencies whose binaries are missing.
func (*Manager) InstallStep ¶
InstallStep executes a single installation step.
func (*Manager) InstallWithResults ¶
func (m *Manager) InstallWithResults(ctx context.Context, steps []loader.InstallStep) []InstallResult
InstallWithResults installs steps and returns detailed results.
func (*Manager) RegisterInstaller ¶
func (m *Manager) RegisterInstaller(kind string, fn InstallerFunc)
RegisterInstaller registers a custom installer for a given kind.
func (*Manager) VerifyBinaries ¶
VerifyBinaries checks if all required binaries are available.
type PinnedSource ¶ added in v0.11.0
type PinnedSource struct {
Source
// Constraint is the version constraint.
Constraint *VersionConstraint
// Pinned is the resolved/pinned version.
Pinned string
}
PinnedSource extends Source with version pinning.
func ParsePinnedSource ¶ added in v0.11.0
func ParsePinnedSource(s string) (*PinnedSource, error)
ParsePinnedSource parses a source string with version constraint.
Formats:
- github.com/user/repo@v1.2.3 (exact version)
- github.com/user/repo@^1.2.0 (caret range)
- github.com/user/repo@~1.2.0 (tilde range)
- github.com/user/repo@>=1.0.0 (range)
- github.com/user/repo@latest (latest)
func (*PinnedSource) ResolveVersion ¶ added in v0.11.0
func (p *PinnedSource) ResolveVersion(available []string) (string, error)
ResolveVersion resolves the constraint against available versions.
Returns the best matching version or an error if no match.
type SemVer ¶ added in v0.11.0
SemVer represents a semantic version.
func ParseSemVer ¶ added in v0.11.0
ParseSemVer parses a semantic version string.
type SkillInstaller ¶
type SkillInstaller struct {
// SkillsDir is the target directory for installed skills.
SkillsDir string
// GlobalDir is the global skills directory.
GlobalDir string
// UseGlobal indicates whether to install to global directory.
UseGlobal bool
// Symlink uses symlinks for local installs instead of copying.
Symlink bool
// Verbose enables verbose output.
Verbose bool
}
SkillInstaller handles installing skills from various sources.
func NewSkillInstaller ¶
func NewSkillInstaller() *SkillInstaller
NewSkillInstaller creates a new skill installer with defaults.
func (*SkillInstaller) Install ¶
func (i *SkillInstaller) Install(ctx context.Context, sourceStr string) (*InstalledSkill, error)
Install installs a skill from the given source string.
func (*SkillInstaller) InstallGit ¶
func (i *SkillInstaller) InstallGit(ctx context.Context, source *Source) (*InstalledSkill, error)
InstallGit installs a skill from a git repository.
func (*SkillInstaller) InstallLocal ¶
func (i *SkillInstaller) InstallLocal(ctx context.Context, source *Source) (*InstalledSkill, error)
InstallLocal installs a skill from a local path.
func (*SkillInstaller) List ¶
func (i *SkillInstaller) List() ([]*InstalledSkill, error)
List returns all installed skills.
func (*SkillInstaller) TargetDir ¶
func (i *SkillInstaller) TargetDir() string
TargetDir returns the target directory based on UseGlobal setting.
func (*SkillInstaller) Uninstall ¶
func (i *SkillInstaller) Uninstall(name string) error
Uninstall removes an installed skill.
type Source ¶
type Source struct {
// Type is the source type (git or local).
Type SourceType
// URL is the git repository URL (for git sources).
URL string
// Path is the local filesystem path (for local sources).
Path string
// Ref is the git reference (branch, tag, commit) to checkout.
// Empty means default branch.
Ref string
// Subdir is an optional subdirectory within the repo/path.
Subdir string
}
Source represents a skill source location.
func ParseSource ¶
ParseSource parses a source string into a Source struct. Formats:
- github.com/user/repo -> git source
- git@github.com:user/repo.git -> git source
- https://github.com/user/repo -> git source
- /path/to/skill -> local source
- ./relative/path -> local source
- github.com/user/repo@v1.0.0 -> git source with ref
- github.com/user/repo/subdir -> git source with subdir
type SourceType ¶
type SourceType string
SourceType identifies the type of skill source.
const ( // SourceTypeGit is a git repository URL. SourceTypeGit SourceType = "git" // SourceTypeLocal is a local filesystem path. SourceTypeLocal SourceType = "local" )
type VersionConstraint ¶ added in v0.11.0
type VersionConstraint struct {
// Raw is the original constraint string.
Raw string
// Type is the constraint type.
Type ConstraintType
// Version is the parsed semver (for exact/range/caret/tilde).
Version *SemVer
// Op is the comparison operator (for range constraints).
Op string
}
VersionConstraint represents a version requirement.
Supported formats:
- Exact: "1.2.3", "v1.2.3"
- Range: ">=1.0.0", "<=2.0.0", ">1.0.0", "<2.0.0"
- Caret: "^1.2.3" (>=1.2.3, <2.0.0)
- Tilde: "~1.2.3" (>=1.2.3, <1.3.0)
- Latest: "latest", "*"
func ParseVersionConstraint ¶ added in v0.11.0
func ParseVersionConstraint(s string) (*VersionConstraint, error)
ParseVersionConstraint parses a version constraint string.
func (*VersionConstraint) Matches ¶ added in v0.11.0
func (c *VersionConstraint) Matches(v *SemVer) bool
Matches returns true if the version satisfies the constraint.