cli copilot-instructions.md

Copilot Instructions for Entire CLI

Repository Overview

Entire CLI is a Go CLI tool that captures AI coding agent sessions (Claude Code, Gemini CLI, OpenCode, Cursor, Factory AI Droid, Copilot CLI, etc.) as searchable metadata stored separately from code commits. It uses a strategy pattern for session/checkpoint management with minimal impact on commit history.

Tech Stack: Go (version in mise.toml), Cobra (CLI), charmbracelet/huh (interactive prompts), go-git/v5 (with caveats)

Build & Validation Commands

All commands use mise as the task runner. Always run these in order before committing:

mise run fmt           # Format with gofmt (required - CI will fail otherwise)
mise run lint          # Lint with golangci-lint (only new issues)
mise run test          # Unit tests
mise run test:ci       # Full tests with race detection (same as CI)

CI runs these checks on every PR (see .github/workflows/):

1. gofmt formatting check (must pass - no unformatted files)
2. golangci-lint
3. go.mod tidy check
4. All tests with race detection (mise run test:ci)

Critical Code Patterns

Error Handling

The CLI uses SilentError to avoid duplicate error output (see errors.go):

// When you print a custom error message, return SilentError
fmt.Fprintln(cmd.ErrOrStderr(), "User-friendly error message")
return NewSilentError(errors.New("internal error"))

// For normal errors, just return them - main.go will print
return fmt.Errorf("failed to do X: %w", err)

Forbidden go-git Operations

NEVER use go-git v5's Reset or Checkout directly - they delete .gitignored directories.

// WRONG - deletes .entire/ and .worktrees/
worktree.Reset(&git.ResetOptions{Mode: git.HardReset, Commit: hash})
worktree.Checkout(&git.CheckoutOptions{Branch: ref})

// CORRECT - use CLI wrappers from strategy/common.go and git_operations.go
HardResetWithProtection(hash)
CheckoutBranch(branch)

Path Handling

NEVER use os.Getwd() for git-relative paths - breaks when running from subdirectories.