project

package
v0.12.4 Latest Latest
Warning

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

Go to latest
Published: Jun 17, 2026 License: AGPL-3.0 Imports: 16 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrNotInProject = errors.New("current directory is not within a configured project root")

ErrNotInProject is returned when the current working directory is not within any registered project root. Callers branch on errors.Is(err, ErrNotInProject) to degrade gracefully (e.g. default to empty ignore patterns, disable walk-up).

View Source
var ErrNotInProjectPath = errors.New("not in a registered project path")
View Source
var ErrProjectExists = errors.New("project already exists")
View Source
var ErrProjectHandleNotInitialized = errors.New("project handle not initialized")
View Source
var ErrProjectNotFound = errors.New("project not found")
View Source
var ErrProjectNotRegistered = errors.New("project root is not registered")
View Source
var ErrWorktreeExists = errors.New("worktree already exists for branch")
View Source
var ErrWorktreeNotFound = errors.New("worktree not found")

Functions

This section is empty.

Types

type GitManagerFactory added in v0.2.0

type GitManagerFactory func(projectRoot string) (*git.GitManager, error)

GitManagerFactory creates a git.GitManager for the given project root. Production callers pass git.NewGitManager; tests pass a factory returning gittest.InMemoryGitManager.GitManager.

type Project added in v0.2.0

type Project interface {
	Name() string
	RepoPath() string
	Record() (ProjectRecord, error)
	// CreateWorktree creates a worktree for branch. When base is empty and branch
	// is not a local head, a uniquely-matching remote-tracking branch is used as
	// the base with upstream tracking configured (the dwim rule). noTrack
	// suppresses upstream tracking (parity with `git worktree add --no-track`).
	CreateWorktree(ctx context.Context, branch, base string, noTrack bool) (string, error)
	AddWorktree(ctx context.Context, branch, base string) (WorktreeState, error)
	RemoveWorktree(ctx context.Context, branch string, deleteBranch bool) error
	PruneStaleWorktrees(ctx context.Context, dryRun bool) (*PruneStaleResult, error)
	ListWorktrees(ctx context.Context) ([]WorktreeState, error)
	GetWorktree(ctx context.Context, branch string) (WorktreeState, error)
}

Project is the runtime behavior contract for a single registered project. The concrete implementation is package-private.

type ProjectEntry added in v0.11.0

type ProjectEntry struct {
	Name      string                   `yaml:"name" label:"Name" desc:"Project slug identifier"`
	Root      string                   `yaml:"root" label:"Root" desc:"Filesystem path to project root"`
	Worktrees map[string]WorktreeEntry `yaml:"worktrees,omitempty" label:"Worktrees" desc:"Active worktrees for this project"`
}

ProjectEntry represents a project in the registry.

type ProjectManager added in v0.2.0

type ProjectManager interface {
	Register(ctx context.Context, name string, repoPath string) (Project, error)
	Update(ctx context.Context, entry ProjectEntry) (Project, error)
	List(ctx context.Context) ([]ProjectEntry, error)
	ListProjects(ctx context.Context) ([]ProjectState, error)
	Remove(ctx context.Context, root string) error
	Get(ctx context.Context, root string) (Project, error)
	ResolvePath(ctx context.Context, cwd string) (Project, error)
	CurrentProject(ctx context.Context) (Project, error)
	ListWorktrees(ctx context.Context) ([]WorktreeState, error)
}

func NewProjectManager added in v0.2.0

func NewProjectManager(log *logger.Logger, gitFactory GitManagerFactory, nameOverride string, reg *Registry) (ProjectManager, error)

NewProjectManager builds a project manager over an injected Registry — the manager never constructs registry storage itself. nameOverride is the config-owned project name (clawker.yaml `name:`), resolved by the caller and passed as a primitive so this package never imports config. config resolves its own walk-up anchor from Registry.CurrentRoot, so the dependency runs one way — the manager reads config-derived values, config never reads the manager.

type ProjectRecord added in v0.2.0

type ProjectRecord struct {
	Name      string
	Root      string
	Worktrees map[string]WorktreeRecord
}

ProjectRecord is the persisted model for a registered project.

type ProjectRegistry added in v0.11.0

type ProjectRegistry struct {
	Projects []ProjectEntry `yaml:"projects" label:"Projects" desc:"Registered projects"`
}

ProjectRegistry is the on-disk structure for the project registry (consts.RegistryFile in the data dir). internal/project is its sole owner: the registry store, walk-up resolver, and all CRUD live here.

func (ProjectRegistry) Fields added in v0.11.0

func (r ProjectRegistry) Fields() storage.FieldSet

Fields implements storage.Schema for ProjectRegistry.

type ProjectState added in v0.4.0

type ProjectState struct {
	Name      string
	Root      string
	Worktrees []WorktreeState
	Status    ProjectStatus
	StatusErr error // non-nil when Status is ProjectInaccessible
}

ProjectState is a caller-facing enriched project view. Analogous to WorktreeState: combines registry data with runtime checks.

type ProjectStatus added in v0.4.0

type ProjectStatus string

ProjectStatus captures the health of a project's root directory.

const (
	ProjectOK           ProjectStatus = "ok"
	ProjectMissing      ProjectStatus = "missing"
	ProjectInaccessible ProjectStatus = "inaccessible"
)

type PruneStaleResult added in v0.2.0

type PruneStaleResult struct {
	Prunable []string
	Removed  []string
	Failed   map[string]error
	Locked   []string // worktrees skipped due to git worktree lock
}

type Registry added in v0.11.0

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

Registry is the project registry facade — the single owner of registry persistence (the registry file in the data dir) and project-root resolution. Construct one per process via NewRegistry and inject it; the CLI factory exposes it as f.ProjectRegistry. Nothing else constructs registry storage.

Registration/mutation methods are unexported: callers outside this package mutate registry state through ProjectManager only.

func NewRegistry added in v0.11.0

func NewRegistry(opts ...RegistryOption) (*Registry, error)

NewRegistry creates the project registry facade, reading the registry through the storage layer (merge + lock) — the canonical path for clawker files, never a raw file read.

func (*Registry) CurrentRoot added in v0.11.0

func (r *Registry) CurrentRoot() (string, error)

CurrentRoot resolves the project root for the current working directory. Returns ErrNotInProject (via ResolveRoot) when CWD is not within any registered project root, so callers can branch on errors.Is(err, ErrNotInProject) without masking real errors.

func (*Registry) ResolveRoot added in v0.11.0

func (r *Registry) ResolveRoot(cwd string) (string, error)

ResolveRoot reads the project registry and returns the deepest registered project root that is an ancestor of cwd. cwd is cleaned and symlink-normalized here, so callers may pass it as-is. Callers pass the result to config.NewConfig to bound project-config walk-up.

A missing or empty registry yields no match. cwd and each registered root are compared via resolveRootPath so a root registered through a symlink matches its real path (and vice versa). The returned root is always expressed in cwd's own path form — a string-ancestor of the cwd the caller navigates from — so it stays a valid walk-up anchor even when os.Getwd reports a logical, symlinked path (e.g. macOS /tmp). Returns ErrNotInProject when cwd is not within any registered project root, including when a depth-changing symlink leaves the logical cwd with no project ancestor in its own path form.

type RegistryOption added in v0.11.0

type RegistryOption func(*registryOptions)

RegistryOption configures NewRegistry.

func WithRegistryDir added in v0.11.0

func WithRegistryDir(dir string) RegistryOption

WithRegistryDir places the registry file in dir instead of the resolved data directory. Injection seam for tests; production callers use the default.

TODO: This variadic option exists only as a test seam, which violates testing.md gotcha #8 (no production params solely for mockability). Replace with a data-layer seed (cf. state.NewFromString, per store-backed-package.md) and drop this option.

type WorktreeEntry added in v0.11.0

type WorktreeEntry struct {
	Path   string `yaml:"path" label:"Path" desc:"Filesystem path to worktree"`
	Branch string `yaml:"branch,omitempty" label:"Branch" desc:"Git branch for this worktree"`
}

WorktreeEntry represents a worktree within a project.

type WorktreeRecord added in v0.2.0

type WorktreeRecord struct {
	Path   string
	Branch string
}

WorktreeRecord is the persisted model for a project worktree.

type WorktreeState added in v0.2.0

type WorktreeState struct {
	Project          string
	Branch           string
	Path             string
	Head             string
	IsDetached       bool
	ExistsInRegistry bool
	ExistsInGit      bool
	Status           WorktreeStatus
	IsLocked         bool  // worktree is locked against pruning (.git/worktrees/<slug>/locked exists)
	InspectError     error // non-nil indicates degraded health check (permissions, git errors)
}

WorktreeState is a caller-facing merged worktree view.

type WorktreeStatus added in v0.2.0

type WorktreeStatus string

WorktreeStatus captures the health/drift status of a worktree.

const (
	WorktreeHealthy            WorktreeStatus = "healthy"
	WorktreeRegistryOnly       WorktreeStatus = "registry_only"
	WorktreeGitOnly            WorktreeStatus = "git_only"
	WorktreeBroken             WorktreeStatus = "broken"
	WorktreeDotGitMissing      WorktreeStatus = "dotgit_missing"
	WorktreeGitMetadataMissing WorktreeStatus = "git_metadata_missing"
)

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL