Documentation
¶
Overview ¶
Package registry implements the client side of the rysh agent registry (design 005): install .md agents / loops / recipes / humanoids into a project's .rysh/ tree, reproducibly (lockfile) and with install-time consent (declared tools / channels / env are shown before anything is written).
Format is open, service is private (npm model). This package is the open client. The manifest is `rysh.pkg.yaml` (YAML for consistency with the rest of rysh's config; the design's TOML sketch is translated to YAML here).
Index ¶
- Constants
- func AbsoluteURL(indexURL, artifactURL string) string
- func InstallName(pkgName string) string
- func IsNamespaced(spec string) bool
- func RenderIndexHTML(idx *Index) ([]byte, error)
- func Sha256Hex(data []byte) string
- func SplitSpec(spec string) (name, version string, err error)
- func TypeDir(t string) (string, error)
- type Index
- type IndexPackage
- type IndexVersion
- type Lock
- type LockEntry
- type Manifest
- func InstallFromDir(srcDir, ryshDir string, opts Options) (*Manifest, []string, error)
- func InstallFromIndex(artifactURL, expectedChecksum, ryshDir string, opts Options) (*Manifest, []string, error)
- func InstallFromTarball(src, ryshDir string, opts Options) (*Manifest, []string, error)
- func ParseManifest(data []byte) (*Manifest, error)
- type Options
- type SearchResult
- type UpdateCandidate
Constants ¶
const DefaultIndexURL = "https://packages.rysh.ai/registry/index.json"
DefaultIndexURL is where the first-party index lives. Overridable via config (`registry.url`) or RYSH_REGISTRY_URL so a company can host its own.
const IndexSchemaVersion = 1
IndexSchemaVersion is the format this client speaks.
const LockFile = "rysh.lock"
LockFile is the reproducibility lockfile, written under .rysh/.
const ManifestFile = "rysh.pkg.yaml"
ManifestFile is the per-package manifest name.
Variables ¶
This section is empty.
Functions ¶
func AbsoluteURL ¶
AbsoluteURL resolves a possibly-relative artifact URL against the index URL, so a whole registry can be relocated by moving the directory.
func InstallName ¶
InstallName is the on-disk directory name for a (possibly namespaced) package name: "@rysh/code-reviewer" → "code-reviewer".
func IsNamespaced ¶
IsNamespaced reports whether spec looks like `@ns/name[@version]` rather than a path or URL.
func RenderIndexHTML ¶
RenderIndexHTML renders the browsable landing page for an index.
Types ¶
type Index ¶
type Index struct {
// SchemaVersion lets a future format change be rejected loudly by an old
// client instead of being silently mis-parsed.
SchemaVersion int `json:"schema_version"`
Generated string `json:"generated,omitempty"`
Packages map[string]IndexPackage `json:"packages"`
}
Index is the published catalogue. Versions are keyed by exact semver string; resolution picks the highest by numeric comparison, so "0.10.0" > "0.9.0" rather than sorting lexically.
func FetchIndex ¶
FetchIndex retrieves and validates the index document.
func (*Index) Outdated ¶
func (idx *Index) Outdated(l *Lock) []UpdateCandidate
Outdated compares the lockfile against the index and returns the installed packages the index publishes a strictly newer version of, sorted by name. Only namespaced installs participate: a package installed from a local dir or ad-hoc tarball has no index identity to update from.
func (*Index) Resolve ¶
func (idx *Index) Resolve(spec string) (name, version string, v IndexVersion, err error)
Resolve maps `@ns/name[@version]` to a concrete artifact. An empty version selects the highest published one.
func (*Index) Search ¶
func (idx *Index) Search(query string) []SearchResult
Search returns the packages whose name or description contains query (case-insensitive; empty query matches everything), sorted by name, each with its highest published version.
type IndexPackage ¶
type IndexPackage struct {
Description string `json:"description,omitempty"`
Type string `json:"type,omitempty"` // agent|loop|recipe|humanoid
Versions map[string]IndexVersion `json:"versions"`
}
IndexPackage is one named package and its published versions.
type IndexVersion ¶
type IndexVersion struct {
// URL is the tarball. Relative values resolve against the index URL, so a
// mirror can be moved wholesale without rewriting every entry.
URL string `json:"url"`
// Checksum is sha256:… over the tarball bytes. Verified before the archive
// is opened — see ResolveSpec's caller.
Checksum string `json:"checksum"`
}
IndexVersion points at one artifact.
type Lock ¶
Lock is the .rysh/rysh.lock document (name → entry).
func (*Lock) InstalledNames ¶
InstalledNames returns the sorted set of installed package names.
type LockEntry ¶
type LockEntry struct {
Version string `yaml:"version"`
Type string `yaml:"type"`
Checksum string `yaml:"checksum"`
Path string `yaml:"path"`
Installed string `yaml:"installed"`
}
LockEntry records an installed package for reproducibility.
type Manifest ¶
type Manifest struct {
Name string `yaml:"name"` // e.g. "@rysh/code-reviewer"
Version string `yaml:"version"` // semver
Type string `yaml:"type"` // agent|loop|recipe|humanoid
Description string `yaml:"description"` // one-liner for search/index page
Entry string `yaml:"entry"` // primary file, e.g. "SKILL.md"
MinRysh string `yaml:"min_rysh"` // minimum rysh version
Checksum string `yaml:"checksum"` // sha256:... over Entry
DeclaresTools []string `yaml:"declares_tools"` // tools the skill uses
DeclaresChannels []string `yaml:"declares_channels"` // humanoid channels
DeclaresEnv []string `yaml:"declares_env"` // ${ENV} vars referenced
Signature string `yaml:"signature"` // detached sig (verified namespaces)
}
Manifest describes a package (open spec).
func InstallFromDir ¶
InstallFromDir installs the package rooted at srcDir into ryshDir, returning the manifest and any warnings. It verifies the entry checksum, refuses a sensitive/unsigned package unless Force, and updates the lockfile.
func InstallFromIndex ¶
func InstallFromIndex(artifactURL, expectedChecksum, ryshDir string, opts Options) (*Manifest, []string, error)
InstallFromIndex downloads an indexed artifact, verifies its digest, and only then unpacks it.
The ordering is the point. InstallFromTarball streams the response straight into extractTarGz, so by the time anything could be checked the archive has already been written to disk. For a registry install the index checksum is the only thing standing between "a name" and "code in ~/.rysh", so the bytes are buffered, hashed, compared, and discarded on mismatch — nothing is extracted from an artifact that failed verification.
A missing checksum in the index is refused rather than warned about: an unverifiable artifact from a name-based install is exactly the case where a warning would be clicked through.
func InstallFromTarball ¶
InstallFromTarball downloads/opens a .tar.gz (URL or local path), extracts it to a temp dir, and installs it. The archive must contain the manifest at its root (or in a single top-level directory).
func ParseManifest ¶
ParseManifest parses and validates a manifest.
func (*Manifest) ConsentSummary ¶
ConsentSummary renders the declared capabilities for an install-time prompt.
func (*Manifest) Sensitive ¶
Sensitive reports whether a package requests high-trust capabilities that warrant explicit confirmation: it wants to commit code or read secrets.
The Signature field deliberately does NOT downgrade this. Nothing in rysh verifies signatures yet, so treating a non-empty signature string as "trusted tier" let any attacker-authored manifest skip the consent gate by writing an arbitrary value — a malicious package got a weaker check than an honest one. Until signature verification exists (design 005 G3), every package is graded on its declared capabilities alone.
type Options ¶
type Options struct {
Yes bool // proceed past the consent prompt non-interactively
Force bool // proceed despite sensitive/unsigned/checksum warnings
}
Options controls an install.
type SearchResult ¶
SearchResult is one `rysh search` hit.
type UpdateCandidate ¶
type UpdateCandidate struct {
Name string
Installed string
Latest string
Artifact IndexVersion
}
UpdateCandidate is one installed package with a newer published version.
Source Files