Bug: clean up release artifacts

[sirkirby]

GitHub Release Assets Correction Plan

Problem Statement

Currently, the GitHub release workflow uploads only the bare executables (tom and tom.exe) to releases, but these executables require additional runtime dependencies to function properly:

• appsettings.json and appsettings.*.json configuration files
• Platform-specific shared libraries (.dylib on macOS, .dll on Windows)

However, the build workflow correctly bundles these dependencies in artifacts for Homebrew bottles. This creates a discrepancy where users downloading from GitHub releases get non-functional binaries, while Homebrew users get complete, working packages.

Current State Analysis

Build Workflow (build.yml)

✅ Correct - Artifacts include all necessary files:

# macOS x64 (lines 179-187)
- name: Upload artifact
  uses: actions/upload-artifact@v4
  with:
    name: ten-second-tom-osx-x64
    path: |
      ./publish/osx-x64/tom
      ./publish/osx-x64/appsettings*.json
      ./publish/osx-x64/*.dylib
    retention-days: 90

# macOS ARM64 (lines 244-252)
- name: Upload artifact
  uses: actions/upload-artifact@v4
  with:
    name: ten-second-tom-osx-arm64
    path: |
      ./publish/osx-arm64/tom
      ./publish/osx-arm64/appsettings*.json
      ./publish/osx-arm64/*.dylib
    retention-days: 90

# Windows x64 (lines 318-326)
- name: Upload artifact
  uses: actions/upload-artifact@v4
  with:
    name: ten-second-tom-win-x64
    path: |
      ./publish/win-x64/tom.exe
      ./publish/win-x64/appsettings*.json
      ./publish/win-x64/*.dll
    retention-days: 90

Release Workflow (release.yml)

❌ Incomplete - Only uploads executables:

# Lines 457-475
# Upload all artifacts
echo "📤 Uploading artifacts..."

# Upload macOS x64
gh release upload "$VERSION" \
  ./artifacts/ten-second-tom-osx-x64/tom \
  --clobber

# Upload macOS ARM64
gh release upload "$VERSION" \
  ./artifacts/ten-second-tom-osx-arm64/tom \
  --clobber

# Upload Windows x64
gh release upload "$VERSION" \
  ./artifacts/ten-second-tom-win-x64/tom.exe \
  --clobber

echo "✅ All artifacts uploaded"

Solution Strategy

Option 1: Upload Complete Directory Contents (RECOMMENDED)

Upload all files from each artifact directory to the GitHub release, ensuring users get functional binaries.

Advantages:

• Users can download individual platform binaries with all dependencies
• Consistent with Homebrew bottle approach
• Simplest implementation
• Most transparent for users

Disadvantages:

• Multiple files per platform on release page (but organized by prefix)
• Slightly larger total download size for users

Option 2: Create Platform-Specific Archives

Create .tar.gz (macOS) and .zip (Windows) archives containing all dependencies before uploading.

Advantages:

• Single download per platform
• Cleaner release page
• More "professional" appearance

Disadvantages:

• Adds complexity to workflow
• Requires additional archiving steps
• Users must extract archives (extra step)
• Deviates from Homebrew bottle structure

Recommended Implementation: Option 1

Changes Required

File: .github/workflows/release.yml
Location: Lines 457-475 (in create-github-release job)

Current Code:

# Upload all artifacts
echo "📤 Uploading artifacts..."

# Upload macOS x64
gh release upload "$VERSION" \
  ./artifacts/ten-second-tom-osx-x64/tom \
  --clobber

# Upload macOS ARM64
gh release upload "$VERSION" \
  ./artifacts/ten-second-tom-osx-arm64/tom \
  --clobber

# Upload Windows x64
gh release upload "$VERSION" \
  ./artifacts/ten-second-tom-win-x64/tom.exe \
  --clobber

echo "✅ All artifacts uploaded"

Replacement Code:

# Upload all artifacts
echo "📤 Uploading artifacts..."

# Upload macOS x64 with dependencies
echo "📦 Uploading macOS x64 binary and dependencies..."
gh release upload "$VERSION" \
  ./artifacts/ten-second-tom-osx-x64/* \
  --clobber

# Upload macOS ARM64 with dependencies
echo "📦 Uploading macOS ARM64 binary and dependencies..."
gh release upload "$VERSION" \
  ./artifacts/ten-second-tom-osx-arm64/* \
  --clobber

# Upload Windows x64 with dependencies
echo "📦 Uploading Windows x64 binary and dependencies..."
gh release upload "$VERSION" \
  ./artifacts/ten-second-tom-win-x64/* \
  --clobber

echo "✅ All artifacts uploaded"

Release Notes Update

Location: Lines 382-419 (release notes generation)

Current Downloads Section:

### 📦 Downloads

Choose the appropriate binary for your platform:

- **macOS (Intel)**: `tom` (from ten-second-tom-osx-x64)
- **macOS (Apple Silicon)**: `tom` (from ten-second-tom-osx-arm64)
- **Windows**: `tom.exe` (from ten-second-tom-win-x64)

### ✅ Verification

Use `shasum -a 256` or `Get-FileHash` to verify the downloaded binaries.

Replacement Downloads Section:

### 📦 Downloads

Choose the appropriate binary and dependencies for your platform:

#### macOS (Intel - x64)
Download all files with the `osx-x64` prefix:
- `tom` - Main executable
- `appsettings.json` - Configuration
- `appsettings.*.json` - Environment-specific configuration (if present)
- `*.dylib` - Required shared libraries (if present)

#### macOS (Apple Silicon - ARM64)
Download all files with the `osx-arm64` prefix:
- `tom` - Main executable
- `appsettings.json` - Configuration
- `appsettings.*.json` - Environment-specific configuration (if present)
- `*.dylib` - Required shared libraries (if present)

#### Windows (x64)
Download all files with the `win-x64` prefix:
- `tom.exe` - Main executable
- `appsettings.json` - Configuration
- `appsettings.*.json` - Environment-specific configuration (if present)
- `*.dll` - Required shared libraries (if present)

**Important:** All files for your platform must be in the same directory for the executable to run.

### ✅ Verification

Use `shasum -a 256` or `Get-FileHash` to verify the downloaded binaries.

Implementation Steps

1. Update release upload commands (lines 457-475)

   • Change from uploading individual files to uploading entire artifact directories
   • Add descriptive echo statements for each platform upload

2. Update release notes template (lines 382-419)

   • Clarify that users need all files for their platform
   • Explain the file naming convention for artifacts
   • Emphasize keeping files together

3. Test the changes

   • Use workflow_dispatch with dry_run=true first
   • Verify artifact downloads work correctly
   • Create a test release with skip_homebrew=true to validate

4. Update documentation (optional but recommended)

   • Update README.md installation section to mention dependencies
   • Consider adding troubleshooting section for missing dependencies

Testing Checklist

• Modify release.yml lines 457-475
• Modify release.yml lines 382-419 (both occurrence in the if/else block)
• Run workflow manually with test version (e.g., v0.0.2-test)
• Enable dry_run=true and skip_homebrew=true
• Verify logs show all files being uploaded for each platform
• Create actual test release (dry_run=false)
• Download artifacts for each platform from test release
• Verify executables run with downloaded dependencies
• Clean up test release
• Merge to main and test with production release

Risk Assessment

Risk Level: Low

Mitigations:

• Changes are additive (adding more files, not removing)
• Existing Homebrew bottles remain unaffected
• Test release process validates changes before production
• Easy rollback if issues arise (just revert the upload command)

Alternative Considerations

If file count on release page becomes an issue:

Consider implementing Option 2 (archives) in a future iteration:

1. Create platform-specific archives in build workflow
2. Upload archives as release assets
3. Update release notes with extraction instructions

This can be done as a follow-up enhancement without breaking current functionality.

Related Files

• .github/workflows/build.yml - No changes required (already correct)
• .github/workflows/release.yml - Primary changes
• README.md - Consider updating installation instructions
• Release notes template in workflow - Updates required

Success Criteria

✅ GitHub release contains all necessary files for each platform
✅ Downloaded executables run without "missing configuration" errors
✅ Release page clearly documents which files are needed
✅ Consistency with Homebrew bottle structure maintained
✅ No breaking changes to existing workflows

---

Document Version: 1.0
Created: October 10, 2025
Status: Ready for Implementation

[sirkirby]

This was completed in the v0.3.0 release