Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
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).
var ErrNotInProjectPath = errors.New("not in a registered project path")
var ErrProjectExists = errors.New("project already exists")
var ErrProjectHandleNotInitialized = errors.New("project handle not initialized")
var ErrProjectNotFound = errors.New("project not found")
var ErrProjectNotRegistered = errors.New("project root is not registered")
var ErrWorktreeExists = errors.New("worktree already exists for branch")
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 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
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
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
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" )