Released v1

2026-02-12 10:37:19 +00:00
commit b07572fed5
77 changed files with 19518 additions and 0 deletions
@@ -0,0 +1,35 @@
+## MODIFIED Requirements
+
+### Requirement: Base HTTP client
+The system SHALL provide a base HTTP client that sends requests to the Planka API. The client SHALL construct URLs by joining the configured base URL with the API path. The client SHALL attach an `x-api-key: <key>` header to every request. The client SHALL send and receive JSON (`Content-Type: application/json`). The client SHALL accept a `*slog.Logger` and log every request at DEBUG level with method, path, status code, and duration. The client SHALL log errors at WARN level.
+
+#### Scenario: Successful API request
+- **WHEN** the client sends a request to a valid endpoint
+- **THEN** the response body SHALL be returned as parsed JSON
+- **AND** the request SHALL include the `x-api-key` header
+- **AND** a DEBUG log entry SHALL be emitted with method, path, status, and duration
+
+#### Scenario: API returns error status
+- **WHEN** the API responds with a 4xx or 5xx status code
+- **THEN** the client SHALL return an `APIError` containing the HTTP status code and response message
+- **AND** a WARN log entry SHALL be emitted
+
+#### Scenario: Network failure
+- **WHEN** the HTTP request fails due to a network error (connection refused, timeout, DNS failure)
+- **THEN** the client SHALL return a Go error wrapping the underlying network error
+
+### Requirement: Authentication from environment
+The system SHALL read `PLANKA_URL` from the environment to determine the API base URL. The system SHALL read `PLANKA_API_KEY` from the environment to determine the API key. Global flags `--url` and `--api-key` SHALL override the corresponding environment variables. Flag values SHALL take precedence over environment variables.
+
+#### Scenario: Auth from environment variables
+- **WHEN** `PLANKA_URL` and `PLANKA_API_KEY` are set in the environment
+- **AND** no `--url` or `--api-key` flags are provided
+- **THEN** the client SHALL use the environment variable values
+
+#### Scenario: Flag overrides environment
+- **WHEN** `--url` or `--api-key` flags are provided
+- **THEN** the flag values SHALL take precedence over environment variables
+
+#### Scenario: Missing configuration
+- **WHEN** neither the environment variable nor the flag is set for URL or API key
+- **THEN** the system SHALL print an error message and exit with code 1
@@ -0,0 +1,22 @@
+## MODIFIED Requirements
+
+### Requirement: Root command and global flags
+The system SHALL provide a root command `pcli` that serves as the entry point. The root command SHALL register global flags: `--format` (string, default `json`, values `json` or `table`), `--url` (string, overrides `PLANKA_URL`), `--api-key` (string, overrides `PLANKA_API_KEY`), and `--log-level` (string, default `warn`, values `debug`, `info`, `warn`, `error`). The root command SHALL initialize the logger based on `--log-level` and configure it to write structured JSON to stderr. The root command SHALL validate that URL and API key are available (from flags or environment) before executing any subcommand.
+
+#### Scenario: Display help
+- **WHEN** `pcli` is run with no arguments or `--help`
+- **THEN** the system SHALL display usage information listing all resource subcommands and global flags
+
+#### Scenario: Invalid format flag
+- **WHEN** `--format` is set to an unsupported value
+- **THEN** the system SHALL print an error and exit with code 1
+
+#### Scenario: Log level controls output
+- **WHEN** `--log-level=debug` is set
+- **THEN** DEBUG-level log entries SHALL appear on stderr
+- **AND** stdout SHALL contain only the command's data output
+
+#### Scenario: Missing API key
+- **WHEN** neither `PLANKA_API_KEY` environment variable nor `--api-key` flag is provided
+- **THEN** the system SHALL print an error indicating `PLANKA_API_KEY` must be set via `--api-key` flag or `PLANKA_API_KEY` environment variable
+- **AND** the system SHALL exit with code 1