vcs

type Access ¶

type Access struct {
	Mounts []string
}

Access describes additional resources needed to operate on version control. Mounts are writable directories mounted at their host paths in containers. A workspace with no repository metadata returns nil from VCS.

type CommitSpec ¶

type CommitSpec struct {
	// Tree is the tree the commit records: a revision the provider
	// resolves to a tree, recorded as its id.
	Tree string
	// FollowsPrevious makes the commit created before it in the same
	// request its first parent, ahead of Parents. A linear history is a
	// first commit with its base in Parents and every later one following
	// the previous.
	FollowsPrevious bool
	// Parents are revisions the provider resolves to commits, recorded as
	// their ids. A first commit with none, and FollowsPrevious unset, is a
	// root commit.
	Parents []string
	// Message is the commit message, written as given: no cleanup, no
	// trailer added.
	Message string
}

CommitSpec is one commit of a signing.

type Directory ¶

type Directory string

Directory is a caller-owned directory with no VCS resources.

func (d Directory) Directory() string

func (d Directory) VCS() *Access

type Provider ¶

type Provider interface {
	Acquire(context.Context, Request) (Workspace, error)
	Release(context.Context, Workspace) error
	Prune(context.Context) error
}

Provider owns workspace creation, release and recovery. Release must receive the workspace returned by Acquire. Callers release on errors and cancellation using a non-cancelled context; providers apply their retention policy there. Prune recovers stale provider metadata after an interrupted process.

type Replay ¶

type Replay struct {
	// InProgress is whether the replay stopped on a conflict and waits for
	// Continue or Abort.
	InProgress bool
	// Candidate is the replayed Head, once the replay has finished; empty
	// while it is in progress.
	Candidate string
	// Conflicts are the paths, relative to the workspace and sorted, that
	// conflict in the revision the replay stopped on.
	Conflicts []string
	// Commits are the replayed revisions in order, each original beside the
	// revision it became; Replayed is empty for one not replayed yet.
	Commits []ReplayedCommit
	// Request is what was replayed, each revision resolved to its id.
	Request ReplayRequest
}

Replay is the state of one replay.

type ReplayRequest ¶

type ReplayRequest struct {
	OldBase string
	Head    string
	Onto    string
}

ReplayRequest names the revisions of a replay: the ones reachable from Head and not from OldBase, oldest first, are replayed onto Onto. OldBase is the boundary the caller chose, typically the revision a dependent branch was started from, and must be an ancestor of Head. A merge-base is not used: when the parent of a dependent branch was integrated as a squash, the merge-base with the new upstream lies below the parent's commits, and replaying from it would bring them back. A range holding a merge is refused. Each value is a revision the provider resolves.

type ReplayedCommit ¶

type ReplayedCommit struct {
	Original string
	Replayed string
}

ReplayedCommit is one revision of a replay.

type Replayer ¶

type Replayer interface {
	// Replay replays req in the workspace. It returns a finished replay with
	// its candidate, or one in progress with the paths that conflict. A
	// workspace with a replay in progress is refused with
	// ErrReplayInProgress.
	Replay(ctx context.Context, ws Workspace, req ReplayRequest) (Replay, error)
	// ReplayStatus reports the replay in progress in the workspace; a
	// Replay whose InProgress is false when there is none.
	ReplayStatus(ctx context.Context, ws Workspace) (Replay, error)
	// Continue takes the caller's resolution of the files in the workspace
	// and goes on with the replay, until it finishes or stops on the next
	// conflict. A conflict the caller has not resolved is refused with an
	// error wrapping ErrUnresolved, returned with the replay as it stands.
	// With no replay in progress it returns ErrNoReplay.
	Continue(ctx context.Context, ws Workspace) (Replay, error)
	// Abort drops the replay in progress and what it created, and returns
	// the workspace to where it was before Replay. With no replay in
	// progress it returns ErrNoReplay.
	Abort(ctx context.Context, ws Workspace) error
}

Replayer is an optional capability of a Provider: it replays a range of revisions onto another revision in a workspace the caller retains, and leaves every branch where it is. vcs/git and vcs/jj implement it over a workspace directory. A caller finds it by type assertion:

if r, ok := provider.(vcs.Replayer); ok { ... }

A replay creates a candidate and nothing else. Moving a branch to the candidate, with the caller's compare-and-swap, and publishing it are the caller's. A replay runs in the caller's process with the caller's VCS access: it is not a session and grants a session nothing.

A replay that stops on a conflict stays in progress in the workspace, its state recorded in the workspace's VCS metadata, until Continue finishes it or Abort drops it. A process that restarts picks it up with ReplayStatus and Continue.

type Request ¶

type Request struct {
	Name   string
	Ref    string
	Branch string
}

Request selects a workspace. Ref and Branch are opaque to agentcore: the provider interprets them. An empty Branch asks for a workspace without a writable branch.

type SignRequest ¶

type SignRequest struct {
	// ID identifies the operation, so that a process that restarts can
	// find it again. It is letters, digits, '-' and '_', 128 at most,
	// starting with a letter or digit.
	ID string
	// Commits are created in order.
	Commits []CommitSpec
}

SignRequest is one signing: commits created in order, each from a tree and with parents and a message the caller gives.

type Signer ¶

type Signer interface {
	// Sign creates the commits of req, signed, or returns the ones a
	// signing under req.ID created before. A request whose ID was used for
	// a different request is refused with ErrSigningMismatch.
	Sign(ctx context.Context, ws Workspace, req SignRequest) (Signing, error)
	// SignStatus reports what the signing with the ID has created. With no
	// signing recorded under it, it returns ErrNoSigning.
	SignStatus(ctx context.Context, ws Workspace, id string) (Signing, error)
	// Forget drops the record of the signing with the ID and the refs that
	// keep its commits, once the caller is done with them. The commits are
	// left to garbage collection unless something else refers to them.
	// With no signing recorded under it, it returns ErrNoSigning.
	Forget(ctx context.Context, ws Workspace, id string) error
}

Signer constructs signed commits from trees the caller has already reviewed, with parents and messages the caller gives explicitly, using the repository's own identity, signing key and signing format. It runs in the caller's process with the caller's VCS access and credentials: it is not a session, and it grants a session nothing, so a session that produced the trees never holds the signing key. vcs/git implements it for any git store, the one a Jujutsu repository shares included.

A signing moves no branch and writes no file of a working tree. Each commit it creates is kept reachable under a ref of its own, outside the branches, until Forget, and what it has created is recorded in the repository as it goes, under the request's ID. A process interrupted part way reads the record with SignStatus, or calls Sign again with the same request, which picks it up and signs only what is missing; a finished signing returned again is the same commits, signed once. Pushing the result and moving branches to it are the caller's.

A commit is never created unsigned: when signing fails, Sign fails.

type Signing ¶

type Signing struct {
	// Request is the signing as recorded, its trees and parents resolved
	// to ids.
	Request SignRequest
	// Commits are the signed commits created so far, in the order of
	// Request.Commits.
	Commits []string
	// Finished is whether every commit of the request has been created;
	// Head is then the last one.
	Finished bool
	Head     string
}

Signing is what a signing has created.

type Workspace ¶

type Workspace interface {
	Directory() string
	VCS() *Access
}

Workspace is the directory a session runs in and its optional VCS resources. Providing resources does not grant access: the session profile must allow it. The caller owns the workspace lifetime, which may span several sessions.