feat: Add Examples CI workflow for PRs

[leogdion]

Summary

Add GitHub Actions workflow to build and test the Examples directory on pull requests to the v1.0.0-alpha.4 branch. This ensures examples stay compatible with MistKit API changes.

Features

• Tests MistDemo, BushelCloud, and CelestraCloud examples
• Matrix strategy with fail-fast: false for independent testing
• Platform-specific runners:
  • MistDemo: ubuntu-latest, macos-latest
  • BushelCloud: ubuntu-latest, macos-latest
  • CelestraCloud: macos-26 (requires macOS 26+)
• Swift 6.2 support across all examples
• CI skip support via commit message (ci skip)
• Codecov integration with per-example flags
• Working directory handling for Examples subdirectories

Matrix Configuration

The workflow creates 5 jobs:

1. MistDemo on ubuntu-latest
2. MistDemo on macos-latest
3. BushelCloud on ubuntu-latest
4. BushelCloud on macos-latest
5. CelestraCloud on macos-26

Codecov Flags

Each example gets its own flag for coverage tracking:

• MistDemo-swift-6.2-ubuntu-latest
• MistDemo-swift-6.2-macos-latest
• BushelCloud-swift-6.2-ubuntu-latest
• BushelCloud-swift-6.2-macos-latest
• CelestraCloud-swift-6.2-macos-26

Implementation Notes

• Workflow currently triggers on PRs to v1.0.0-alpha.4 branch
• Before merging to main, update trigger to branches: [main]
• Uses brightdigit/swift-build@v1.5.0-beta.2 action with working-directory support
• Follows same pattern as MistKit.yml for consistency

Testing & Verification

• Workflow file created at .github/workflows/examples.yml
• Verified all examples have test targets
• Matrix includes proper OS for each example
• Uses same build action and coverage pattern as MistKit.yml
• Verify workflow triggers on this PR
• Check all 5 matrix jobs run successfully

Future Enhancements

• Multi-Swift version testing (6.1, 6.2, 6.3 nightly)
• Custom continue-on-error for nightly builds
• Update trigger to main branch when ready

🤖 Generated with Claude Code

---

Perform an AI-assisted review on

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

• 🔍 Trigger a full review

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch add-examples-ci-workflow

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 17.88%. Comparing base (88f1e02) to head (84137c8).
⚠️ Report is 23 commits behind head on v1.0.0-alpha.4.

Additional details and impacted files

@@                Coverage Diff                 @@
##           v1.0.0-alpha.4     #233      +/-   ##
==================================================
+ Coverage           14.27%   17.88%   +3.60%     
==================================================
  Files                  67       78      +11     
  Lines                7179     7829     +650     
==================================================
+ Hits                 1025     1400     +375     
- Misses               6154     6429     +275     

Flag	Coverage Δ
spm	17.88% <ø> (+3.60%)	⬆️
swift-6.1-jammy	17.88% <ø> (+3.60%)	⬆️
swift-6.1-noble	17.88% <ø> (+3.60%)	⬆️
swift-6.2-jammy	17.88% <ø> (+3.60%)	⬆️
swift-6.2-jammynightly	?
swift-6.2-noble	17.88% <ø> (+3.60%)	⬆️
swift-6.2-noblenightly	?
swift-6.3-jammynightly	17.88% <ø> (?)
swift-6.3-noblenightly	17.88% <ø> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[claude]

Code Review: Examples CI Workflow

I've reviewed PR #233 and found several critical issues that need to be addressed before merging.

---

🔴 Critical Issues

1. Matrix Configuration Logic Error

The matrix configuration has a fundamental flaw. Lines 17-30 define:

• matrix.example with 3 values: [MistDemo, BushelCloud, CelestraCloud]
• matrix.swift.version with 1 value: "6.2"

Then the include section adds 5 entries with specific example + os combinations.

Problem: This creates a Cartesian product resulting in 15 jobs (3 examples × 1 Swift version × 5 include entries), not the intended 5 jobs.

Fix: Remove the base example array and use only the include section. Reference: Main MistKit.yml workflow (lines 134-183) uses this pattern correctly.

2. Platform Compatibility Issue: CelestraCloud

Problem: CelestraCloud requires macOS 26+ across ALL platforms (macOS, iOS, tvOS, watchOS, visionOS). The workflow uses type: "" (line 41), which defaults to SPM build mode.

• ✅ macOS-26 runner works - It has macOS 26 SDK
• ❌ ubuntu-latest fails - Linux doesn't support iOS/tvOS/watchOS/visionOS platforms in Package.swift

Fix: Remove CelestraCloud from ubuntu/Linux testing entirely.

3. Missing Tests Directory

Glob search for Examples/*/Tests returns no results. Examples/MistDemo/Package.swift:117-125 shows a testTarget exists, but verify the Tests directory is in the repo.

---

⚠️ Medium Priority Issues

4. Codecov Flags Pattern Inconsistency

The main MistKit.yml uses different flag patterns than this PR. Consider aligning for consistency.

5. Missing working-directory in Coverage Step

Line 48 specifies working-directory for the coverage action. Verify that sersoft-gmbh/swift-coverage-action@v4 supports this parameter.

6. Branch Trigger Strategy

Consider using path filters to prevent unnecessary CI runs when Examples aren't affected.

---

✅ Positive Aspects

1. Good separation of concerns - Examples have their own workflow
2. Proper use of fail-fast: false - Examples can fail independently
3. Consistent action versions - Uses same brightdigit/swift-build as main workflow
4. Coverage integration - Matches main workflow's Codecov setup
5. CI skip support - Respects commit message convention

---

📋 Recommendations Before Merging:

1. ✅ Fix matrix configuration (use only include, remove base example array)
2. ✅ Remove CelestraCloud from ubuntu-latest (platform incompatibility)
3. ✅ Verify Tests directories exist or document their absence
4. ✅ Test the corrected workflow on a test branch
5. ✅ Update branch trigger from v1.0.0-alpha.4 to main

---

📖 Reference Files

• Main workflow: .github/workflows/MistKit.yml:8-242
• MistDemo package: Examples/MistDemo/Package.swift:79-128
• CelestraCloud platforms: Examples/CelestraCloud/Package.swift

The workflow structure is sound, but the matrix configuration and platform compatibility issues must be fixed to avoid CI failures.

🤖 Review generated by Claude Code

[claude]

PR Review: Add Examples CI workflow for PRs

Thank you for this contribution! I've reviewed the workflow and have feedback across several areas.

---

Strengths

1. Good Structure: The workflow follows the established pattern from MistKit.yml with proper job naming, fail-fast strategy, and codecov integration
2. Working Directory Support: Correctly uses working-directory parameter for building examples in subdirectories
3. Matrix Strategy: Uses fail-fast: false to allow independent testing of each example
4. CI Skip Support: Includes the standard ci skip commit message check
5. Platform-Specific Runners: Properly targets different OS platforms based on example requirements

---

Issues Found

1. CRITICAL: Incorrect OS Version (Blocking Issue)

Problem: The workflow uses macos-26 runners, which don't exist yet. GitHub Actions currently supports:

• macos-15 (macOS Sequoia with Xcode 16.x)
• macos-14 (macOS Sonoma with Xcode 15.x)
• macos-13 (macOS Ventura with Xcode 14.x)

Evidence from Package.swift files:

• MistDemo requires macOS 15
• BushelCloud requires macOS 15
• CelestraCloud requires macOS 26 (future platform!)

Impact: The workflow will fail immediately since macos-26 runners are not available.

Fix Required: For MistDemo and BushelCloud use macos-latest with Xcode 16.2. For CelestraCloud, temporarily exclude from CI until macOS 26 runners are available.

2. Xcode Version Mismatch

Problem: The workflow specifies Xcode_26.2.app which doesn't exist.

Available Xcode versions on macos-15: Xcode 16.4, 16.3, 16.2, 16.1

Fix: Use available Xcode like /Applications/Xcode_16.2.app

3. Platform Compatibility - CelestraCloud

CelestraCloud requires macOS 26 (Package.swift line 82), which is a future platform release.

Recommended: Temporarily exclude from CI with a comment explaining it will be added when macOS 26 runners are available.

4. Unused Swift Version in Matrix

Problem: Matrix defines swift.version: "6.2" but never uses it in the actual job configuration.

Recommendation: Remove the unused swift matrix variable to simplify configuration.

5. Codecov Flag Inconsistency

Issue: Flags reference non-existent runner versions and mix concerns.

Better approach: Use simpler flag names like examples-MistDemo-macos-latest following MistKit.yml pattern.

---

Recommendations

High Priority

1. Fix runner versions: Change macos-26 to macos-latest
2. Fix Xcode paths: Use available Xcode versions (16.2, 16.3, 16.4)
3. Handle CelestraCloud: Temporarily exclude
4. Simplify matrix: Remove unused swift.version variable

Medium Priority

1. Branch trigger: Change from v1.0.0-alpha.4 to main before merging
2. Codecov flags: Use simpler, more semantic flag names
3. Add timeout-minutes: Prevent hung jobs (30 minutes recommended)

---

Security Considerations

No security issues found:

• Uses official GitHub actions
• Uses trusted third-party actions
• Properly scoped secrets
• No arbitrary code execution risks

---

Testing Recommendations

Before merging:

1. Verify runner availability
2. Test each example builds locally
3. Check Xcode paths exist on runners
4. Validate codecov integration
5. Test workflow triggers on PR branch

---

Reference

• GitHub Runner Images: https://github.com/actions/runner-images
• Available macOS Runners: https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners
• MistKit.yml: Lines 125-210 for macOS matrix pattern

---

Next Steps

1. Address CRITICAL issues (runner versions, Xcode paths)
2. Decide on CelestraCloud strategy
3. Update branch trigger to main
4. Test workflow on draft PR
5. Request re-review

Please let me know if you'd like help implementing these changes!

[claude]

Pull Request Review

I've reviewed this PR and found several critical issues that need to be addressed before merging.

---

Critical Issues

1. Platform Incompatibility

The workflow runs all three examples on Ubuntu with swift:6.2-noble container, but the examples have incompatible platform requirements:

• MistDemo: .platforms: [.macOS(.v15)] - macOS v15+ only
• BushelCloud: .platforms: [.macOS(.v15), .iOS(.v18), ...] - macOS v15+ and Apple platforms
• CelestraCloud: .platforms: [.macOS(.v26), ...] - macOS v26+ only (cutting-edge)

Impact: All three examples will fail to build on Linux/Ubuntu because they declare macOS-only platform minimums. Swift Package Manager will reject them on Linux.

Solution: Remove platform restrictions OR split the matrix to run only compatible examples on each platform.

---

2. Mismatch Between Description and Implementation

The PR description claims 5 jobs across ubuntu-latest, macos-latest, and macos-26, but the actual workflow has only 1 job running all examples on Ubuntu only.

Solution: Implement the full matrix as described, or update description to match reality.

---

3. Missing Codecov Integration

The PR description mentions "Codecov integration with per-example flags" but the workflow has NO Codecov steps at all.

Solution: Add coverage processing/upload steps, or remove codecov claims from description.

---

4. CelestraCloud Cannot Run on Linux

CelestraCloud requires macOS v26+ which is only available on macos-26 GitHub runners. It cannot run on ubuntu-latest (the only runner in this workflow).

---

Code Quality Issues

5. Workflow Trigger is Temporary

Workflow only runs on PRs to v1.0.0-alpha.4. Description says to update to main before merge. This creates technical debt.

6. Missing Error Handling

Unlike MistKit.yml, this lacks continue-on-error, disk space management, caching, and timeout limits.

7. Unused Environment Variable

PACKAGE_NAME is never referenced. Should be used or removed.

---

Recommendations

Must Fix Before Merge:

1. Resolve platform incompatibility
2. Implement the described 5-job matrix
3. Add Codecov integration or remove claims
4. Update workflow trigger to main branch

Should Fix:
5. Add error handling and resource management
6. Add dependency caching
7. Align description with implementation

---

Summary

Overall Assessment: Needs Work

This PR has significant gaps between intent and implementation:

• Platform compatibility issues will cause immediate failures
• Missing coverage integration despite being claimed
• Workflow doesn't match the detailed description

Recommendation: Request changes to address critical issues 1-4 before merging.

---

Review generated with reference to CLAUDE.md project guidelines and MistKit.yml workflow patterns.

[claude]

Test comment from Claude Code review

[claude]

Code Review Part 1: Critical issue - PR description claims 5 jobs across ubuntu/macos platforms with Codecov, but actual workflow has only 1 job running all 3 examples on ubuntu-latest only. No macOS runners, no Codecov integration. This is a major mismatch that must be resolved before merging.

[claude]

Code Review Part 2: CelestraCloud platform issue - PR description states CelestraCloud requires macOS 26+, but workflow runs it on ubuntu-latest. This will likely fail if CelestraCloud has macOS-specific dependencies. Need to either exclude CelestraCloud from Ubuntu matrix or add macOS job as described.

[claude]

Code Review Part 3: Other findings - Missing test verification, using beta action version, branch trigger needs update before merge to main, no Codecov despite PR description. Workflow structure is clean with good fail-fast strategy. Recommend fixing description/implementation mismatch before merging.

[claude]

Pull Request Review: Examples CI Workflow

I've reviewed PR #233 and have several observations about code quality, potential issues, and architectural concerns.

---

🔴 Critical Issues

1. Incomplete Workflow Configuration

File: .github/workflows/examples.yml

The workflow is extremely minimal and doesn't follow the established patterns from MistKit.yml:

• Missing OS matrix: The PR description mentions testing on multiple platforms (Ubuntu + macOS, with CelestraCloud requiring macOS 26), but the workflow only defines Ubuntu
• No macOS jobs: According to the PR description, there should be 5 matrix jobs total, but only 1 is defined
• No codecov integration: Unlike MistKit.yml, there's no code coverage upload
• Incomplete configuration: The brightdigit/swift-build@v1.5.0-beta.2 action is used with only working-directory, missing all other configuration

Expected structure (based on PR description):

strategy:
  fail-fast: false
  matrix:
    include:
      - example: MistDemo
        runs-on: ubuntu-latest
        container: swift:6.2-noble
      - example: MistDemo
        runs-on: macos-latest
      - example: BushelCloud
        runs-on: ubuntu-latest
        container: swift:6.2-noble
      - example: BushelCloud
        runs-on: macos-latest
      - example: CelestraCloud
        runs-on: macos-26

2. Unverified Example Directories

The workflow assumes BushelCloud and CelestraCloud exist with valid test targets, but this isn't verified:

• Are these examples complete and buildable?
• Do they have test targets that can be run?
• Will they actually pass on the specified platforms?

3. Branch Trigger Mismatch

on:
  pull_request:
    branches: [v1.0.0-alpha.4]

• This only triggers for PRs targeting v1.0.0-alpha.4, not for main
• The PR description acknowledges this needs changing before merging to main
• Risk: Easy to forget to update this before merging

---

⚠️ Code Quality Issues

4. Test Helper Design - AnyCodable Extension

File: Examples/MistDemo/Tests/MistDemoTests/Types/AnyCodableTests.swift:238-271

The new AnyCodable.init(value:) test helper has architectural issues:

extension AnyCodable {
    /// Test helper that creates AnyCodable by encoding and decoding a value
    init(value: Any) throws {
        // ...
        if let stringValue = value as? String {
            jsonData = try JSONEncoder().encode(stringValue)
        } else if let intValue = value as? Int {
            // ... repeated if-else chain

Problems:

1. Overly complex: Uses encode-then-decode roundtrip instead of direct initialization
2. Limited types: Only handles String, Int, Double, Bool, NSNull
3. Not actually a test helper: This looks like it should be production code, not test code
4. Error-prone: If the real AnyCodable changes, tests might pass incorrectly because they're testing the mock implementation

Better approach:

• If AnyCodable needs this initializer, add it to production code
• If it's truly test-only, use simple value injection: self.value = value

5. Test Configuration Complexity

File: Examples/MistDemo/Tests/MistDemoTests/Helpers/MistDemoConfig+Testing.swift:51-113

The memberwise-style test initializer is overly complex:

func key(_ path: String) -> AbsoluteConfigKey {
    AbsoluteConfigKey(path.split(separator: ".").map(String.init), context: [:])
}

var values: [AbsoluteConfigKey: ConfigValue] = [
    key("container.identifier"): .init(stringLiteral: containerIdentifier),
    // ... 10 more entries
]

Issues:

1. Fragile: Hardcoded key paths ("container.identifier") are string-based, prone to typos
2. Maintenance burden: If key names change, this breaks silently
3. Unnecessary abstraction: The key() helper is used 15+ times

Suggestions:

• Consider exposing key constants from the production code
• Use configuration's native APIs if available
• Add tests that verify key paths match production usage

6. Accessibility Change Without Justification

File: Examples/MistDemo/Sources/ConfigKeyKit/CommandRegistry.swift:89-90

-    private init() {}
+    // Internal initializer for testability - allows tests to create isolated instances
+    internal init() {}

Concerns:

1. Breaking singleton pattern: CommandRegistry has static let shared, but now allows creating instances
2. Thread safety risk: If tests create multiple instances, the actor isolation benefit is lost
3. Production accessibility: internal means production code in other modules could misuse this

Better approach:

• Keep initializer private
• Use protocol abstraction for testing
• Or provide a reset() method for the shared instance

7. Public API Exposure

Files:

• Examples/MistDemo/Sources/ConfigKeyKit/ConfigKey.swift:102-104
• Examples/MistDemo/Sources/ConfigKeyKit/OptionalConfigKey.swift:116-118

+  /// The base key string used for this configuration key
+  public var base: String? { baseKey }

Questions:

1. Why is this public? No tests in this PR use it
2. Is baseKey intentionally exposed, or should it remain internal?
3. If added for testing, should it be marked @testable or documented for production use?

---

✅ Good Changes

8. MistKit.yml Cleanup

Removing the iOS 18.5 / iPhone 16e configuration and fixing OS versions from 26.0 → 26.2 is a good maintenance change.

9. Test Helper Consolidation

Moving the MistDemoConfig test extension from MistKitClientFactoryTests.swift to the dedicated MistDemoConfig+Testing.swift file improves organization.

10. Unused Test Code Removal

File: Examples/MistDemo/Tests/MistDemoTests/Utilities/AsyncHelpersTests.swift:772-784

Removing the operationCompleted flag and assertion is correct — the variable was never set to true before the timeout anyway due to the sleep duration.

---

🎯 Testing Concerns

11. No Verification of Workflow Execution

The PR checklist shows:

- [ ] Verify workflow triggers on this PR
- [ ] Check all 5 matrix jobs run successfully

These are unchecked, meaning:

• The workflow hasn't been tested in CI
• We don't know if it actually works
• The examples might not even compile

12. Breaking Changes to Test APIs

Multiple test helpers now throw, changing the test ergonomics:

-        let config = makeConfig(apiToken: "api-token-123")
+        let config = try makeConfig(apiToken: "api-token-123")

While technically correct (configuration can fail), consider:

• Should the default test config be infallible?
• Does every test really need try?
• Alternative: Provide both throwing and non-throwing variants

---

🔍 Security & Performance

13. No Security Issues Identified

The changes don't introduce security vulnerabilities.

14. Performance Considerations

• The _runBlocking pattern in tests (using DispatchSemaphore) is acceptable for tests but blocks a thread
• Consider using XCTestExpectation or Swift Testing's async support instead

---

📋 Recommendations

High Priority

1. Complete the workflow configuration to match the PR description (5 jobs across Ubuntu and macOS)
2. Add codecov integration like MistKit.yml
3. Verify all examples build and test before merging
4. Update branch trigger to main before merging

Medium Priority

5. Simplify the AnyCodable test helper or move to production code
6. Reconsider CommandRegistry.init() accessibility — preserve singleton pattern
7. Document or remove base property on ConfigKey types
8. Add key path constants to reduce fragility in test configuration

Low Priority

9. Consider providing non-throwing test config variant for ergonomics
10. Add inline documentation for why MistDemoConfiguration.init(testProvider:) is internal

---

Summary

Approve with changes: The PR has the right intent (CI for examples), but the workflow is incomplete and doesn't match its own description. The test infrastructure changes are generally good, but some design decisions (AnyCodable helper, CommandRegistry accessibility) need reconsideration.

Blocking issues:

• Workflow only defines 1 job instead of 5
• No verification that examples actually build/test
• Branch trigger needs updating

Recommendation: Request changes to complete the workflow configuration and verify it runs successfully before merging.

---

Review performed using repository CLAUDE.md conventions and Swift best practices.

[leogdion]

Clarification on Workflow Design

Several review comments suggest this workflow is incomplete or missing features (macOS runners, comprehensive coverage, multiple platforms). This is intentional by design.

Architecture

Main Repo (examples.yml): Simple smoke test

• Purpose: Ensure examples still compile when MistKit changes
• Scope: Ubuntu + Swift 6.2 only - quick feedback for MistKit PRs
• Philosophy: Minimal, fast checks

Subrepo Workflows: Comprehensive testing

• BushelCloud: Has .github/workflows/BushelCloud.yml with multi-OS (Ubuntu noble/jammy), multi-Swift (6.2, 6.3-nightly), coverage
• CelestraCloud: Has .github/workflows/CelestraCloud.yml with Ubuntu/Windows/macOS, multi-Swift versions, coverage, security scanning
• MistDemo: Tracked in issue Add comprehensive CI workflow for MistDemo example #239 - will add comprehensive workflow

Why This Approach?

1. Separation of concerns: MistKit's CI focuses on the library; example subrepos test their own complexity
2. Avoid duplication: Don't replicate comprehensive testing that already exists in subrepos
3. Fast feedback: Simple workflow gives quick signal without blocking on extensive multi-platform matrices
4. Scalability: New examples can be added to the simple smoke test easily

Notes on Review Comments

• "macos-26 doesn't exist" - It does exist (see main MistKit.yml workflow), but we intentionally don't use it here
• "Missing Codecov" - Codecov lives in the subrepo workflows
• "Only 1 job instead of 5" - Correct, we only need Ubuntu smoke test; comprehensive testing is in subrepos
• "Platform incompatibility" - All examples build on Ubuntu fine; they declare minimum macOS versions but SPM handles this on Linux

This PR is ready to merge now that the branch trigger has been updated to main.