Applies the change's delta specs to the main specs and files the change under openspec/changes/archive/2026-09-16-scoped-beer-override. keg-auto-detection gains the scoped-override and override-visibility requirements, and its detection precedence is rewritten so no config value can precede detection except by matching the reported product ID. card-config drops the beer_name override requirement in favour of the beer_overrides map, and records beer_name alongside beer_entity as an ignored legacy key. Also corrects three stale beer_name references in beer-catalog and beer-label. The proposal's capability list missed those two specs; the substance of their requirements is unchanged, only the key name they name, so this is a naming correction rather than a requirement change. Co-authored-by: Cursor <cursoragent@cursor.com>
4.1 KiB
4.1 KiB
beer-catalog Specification
Purpose
TBD - created by archiving change perfectdraft-card. Update Purpose after archive.
Requirements
Requirement: Built-in PerfectDraft beer database
The card SHALL include a built-in catalog of PerfectDraft beers with metadata for display purposes.
Scenario: Catalog data structure
- WHEN the card is loaded
- THEN each beer entry in the catalog SHALL contain: a unique slug (kebab-case), display name, brewery name, style, ABV (number), and a brand color palette (primary color, secondary color, text color)
- THEN each entry MAY additionally carry a
kegIdproduct ID, a keg image path, and a brewery logo reference
Scenario: Catalog coverage
- WHEN the card is loaded
- THEN the catalog SHALL include an entry for every keg the paired integration can identify, and MAY include further entries for beers the integration does not list
Requirement: Beer logo images
The card SHALL include static logo images for beers in the built-in catalog.
Scenario: Image availability
- WHEN a beer from the built-in catalog is selected
- THEN the card SHALL display the beer's logo image in the label zone
- THEN images SHALL be optimised static assets (PNG or WebP) bundled with the card
Scenario: Image fallback
- WHEN a beer has no logo image available (custom beer or missing asset)
- THEN the card SHALL display the beer's brand color palette as the visual background instead of an image
Requirement: Custom beer entries via configuration
The card SHALL support user-defined beer entries that extend or override the built-in catalog, reachable through a beer_overrides entry.
Scenario: Custom beer defined in config
- WHEN the card config includes a
custom_beersarray with entries containing at minimum anamefield - THEN those beers SHALL be resolvable by a
beer_overridesentry alongside built-in entries - THEN custom entries SHALL support optional fields:
color_primary,color_secondary,color_text,image_url,brewery,style,abv
Scenario: Custom beer overrides built-in
- WHEN a custom beer entry has the same slug as a built-in beer
- THEN the custom entry SHALL override the built-in entry's fields
Requirement: Product ID mapping to the integration catalog
Each catalog entry SHALL be able to carry the PerfectDraft product ID of its keg, so the card can join against the product ID reported by the integration.
Scenario: Entry carries a product ID
- WHEN a catalog entry corresponds to a keg listed in the integration's
keg_catalog.json - THEN the entry SHALL carry a
kegIdfield holding that product ID as a string
Scenario: Full coverage of the integration catalog
- WHEN the card is loaded
- THEN every product ID present in the integration's bundled keg catalog SHALL be carried by exactly one card catalog entry
- THEN no
kegIdSHALL appear on more than one entry - THEN no
kegIdSHALL reference a product ID absent from the integration catalog
Scenario: Lookup by product ID
- WHEN the card looks up a beer by product ID
- THEN the lookup SHALL resolve without scanning the catalog linearly, using an index built once at module load alongside the existing slug and name indexes
Requirement: Catalog coverage is verifiable
The project SHALL provide a repeatable check that the card's product ID mapping agrees with the integration's keg catalog, so drift is detected rather than discovered by users.
Scenario: Check detects a missing mapping
- WHEN the integration catalog contains a product ID that no card catalog entry carries
- THEN the check SHALL fail and SHALL name the unmapped product ID and its integration-reported name
Scenario: Check detects a stale or duplicate mapping
- WHEN a card catalog entry carries a
kegIdthat is absent from the integration catalog, or two entries carry the samekegId - THEN the check SHALL fail and SHALL name the offending entries
Scenario: Check is offline
- WHEN the check runs
- THEN it SHALL compare against a committed snapshot of the integration catalog and SHALL NOT require network access