Documentation
¶
Overview ¶
Package active manages the project active-skill layer: the per-skill entry at .agents/skills/<name> that links into the content store and is the single source of truth every agent target derives from.
The three layers gskill maintains are:
.gskill/store/<algo>/<hash> immutable canonical content (one physical copy)
▲ symlink (copy fallback)
.agents/skills/<name> active project skill (one per installed skill)
▲ symlink (copy fallback)
.<agent>/skills/<name> per-agent targets (claude, codex, cursor, …)
The active layer holds no independent copy of the content: it links into the store, so adding an agent is one cheap link and a skill shared by N agents still exists exactly once on disk. The active layer is gitignored and regenerated by `gskill project sync` from the committed manifest + lockfile.
Index ¶
- func Dir(root string) string
- func EnsureActive(root, name, src string, opts EnsureOptions) (string, error)
- func List(root string) ([]string, error)
- func Owned(dest string, roots []string, acceptHashes ...string) bool
- func Path(root, name string) string
- func Rel(name string) string
- func Remove(root, name string, acceptHashes ...string) error
- type EnsureOptions
- type Health
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EnsureActive ¶
func EnsureActive(root, name, src string, opts EnsureOptions) (string, error)
EnsureActive makes .agents/skills/<name> a real directory whose content is copied from src and verified against opts.ExpectedHash (spec 022: the repo owns skill content; the entry is committed, never a link into a store). It is idempotent — an entry already matching ExpectedHash is left untouched — and atomic: the copy is staged as a temporary sibling, verified, then swapped in, so the project never observes a half-written skill. It NEVER destroys content gskill does not own: foreign symlinks and unrecognized directories fail closed and are left intact.
func List ¶
List returns the names of active entries (directories and symlinks) under root. Plain files are skipped: they are never gskill-managed.
func Owned ¶ added in v0.3.0
Owned reports whether dest is gskill-managed content: a symlink resolving under any of the given roots (the repo's .agents/skills root; agent links resolve there), or a real directory whose content hash matches one of acceptHashes (the active entry itself, or a copy-mode install). A missing dest is not owned. This is the single ownership predicate shared by the installer's overwrite guard and the plan layer's conflict detection, so the two cannot drift (spec 011 FR-016).
func Remove ¶
Remove deletes a gskill-managed active entry for name: a symlink (a legacy or stale managed link), or a real directory whose content matches one of acceptHashes (the lock-recorded content). It is a no-op when the entry is absent, and it never deletes content it cannot prove gskill installed — a drifted or foreign directory is left intact.
Types ¶
type EnsureOptions ¶ added in v0.7.0
type EnsureOptions struct {
// ExpectedHash is the content hash the entry must match after the call
// (the lock's recorded hash for the incoming content). Required.
ExpectedHash string
// AcceptHashes are additional gskill-owned content hashes (e.g. the
// previously locked version): an existing directory matching one of them
// is replaced rather than treated as foreign.
AcceptHashes []string
// Replace allows replacing a real directory that matches neither
// ExpectedHash nor AcceptHashes. Reconcile paths (install/sync/repair,
// --force) set it; guarded add paths leave it false so drifted or foreign
// content fails closed.
Replace bool
// LegacyRoots are store roots from the pre-022 layout: a symlink entry
// resolving under one of them is a stale managed link and is replaced by
// the real copy. Symlinks resolving anywhere else are foreign.
LegacyRoots []string
}
EnsureOptions parameterizes EnsureActive.
type Health ¶
type Health string
Health classifies the state of an active entry in the repo-owned model (spec 022): the entry is a real committed directory, and its identity is its content hash against the lock.
const ( // HealthOK means the entry is a real directory whose content hash matches // the expected (lock-recorded) hash. HealthOK Health = "ok" // HealthMissing means no entry exists. HealthMissing Health = "missing" // HealthDrifted means the entry is a real directory whose content no // longer matches the expected hash (hand-edited committed content). HealthDrifted Health = "drifted" // HealthLegacy means the entry is a symlink into a known legacy store // root (the pre-022 layout); migration converts it on the next mutating // command. HealthLegacy Health = "legacy" // HealthForeign means something gskill does not own occupies the entry: // a symlink resolving elsewhere, or a plain file. HealthForeign Health = "foreign" )
Active-entry health states.
Source Files