---

name: dotfiles-installer-dev description: Development guide for the dotfiles-installer project. Use when working with package managers (brew, apt, dnf), implementing interfaces, using the commander/logger/filesystem utilities, handling privilege escalation, or understanding the codebase architecture. Covers project structure, key interfaces, configuration files, and development commands. For general Go coding conventions and testing patterns, use the go-dev skill.

Dotfiles Installer Development

Development guide for the dotfiles-installer Go codebase.

Project Structure

Copyinstaller/
├── main.go                    # Entry point (version injection)
├── cmd/                       # CLI commands (Cobra)
│   ├── root.go               # Root command, global setup
│   ├── install.go            # Main installation workflow
│   ├── checkCompatibility.go # Compatibility check command
│   └── version.go            # Version display
├── lib/                       # Core business logic
│   ├── compatibility/        # OS/distro detection
│   ├── pkgmanager/          # Package manager interface
│   ├── brew/                # Homebrew implementation
│   ├── apt/                 # APT implementation
│   ├── dnf/                 # DNF implementation
│   ├── gpg/                 # GPG key management
│   ├── shell/               # Shell installation
│   ├── dotfilesmanager/     # Chezmoi integration
│   └── packageresolver/     # Package name resolution
├── utils/                     # Shared utilities
│   ├── logger/              # Logging with progress display
│   ├── osmanager/           # OS operations interface
│   ├── privilege/           # Sudo/doas escalation
│   ├── commander.go         # Command execution
│   ├── filesystem.go        # File operations
│   └── httpclient/          # HTTP client interface
├── cli/                       # Interactive UI components
├── internal/config/           # Embedded YAML configs
├── Taskfile.yml              # Task runner commands
└── .goreleaser.yaml          # Release configuration

Key Interfaces

Commander (utils/commander.go)

Execute system commands with functional options:

Copyresult, err := commander.RunCommand(ctx, "brew", []string{"install", pkg},
    WithCaptureOutput(),
    WithEnv(env),
    WithTimeout(5 * time.Minute),
)

Available options: WithEnv(), WithDir(), WithInput(), WithCaptureOutput(), WithDiscardOutput(), WithInteractive(), WithTimeout(), WithStdout(), WithStderr()

Logger (utils/logger/)

Logging with progress tracking:

Copylogger.StartProgress("Installing packages")
logger.UpdateProgress("Installing git")
logger.FinishProgress()
// or
logger.FailProgress(err)

Methods: Trace, Debug, Info, Success, Warning, Error

FileSystem (utils/filesystem.go)

File operations interface for testability:

Copyexists, err := fs.PathExists(path)
data, err := fs.ReadFile(path)
err = fs.WriteFile(path, data, 0644)
err = fs.CreateDirectory(path)

OsManager (utils/osmanager/)

OS-level operations (user management, environment, program queries, permissions).

Privilege Escalator (utils/privilege/)

Smart privilege escalation (prefers sudo, falls back to doas):

CopyescalatedCmd, escalatedArgs, err := escalator.EscalateCommand("apt-get", []string{"install", "git"})
isRoot := escalator.IsRunningAsRoot()

Development Commands

Adding Features

New Package Manager

1. Create package in lib/{managername}/
2. Implement PackageManager interface (see lib/pkgmanager/pkgmanager.go)
3. Add installer interface if installation needed
4. Add unit and integration tests
5. Update internal/config/packagemap.yaml for package name mappings

New Utility Interface

1. Define interface in utils/
2. Create implementation with constructor
3. Generate mock: run mockery in project root
4. Inject via constructors where needed

New CLI Command

1. Create file in cmd/
2. Define cobra.Command with flags
3. Register in root.go init()
4. Implement run logic using injected dependencies

Configuration Files

compatibility.yaml (internal/config/)

Defines supported OS/distros, architectures, and prerequisites:

Copysupported_os:
  darwin:
    name: macOS
    distros:
      - name: macOS
        architectures: [amd64, arm64]
        prerequisites: [git, curl]

packagemap.yaml (internal/config/)

Maps generic package codes to manager-specific names:

Copypackages:
  git:
    brew: git
    apt: git
    dnf: git
  neovim:
    brew: neovim
    apt: neovim
    dnf: neovim