brightdigit
diff --git a/‎.claude/migration-to-bushelkit.md‎
Lines changed: 918 additions & 0 deletions b/‎.claude/migration-to-bushelkit.md‎
Lines changed: 918 additions & 0 deletions
diff --git a/‎.github/workflows/BushelCloud.yml‎
Lines changed: 27 additions & 27 deletions b/‎.github/workflows/BushelCloud.yml‎
Lines changed: 27 additions & 27 deletions
diff --git a/‎.swiftlint.yml‎
Lines changed: 1 addition & 1 deletion b/‎.swiftlint.yml‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎CLAUDE.md‎
Lines changed: 145 additions & 4 deletions b/‎CLAUDE.md‎
Lines changed: 145 additions & 4 deletions
diff --git a/‎Package.resolved‎
Lines changed: 12 additions & 12 deletions b/‎Package.resolved‎
Lines changed: 12 additions & 12 deletions
diff --git a/‎Package.swift‎
Lines changed: 6 additions & 4 deletions b/‎Package.swift‎
Lines changed: 6 additions & 4 deletions
diff --git a/‎README.md‎
Lines changed: 19 additions & 0 deletions b/‎README.md‎
Lines changed: 19 additions & 0 deletions
diff --git a/‎Sources/BushelCloudCLI/Commands/ClearCommand.swift‎
Lines changed: 3 additions & 1 deletion b/‎Sources/BushelCloudCLI/Commands/ClearCommand.swift‎
Lines changed: 3 additions & 1 deletion
diff --git a/‎Sources/BushelCloudCLI/Commands/ExportCommand.swift‎
Lines changed: 1 addition & 0 deletions b/‎Sources/BushelCloudCLI/Commands/ExportCommand.swift‎
Lines changed: 1 addition & 0 deletions
@@ -37,32 +37,32 @@ jobs:
           verbose: true
           token: ${{ secrets.CODECOV_TOKEN }}
           files: ${{ join(fromJSON(steps.coverage-files.outputs.files), ',') }}
-  build-windows:
-    name: Build on Windows
-    runs-on: ${{ matrix.runs-on }}
-    if: "!contains(github.event.head_commit.message, 'ci skip')"
-    strategy:
-      fail-fast: false
-      matrix:
-        runs-on: [windows-2022, windows-2025]
-        swift:
-          - version: swift-6.2-release
-            build: 6.2-RELEASE
-    steps:
-      - uses: actions/checkout@v4
-      - uses: brightdigit/swift-build@v1.3.3
-        with:
-          windows-swift-version: ${{ matrix.swift.version }}
-          windows-swift-build: ${{ matrix.swift.build }}
-      - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v5
-        with:
-          fail_ci_if_error: true
-          flags: swift-${{ matrix.swift.version }},windows
-          verbose: true
-          token: ${{ secrets.CODECOV_TOKEN }}
-          os: windows
-          swift_project: BushelCloud-Package
+  # build-windows:
+  #   name: Build on Windows
+  #   runs-on: ${{ matrix.runs-on }}
+  #   if: "!contains(github.event.head_commit.message, 'ci skip')"
+  #   strategy:
+  #     fail-fast: false
+  #     matrix:
+  #       runs-on: [windows-2022, windows-2025]
+  #       swift:
+  #         - version: swift-6.2-release
+  #           build: 6.2-RELEASE
+  #   steps:
+  #     - uses: actions/checkout@v4
+  #     - uses: brightdigit/swift-build@v1.3.3
+  #       with:
+  #         windows-swift-version: ${{ matrix.swift.version }}
+  #         windows-swift-build: ${{ matrix.swift.build }}
+  #     - name: Upload coverage to Codecov
+  #       uses: codecov/codecov-action@v5
+  #       with:
+  #         fail_ci_if_error: true
+  #         flags: swift-${{ matrix.swift.version }},windows
+  #         verbose: true
+  #         token: ${{ secrets.CODECOV_TOKEN }}
+  #         os: windows
+  #         swift_project: BushelCloud-Package
   build-macos:
     name: Build on macOS
     env:
@@ -143,7 +143,7 @@ jobs:
     name: Linting
     if: "!contains(github.event.head_commit.message, 'ci skip')"
     runs-on: ubuntu-latest
-    needs: [build-ubuntu, build-macos, build-windows]
+    needs: [build-ubuntu, build-macos] # , build-windows]
     env:
       MINT_PATH: .mint/lib
       MINT_LINK_PATH: .mint/bin
 
@@ -116,7 +116,7 @@ excluded:
   - .build
   - Mint
   - Examples
-  - Sources/MistKit/Generated
+  - Packages
 indentation_width:
   indentation_width: 2
 file_name:
 
@@ -54,6 +54,32 @@ export CLOUDKIT_CONTAINER_ID="iCloud.com.yourcompany.Bushel"  # Optional, has de
 
 ## Architecture
 
+### Modular Architecture with BushelKit
+
+Starting with v0.0.1, BushelCloud uses **BushelKit** as a modular foundation:
+
+**BushelKit** (`Packages/BushelKit/`):
+- `BushelFoundation` - Core domain models (RestoreImageRecord, XcodeVersionRecord, SwiftVersionRecord)
+- `BushelUtilities` - Shared utilities (FormattingHelpers, JSONDecoder extensions)
+- `BushelLogging` - Logging abstractions
+
+**BushelCloudKit** (`Sources/BushelCloudKit/`):
+- Extends BushelKit models with CloudKit integration
+- `Extensions/*+CloudKit.swift` - CloudKitRecord protocol conformance
+- `DataSources/` - API fetchers (IPSW, AppleDB, MESU, etc.)
+- `CloudKit/` - SyncEngine and service layer
+
+**Dependency Flow**:
+```
+BushelCloudCLI → BushelCloudKit → BushelFoundation → BushelUtilities → MistKit
+```
+
+**Why This Architecture**:
+- Domain models reusable across projects (BushelKit can evolve independently)
+- CloudKit logic isolated to extensions (clean separation)
+- Shared utilities promote consistency
+- Testing each layer independently
+
 ### Core Data Flow
 
 The application follows a pipeline architecture:
@@ -81,11 +107,18 @@ External Data Sources → DataSourcePipeline → CloudKitService → CloudKit
 - `DataSourcePipeline.swift` - Coordinates fetching from all sources with metadata tracking
 - Individual fetchers: `IPSWFetcher`, `AppleDBFetcher`, `MESUFetcher`, `XcodeReleasesFetcher`, etc.
 
-**Models** (`Sources/BushelCloud/Models/`):
-- `RestoreImageRecord` - macOS restore images (IPSW files for virtualization)
-- `XcodeVersionRecord` - Xcode releases with references to RestoreImage and SwiftVersion
+**Models** (`Packages/BushelKit/Sources/BushelFoundation/`):
+- `RestoreImageRecord` - macOS restore images (uses `URL` and `Int` types)
+- `XcodeVersionRecord` - Xcode releases with CKReference relationships
 - `SwiftVersionRecord` - Swift compiler versions
-- `DataSourceMetadata` - Tracks fetch timestamps and throttling
+- `DataSourceMetadata` - Fetch metadata with timestamp tracking
+
+**CloudKit Extensions** (`Sources/BushelCloudKit/Extensions/`):
+- `RestoreImageRecord+CloudKit.swift` - Implements CloudKitRecord protocol
+- `XcodeVersionRecord+CloudKit.swift` - Handles CKReference serialization
+- `SwiftVersionRecord+CloudKit.swift` - Basic CloudKit mapping
+- `DataSourceMetadata+CloudKit.swift` - Metadata sync record
+- `FieldValue+URL.swift` - URL ↔ STRING conversion
 
 **Commands** (`Sources/BushelCloud/Commands/`):
 - CLI commands using swift-argument-parser
@@ -122,6 +155,59 @@ The project uses structured logging with `BushelLogger` (wrapping `os.Logger`):
 - **Verbose logs** (`--verbose`): MistKit API calls, batch details
 - **Subsystems**: `.sync`, `.cloudKit`, `.dataSource`
 
+## Git Subrepo Development
+
+BushelKit is embedded as a git subrepo for rapid development during the migration phase.
+
+### Configuration
+- **Remote:** `git@github.com:brightdigit/BushelKit.git`
+- **Branch:** `bushelcloud`
+- **Location:** `Packages/BushelKit/`
+
+### Making Changes to BushelKit
+
+```bash
+# 1. Edit files in Packages/BushelKit/
+vim Packages/BushelKit/Sources/BushelFoundation/RestoreImageRecord.swift
+
+# 2. Commit changes in BushelCloud repository
+git add Packages/BushelKit/
+git commit -m "Update BushelKit: add field documentation"
+
+# 3. Push changes to BushelKit repository
+git subrepo push Packages/BushelKit
+```
+
+### Pulling Updates from BushelKit
+
+```bash
+git subrepo pull Packages/BushelKit
+```
+
+### When to Switch to Remote Dependency
+
+| Development Stage | Approach | Package.swift |
+|-------------------|----------|---------------|
+| Now (active migration) | Git subrepo (local path) | `.package(path: "Packages/BushelKit")` |
+| After BushelKit v2.0 stable | Remote dependency | `.package(url: "https://github.com/brightdigit/BushelKit.git", from: "2.0.0")` |
+
+**Benefits of Subrepo Now:**
+- Edit BushelKit and BushelCloud together
+- Test integration immediately
+- No version coordination overhead
+
+**Migration to Remote:**
+1. Tag stable BushelKit version
+2. Update `Package.swift` to use URL dependency
+3. Remove `Packages/BushelKit/` directory
+4. Use standard SPM workflow
+
+### Best Practices
+- Commit BushelKit changes separately from BushelCloud changes
+- Push to subrepo after each logical change
+- Pull before starting new work
+- Test both repositories after changes
+
 ## Development Essentials
 
 ### Swift 6 Configuration
@@ -135,6 +221,61 @@ The project uses strict Swift 6 concurrency checking (see `Package.swift:10-78`)
 
 **When adding code**: Ensure all new types conform to `Sendable` and use `async/await` patterns consistently.
 
+### Type Design Decisions
+
+#### Int vs Int64 for File Sizes
+
+**Decision:** All models use `Int` for byte counts (fileSize fields)
+
+**Rationale:**
+- All supported platforms are 64-bit (macOS 14+, iOS 17+, watchOS 10+)
+- On 64-bit systems: `Int` == `Int64` (same size and range)
+- Swift convention: use `Int` for counts, sizes, and indices
+- CloudKit automatically converts via `.int64(fileSize)`
+
+**Safety Analysis:**
+- Largest image file: ~15 GB
+- `Int.max` on 64-bit: 9,223,372,036,854,775,807 bytes (~9 exabytes)
+- **No overflow risk** for any realistic file size
+
+**CloudKit Integration:**
+```swift
+// Write to CloudKit
+fields["fileSize"] = .int64(record.fileSize)  // Auto-converts Int → Int64
+
+// Read from CloudKit
+let size: Int? = recordInfo.fields["fileSize"]?.intValue  // Returns Int
+```
+
+#### URL Type for Download Links
+
+**Decision:** Models use `URL` (not `String`) for download links
+
+**Benefits:**
+- Type safety at compile time
+- URL component access (scheme, host, path, query)
+- Automatic validation on creation
+- Custom `FieldValue(url:)` extension handles CloudKit STRING conversion
+
+**CloudKit Integration:**
+```swift
+// Extension: Sources/BushelCloudKit/Extensions/FieldValue+URL.swift
+public extension FieldValue {
+  init(url: URL) {
+    self = .string(url.absoluteString)
+  }
+
+  var urlValue: URL? {
+    if case .string(let value) = self {
+      return URL(string: value)
+    }
+    return nil
+  }
+}
+```
+
+**Tests:** See `Tests/BushelCloudTests/Extensions/FieldValueURLTests.swift` (13 test methods)
+
 ### CloudKitRecord Protocol
 
 All domain models conform to `CloudKitRecord`:
 
@@ -91,9 +91,9 @@ let package = Package(
         .executable(name: "bushel-cloud", targets: ["BushelCloudCLI"])
     ],
     dependencies: [
-        .package(url: "https://github.com/brightdigit/MistKit.git", from: "1.0.0-alpha.3"),
+        .package(url: "https://github.com/brightdigit/MistKit.git", from: "1.0.0-alpha.3"),        
+        .package(url: "https://github.com/brightdigit/BushelKit.git", branch: "v3.0.0-alpha.2"),
         .package(url: "https://github.com/brightdigit/IPSWDownloads.git", from: "1.0.0"),
-        .package(url: "https://github.com/brightdigit/BushelKit.git", from: "3.0.0-alpha.1"),
         .package(url: "https://github.com/scinfu/SwiftSoup.git", from: "2.6.0"),
         .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.5.0")
     ],
@@ -102,9 +102,11 @@ let package = Package(
             name: "BushelCloudKit",
             dependencies: [
                 .product(name: "MistKit", package: "MistKit"),
+                .product(name: "BushelLogging", package: "BushelKit"),
+                .product(name: "BushelFoundation", package: "BushelKit"),
+                .product(name: "BushelUtilities", package: "BushelKit"),
                 .product(name: "IPSWDownloads", package: "IPSWDownloads"),
-                .product(name: "SwiftSoup", package: "SwiftSoup"),
-                .product(name: "BushelLogging", package: "BushelKit")
+                .product(name: "SwiftSoup", package: "SwiftSoup")
             ],
             swiftSettings: swiftSettings
         ),
 
@@ -97,6 +97,25 @@ BushelCloud/
     └── ExportCommand.swift
 ```
 
+### BushelKit Integration
+
+BushelCloud uses [BushelKit](https://github.com/brightdigit/BushelKit) as its modular foundation, providing:
+
+**Core Modules:**
+- **BushelFoundation** - Domain models (RestoreImageRecord, XcodeVersionRecord, SwiftVersionRecord)
+- **BushelUtilities** - Formatting helpers, JSON decoding, console output
+- **BushelLogging** - Unified logging abstractions
+
+**Current Integration:**
+- Git subrepo at `Packages/BushelKit/` for rapid development
+- Local path dependency during migration phase
+
+**Future:**
+- After BushelKit v2.0 stable release → versioned remote dependency
+- BushelKit will support VM management features
+
+**Documentation:** [BushelKit Docs](https://docs.getbushel.app/docc)
+
 ## Features Demonstrated
 
 ### MistKit Capabilities
 
@@ -29,6 +29,8 @@
 
 import ArgumentParser
 import BushelCloudKit
+import BushelFoundation
+import BushelUtilities
 import Foundation
 
 struct ClearCommand: AsyncParsableCommand {
@@ -69,7 +71,7 @@ struct ClearCommand: AsyncParsableCommand {
 
   mutating func run() async throws {
     // Enable verbose console output if requested
-    ConsoleOutput.isVerbose = verbose
+    BushelUtilities.ConsoleOutput.isVerbose = verbose
 
     // Get Server-to-Server credentials from environment if not provided
     let resolvedKeyID =
 
@@ -29,6 +29,7 @@
 
 import ArgumentParser
 import BushelCloudKit
+import BushelFoundation
 import Foundation
 import MistKit