Documentation
¶
Overview ¶
Package gitrepo runs the installed `git` executable on behalf of skill imports.
Every invocation uses an argument array (never a shell command string), disables interactive prompting, and works inside a caller-owned temporary directory so an import can never mutate the consuming project's repository. The user's existing Git authentication and identity remain authoritative: Agent Layer neither reads nor stores credentials. Protocol, hook, template, and publication-signing settings are narrowed at the execution boundary.
Index ¶
- Variables
- func IsCommitID(value string) bool
- type CommandError
- type Destination
- func (d *Destination) DefaultBranch(ctx context.Context) (string, error)
- func (d *Destination) FetchCommit(ctx context.Context, repository Repository, commit string) error
- func (d *Destination) Head(ctx context.Context, branch string) (commit string, exists bool, err error)
- func (d *Destination) IsAncestor(ctx context.Context, ancestor string, descendant string) (bool, error)
- func (d *Destination) Publish(ctx context.Context, base string, branch string, updates []Update, ...) (string, error)
- func (d *Destination) ReadTree(ctx context.Context, commit string, repoPath string) (skilltree.Tree, error)
- func (d *Destination) Repository() string
- type Repository
- type Resolution
- type Runner
- type Secrets
- type Source
- func (s *Source) DefaultBranch(ctx context.Context) (string, error)
- func (s *Source) Fetch(ctx context.Context, commit string) error
- func (s *Source) ListDirectories(ctx context.Context, commit string) ([]string, error)
- func (s *Source) PathExists(ctx context.Context, commit string, repoPath string) (exists bool, isDir bool, err error)
- func (s *Source) ReadTree(ctx context.Context, commit string, repoPath string) (skilltree.Tree, error)
- func (s *Source) Repository() string
- func (s *Source) Resolve(ctx context.Context, ref string) (Resolution, error)
- type Update
Constants ¶
This section is empty.
Variables ¶
ErrCommitUnavailable means the repository was reachable but did not provide the requested commit. Callers may safely distinguish this from transport, authentication, server, and local object-database failures.
ErrGitUnavailable reports that no usable `git` executable is on PATH.
Functions ¶
func IsCommitID ¶
IsCommitID reports whether value is a full object id rather than a symbolic ref name.
Types ¶
type CommandError ¶
CommandError carries the captured stderr of a failed git invocation so the caller can report an actionable message.
Its Args and Stderr are already redacted: a repository URL is an ordinary command argument, and git echoes it back in most of its own diagnostics, so both are passed through the runner's Secrets before being stored.
func (*CommandError) Error ¶
func (e *CommandError) Error() string
Error renders the failing git command with its captured diagnostics.
func (*CommandError) Unwrap ¶
func (e *CommandError) Unwrap() error
Unwrap exposes the underlying execution error.
type Destination ¶
type Destination struct {
// contains filtered or unexported fields
}
Destination is an isolated working repository used to publish one grouped upstream contribution. It can fetch the destination base and any locked source commits needed for reconciliation without checking out either tree.
func OpenDestination ¶
func OpenDestination(ctx context.Context, runner *Runner, workDir string, repository Repository) (*Destination, error)
OpenDestination initializes an isolated working repository under workDir for the destination repository.
func (*Destination) DefaultBranch ¶
func (d *Destination) DefaultBranch(ctx context.Context) (string, error)
DefaultBranch resolves the destination repository's default branch name.
func (*Destination) FetchCommit ¶
func (d *Destination) FetchCommit(ctx context.Context, repository Repository, commit string) error
FetchCommit makes a commit from repository available in the destination working repository.
func (*Destination) Head ¶
func (d *Destination) Head(ctx context.Context, branch string) (commit string, exists bool, err error)
Head returns the destination branch's current commit. It reports exists = false when the branch does not exist yet, which `branch` write policy handles by creating it from the destination's default-branch commit.
func (*Destination) IsAncestor ¶ added in v0.16.2
func (d *Destination) IsAncestor(ctx context.Context, ancestor string, descendant string) (bool, error)
IsAncestor reports whether ancestor is reachable from descendant. Both commits must already be available in the destination repository.
func (*Destination) Publish ¶
func (d *Destination) Publish(ctx context.Context, base string, branch string, updates []Update, message string) (string, error)
Publish loads base into Git's index, replaces each update's path with exact blobs, creates a commit through Git's object database, and pushes it to branch without force. It never checks out remote-controlled content.
It returns the pushed commit. Publish never rewrites history and never falls back to another branch or repository.
func (*Destination) ReadTree ¶
func (d *Destination) ReadTree(ctx context.Context, commit string, repoPath string) (skilltree.Tree, error)
ReadTree returns the content of a repository path at a commit that is already available in the destination working repository.
func (*Destination) Repository ¶
func (d *Destination) Repository() string
Repository returns the configured destination repository reference, with any placeholder text intact.
type Repository ¶
type Repository struct {
// contains filtered or unexported fields
}
Repository is one repository reference in both of the forms Agent Layer needs: the configured text, which stays canonical everywhere it is recorded or displayed, and the resolved value, which only a Git command ever sees.
Its String method returns the display form, so a repository formatted into any message is safe by construction rather than by remembering to pick a field.
func (Repository) IsZero ¶
func (r Repository) IsZero() bool
IsZero reports whether the repository was never resolved.
func (Repository) String ¶
func (r Repository) String() string
String returns the configured text, with any `${AL_*}` placeholder intact.
type Resolution ¶
type Resolution struct {
// Ref is the resolved ref name: a branch name, a tag name, or the object id
// when the configured ref was an object id.
Ref string
// Kind is the ref kind proven by resolution, never guessed.
Kind string
// Commit is the resolved commit object id.
Commit string
}
Resolution is remote-resolved evidence about one configured ref.
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner invokes git with a fixed non-interactive environment.
func NewRunner ¶
NewRunner locates git and returns a runner whose repository references resolve from env, an AL_-filtered `.agent-layer/.env` map.
func (*Runner) MergeText ¶
MergeText performs a deterministic three-way text merge using git's own merge-file implementation, so Agent Layer does not maintain a second, subtly different diff3.
func (*Runner) Secrets ¶
Secrets returns the runner's resolution and redaction boundary. Every repository reference a caller hands to this runner must be resolved through it, so the resolved value is known to the redactor.
func (*Runner) TextMerger ¶
func (r *Runner) TextMerger(ctx context.Context) skilltree.TextMerger
TextMerger adapts MergeText to the skilltree merge contract.
type Secrets ¶
type Secrets struct {
// contains filtered or unexported fields
}
Secrets is the single boundary at which a configured repository reference becomes a value a Git command can use, and the single place that keeps the resolved value from coming back out.
Placeholders resolve from the AL_-filtered `.agent-layer/.env` map. Every value substituted is remembered so it can be replaced with the placeholder that named it in any command arguments or Git diagnostics rendered to the user. Redaction is therefore driven by what was actually resolved, not by a guess about which strings look secret.
func NewSecrets ¶
NewSecrets returns a resolver over an AL_-filtered environment map.
func (*Secrets) Redact ¶
Redact replaces every value this resolver substituted with the placeholder that named it, so a rendered Git argument or diagnostic shows `https://${AL_TOKEN}@host/repo.git` rather than the credential.
Longer values are replaced first so a secret that contains another secret cannot be left partly exposed by an earlier substitution.
func (*Secrets) Resolve ¶
func (s *Secrets) Resolve(reference string) (Repository, error)
Resolve turns a configured repository reference into a Repository.
A reference with no placeholder resolves to itself. A referenced value that is missing or empty fails with an actionable message naming the variables and the file they belong in, rather than handing Git a half-substituted URL.
type Source ¶
type Source struct {
// contains filtered or unexported fields
}
Source is an isolated local mirror of one remote repository. It lives inside a caller-owned temporary directory and is discarded with it.
func OpenSource ¶
func OpenSource(ctx context.Context, runner *Runner, workDir string, repository Repository) (*Source, error)
OpenSource initializes an isolated repository for repository under workDir. Nothing is fetched until a resolution or read requires it.
func (*Source) DefaultBranch ¶
DefaultBranch resolves the repository's actual default branch name.
func (*Source) ListDirectories ¶
ListDirectories returns every directory path at a commit, sorted, so wildcard selectors can be expanded without checking out a working tree.
func (*Source) PathExists ¶
func (s *Source) PathExists(ctx context.Context, commit string, repoPath string) (exists bool, isDir bool, err error)
PathExists reports whether a repository path exists at a commit and whether it is a directory.
func (*Source) ReadTree ¶
func (s *Source) ReadTree(ctx context.Context, commit string, repoPath string) (skilltree.Tree, error)
ReadTree returns the exact content of a repository path at a commit.
The returned tree carries the same canonical shape as a local skill tree: slash-normalized relative paths, exact bytes, and the executable bit. A gitlink (submodule) or symlink entry is rejected without being followed.
A path that does not exist at the commit yields an empty tree rather than an error: that is the correct merge input when a destination branch does not carry a skill yet. Callers that require the path to exist compare the result against recorded state, which an empty tree can never match.
func (*Source) Repository ¶
Repository returns the configured source repository reference, with any placeholder text intact.
func (*Source) Resolve ¶
Resolve determines what a configured ref names and which commit it points at.
An empty ref resolves to the repository's default branch. A full object id resolves to a commit. Every other value must exist as exactly one of a branch or a tag; an ambiguous name is an actionable error rather than a silent preference.
Source Files