declpac/openspec/changes/declpac-cli-tool/design.md

Context

Pacman, Arch Linux's package manager, lacks declarative package management and doesn't support partial upgrades. Users managing system packages from scripts or configuration files need a way to ensure their system state matches a declared package list, with all packages at their latest available versions.

Goals / Non-Goals

Goals:

• Provide a declarative interface for pacman package management through command-line interface
• Support flexible input sources (stdin and multiple state files) with additive merging
• Automatically resolve transitive dependencies (users specify only direct packages)
• Enforce full package upgrades (no partial upgrades) to prevent version mismatches
• Generate machine-readable output suitable for automated scripting
• Enable AI-driven implementation for new Go developers

Non-Goals:

• Package dependency resolution or smart upgrade scheduling
• Transaction rollback capabilities
• Pretty terminal output or interactive prompts
• Support for partial upgrades or selective package versions
• State persistence (tool only syncs, doesn't save state)

Decisions

Language: Go

• Rationale: User wants modern CLI tool with native package management capabilities
• Go provides strong standard library, easy command-line parsing, and excellent for system-level operations
• User unfamiliar with Go - implementation will be AI-driven with detailed documentation

Input Parsing Approach

• Parse whitespace, tabs, newlines for package names
• Support multiple --state files: all additive including with stdin
• Validate package names against pacman available packages (optional validation)
• Empty state detection: print error to stderr and exit with code 1 (abort)

State Merging Logic

• All inputs are additive: combine all packages from stdin and all state files
• No conflict resolution: missing packages are added, duplicates accumulate
• Order-independent: inputs don't override each other

Pacman Interaction

• Use os/exec.Command to run pacman with -Sy (sync databases) and -S flag
• Run pacman -Syu with all target packages to ensure full upgrade
• Capture stderr/stdout for error reporting and machine output
• Detect pacman exit codes and translate to tool exit codes

Error Handling Strategy

• Parse pacman error messages from stderr output
• Distinguish between package-not-found (warning) vs. execution failures (errors)
• Return appropriate exit codes: 0 for success, non-zero for errors
• Include error details in output for scripting purposes

AUR Integration

• For packages not found in pacman repositories, check if available in AUR
• Use makepkg directly to build and install AUR packages (no AUR helpers)
• Clone AUR git repo to temp directory
• Run makepkg -si in temp directory for installation
• Capture stdout/stderr for output and error handling
• Report error to stderr if package not found in pacman or AUR

Dependency Resolution

• Use pacman's dependency resolution by passing all declared packages to pacman -Syu
• Pacman automatically resolves and includes transitive dependencies
• For AUR packages, makepkg handles dependency resolution during build
• No custom dependency resolution logic required - delegate to pacman/makepkg

Explicit Marking & Orphan Cleanup

• Before syncing, get list of all currently installed packages
• Mark declared state packages as explicitly installed via pacman -D --explicit <pkg>
• All other installed packages remain as non-explicit (dependencies)
• After sync completes, run pacman -Rns $(pacman -Qdtq) to remove orphaned packages
• Pacman -Rns $(pacman -Qdtq) only removes packages that are not explicitly installed and not required
• Capture and report number of packages removed during cleanup

Package Version Management

• Always force full system upgrade via pacman -Syu <packages>
• Pacman handles version selection automatically, ensuring latest versions
• No semantic version comparison or pinning logic required

Risks / Trade-offs

Known Risks:

• [User unfamiliarity with Go] → Mitigation: Provide complete implementation with detailed comments; user can review and run without understanding deeply
• [Pacman error message parsing complexity] → Mitigation: Use broad error pattern matching; include error output as-is for debugging
• [Empty state triggers abort] → Mitigation: Print error to stderr and exit with code 1 instead of proceeding with empty state
• [Additive merging could accumulate duplicates] → Mitigation: Accept as design choice; pacman handles duplicates gracefully
• [Dependency conflicts could occur] → Mitigation: Let pacman handle standard conflicts; tool won't implement complex dependency resolution

Trade-offs:

• No conflict resolution: simpler merging but may include packages the system rejects
• Additive vs replacement: safer but less predictable for users expecting replacements
• No user prompts: fully automated for scripting but could be risky without warnings