52d8e5b95e
All checks were successful
Build-Test-Publish / build (linux/amd64) (push) Successful in 53s
Build-Test-Publish / build (linux/arm64) (push) Successful in 1m34s
Build-Test-Publish / test-install-from-scratch (linux/amd64) (push) Successful in 6s
Build-Test-Publish / test-install-from-scratch (linux/arm64) (push) Successful in 7s
79 lines
5.4 KiB
Markdown
79 lines
5.4 KiB
Markdown
# Requirements Document
|
|
|
|
## Introduction
|
|
|
|
This feature extends getpkg to support multiple package servers instead of being limited to only getpkg.xyz. Users will be able to add and remove package servers, with getpkg searching across all configured servers to find packages. The system will maintain backward compatibility while providing flexible server management capabilities.
|
|
|
|
## Requirements
|
|
|
|
### Requirement 1
|
|
|
|
**User Story:** As a developer, I want to configure multiple package servers, so that I can access packages from different repositories and have redundancy in case one server is unavailable.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN I run `getpkg server add <server_url>` THEN the system SHALL add the server to the configuration and confirm the addition
|
|
2. WHEN I run `getpkg server remove <server_url>` THEN the system SHALL remove the server from the configuration and confirm the removal
|
|
3. WHEN I run `getpkg server list` THEN the system SHALL display all configured servers in the order they were added
|
|
4. WHEN no servers are configured THEN the system SHALL default to using getpkg.xyz as the primary server
|
|
5. WHEN I add the first custom server THEN getpkg.xyz SHALL remain as the default first server unless explicitly removed
|
|
|
|
### Requirement 2
|
|
|
|
**User Story:** As a user, I want getpkg to search across all configured servers when installing packages, so that I can access packages from any of my configured repositories.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN I run `getpkg install <tool_name>` THEN the system SHALL search servers in the order they were configured
|
|
2. WHEN a package is found on the first server THEN the system SHALL install from that server and not check remaining servers
|
|
3. WHEN a package is not found on the first server THEN the system SHALL try the next server in order
|
|
4. WHEN a package is not found on any server THEN the system SHALL report that the package was not found
|
|
5. WHEN checking for updates THEN the system SHALL use the same server where the package was originally installed
|
|
|
|
### Requirement 3
|
|
|
|
**User Story:** As a package publisher, I want to specify which server to publish to and manage write tokens per server, so that I can control where my packages are distributed and authenticate appropriately.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN I run `getpkg publish <tool_name> <folder>` without specifying a server THEN the system SHALL publish to the first configured server that has a write token
|
|
2. WHEN I run `getpkg publish --server <server_url> <tool_name> <folder>` THEN the system SHALL publish to the specified server using its stored write token
|
|
3. WHEN I run `getpkg unpublish <tool_name>` without specifying a server THEN the system SHALL unpublish from the first configured server that has a write token
|
|
4. WHEN I run `getpkg unpublish --server <server_url> <tool_name>` THEN the system SHALL unpublish from the specified server using its stored write token
|
|
5. WHEN no servers have write tokens THEN the system SHALL report an error and suggest adding a write token to a server
|
|
|
|
### Requirement 4
|
|
|
|
**User Story:** As a user, I want my package metadata to be organized by server, so that I can track which packages came from which servers and manage them appropriately.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN a package is installed THEN the system SHALL store the package metadata in `~/.config/getpkg/packages/<tool_name>.json`
|
|
2. WHEN package metadata is stored THEN it SHALL include the source server URL in addition to existing fields
|
|
3. WHEN the packages directory doesn't exist THEN the system SHALL create it automatically
|
|
4. WHEN migrating from the old format THEN existing package JSON files SHALL be moved to the packages subdirectory
|
|
5. WHEN migrating from the old format THEN existing package metadata SHALL be updated to include getpkg.xyz as the source server
|
|
|
|
### Requirement 5
|
|
|
|
**User Story:** As a user, I want server configuration to be persistent and secure, so that my settings are maintained across sessions and my authentication tokens are protected.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN server configuration is modified THEN it SHALL be stored in `~/.config/getpkg/servers.json`
|
|
2. WHEN the configuration file doesn't exist THEN the system SHALL create it with getpkg.xyz as the default server
|
|
3. WHEN reading server configuration THEN the system SHALL validate the JSON format and handle corruption gracefully
|
|
4. WHEN a server URL is invalid THEN the system SHALL reject the addition and provide a helpful error message
|
|
5. WHEN authentication tokens are needed THEN they SHALL continue to be stored per-server in the existing location pattern
|
|
|
|
### Requirement 6
|
|
|
|
**User Story:** As a user, I want the multi-server functionality to be backward compatible, so that existing installations continue to work without modification.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN getpkg starts with no server configuration THEN it SHALL automatically configure getpkg.xyz as the default server
|
|
2. WHEN existing package JSON files are found in `~/.config/getpkg/` THEN they SHALL be automatically migrated to the packages subdirectory
|
|
3. WHEN migrated package files are processed THEN they SHALL be updated to include server source information
|
|
4. WHEN all existing functionality is used THEN it SHALL work exactly as before for users who don't configure additional servers
|
|
5. WHEN the migration process fails THEN the system SHALL provide clear error messages and not break existing functionality |