skillsync

type Action ¶

type Action string

const (
	Added     Action = "added"
	Updated   Action = "updated"
	Unchanged Action = "unchanged"
	Removed   Action = "removed"
	Conflict  Action = "conflict"
)

type Bundle ¶

type Bundle struct {
	Plugin          PluginIdentity
	Source          Source
	FS              fs.FS
	ExecutablePaths []string
}

Bundle is an immutable source snapshot. Source is its sole provenance and version authority. ExecutablePaths preserves the executable bits that embed.FS cannot represent.

func EmbeddedBundle(d BundleDescriptor, content fs.FS) (Bundle, error)

type BundleDescriptor ¶

type BundleDescriptor struct {
	Plugin          PluginIdentity `json:"plugin"`
	Source          Source         `json:"source"`
	ExecutablePaths []string       `json:"executable_paths,omitempty"`
}

BundleDescriptor is serializable build metadata. EmbeddedBundle is the common loader for go:embed snapshots, so hosts need not duplicate fs.Sub, source-provenance validation, or digest checks.

type Change ¶

type Change struct {
	Plugin  PluginIdentity `json:"plugin"`
	Name    string         `json:"name"`
	Action  Action         `json:"action"`
	Outcome Outcome        `json:"outcome,omitempty"`
	Reason  string         `json:"reason,omitempty"`
}

type Compatibility ¶

type Compatibility struct {
	MinCLI string `json:"min_cli,omitempty"`
	MaxCLI string `json:"max_cli,omitempty"`
}

Compatibility limits the CLI versions a bundle can be installed by. Empty bounds are open; values use numeric dot-separated versions, optionally with a leading "v". Pre-release selection is intentionally host policy.

type Config ¶

type Config struct {
	CLI            Identity
	CurrentVersion string
	Bundles        []Bundle
}

Config declares the installed CLI and its offline matched snapshots. A development build may use an undetermined CurrentVersion only when its embedded matched bundles declare no compatibility bounds; it never selects a newer release by default.

type Identity ¶

type Identity struct {
	Publisher string `json:"publisher"`
	Name      string `json:"name"`
}

Identity identifies the CLI that supplied a bundle. It is recorded as provenance only; plugin ownership always uses PluginIdentity.

func (i Identity) String() string

type LegacyImport ¶

type LegacyImport struct {
	MarkerFile string
	Plugin     PluginIdentity
}

LegacyImport enables only a host's explicit one-time marker migration. MarkerFile is relative to the target directory and Plugin is the identity that will own matching, verified legacy skills.

type Options ¶

type Options struct {
	Dir                   string
	DryRun                bool
	PreferNewerCompatible bool
	Resolver              Resolver
	LockTimeout           time.Duration
	Legacy                LegacyImport
}

Options supplies a target and controls whether Sync changes it. Resolver is reserved for explicit newer-compatible bundle selection; normal sync never calls it and therefore never requires network access.

type Outcome ¶

type Outcome string

Outcome tells callers whether a planned mutation reached durable ownership. Conflict and unchanged entries deliberately have no mutation outcome.

const (
	Planned    Outcome = "planned"
	Applied    Outcome = "applied"
	Restored   Outcome = "restored"
	Incomplete Outcome = "incomplete"
)

type PluginIdentity ¶

type PluginIdentity struct {
	Publisher string `json:"publisher"`
	Name      string `json:"name"`
}

PluginIdentity is globally stable and deliberately separate from a skill directory name, which avoids flat-directory collisions between products.

A plugin identity is also Sync's independent-install and removal boundary: one Sync call computes desired state, including removals, only within the plugin keys present in that call's Config.Bundles, and only from skills that plugin key already owns. Two skills sharing one PluginIdentity are therefore installed and removed together — Sync-ing one of them alone drops the other, because it is no longer "desired" under that shared key. A caller that wants each skill installable and removable on its own (for example a CLI offering per-skill consent, one `install <skill>` call per bundle) MUST give each such skill its own PluginIdentity. Skills owned by a different plugin key, or never registered with skillsync at all, are never touched by a Sync call that does not name their key.

func (p PluginIdentity) String() string

type Prepared ¶

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

Prepared is one validated, immutable source selection. A host that syncs multiple harnesses prepares it once, then uses Sync for every target so an explicit newer-compatible resolver cannot select different releases midway through a command.

func Prepare(ctx context.Context, cfg Config, opts Options) (Prepared, error)

func (p Prepared) Sync(ctx context.Context, opts Options) (Report, error)

type ReleaseResolver ¶

type ReleaseResolver struct {
	Source         ReleaseSource
	CurrentVersion string
}

ReleaseResolver is the standard explicit newer-compatible adapter. Put it in Options.Resolver at CLI wiring time; ordinary sync does not invoke it.

func (r ReleaseResolver) Resolve(ctx context.Context, matched Bundle) (Bundle, error)

type ReleaseSource ¶

type ReleaseSource interface {
	NewerCompatible(context.Context, Source, string) (BundleDescriptor, fs.FS, error)
}

ReleaseSource retrieves one newer source snapshot chosen against a CLI version. Implementations may read a signed release archive or a local cache; the shared resolver still validates its immutable descriptor and content digest before it reaches Sync.

type Report ¶

type Report struct {
	Dir        string           `json:"dir"`
	CLI        Identity         `json:"cli"`
	CLIVersion string           `json:"cli_version"`
	DryRun     bool             `json:"dry_run"`
	Bundles    []ResolvedBundle `json:"bundles"`
	Changes    []Change         `json:"changes"`
}

func Sync(ctx context.Context, cfg Config, opts Options) (Report, error)

func (r Report) Changed() bool

func (r Report) ChangesFor(a Action, outcomes ...Outcome) []Change

func (r Report) Names(a Action) []string

func (r Report) NamesFor(a Action, outcomes ...Outcome) []string

type ResolvedBundle ¶

type ResolvedBundle struct {
	Plugin          PluginIdentity `json:"plugin"`
	Source          Source         `json:"source"`
	PriorCLIVersion string         `json:"prior_cli_version,omitempty"`
}

type Resolver ¶

type Resolver interface {
	Resolve(context.Context, Bundle) (Bundle, error)
}

Resolver resolves an explicitly requested newer compatible bundle. It must return a complete, digest-pinned Bundle; Sync verifies it before planning.

type Skill ¶

type Skill struct{ Name, Digest string }

Skill is one valid skill directory in a bundle.

func Discover(source fs.FS) ([]Skill, error)

type Source ¶

type Source struct {
	Repository    string        `json:"repository"`
	Path          string        `json:"path"`
	Revision      string        `json:"revision"`
	Version       string        `json:"version"`
	Digest        string        `json:"digest"`
	Compatibility Compatibility `json:"compatibility,omitempty"`
}

Source is reproducible bundle provenance. Repository, Path, Revision, and Digest identify exact bytes; Version names the plugin release for people and plugin hosts. It is persisted with ownership state for diagnostics.

type Status ¶

type Status struct {
	Installed           bool                         `json:"installed"`
	Plugins             map[string]Source            `json:"plugins"`
	SupplierCLIVersions map[string]map[string]string `json:"supplier_cli_versions,omitempty"`
}

Status is the marker-only query hosts use for drift banners; it never walks installed skill trees or contacts a release source.

func ReadStatus(dir string) (Status, error)