Help us shape the future of Go! Take the 2026 Go Developer Survey

skillimport

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Oct 12, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package skillimport orchestrates Git-backed Agent Skill imports: selector resolution, desired-set reconciliation, atomic local state transactions, pull merges, grouped upstream pushes, and status reporting.

Every operation reads and mutates skill sources inside the shared project lock so ordinary projection can never observe a half-applied import.

Index

Constants

This section is empty.

Variables

View Source 
var ErrPendingRecovery = errors.New("skill import pending recovery")

ErrPendingRecovery prevents diagnostics from reading a transitional generation.

Functions

This section is empty.

Types

type AddOptions 

type AddOptions struct {
	Repository     string
	Selectors      []string
	Ref            string
	Tracking       string
	WritePolicy    string
	PushRepository string
	PushBranch     string
	Order          *int
	AdoptLegacy    bool
}

AddOptions carries the policy an `al skills add` invocation declares.

type CatalogMember added in v1.0.0 

type CatalogMember struct {
	Name         string
	Selector     string
	Imported     bool
	Legacy       bool
	Configured   bool
	DefaultExact bool
	// AddBlocked explains why an uncovered selector cannot be added by the wizard.
	AddBlocked string
	Problem    string
	// ForeignOwned distinguishes a valid configured import from another source.
	// It still blocks canonical catalog edits, but is not an ownership defect.
	ForeignOwned bool
}

CatalogMember describes offline evidence for one exact catalog path. Configured missing content remains the responsibility of ordinary import commands.

func CatalogState added in v1.0.0 

func CatalogState(root string, entry templates.CLISkillCatalogEntry) ([]CatalogMember, error)

CatalogState recovers interrupted imports under the project lock before reading local config, lock, and content for wizard edits. It never fetches. Missing config is allowed for install previews; malformed lock evidence is fatal.

func InspectCatalogState added in v1.0.0 

func InspectCatalogState(root string, entry templates.CLISkillCatalogEntry) ([]CatalogMember, error)

InspectCatalogState reads stable local evidence without fetching or recovering. Any staging node requires an explicit sync before diagnostic inspection.

type Condition 

type Condition string

Condition classifies one imported skill's local directory against its recorded upstream state. 

const (
	// ConditionClean means the local tree still matches the locked upstream hash.
	ConditionClean Condition = "clean"
	// ConditionModified means the local tree diverged from the locked hash.
	ConditionModified Condition = "modified"
	// ConditionMissing means the imported directory is absent.
	ConditionMissing Condition = "missing"
	// ConditionInvalid means the directory exists but is not a readable, valid
	// Agent Skill.
	ConditionInvalid Condition = "invalid"
	// ConditionCollided means a user-managed skill owns the same name.
	ConditionCollided Condition = "collided"
	// ConditionConflicted means an active Git conflict workspace still matches
	// the recorded lock and configuration.
	ConditionConflicted Condition = "conflicted"
)

type Outcome 

type Outcome string

Outcome names what happened to one skill in an operation. The set is closed so reports stay comparable across commands. 

const (
	// OutcomeImported reports a newly imported skill.
	OutcomeImported Outcome = "imported"
	// OutcomeUpdated reports a skill advanced to new upstream content.
	OutcomeUpdated Outcome = "updated"
	// OutcomeUnchanged reports a skill that already matched its target state.
	OutcomeUnchanged Outcome = "unchanged"
	// OutcomeRestored reports a missing imported directory rebuilt from source.
	OutcomeRestored Outcome = "restored"
	// OutcomeReset reports a skill whose local edits were discarded in favor of
	// the current configured upstream content.
	OutcomeReset Outcome = "reset"
	// OutcomeRetired reports a skill removed from the desired set and deleted.
	OutcomeRetired Outcome = "retired"
	// OutcomePruned reports a lock entry dropped because its directory was
	// already absent, including adoption into the user-managed tier.
	OutcomePruned Outcome = "pruned"
	// OutcomePushed reports a skill contributed upstream.
	OutcomePushed Outcome = "pushed"
	// OutcomeSkipped reports a skill excluded from the operation by policy.
	OutcomeSkipped Outcome = "skipped"
	// OutcomeFailed reports a skill-level failure that blocked only that skill.
	OutcomeFailed Outcome = "failed"
	// OutcomeResolved reports a conflicted pull or push completed from its workspace.
	OutcomeResolved Outcome = "resolved"
)

type Report 

type Report struct {
	Sources []SourceResult
	Skills  []SkillResult
	// ProjectionErr records a projection failure that happened after valid
	// source state was already committed. It never rolls that state back.
	ProjectionErr error
	// contains filtered or unexported fields
}

Report is the complete outcome of one import operation.

func (*Report) Add 

func (r *Report) Add(result SkillResult)

Add records a skill result, replacing any earlier result for the same skill. One operation can touch a skill in more than one stage (membership reconciliation then branch advancement); the report keeps exactly one final line per skill so identical state always renders identically.

A skill is identified by its repository and selected path, not by its name: two import blocks can resolve different paths to the same name, and that is precisely the case a report must show, because one of them succeeded and the other was rejected for colliding with it.

func (*Report) AddSourceFailure 

func (r *Report) AddSourceFailure(repository string, ref string, err error)

AddSourceFailure records a source-level failure.

func (*Report) Failed 

func (r *Report) Failed() bool

Failed reports whether any scoped unit of work failed.

func (*Report) Partial 

func (r *Report) Partial() bool

Partial reports whether the operation both completed and failed work, which callers surface differently from a total failure.

func (*Report) Render 

func (r *Report) Render(operation string) string

Render returns the deterministic human-readable operation report.

func (*Report) Sort 

func (r *Report) Sort()

Sort orders results deterministically so identical state always renders the same report.

func (*Report) Succeeded 

func (r *Report) Succeeded() int

Succeeded returns the number of skills whose work completed.

type Service 

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

Service performs skill import operations for one repository root.

func New 

func New(root string) *Service

New returns a service bound to a repository root.

func NewInstructions added in v1.0.0 

func NewInstructions(root string) *Service

NewInstructions uses the same lifecycle with regular Markdown file nodes.

func NewInstructionsSourceOnly added in v1.0.0 

func NewInstructionsSourceOnly(root string) *Service

NewInstructionsSourceOnly leaves final projection to the caller.

func NewSourceOnly added in v1.0.0 

func NewSourceOnly(root string) *Service

NewSourceOnly commits imports for a caller that owns the final project sync.

func (*Service) Add 

func (s *Service) Add(ctx context.Context, opts AddOptions) (*Report, error)

Add validates explicit selectors, creates or extends the one block with a matching policy, imports every newly desired skill, and projects the result.

The entire old-to-new desired-set transition is validated before any local state changes; configuration, imported skills, and lock state then commit together. A projection failure afterwards is reported without discarding that valid source state.

func (*Service) Diff added in v0.17.1 

func (s *Service) Diff(ctx context.Context, name string, from string, to string) ([]byte, error)

Diff compares two live sides of an imported skill and returns an ordinary Git unified diff. Identical trees produce no output.

func (*Service) InstallCatalog added in v1.0.0 

func (s *Service) InstallCatalog(ctx context.Context, selectors, approvedLegacy []string) (*Report, error)

InstallCatalog adds absent exact catalog selectors and, when approved, retires validated legacy slots together. It is intentionally restricted to the migration's default policy and declared catalog coordinates, not a collision bypass for ordinary Add.

func (*Service) Pull 

func (s *Service) Pull(ctx context.Context) (*Report, error)

Pull fetches every configured source, reconciles it with local state, commits each independently successful skill, and projects the results.

It is the only command that advances tracked imports. Pinned imports stay at their locked commits unless the configured ref itself changed.

func (*Service) Push 

func (s *Service) Push(ctx context.Context) (*Report, error)

Push performs the configured upstream writes. It never pulls first and never force-pushes.

func (*Service) Remove 

func (s *Service) Remove(ctx context.Context, repository string, selector string) (*Report, error)

Remove drops one configured positive or exclusion selector, keeps each existing entry on its own lock evidence, imports newly revealed membership at the current resolved target, and projects the result.

func (*Service) RemoveCatalogSelectors added in v1.0.0 

func (s *Service) RemoveCatalogSelectors(ctx context.Context, selectors []string) (*Report, error)

RemoveCatalogSelectors rechecks whole-block eligibility for wizard removals. The complete retirement set commits together; absent targets are no-ops.

func (*Service) Reset 

func (s *Service) Reset(ctx context.Context, name string) (*Report, error)

Reset permanently discards one imported skill's local edits and replaces it with the current configured upstream tree. It does not reconcile any other selector membership.

func (*Service) Resolve added in v0.17.1 

func (s *Service) Resolve(ctx context.Context, name string) (*Report, error)

Resolve applies the staged Git index of a skill conflict workspace.

func (*Service) Status 

func (s *Service) Status() (*Status, error)

Status reports local skill import state without contacting any remote.

type SkillResult 

type SkillResult struct {
	Name         string
	Repository   string
	SelectedPath string
	Outcome      Outcome
	// Detail carries operation-specific context such as a merge conflict list
	// or the destination a change was pushed to.
	Detail string
	Err    error
}

SkillResult is one skill's outcome.

type SourceResult 

type SourceResult struct {
	Repository string
	Ref        string
	Err        error
}

SourceResult is one import block's source-level outcome. A fetch, authentication, or ref failure blocks every skill in that block but leaves other sources unaffected.

type Status 

type Status struct {
	Entries    []StatusEntry
	Exclusions []StatusExclusion
	// MissingRefEvidence lists configured blocks with no locked ref-kind
	// evidence. Status never guesses a ref kind offline.
	MissingRefEvidence []string
	// contains filtered or unexported fields
}

Status is the complete local view of configured skill imports.

func (*Status) Render 

func (s *Status) Render(all bool) string

Render returns the default summary, or the expanded per-skill listing when all is true.

type StatusEntry 

type StatusEntry struct {
	Name         string
	Repository   string
	SelectedPath string
	// Ref is the recorded resolved ref, or the configured ref when no lock
	// evidence exists yet.
	Ref string
	// Tracking is the recorded tracking mode, empty when no lock evidence
	// exists yet.
	Tracking     string
	WritePolicy  string
	Condition    Condition
	WriteEnabled bool
	// Workspace is the conflict workspace path relative to the repository root
	// when Condition is conflicted.
	Workspace string
}

StatusEntry is one resolved skill's local, network-free status.

type StatusExclusion 

type StatusExclusion struct {
	Repository string
	Selector   string
}

StatusExclusion is one configured exclusion selector.

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.