vault

package
v0.14.4 Latest Latest
Warning

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

 Go to latest Published: Mar 25, 2026 License: Apache-2.0 Imports: 33 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrLockFileNotFound = errors.New("lock file not found")

ErrLockFileNotFound is returned when the lock file does not exist in the vault

Functions

This section is empty.

Types

type AssetDetails added in v0.6.0 

type AssetDetails struct {
	Name        string
	Type        asset.Type
	Description string
	CreatedAt   time.Time
	UpdatedAt   time.Time
	Versions    []AssetVersion
	Metadata    *metadata.Metadata // Metadata for latest version (or nil if not available)
}

AssetDetails contains detailed information about a specific asset

type AssetSummary added in v0.6.0 

type AssetSummary struct {
	Name          string
	Type          asset.Type
	LatestVersion string
	VersionsCount int
	Description   string
	CreatedAt     time.Time
	UpdatedAt     time.Time
}

AssetSummary contains summary information about a vault asset

type AssetVersion added in v0.6.0 

type AssetVersion struct {
	Version    string
	CreatedAt  time.Time
	FilesCount int
}

AssetVersion contains version information for an asset

type Config 

type Config interface {
	GetType() string
	GetServerURL() string
	GetAuthToken() string
	GetRepositoryURL() string
}

Config represents the minimal configuration needed to create a vault This avoids circular dependency with the config package

type ErrVersionExists added in v0.9.1 

type ErrVersionExists struct {
	Name    string
	Version string
	Message string
}

ErrVersionExists is returned when attempting to add an asset version that already exists

func (*ErrVersionExists) Error added in v0.9.1 

func (e *ErrVersionExists) Error() string

type GitSourceHandler 

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

GitSourceHandler handles assets with source-git

func NewGitSourceHandler 

func NewGitSourceHandler(gitClient *git.Client) *GitSourceHandler

NewGitSourceHandler creates a new Git source handler

func (*GitSourceHandler) Fetch 

func (g *GitSourceHandler) Fetch(ctx context.Context, asset *lockfile.Asset) ([]byte, error)

Fetch clones/fetches a git repository and retrieves the asset

func (*GitSourceHandler) ResolveRef 

func (g *GitSourceHandler) ResolveRef(ctx context.Context, repoURL, ref string) (string, error)

ResolveRef resolves a branch or tag name to a commit SHA This is used during lock file generation to convert friendly names to commit SHAs

type GitVault 

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

GitVault implements Vault for Git vaults

func NewGitVault 

func NewGitVault(repoURL string) (*GitVault, error)

NewGitVault creates a new Git repository

func (*GitVault) AddAsset 

func (g *GitVault) AddAsset(ctx context.Context, asset *lockfile.Asset, zipData []byte) error

AddAsset uploads an asset to the Git repository

func (*GitVault) Authenticate 

func (g *GitVault) Authenticate(ctx context.Context) (string, error)

Authenticate performs authentication with the Git repository For Git repos, this is a no-op as authentication is handled by git itself

func (*GitVault) CommitAndPush 

func (g *GitVault) CommitAndPush(ctx context.Context, asset *lockfile.Asset) error

CommitAndPush commits all changes and pushes to remote

func (*GitVault) GetAsset 

func (g *GitVault) GetAsset(ctx context.Context, asset *lockfile.Asset) ([]byte, error)

GetAsset downloads an asset using its source configuration

func (*GitVault) GetAssetByVersion 

func (g *GitVault) GetAssetByVersion(ctx context.Context, name, version string) ([]byte, error)

GetAssetByVersion retrieves an asset by name and version from the git repository This creates a zip from the exploded directory

func (*GitVault) GetAssetDetails added in v0.6.0 

func (g *GitVault) GetAssetDetails(ctx context.Context, name string) (*AssetDetails, error)

GetAssetDetails returns detailed information about a specific asset

func (*GitVault) GetBootstrapOptions added in v0.9.2 

func (g *GitVault) GetBootstrapOptions(ctx context.Context) []bootstrap.Option

GetBootstrapOptions returns no bootstrap options for GitVault

func (*GitVault) GetLockFile 

func (g *GitVault) GetLockFile(ctx context.Context, cachedETag string) (content []byte, etag string, notModified bool, err error)

GetLockFile retrieves the lock file from the Git repository

func (*GitVault) GetLockFilePath 

func (g *GitVault) GetLockFilePath() string

GetLockFilePath returns the path to the lock file in the git repository

func (*GitVault) GetMCPTools added in v0.6.0 

func (g *GitVault) GetMCPTools() any

GetMCPTools returns no additional MCP tools for GitVault

func (*GitVault) GetMetadata 

func (g *GitVault) GetMetadata(ctx context.Context, name, version string) (*metadata.Metadata, error)

GetMetadata retrieves metadata for a specific asset version Not applicable for Git repositories (metadata is inside the zip)

func (*GitVault) GetVersionList 

func (g *GitVault) GetVersionList(ctx context.Context, name string) ([]string, error)

GetVersionList retrieves available versions for an asset from list.txt

func (*GitVault) InheritInstallations added in v0.12.8 

func (g *GitVault) InheritInstallations(ctx context.Context, asset *lockfile.Asset) error

InheritInstallations preserves existing scopes when adding a new version. Reads the lock file, finds any existing version of the asset, copies its scopes, then commits and pushes.

func (*GitVault) ListAssets added in v0.6.0 

func (g *GitVault) ListAssets(ctx context.Context, opts ListAssetsOptions) (*ListAssetsResult, error)

ListAssets returns a list of all assets in the vault by reading the assets/ directory

func (*GitVault) PostUsageStats 

func (r *GitVault) PostUsageStats(ctx context.Context, jsonlData string) error

PostUsageStats is a no-op for Git repositories Git repositories don't support stats collection

func (*GitVault) RemoveAsset 

func (g *GitVault) RemoveAsset(ctx context.Context, assetName, version string, delete bool) error

RemoveAsset removes an asset from the lock file and pushes to remote. If delete is true, also permanently removes the asset files from the vault.

func (*GitVault) RenameAsset added in v0.14.0 

func (g *GitVault) RenameAsset(ctx context.Context, oldName, newName string) error

RenameAsset renames an asset in the vault. All versions and installations are preserved under the new name.

func (*GitVault) SetInstallations added in v0.6.0 

func (g *GitVault) SetInstallations(ctx context.Context, asset *lockfile.Asset, scopeEntity string) error

SetInstallations updates the lock file with installation scopes and commits/pushes

func (*GitVault) UpdateTemplates 

func (g *GitVault) UpdateTemplates(ctx context.Context, commit bool) ([]string, error)

UpdateTemplates updates templates in the repository if needed and returns the list of updated files The commit parameter controls whether to commit and push changes (git-specific behavior)

func (*GitVault) VerifyIntegrity 

func (g *GitVault) VerifyIntegrity(data []byte, hashes map[string]string, size int64) error

VerifyIntegrity checks hashes and sizes for downloaded assets

type HTTPSourceHandler 

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

HTTPSourceHandler handles assets with source-http

func NewHTTPSourceHandler 

func NewHTTPSourceHandler(authToken string) *HTTPSourceHandler

NewHTTPSourceHandler creates a new HTTP source handler

func (*HTTPSourceHandler) DownloadWithProgress 

func (h *HTTPSourceHandler) DownloadWithProgress(ctx context.Context, url string, progressCallback func(current, total int64)) ([]byte, error)

DownloadWithProgress downloads a file with progress reporting This is used for user-facing downloads with progress bars

func (*HTTPSourceHandler) Fetch 

func (h *HTTPSourceHandler) Fetch(ctx context.Context, asset *lockfile.Asset) ([]byte, error)

Fetch downloads an asset from an HTTP URL

type ListAssetsOptions added in v0.6.0 

type ListAssetsOptions struct {
	Type   string // Filter by asset type (skill, mcp, etc.)
	Search string // Search query for filtering assets
	Limit  int    // Maximum number of assets to return (default 100)
}

ListAssetsOptions contains options for listing vault assets

type ListAssetsResult added in v0.6.0 

type ListAssetsResult struct {
	Assets []AssetSummary
}

ListAssetsResult contains the results of a ListAssets call

type PathSourceHandler 

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

PathSourceHandler handles assets with source-path

func NewPathSourceHandler 

func NewPathSourceHandler(lockFileDir string) *PathSourceHandler

NewPathSourceHandler creates a new path source handler

func (*PathSourceHandler) Fetch 

func (p *PathSourceHandler) Fetch(ctx context.Context, asset *lockfile.Asset) ([]byte, error)

Fetch reads an asset from a local file path

func (*PathSourceHandler) ResolvePath 

func (p *PathSourceHandler) ResolvePath(path string) (string, error)

ResolvePath resolves a path (absolute, relative, or tilde) to an absolute path

type PathVault 

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

PathVault implements Vault for local filesystem directories It follows the same pattern as GitRepository and SleuthRepository

func NewPathVault 

func NewPathVault(repoURL string) (*PathVault, error)

NewPathVault creates a new path repository from a file:// URL

func (*PathVault) AddAsset 

func (p *PathVault) AddAsset(ctx context.Context, asset *lockfile.Asset, zipData []byte) error

AddAsset adds an asset to the local repository Follows the same pattern as GitRepository: exploded storage + list.txt

func (*PathVault) Authenticate 

func (p *PathVault) Authenticate(ctx context.Context) (string, error)

Authenticate performs authentication - no-op for path repositories

func (*PathVault) GetAsset 

func (p *PathVault) GetAsset(ctx context.Context, asset *lockfile.Asset) ([]byte, error)

GetAsset downloads an asset using its source configuration Reuses the same dispatch pattern as GitRepository and SleuthRepository

func (*PathVault) GetAssetByVersion added in v0.9.1 

func (p *PathVault) GetAssetByVersion(ctx context.Context, name, version string) ([]byte, error)

GetAssetByVersion retrieves an asset by name and version Creates a zip from the exploded directory

func (*PathVault) GetAssetDetails added in v0.6.0 

func (p *PathVault) GetAssetDetails(ctx context.Context, name string) (*AssetDetails, error)

GetAssetDetails returns detailed information about a specific asset

func (*PathVault) GetBootstrapOptions added in v0.9.2 

func (p *PathVault) GetBootstrapOptions(ctx context.Context) []bootstrap.Option

GetBootstrapOptions returns no bootstrap options for PathVault

func (*PathVault) GetLockFile 

func (p *PathVault) GetLockFile(ctx context.Context, cachedETag string) (content []byte, etag string, notModified bool, err error)

GetLockFile retrieves the lock file from the local directory

func (*PathVault) GetLockFilePath 

func (p *PathVault) GetLockFilePath() string

GetLockFilePath returns the path to the lock file in the path repository

func (*PathVault) GetMCPTools added in v0.6.0 

func (p *PathVault) GetMCPTools() any

GetMCPTools returns no additional MCP tools for PathVault

func (*PathVault) GetMetadata 

func (p *PathVault) GetMetadata(ctx context.Context, name, version string) (*metadata.Metadata, error)

GetMetadata retrieves metadata for a specific asset version

func (*PathVault) GetVersionList 

func (p *PathVault) GetVersionList(ctx context.Context, name string) ([]string, error)

GetVersionList retrieves available versions for an asset from list.txt Reuses the same pattern as GitRepository

func (*PathVault) InheritInstallations added in v0.12.8 

func (p *PathVault) InheritInstallations(ctx context.Context, asset *lockfile.Asset) error

InheritInstallations preserves existing scopes when adding a new version. Reads the lock file, finds any existing version of the asset, and copies its scopes.

func (*PathVault) ListAssets added in v0.6.0 

func (p *PathVault) ListAssets(ctx context.Context, opts ListAssetsOptions) (*ListAssetsResult, error)

ListAssets returns a list of all assets in the vault by reading the assets/ directory

func (*PathVault) PostUsageStats 

func (p *PathVault) PostUsageStats(ctx context.Context, jsonlData string) error

PostUsageStats is a no-op for path repositories Same as GitRepository

func (*PathVault) RemoveAsset 

func (p *PathVault) RemoveAsset(ctx context.Context, assetName, version string, delete bool) error

RemoveAsset removes an asset from the lock file. If delete is true, also permanently removes the asset files from the vault.

func (*PathVault) RenameAsset added in v0.14.0 

func (p *PathVault) RenameAsset(ctx context.Context, oldName, newName string) error

RenameAsset renames an asset in the vault.

func (*PathVault) SetInstallations added in v0.6.0 

func (p *PathVault) SetInstallations(ctx context.Context, asset *lockfile.Asset, scopeEntity string) error

SetInstallations updates the lock file with installation scopes

func (*PathVault) VerifyIntegrity 

func (p *PathVault) VerifyIntegrity(data []byte, hashes map[string]string, size int64) error

VerifyIntegrity checks hashes and sizes for downloaded assets Same as GitRepository: no verification needed for local files

type QueryInput added in v0.6.0 

type QueryInput struct {
	Query       string `` /* 235-byte string literal not displayed */
	Integration string `json:"integration" jsonschema:"which integration to query (github, circleci, linear, or datadog)"`
}

QueryInput is the input type for query tool

type Role added in v0.11.1 

type Role struct {
	Title       string `json:"title"`
	Slug        string `json:"slug"`
	Description string `json:"description"`
}

Role represents a skill profile (role) from the server

type RoleListResponse added in v0.11.1 

type RoleListResponse struct {
	Roles  []Role  `json:"profiles"`
	Active *string `json:"active"`
}

RoleListResponse represents the response from the roles list endpoint

type ScopeOption added in v0.12.8 

type ScopeOption struct {
	Label       string // Display text (e.g., "Just for me")
	Value       string // Machine value passed to SetInstallations
	Description string // Help text
}

ScopeOption represents a vault-specific scope option (e.g., "personal", "team") displayed in the interactive UI alongside the built-in global/repo options.

type ScopeOptionProvider added in v0.12.8 

type ScopeOptionProvider interface {
	GetScopeOptions() []ScopeOption
}

ScopeOptionProvider is implemented by vaults that provide additional scope options beyond global and per-repository scoping.

type SleuthVault 

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

SleuthVault implements Vault for Sleuth HTTP servers

func NewSleuthVault 

func NewSleuthVault(serverURL, authToken string) *SleuthVault

NewSleuthVault creates a new Sleuth repository

func (*SleuthVault) AddAsset 

func (s *SleuthVault) AddAsset(ctx context.Context, asset *lockfile.Asset, zipData []byte) error

AddAsset uploads an asset to the Sleuth server

func (*SleuthVault) Authenticate 

func (s *SleuthVault) Authenticate(ctx context.Context) (string, error)

Authenticate performs authentication with the Sleuth server

func (*SleuthVault) GetAsset 

func (s *SleuthVault) GetAsset(ctx context.Context, asset *lockfile.Asset) ([]byte, error)

GetAsset downloads an asset using its source configuration

func (*SleuthVault) GetAssetByVersion added in v0.9.1 

func (s *SleuthVault) GetAssetByVersion(ctx context.Context, name, ver string) ([]byte, error)

GetAssetByVersion downloads an asset by name and version

func (*SleuthVault) GetAssetDetails added in v0.6.0 

func (s *SleuthVault) GetAssetDetails(ctx context.Context, name string) (*AssetDetails, error)

GetAssetDetails retrieves detailed information about a specific asset using GraphQL

func (*SleuthVault) GetBootstrapOptions added in v0.9.2 

func (s *SleuthVault) GetBootstrapOptions(ctx context.Context) []bootstrap.Option

GetBootstrapOptions returns bootstrap options for the Sleuth vault. This includes the Sleuth AI Query MCP server.

func (*SleuthVault) GetLockFile 

func (s *SleuthVault) GetLockFile(ctx context.Context, cachedETag string) (content []byte, etag string, notModified bool, err error)

GetLockFile retrieves the lock file from the Sleuth server

func (*SleuthVault) GetMCPTools added in v0.6.0 

func (s *SleuthVault) GetMCPTools() any

GetMCPTools returns the query tool for Sleuth vault

func (*SleuthVault) GetMetadata 

func (s *SleuthVault) GetMetadata(ctx context.Context, name, version string) (*metadata.Metadata, error)

GetMetadata retrieves metadata for a specific asset version

func (*SleuthVault) GetScopeOptions added in v0.12.8 

func (s *SleuthVault) GetScopeOptions() []ScopeOption

GetScopeOptions returns additional scope options for the Sleuth vault

func (*SleuthVault) GetVersionList 

func (s *SleuthVault) GetVersionList(ctx context.Context, name string) ([]string, error)

GetVersionList retrieves available versions for an asset

func (*SleuthVault) InheritInstallations added in v0.12.8 

func (s *SleuthVault) InheritInstallations(ctx context.Context, asset *lockfile.Asset) error

InheritInstallations is a no-op for Sleuth vaults. The server auto-inherits installations when AddAsset uploads a new version.

func (*SleuthVault) ListAssets added in v0.6.0 

func (s *SleuthVault) ListAssets(ctx context.Context, opts ListAssetsOptions) (*ListAssetsResult, error)

ListAssets retrieves a list of all assets in the vault using GraphQL

func (*SleuthVault) ListRoles added in v0.11.1 

func (s *SleuthVault) ListRoles(ctx context.Context) (*RoleListResponse, error)

ListRoles retrieves the list of available roles from the server

func (*SleuthVault) PostUsageStats 

func (s *SleuthVault) PostUsageStats(ctx context.Context, jsonlData string) error

PostUsageStats sends asset usage statistics to the Sleuth server

func (*SleuthVault) QueryIntegration added in v0.6.0 

func (s *SleuthVault) QueryIntegration(ctx context.Context, query, integration string, gitContext any) (string, error)

QueryIntegration queries integrated services (GitHub, CircleCI, Linear) using natural language

func (*SleuthVault) QueryIntegrationStream added in v0.6.1 

func (s *SleuthVault) QueryIntegrationStream(
	ctx context.Context,
	query, integration string,
	gitContext any,
	onEvent func(eventType, content string),
) (string, error)

QueryIntegrationStream queries integrated services using SSE streaming. The onEvent callback is called for each event received, which can be used to send MCP log notifications to keep the connection alive.

func (*SleuthVault) RemoveAsset 

func (s *SleuthVault) RemoveAsset(ctx context.Context, assetName, version string, delete bool) error

RemoveAsset removes an asset from the Sleuth server's lock file. The delete flag is passed to the server mutation for permanent deletion.

func (*SleuthVault) RenameAsset added in v0.14.0 

func (s *SleuthVault) RenameAsset(ctx context.Context, oldName, newName string) error

RenameAsset renames an asset on the Sleuth server using a GraphQL mutation.

func (*SleuthVault) SetActiveRole added in v0.11.1 

func (s *SleuthVault) SetActiveRole(ctx context.Context, slug *string) (*Role, error)

SetActiveRole sets or clears the active role on the server. Pass nil to clear the active role.

func (*SleuthVault) SetInstallations added in v0.6.0 

func (s *SleuthVault) SetInstallations(ctx context.Context, asset *lockfile.Asset, scopeEntity string) error

SetInstallations sets the installation scopes for an asset using GraphQL mutation

func (*SleuthVault) VerifyIntegrity 

func (s *SleuthVault) VerifyIntegrity(data []byte, hashes map[string]string, size int64) error

VerifyIntegrity checks hashes and sizes for downloaded assets

type SourceHandler 

type SourceHandler interface {
	// Fetch retrieves asset data from the source
	Fetch(ctx context.Context, asset *lockfile.Asset) ([]byte, error)
}

SourceHandler handles fetching assets from specific source types This is used internally by Vault implementations to handle different source types

type ToolDef added in v0.6.0 

type ToolDef struct {
	Tool    *mcp.Tool
	Handler func(context.Context, *mcp.CallToolRequest, QueryInput) (*mcp.CallToolResult, any, error)
}

ToolDef represents an MCP tool with its handler

type Vault 

type Vault interface {
	// Authenticate performs authentication with the repository
	// Returns an auth token or empty string if no auth needed
	Authenticate(ctx context.Context) (string, error)

	// GetLockFile retrieves the lock file from the repository
	// Returns lock file content and ETag for caching
	// If cachedETag matches, returns notModified=true with empty content
	GetLockFile(ctx context.Context, cachedETag string) (content []byte, etag string, notModified bool, err error)

	// GetAsset downloads an asset using its source configuration from the lock file
	// The asset parameter contains the source configuration (source-http, source-git, source-path)
	GetAsset(ctx context.Context, asset *lockfile.Asset) ([]byte, error)

	// AddAsset uploads an asset to the repository
	AddAsset(ctx context.Context, asset *lockfile.Asset, zipData []byte) error

	// SetInstallations configures where an asset should be installed
	// Updates the lock file with the installation scopes
	// scopeEntity is a vault-specific value from ScopeOptionProvider (e.g., "personal").
	// Empty string means standard global/repo scoping via asset.Scopes.
	SetInstallations(ctx context.Context, asset *lockfile.Asset, scopeEntity string) error

	// InheritInstallations preserves existing installation scopes for an asset.
	// Called when no scope flags are provided (e.g., `sx add ./skill --yes`).
	// For server-managed vaults (Sleuth), this is a no-op since the server
	// auto-inherits installations when a new version is uploaded.
	// For file-based vaults (Path, Git), this copies scopes from any existing
	// version of the asset in the lock file.
	InheritInstallations(ctx context.Context, asset *lockfile.Asset) error

	// GetVersionList retrieves available versions for an asset (for resolution)
	// Only applicable to repositories with version management (Sleuth, not Git)
	GetVersionList(ctx context.Context, name string) ([]string, error)

	// GetMetadata retrieves metadata for a specific asset version
	GetMetadata(ctx context.Context, name, version string) (*metadata.Metadata, error)

	// GetAssetByVersion downloads an asset by name and version
	// Used for comparing content when adding assets
	GetAssetByVersion(ctx context.Context, name, version string) ([]byte, error)

	// VerifyIntegrity checks hashes and sizes for downloaded assets
	VerifyIntegrity(data []byte, hashes map[string]string, size int64) error

	// PostUsageStats sends asset usage statistics to the repository
	// jsonlData is newline-separated JSON (JSONL format)
	PostUsageStats(ctx context.Context, jsonlData string) error

	// RemoveAsset removes an asset from the lock file.
	// If delete is true, also permanently removes the asset files from the vault.
	// If version is empty, removes all versions of the asset.
	RemoveAsset(ctx context.Context, assetName, version string, delete bool) error

	// RenameAsset renames an asset in the vault.
	// All versions and installations are preserved under the new name.
	RenameAsset(ctx context.Context, oldName, newName string) error

	// ListAssets returns a list of all assets in the vault
	// This enables asset discovery via `sx vault list`
	ListAssets(ctx context.Context, opts ListAssetsOptions) (*ListAssetsResult, error)

	// GetAssetDetails returns detailed information about a specific asset
	// This enables asset inspection via `sx vault show <name>`
	GetAssetDetails(ctx context.Context, name string) (*AssetDetails, error)

	// GetMCPTools returns additional MCP tools provided by this vault
	// Returns nil if the vault doesn't provide any MCP tools
	GetMCPTools() any

	// GetBootstrapOptions returns bootstrap options provided by this vault
	// These are options for MCP servers or other infrastructure the vault provides
	GetBootstrapOptions(ctx context.Context) []bootstrap.Option
}

Vault represents a source of assets with read and write capabilities This interface unifies the concepts of "vault" and "source fetcher"

func NewFromConfig 

func NewFromConfig(cfg Config) (Vault, error)

NewFromConfig creates a vault instance from configuration This factory function eliminates repetitive switch statements across commands

Source Files

View all Source files

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.