skillimport

package
v0.17.5 Latest Latest
Warning

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

 Go to latest Published: Aug 27, 2026 License: MIT Imports: 18 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

This section is empty.

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
}

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

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
}

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 (*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) 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) 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
}

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.