Update openspec with clarified design decisions

2026-04-13 16:36:17 +02:00
parent 9d6c1ec3ee
commit ba05908cc4
6 changed files with 162 additions and 64 deletions
@@ -1,23 +1,30 @@
 ## ADDED Requirements

-### Requirement: Can handle AUR packages with pacman fallback
+### Requirement: Handle AUR packages with fallback and upgrade

-The system SHALL attempt to install AUR packages by first trying pacman
-repositories, then falling back to AUR when pacman fails, and finally reporting
-errors for packages still missing.
+The system SHALL first attempt to install packages via pacman, then fall back
+to AUR for packages not found in repos, and upgrade AUR packages to
+latest versions.

-#### Scenario: Install from pacman first
+#### Scenario: Try pacman first
 - **WHEN** package is in pacman repositories
- **THEN** system shall install via pacman
+- **THEN** install via pacman -Syu

 #### Scenario: Fall back to AUR
 - **WHEN** package is not in pacman repositories but is in AUR
- **THEN** system shall attempt installation via makepkg (direct AUR build)
+- **THEN** query AUR via Jguer/aur library
+- **AND** build and install with makepkg -si
+
+#### Scenario: Upgrade AUR packages
+- **WHEN** AUR package is already installed but outdated
+- **THEN** rebuild and reinstall with makepkg to get latest version

 #### Scenario: Report error for missing packages
 - **WHEN** package is not in pacman repositories or AUR
- **THEN** system shall report error and print to stderr
+- **THEN** print error to stderr with package name
+- **AND** exit with code 1

-#### Scenario: Continue for remaining packages
- **WHEN** some packages are installed and some fail
- **THEN** system shall continue installation process for successful packages
+#### Scenario: AUR build failure
+- **WHEN** makepkg fails to build package
+- **THEN** print makepkg error to stderr
+- **AND** exit with code 1
@@ -1,21 +1,30 @@
 ## ADDED Requirements

-### Requirement: Can generate machine-readable output
+### Requirement: Generate consistent output format

-The system SHALL produce output suitable for automated scripting.
+The system SHALL produce console output suitable for logging and scripting.

-#### Scenario: Install/remove count output
- **WHEN** sync completes successfully
- **THEN** system shall output: "<installed_count> package(s) installed, <removed_count> package(s) removed"
+#### Scenario: Successful sync with changes
+- **WHEN** sync completes with packages installed or removed
+- **THEN** print to stdout: `Installed X packages, removed Y packages`
+- **AND** exit with code 0

-#### Scenario: Empty output format
- **WHEN** no packages to sync
- **THEN** system shall output nothing (or indicate no changes)
+#### Scenario: No changes needed
+- **WHEN** all packages already match declared state
+- **THEN** print to stdout: `Installed 0 packages, removed 0 packages`
+- **AND** exit with code 0

-#### Scenario: Error details in output
- **WHEN** pacman operation fails
- **THEN** system shall include error details in output (package names, pacman error messages)
+#### Scenario: Error during sync
+- **WHEN** pacman or makepkg operation fails
+- **THEN** print error to stderr with details
+- **AND** exit with code 1

-#### Scenario: Exit code for scripting
- **WHEN** sync completes
- **THEN** system shall return exit code 0 for success, non-zero for errors
+#### Scenario: Validation failure
+- **WHEN** package validation fails (package not in pacman or AUR)
+- **THEN** print error to stderr with package name
+- **AND** exit with code 1
+
+#### Scenario: Empty state input
+- **WHEN** no packages provided from stdin or state files
+- **THEN** print error to stderr: `empty state input`
+- **AND** exit with code 1
@@ -0,0 +1,22 @@
+## ADDED Requirements
+
+### Requirement: Query pacman package database via libalpm
+
+The system SHALL use libalpm for fast local queries against the pacman
+package database.
+
+#### Scenario: Query installed packages
+- **WHEN** needing list of currently installed packages
+- **THEN** query via libalpm alpm_list_get(ALPM_LIST_PACKAGES)
+
+#### Scenario: Query available packages
+- **WHEN** validating package exists in pacman repos
+- **THEN** query via libalpm alpm_db_get_pkg()
+
+#### Scenario: Check database last sync time
+- **WHEN** checking if database needs refresh
+- **THEN** check /var/lib/pacman/db.lock timestamp
+
+#### Scenario: Query foreign packages
+- **WHEN** checking if package is AUR-installed
+- **THEN** query via libalpm alpm_db_get_pkg(ALPM_DB_TYPE_LOCAL)
@@ -1,17 +1,28 @@
 ## ADDED Requirements

-### Requirement: Can detect empty state input
+### Requirement: Validate package names exist in pacman or AUR

-The system SHALL detect when no packages are provided in any input source.
+The system SHALL validate that all declared packages exist in pacman
+repositories or AUR before attempting to sync.

-#### Scenario: Empty state warning
+#### Scenario: Empty state detection
 - **WHEN** no package names are found in stdin or state files
- **THEN** system shall print a warning to stderr
+- **THEN** print error to stderr: `empty state input`
+- **AND** exit with code 1

-#### Scenario: Empty state warning message
- **WHEN** warning is printed for empty state
- **THEN** message shall say: "Called without state, aborting.."
+#### Scenario: Validate package in pacman repos
+- **WHEN** package exists in pacman repositories
+- **THEN** validation passes

-#### Scenario: Abort on empty state
- **WHEN** empty state is detected
- **THEN** system shall exit with code 1 (error: no packages to sync)
+#### Scenario: Validate package in AUR
+- **WHEN** package not in pacman repos but exists in AUR
+- **THEN** validation passes
+
+#### Scenario: Package not found
+- **WHEN** package not in pacman repos or AUR
+- **THEN** print error to stderr with package name
+- **AND** exit with code 1
+
+#### Scenario: Database freshness check
+- **WHEN** pacman database last sync was more than 1 day ago
+- **THEN** run pacman -Syy to refresh before validation