repo

package
v0.4.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 28, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package repo handles JVS repository initialization and discovery.

Index

Constants

View Source 
const (
	// FormatVersion is the current repository format version.
	FormatVersion = 1
	// JVSDirName is the name of the JVS metadata directory.
	JVSDirName = ".jvs"
	// FormatVersionFile is the name of the file storing the format version.
	FormatVersionFile = "format_version"
	// RepoIDFile is the name of the file storing the repository ID.
	RepoIDFile = "repo_id"
)

Variables

This section is empty.

Functions

func DescriptorsDirPath 

func DescriptorsDirPath(repoRoot string) (string, error)

DescriptorsDirPath returns the descriptors control directory after validating it.

func GCDirPath 

func GCDirPath(repoRoot string) (string, error)

GCDirPath returns the GC control directory after validating it.

func GCPinPathForRead 

func GCPinPathForRead(repoRoot, pinFileName string) (string, error)

GCPinPathForRead returns an existing documented GC pin path after rejecting a symlink or wrong-type final leaf.

func GCPinsDirPath 

func GCPinsDirPath(repoRoot string) (string, error)

GCPinsDirPath returns the documented GC pins control directory after validating it.

func GCPlanPath 

func GCPlanPath(repoRoot, planID string) (string, error)

GCPlanPath returns the path for a GC plan ID after rejecting path-like names.

func GCPlanPathForDelete 

func GCPlanPathForDelete(repoRoot, planID string) (string, error)

GCPlanPathForDelete returns a GC plan path after rejecting a symlink or wrong-type existing final leaf. Missing leaves are allowed.

func GCPlanPathForRead 

func GCPlanPathForRead(repoRoot, planID string) (string, error)

GCPlanPathForRead returns an existing GC plan path after rejecting a symlink or wrong-type final leaf.

func GCPlanPathForWrite 

func GCPlanPathForWrite(repoRoot, planID string) (string, error)

GCPlanPathForWrite returns a GC plan path after rejecting a symlink or wrong-type existing final leaf. Missing leaves are allowed.

func GCTombstonePath 

func GCTombstonePath(repoRoot string, snapshotID model.SnapshotID) (string, error)

GCTombstonePath returns the tombstone path for a canonical snapshot ID.

func GCTombstonePathForDelete 

func GCTombstonePathForDelete(repoRoot string, snapshotID model.SnapshotID) (string, error)

GCTombstonePathForDelete returns a tombstone path after rejecting a symlink or wrong-type existing final leaf. Missing leaves are allowed.

func GCTombstonePathForRead 

func GCTombstonePathForRead(repoRoot string, snapshotID model.SnapshotID) (string, error)

GCTombstonePathForRead returns an existing tombstone path after rejecting a symlink or wrong-type final leaf.

func GCTombstonePathForWrite 

func GCTombstonePathForWrite(repoRoot string, snapshotID model.SnapshotID) (string, error)

GCTombstonePathForWrite returns a tombstone path after rejecting a symlink or wrong-type existing final leaf. Missing leaves are allowed.

func GCTombstonesDirPath 

func GCTombstonesDirPath(repoRoot string) (string, error)

GCTombstonesDirPath returns the tombstones control directory after validating it.

func IntentPath 

func IntentPath(repoRoot string, snapshotID model.SnapshotID) (string, error)

IntentPath returns the intent record path for a canonical snapshot ID.

func IntentsDirPath 

func IntentsDirPath(repoRoot string) (string, error)

IntentsDirPath returns the intents control directory after validating it.

func LegacyPinPathForRead 

func LegacyPinPathForRead(repoRoot, pinFileName string) (string, error)

LegacyPinPathForRead returns an existing legacy pin path after rejecting a symlink or wrong-type final leaf.

func LegacyPinsDirPath 

func LegacyPinsDirPath(repoRoot string) (string, error)

LegacyPinsDirPath returns the legacy pins control directory after validating it.

func LoadWorktreeConfig 

func LoadWorktreeConfig(repoRoot, name string) (*model.WorktreeConfig, error)

LoadWorktreeConfig loads a worktree config.

func RecoveryPlanPath 

func RecoveryPlanPath(repoRoot, planID string) (string, error)

RecoveryPlanPath returns the path for a recovery plan ID after rejecting path-like names.

func RecoveryPlanPathForRead 

func RecoveryPlanPathForRead(repoRoot, planID string) (string, error)

RecoveryPlanPathForRead returns an existing recovery plan path after rejecting a symlink or wrong-type final leaf.

func RecoveryPlanPathForWrite 

func RecoveryPlanPathForWrite(repoRoot, planID string) (string, error)

RecoveryPlanPathForWrite returns a recovery plan path after rejecting a symlink or wrong-type existing final leaf. Missing leaves are allowed.

func RecoveryPlansDirPath 

func RecoveryPlansDirPath(repoRoot string) (string, error)

RecoveryPlansDirPath returns the recovery plan control directory after validating it.

func RestorePlanPath 

func RestorePlanPath(repoRoot, planID string) (string, error)

RestorePlanPath returns the path for a restore operation plan ID after rejecting path-like names.

func RestorePlanPathForRead 

func RestorePlanPathForRead(repoRoot, planID string) (string, error)

RestorePlanPathForRead returns an existing restore plan path after rejecting a symlink or wrong-type final leaf.

func RestorePlanPathForWrite 

func RestorePlanPathForWrite(repoRoot, planID string) (string, error)

RestorePlanPathForWrite returns a restore plan path after rejecting a symlink or wrong-type existing final leaf. Missing leaves are allowed.

func SnapshotDescriptorPath 

func SnapshotDescriptorPath(repoRoot string, snapshotID model.SnapshotID) (string, error)

SnapshotDescriptorPath returns the descriptor path for a canonical snapshot ID.

func SnapshotDescriptorPathForDelete 

func SnapshotDescriptorPathForDelete(repoRoot string, snapshotID model.SnapshotID) (string, error)

SnapshotDescriptorPathForDelete returns a descriptor path after rejecting a symlink or wrong-type existing final leaf. Missing leaves are allowed.

func SnapshotDescriptorPathForRead 

func SnapshotDescriptorPathForRead(repoRoot string, snapshotID model.SnapshotID) (string, error)

SnapshotDescriptorPathForRead returns an existing descriptor path after rejecting a symlink or wrong-type final leaf.

func SnapshotDescriptorPathForWrite 

func SnapshotDescriptorPathForWrite(repoRoot string, snapshotID model.SnapshotID) (string, error)

SnapshotDescriptorPathForWrite returns a descriptor path after rejecting a symlink or wrong-type existing final leaf. Missing leaves are allowed.

func SnapshotPath 

func SnapshotPath(repoRoot string, snapshotID model.SnapshotID) (string, error)

SnapshotPath returns the on-disk snapshot storage path for a canonical ID.

func SnapshotPathForDelete 

func SnapshotPathForDelete(repoRoot string, snapshotID model.SnapshotID) (string, error)

SnapshotPathForDelete returns a snapshot directory path after rejecting a symlink or wrong-type final leaf. Missing leaves are allowed for idempotent delete/retry paths.

func SnapshotPathForRead 

func SnapshotPathForRead(repoRoot string, snapshotID model.SnapshotID) (string, error)

SnapshotPathForRead returns an existing snapshot directory path after rejecting a symlink or wrong-type final leaf.

func SnapshotTmpPath 

func SnapshotTmpPath(repoRoot string, snapshotID model.SnapshotID) (string, error)

SnapshotTmpPath returns the unpublished temporary snapshot path for a canonical ID.

func SnapshotsDirPath 

func SnapshotsDirPath(repoRoot string) (string, error)

SnapshotsDirPath returns the snapshots control directory after validating it.

func ValidateInitTarget 

func ValidateInitTarget(path string) (string, error)

ValidateInitTarget returns the absolute target path after enforcing the repository creation rules: the target must be missing or empty, must not already contain .jvs metadata, and must not be lexically or physically nested inside a JVS repo.

func ValidateManagedPayloadOnly 

func ValidateManagedPayloadOnly(boundary WorktreePayloadBoundary, payloadRoot string) error

ValidateManagedPayloadOnly verifies that a materialized payload source does not contain root-level control data excluded from the managed workspace.

func ValidateWorktreeRealPathForRepair 

func ValidateWorktreeRealPathForRepair(repoRoot, name, realPath string) (string, error)

ValidateWorktreeRealPathForRepair validates a replacement real path and returns the canonical physical path that should be stored.

func ValidateWorktreeRealPathRegistry 

func ValidateWorktreeRealPathRegistry(repoRoot string) error

ValidateWorktreeRealPathRegistry verifies that registered workspace payload roots do not overlap each other or point into repository control data.

func WithMutationLock 

func WithMutationLock(repoRoot, operation string, fn func() error) error

WithMutationLock acquires the repository mutation lock, runs fn, and always releases the lock before returning.

func WorktreeConfigDirPath 

func WorktreeConfigDirPath(repoRoot, name string) (string, error)

WorktreeConfigDirPath returns the metadata directory for a worktree.

func WorktreeConfigPath 

func WorktreeConfigPath(repoRoot, name string) (string, error)

WorktreeConfigPath returns the path to a worktree's config.json.

func WorktreePayloadPath 

func WorktreePayloadPath(repoRoot, name string) (string, error)

WorktreePayloadPath returns the payload directory for a worktree.

func WorktreesDirPath 

func WorktreesDirPath(repoRoot string) (string, error)

WorktreesDirPath returns the worktrees control directory after validating it.

func WriteWorktreeConfig 

func WriteWorktreeConfig(repoRoot, name string, cfg *model.WorktreeConfig) error

WriteWorktreeConfig atomically writes a worktree config.

Types

type MutationLock 

type MutationLock struct {
	// contains filtered or unexported fields
}

MutationLock is a no-wait repository-wide lock for metadata/payload mutations. It is implemented with atomic mkdir so contenders fail immediately with E_REPO_BUSY instead of blocking.

func AcquireMutationLock 

func AcquireMutationLock(repoRoot, operation string) (*MutationLock, error)

AcquireMutationLock attempts to acquire the repository mutation lock without waiting. Call Release when the mutation is complete.

func (*MutationLock) Release 

func (l *MutationLock) Release() error

Release releases the mutation lock. It is safe to call more than once.

type MutationLockInspection 

type MutationLockInspection struct {
	Path         string
	OwnerPath    string
	Owner        *MutationLockOwner
	Status       MutationLockStatus
	SafeToRemove bool
	Reason       string
}

MutationLockInspection is a fail-closed view of the repository mutation lock.

func InspectMutationLock 

func InspectMutationLock(repoRoot string) (MutationLockInspection, error)

InspectMutationLock returns a non-mutating, fail-closed view of repo.lock.

func RemoveStaleMutationLock 

func RemoveStaleMutationLock(repoRoot string) (MutationLockInspection, bool, error)

RemoveStaleMutationLock removes repo.lock only when inspection proves the owner is on this host, the process is gone, and the lock is old enough.

type MutationLockOwner 

type MutationLockOwner struct {
	Operation string    `json:"operation"`
	PID       int       `json:"pid"`
	Hostname  string    `json:"hostname,omitempty"`
	CreatedAt time.Time `json:"created_at"`
}

MutationLockOwner is the process identity written by the lock holder.

type MutationLockStatus 

type MutationLockStatus string

MutationLockStatus describes the observed state of the repository mutation lock. 

const (
	MutationLockAbsent  MutationLockStatus = "absent"
	MutationLockHeld    MutationLockStatus = "held"
	MutationLockStale   MutationLockStatus = "stale"
	MutationLockInvalid MutationLockStatus = "invalid"
)

type Repo 

type Repo struct {
	Root          string
	FormatVersion int
	RepoID        string
}

Repo represents an initialized JVS repository.

func Discover 

func Discover(cwd string) (*Repo, error)

Discover walks up from cwd to find the repo root (directory containing .jvs/).

func DiscoverWorktree 

func DiscoverWorktree(cwd string) (*Repo, string, error)

DiscoverWorktree discovers the repo and maps cwd to a worktree name.

func Init 

func Init(path string, name string) (*Repo, error)

Init creates a new JVS repository at the specified path.

func InitAdoptedWorkspace 

func InitAdoptedWorkspace(folder string) (*Repo, error)

InitAdoptedWorkspace initializes JVS control data inside an existing folder and registers that folder itself as the main workspace payload.

func InitTarget 

func InitTarget(path string) (*Repo, error)

InitTarget creates a new repository at an absolute or relative target path.

type WorktreePayloadBoundary 

type WorktreePayloadBoundary struct {
	Root              string
	ExcludedRootNames []string
}

WorktreePayloadBoundary describes the managed portion of a worktree payload.

func WorktreeManagedPayloadBoundary 

func WorktreeManagedPayloadBoundary(repoRoot, name string) (WorktreePayloadBoundary, error)

WorktreeManagedPayloadBoundary returns the managed payload root and any root-level control paths that must be excluded from captures.

func (WorktreePayloadBoundary) ExcludesRelativePath 

func (b WorktreePayloadBoundary) ExcludesRelativePath(rel string) bool

ExcludesRelativePath reports whether rel is outside the managed payload because it is reserved for repository control data.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.