Multi-distro package support with extended naming convention

[mairas]

Problem Statement

The apt.hatlabs.fi repository workflow has critical metadata issues during full rebuilds:

1. Metadata loss: No information about target distro/channel/component during full rebuild
2. Incorrect routing: Same packages copied to all 6 distributions
3. Missing unstable packages: Pre-releases not properly detected

During dispatch-based updates (when component repos trigger updates), metadata is provided in the payload. During full rebuilds, this metadata doesn't exist, causing incorrect package placement.

Solution: Extended Naming Convention

Filename Format: {package}_{version}_{arch}+{distro}+{component}.deb

Examples:

• halpi2-daemon_1.0.0-1_all+any+hatlabs.deb
• signalk-server-container_2.17.2-1_all+trixie+main.deb
• cockpit-apt_0.2.0-1_all+trixie+main.deb

Why channel is omitted: Channel (stable/unstable) is determined by GitHub release type, not at build time. The same binary can be in both a pre-release (unstable) and a release (stable).

Design Decisions

Three-Dimensional Routing: (distro, channel, component)

Distro dimension:

• any - Deploy to ALL current and future distros (bookworm, trixie, forky)
• trixie, bookworm, forky - Specific distro only

Channel dimension (from GitHub release type):

• stable - Regular GitHub releases
• unstable - Pre-releases

Component dimension:

• main - General packages (marine apps, third-party software)
• hatlabs - Hat Labs product packages (HALPI2 daemon, firmware)

Special Routing Rules

Legacy compatibility (stable/main and unstable/main):

These repos are ONLY for Hat Labs product packages. Routing to legacy repos happens ONLY when:

• component = "hatlabs" AND
• distro = "any"

Example: halpi2-daemon+any+hatlabs.deb (pre-release) routes to:

• unstable/main (legacy)
• bookworm-unstable/hatlabs
• trixie-unstable/hatlabs
• forky-unstable/hatlabs (when available)

Example: signalk+trixie+main.deb routes ONLY to:

• trixie-stable/main (if release) OR
• trixie-unstable/main (if pre-release)

Suffix Stripping

The suffix is stripped when packages are stored in the APT repository.

1. Download: halpi2-daemon_1.0.0-1_all+any+hatlabs.deb
2. Parse suffix for routing: distro=any, component=hatlabs
3. Extract canonical metadata from .deb control file
4. Rename to: halpi2-daemon_1.0.0-1_all.deb
5. Store in appropriate pool directories

Rationale: The suffix is routing metadata. Once routed to the correct pool/dist location, it's no longer needed. APT repository maintains standard Debian naming.

Fallback Behavior

For packages without suffix (backward compatibility):

• Route to bare stable/ or unstable/ repos
• Future: Require suffix, reject packages without

Implementation Phases

1. Core Infrastructure - Update apt.hatlabs.fi workflow
2. Pilot - Test with cockpit-apt
3. Rollout - Update all 7 component repos
4. Cleanup - Remove non-hatlabs packages from stable/main

References

• Updated ARCHITECTURE.md: (will be added when PR is merged)
• Related issues: fix: correct heredoc syntax in remove-package workflow #26, fix: resolve all YAML syntax errors in remove-package workflow #27
• Workflow run showing issue: https://github.com/hatlabs/apt.hatlabs.fi/actions/runs/19424570065

Implementation Requirements

MANDATORY: Follow docs/IMPLEMENTATION_CHECKLIST.md during implementation.

This includes:

• Exploration phase WITHOUT coding
• Planning with "think hard"
• Test-Driven Development (write tests first)
• Verification with subagents
• References to SPEC.md and ARCHITECTURE.md

[mairas]

Implementation Issues Created

Phase 1: Core Infrastructure (apt.hatlabs.fi)

• Add suffix parsing to update-repo.yml workflow #29 - Add suffix parsing to update-repo.yml workflow
• Implement routing logic with distro expansion #30 - Implement routing logic with distro expansion
• Implement canonical filename normalization #31 - Implement canonical filename normalization
• Fix full rebuild to download packages once and route correctly #32 - Fix full rebuild to download packages once and route correctly
• Update repository generation for component structure #33 - Update repository generation for component structure

Phase 2: Pilot Implementation (cockpit-apt)

• Update cockpit-apt build workflow with extended naming halos-org/cockpit-apt#68 - Update cockpit-apt build workflow with extended naming
• End-to-end testing with cockpit-apt pilot halos-org/cockpit-apt#69 - End-to-end testing with cockpit-apt pilot

Phase 3: Rollout to Component Repos

• Update halos-marine-containers workflows with extended naming #36 - Classify component repositories for extended naming
• Update remaining component repos with extended naming #37 - Update halos-marine-containers workflows with extended naming
• Remove non-hatlabs packages from legacy stable/main #38 - Update remaining component repos with extended naming

Phase 4: Cleanup and Validation

• Full rebuild validation and testing #39 - Remove non-hatlabs packages from legacy stable/main
• Update documentation for multi-distro support #40 - Full rebuild validation and testing
• Delete temporary planning files #41 - Update documentation for multi-distro support
• docs: add multi-distro package routing architecture #42 - Delete temporary planning files

All issues include:

• ✅ Implementation checklist from DEVELOPMENT_WORKFLOW.md
• ✅ Mandatory workflow requirements
• ✅ Test scenarios and acceptance criteria
• ✅ Dependencies clearly marked