Documentation
¶
Overview ¶
Package integrity provides canonical content hashing, fail-closed verification, and drift classification for installed skills.
Index ¶
- Constants
- func CompatHash(dir string) (string, error)
- func HashContent(data []byte) string
- func OverrideDigest(root string, spec OverrideSpec) (string, error)
- func ValidateContent(dir string) ([]string, error)
- func VerifyDir(dir, expected string) (ok bool, actual string, err error)
- type DriftStatus
- type Hashes
- type OverrideSpec
- type SkillState
Constants ¶
const SkillFileName = "SKILL.md"
SkillFileName is the canonical skill manifest filename.
Variables ¶
This section is empty.
Functions ¶
func CompatHash ¶ added in v0.3.0
CompatHash computes the skills-lock.json "computedHash" for a skill directory using the same rules as the external lock producer (the vercel-labs/skills CLI, src/local-lock.ts computeSkillFolderHash):
- collect regular files recursively; directories named ".git" or "node_modules" are skipped at any depth
- symlinks are neither followed nor hashed; empty directories contribute nothing; file modes are ignored
- file bytes are hashed verbatim (no line-ending normalization)
- files sort by relative forward-slash path using locale-aware collation (JavaScript localeCompare)
- sha256 over the concatenation of each file's path then content, hex encoded with no prefix
Parity is pinned by TestCompatHashParity against hashes recorded from the reference implementation (testdata/compat). This is deliberately distinct from HashDir, gskill's own canonical hash, which stays in the namespaced gskill.storeHash field.
func HashContent ¶
HashContent returns the canonical hash of a single file's content, applying LF normalization to text. The result is prefixed with "sha256:".
func OverrideDigest ¶ added in v0.7.0
func OverrideDigest(root string, spec OverrideSpec) (string, error)
OverrideDigest computes the canonical identity of an override declaration: SHA-256 over the declaration itself plus the content hash of every file it references (spec 023 FR-007, research R5).
This is the Nix idea the feature rests on — output identity is a function of input identity. Including the referenced files' bytes is what makes drift detection mechanical (FR-010): editing house-rules.md changes an input hash, so the digest changes, with no file watching and no special cases.
Determinism rules (Constitution I): kinds are visited in fixed pipeline order; declared list order is preserved because patches and layers apply in sequence, so that order is data; the Replace map is visited in sorted key order, because map iteration order is ambient environment and must never reach output. An empty declaration has no identity and digests to "".
func ValidateContent ¶ added in v0.4.0
ValidateContent scans a skill directory before it is staged or admitted to a store. It rejects symlinks that escape the skill directory (path-traversal / unsafe symlinks, FR-042) and returns warnings for executable-bit files, which gskill never runs (FR-043). Content is never executed.
Types ¶
type DriftStatus ¶
type DriftStatus string
DriftStatus classifies the state of an installed skill relative to the manifest, lockfile, and on-disk content, as surfaced by check and verify (FR-016).
const ( DriftInstalled DriftStatus = "installed" DriftMissing DriftStatus = "missing" DriftModified DriftStatus = "modified" DriftOutdated DriftStatus = "outdated" DriftOrphaned DriftStatus = "orphaned" DriftPartiallyInstalled DriftStatus = "partially-installed" DriftChecksumMismatch DriftStatus = "checksum-mismatch" )
Drift statuses (FR-016).
func Classify ¶
func Classify(s SkillState) DriftStatus
Classify maps a SkillState to a DriftStatus (FR-016, FR-017). The checks are ordered from most to least severe so the first matching condition wins.
func (DriftStatus) Clean ¶
func (s DriftStatus) Clean() bool
Clean reports whether s represents an in-sync installation needing no action.
func (DriftStatus) Valid ¶
func (s DriftStatus) Valid() bool
Valid reports whether s is a recognized drift status.
type Hashes ¶
type Hashes struct {
// ContentHash is the canonical recursive hash of the skill directory.
ContentHash string
// SkillFileHash is the hash of SKILL.md alone.
SkillFileHash string
}
Hashes holds the canonical content identity of an installed skill (FR-014).
type OverrideSpec ¶ added in v0.7.0
type OverrideSpec struct {
Replace map[string]string
Patch []string
Prepend []string
Append []string
}
OverrideSpec is a resolved override declaration, expressed with repo-relative paths. It mirrors the manifest and lockfile shapes without importing either, so the digest stays a leaf computation.
func (OverrideSpec) Empty ¶ added in v0.7.0
func (s OverrideSpec) Empty() bool
Empty reports whether the spec transforms nothing.
type SkillState ¶
type SkillState struct {
InLock bool
SourceAvailable bool
ContentMismatch bool // installed content hash != locked hash (set only by content checks)
TargetsTotal int
TargetsPresent int
}
SkillState is the observed lock and filesystem state of one skill, used to classify its drift without coupling this package to the lock types.
Source Files