kandev/apps/backend/internal/worktree/worktree.go

package worktree

import "time"

// SyncProgressStatus represents the status of a base-branch sync progress event.
type SyncProgressStatus string

const (
	SyncProgressRunning   SyncProgressStatus = "running"
	SyncProgressCompleted SyncProgressStatus = "completed"
)

// SyncProgressEvent reports pre-worktree base-branch synchronization progress.
type SyncProgressEvent struct {
	StepName string
	Status   SyncProgressStatus
	Output   string
	Error    string
}

// SyncProgressCallback is called when base-branch sync status changes.
type SyncProgressCallback func(event SyncProgressEvent)

// Worktree represents a Git worktree associated with a task.
type Worktree struct {
	// ID is the unique identifier for this worktree record.
	ID string `json:"id"`

	// SessionID is the task session associated with this worktree.
	SessionID string `json:"session_id,omitempty"`

	// TaskID is the ID of the task this worktree is associated with.
	// Multiple worktrees can exist for the same task (one per agent session).
	TaskID string `json:"task_id"`

	// RepositoryID is the ID of the repository this worktree belongs to.
	RepositoryID string `json:"repository_id"`

	// RepositoryPath is the local filesystem path to the main repository.
	// Stored for recreation if the worktree directory is lost.
	RepositoryPath string `json:"repository_path"`

	// Path is the absolute filesystem path to the worktree directory.
	Path string `json:"path"`

	// Branch is the Git branch name checked out in this worktree.
	Branch string `json:"branch"`

	// BaseBranch is the branch this worktree was created from.
	BaseBranch string `json:"base_branch"`

	// Status indicates the current state of the worktree.
	// Valid values: active, merged, deleted
	Status string `json:"status"`

	// CreatedAt is when this worktree was created.
	CreatedAt time.Time `json:"created_at"`

	// UpdatedAt is when this worktree was last modified.
	UpdatedAt time.Time `json:"updated_at"`

	// MergedAt is when this worktree's branch was merged (if applicable).
	MergedAt *time.Time `json:"merged_at,omitempty"`

	// DeletedAt is when this worktree was deleted (if applicable).
	DeletedAt *time.Time `json:"deleted_at,omitempty"`
}

// CreateRequest contains the parameters for creating a new worktree.
type CreateRequest struct {
	// TaskID is the unique task identifier (required).
	TaskID string

	// SessionID is the task session identifier (required for persistence).
	SessionID string

	// TaskTitle is the human-readable task title (optional).
	// If provided, it will be used to generate semantic worktree/branch names.
	// The title is sanitized and truncated to 20 characters.
	TaskTitle string

	// RepositoryID is the repository identifier (required).
	RepositoryID string

	// RepositoryPath is the local path to the main repository (required).
	RepositoryPath string

	// BaseBranch is the branch to base the worktree on (required).
	// Typically "main" or "master".
	BaseBranch string

	// CheckoutBranch is a branch to fetch from origin and checkout after worktree creation.
	// Used for PR reviews where the worktree is created from the default branch, then
	// the PR's head branch is fetched and checked out. Empty means no post-creation checkout.
	CheckoutBranch string

	// WorktreeBranchPrefix is the prefix to use for the worktree branch name.
	// If empty, the default prefix is used.
	WorktreeBranchPrefix string

	// PullBeforeWorktree indicates whether to pull from remote before creating the worktree.
	PullBeforeWorktree bool

	// WorktreeID is the ID of an existing worktree to reuse (optional).
	// If provided and valid, the existing worktree is returned instead of creating a new one.
	WorktreeID string

	// OnSyncProgress receives progress updates for pre-worktree branch sync.
	OnSyncProgress SyncProgressCallback
}

// Validate validates the create request.
func (r *CreateRequest) Validate() error {
	if r.TaskID == "" {
		return ErrWorktreeNotFound
	}
	if r.RepositoryPath == "" {
		return ErrRepoNotGit
	}
	if r.BaseBranch == "" {
		return ErrInvalidBaseBranch
	}
	return nil
}

// MergeRequest contains the parameters for merging a worktree's branch.
type MergeRequest struct {
	// TaskID identifies the worktree to merge.
	TaskID string

	// Method is the merge method: "merge", "squash", or "rebase".
	Method string

	// CleanupAfter indicates whether to delete the worktree after merging.
	CleanupAfter bool
}

// StatusActive is the status for an active, usable worktree.
const StatusActive = "active"

// StatusMerged is the status for a worktree whose branch has been merged.
const StatusMerged = "merged"

// StatusDeleted is the status for a deleted worktree.
const StatusDeleted = "deleted"