packs

Documentation

Overview

Package packs provides shared git-workflow operations for installable entities (plugins, skills) that can be sourced from git repos or local paths.

Index

• func CleanSubpaths(subpaths []string) ([]string, error)
• func CopySource(w io.Writer, source, targetDir, name, subpath, kind string) (string, error)
• func DeriveName(source string, subpaths []string, prefix string) string
• func DiscoveryRoots(targetDir string, subpaths []string) []string
• func WriteCloneOrigin(w io.Writer, targetDir, source, ref, commit string, subpaths []string)
• type CloneResult
  • func CloneSource(w io.Writer, source, targetDir, name, ref string, subpaths []string, ...) (CloneResult, error)
• type PullResult
  • func PullUpdate(w io.Writer, originDir string, origin gitutil.Origin, label string) (PullResult, error)

Functions

func CleanSubpaths

func CleanSubpaths(subpaths []string) ([]string, error)

CleanSubpaths validates and normalizes --subpath flag values. Returns an error if any path is absolute or contains ".." components.

func CopySource

func CopySource(w io.Writer, source, targetDir, name, subpath, kind string) (string, error)

CopySource copies a local directory to targetDir/name, handling subpath scoping. Returns the absolute path of the created target directory.

Note: callers that need to validate the source BEFORE copying (e.g., skill frontmatter validation) should scope the source by subpath themselves and pass the scoped path. The subpath parameter here handles the copy-time scoping — if the caller already scoped, the redundant scoping is harmless (same result path).

func DeriveName

func DeriveName(source string, subpaths []string, prefix string) string

DeriveName determines the install directory name from subpaths or source URL. Single subpath: uses the subpath's last segment (e.g., "plugins/injectors" → "injectors"). Multiple subpaths or none: derives from the source URL via gitutil.DeriveName.

func DiscoveryRoots

func DiscoveryRoots(targetDir string, subpaths []string) []string

DiscoveryRoots returns the discovery root paths for the given subpaths within a target directory. If no subpaths are set, returns the target directory itself.

func WriteCloneOrigin

func WriteCloneOrigin(w io.Writer, targetDir, source, ref, commit string, subpaths []string)

WriteCloneOrigin writes the .origin.yaml sidecar for a freshly cloned source. Prints a warning on failure but does not return an error — the install succeeded, the origin is metadata.

Types

type CloneResult

type CloneResult struct {
	TargetDir string // absolute path of the cloned directory
	Commit    string // HEAD commit after clone (may be empty on error)
}

CloneResult holds the outcome of a git clone operation.

func CloneSource

func CloneSource(
	w io.Writer,
	source, targetDir, name, ref string,
	subpaths []string,
	kind string,
) (CloneResult, error)

CloneSource clones a git repo into targetDir/name, validates subpaths exist within the clone, reads HEAD commit, and returns the result.

On clone or subpath failure, the target directory is cleaned up automatically. The caller is responsible for entity-specific validation after this returns. If entity validation fails, the caller should clean up via folder.New(result.TargetDir).Remove().

type PullResult

type PullResult struct {
	OldCommit string
	NewCommit string
	Changed   bool
}

PullResult holds the outcome of a git pull operation.

func PullUpdate

func PullUpdate(w io.Writer, originDir string, origin gitutil.Origin, label string) (PullResult, error)

PullUpdate pulls latest changes and returns the result.

Prints "Updating X from Y..." before pulling and "Already up to date (hash)" when unchanged. Does NOT write origin or print "Updated" — the caller must do that after any entity-specific post-pull validation (e.g., plugin vendoring/SDK checks). This prevents stale origin commits when post-pull validation fails.