pcli/openspec/specs/permission-errors/spec.md

ADDED Requirements

Requirement: Permission error translation helper

The system SHALL provide a friendlyAPIError function in the cmd package that translates APIError status codes into human-readable messages with operation context.

Scenario: Authentication error (401)

• WHEN an APIError with StatusCode 401 is passed to friendlyAPIError with operation "create board"
• THEN the function SHALL return an error with message "create board: authentication failed — check your API key"

Scenario: Permission denied (403) with hint

• WHEN an APIError with StatusCode 403 is passed to friendlyAPIError with operation "create board" and permissionHint "requires project manager role"
• THEN the function SHALL return an error with message "create board: permission denied (requires project manager role)"

Scenario: Permission denied (403) without hint

• WHEN an APIError with StatusCode 403 is passed to friendlyAPIError with operation "create project" and empty permissionHint
• THEN the function SHALL return an error with message "create project: permission denied"

Scenario: Not found (404)

• WHEN an APIError with StatusCode 404 is passed to friendlyAPIError with operation "delete board"
• THEN the function SHALL return an error with message "delete board: not found — the resource may not exist or you may not have access to it"

Scenario: Non-API error

• WHEN a non-APIError (e.g., network error) is passed to friendlyAPIError
• THEN the function SHALL return the original error unchanged

Scenario: Unknown status code

• WHEN an APIError with StatusCode 500 is passed to friendlyAPIError
• THEN the function SHALL return the original APIError unchanged