installer

package
v0.12.0 Latest Latest
Warning

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

Go to latest
Published: Aug 9, 2026 License: MIT Imports: 17 Imported by: 0

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

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

func IsClawHubRef(ref string) bool

Helper to determine if a reference is a ClawHub reference.

func NormalizeClawHubRef added in v0.9.0

func NormalizeClawHubRef(ref string) string

NormalizeClawHubRef normalizes a ClawHub reference.

func ParseGitHubRef added in v0.9.0

func ParseGitHubRef(ref string) (owner, repo, tag string, err error)

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

func (s *ClawHubSource) GetSkillInfo(ctx context.Context, name string) (*clawhub.SkillInfo, error)

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) Install

func (m *Manager) Install(ctx context.Context, steps []loader.InstallStep) error

Install executes the installation steps for a skill.

func (*Manager) InstallMissing

func (m *Manager) InstallMissing(ctx context.Context, steps []loader.InstallStep) error

InstallMissing installs only the dependencies whose binaries are missing.

func (*Manager) InstallStep

func (m *Manager) InstallStep(ctx context.Context, step loader.InstallStep) error

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

func (m *Manager) VerifyBinaries(bins []string) (missing []string)

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

type SemVer struct {
	Major      int
	Minor      int
	Patch      int
	Prerelease string
	Build      string
}

SemVer represents a semantic version.

func ParseSemVer added in v0.11.0

func ParseSemVer(s string) (*SemVer, error)

ParseSemVer parses a semantic version string.

func (SemVer) Compare added in v0.11.0

func (v SemVer) Compare(other SemVer) int

Compare returns -1, 0, or 1 if v is less than, equal to, or greater than other.

func (SemVer) String added in v0.11.0

func (v SemVer) String() string

String returns the string representation.

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

func ParseSource(s string) (*Source, error)

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL