refactor: extract workflow scripts into separate files

[mairas]

Problem

The .github/workflows/update-repo.yml file has become bloated with inline bash scripts that handle:

• Package downloading from GitHub releases
• Metadata extraction and parsing
• Package routing to distribution-specific pools
• GPG key import and signing configuration

This makes the workflow file:

• Hard to test independently
• Difficult to maintain and modify
• Impossible to reuse scripts in other workflows
• Not suitable for local testing during development

Solution

Extract the complex bash script logic from the workflow into dedicated shell script files in /scripts/ directory:

1. scripts/download-packages.sh - Download packages from GitHub releases

   • Handle release version resolution (latest, prerelease, specific tag)
   • Manage package download and temporary file handling
   • Validate downloaded packages with dpkg-deb

2. scripts/route-packages.sh - Route packages to distribution pools

   • Source routing functions
   • Implement routing logic for distro expansion
   • Handle legacy routing for any/hatlabs packages

3. scripts/gpg-setup.sh - GPG configuration

   • Import signing keys
   • Extract key IDs
   • Set environment variables

4. Update workflow to call these scripts instead of containing inline logic

Benefits

• ✅ Scripts can be unit tested independently
• ✅ Easy to debug locally before committing
• ✅ Code reuse across multiple workflows
• ✅ Cleaner, more maintainable workflow files
• ✅ Easier to onboard new contributors
• ✅ Better error handling and logging

Implementation Notes

Follow the DEVELOPMENT_WORKFLOW.md for this refactoring.

Implementation Checklist

Phase 1: EXPLORE (No Coding!)

• Read /docs/SPEC.md relevant sections
• Read /docs/ARCHITECTURE.md relevant sections
• Explore existing code WITHOUT writing anything
• Use Task tool with subagent_type=Explore for complex navigation

Phase 2: PLAN

• Use think hard to evaluate approaches
• Create detailed refactoring plan
• Identify test scenarios for extracted scripts
• Document plan in GitHub comment

Phase 3: TEST (TDD)

• Write comprehensive tests FIRST for each script
• Verify tests FAIL (no implementation yet)
• Commit tests: git commit -m "test: add script tests"

Phase 4: IMPLEMENT

• Extract download logic to scripts/download-packages.sh
• Extract routing logic to scripts/route-packages.sh
• Extract GPG setup to scripts/gpg-setup.sh
• Run tests after each change
• DO NOT modify tests to pass
• Iterate until ALL tests pass

Phase 5: VERIFY

• Use subagents to verify correctness
• Check for edge cases
• Verify workflow still functions correctly
• Test locally with sample data

Phase 6: COMMIT

• All tests pass
• Commit: git commit -m "refactor: extract workflow scripts"
• Create PR with summary

Success Criteria

• ✅ All new scripts have unit tests (100% coverage)
• ✅ Workflow file is significantly simplified
• ✅ All existing functionality preserved
• ✅ Scripts are independently testable
• ✅ No regression in CI/CD behavior
• ✅ Documentation updated

Related

• PR fix: source helper scripts in subshell for full rebuild mode #49-54: Recent workflow fixes that grew the file complexity
• DEVELOPMENT_WORKFLOW.md: Follow this workflow for implementation
• IMPLEMENTATION_CHECKLIST.md: Use this checklist throughout

---

Remember: This is a refactoring task - Quality > Speed. Take time to plan and test thoroughly.