Phase 0: Module Foundation

[leogdion]

Phase 0: Module Foundation

Related Issue: #199 - Enable Remote Debugging
Timeline: Week 1
Priority: Critical (Foundational)
Packages Modified: bushelkit, bushelapp
POC Focus: Create protocol modules and establish dependencies

Overview

Establish the foundational module structure and shared protocol definitions required by all subsequent phases. This phase creates the BushelHarvestProtocol module in BushelKit (shared between host and guest) and sets up the host-side module skeleton in BushelApp.

Goals

• Create BushelHarvestProtocol target in BushelKit with shared protocol definitions
• Create BushelHarvestHostCore target in BushelApp
• Create BushelHarvestHost target in BushelApp
• Add BushelHarvestHost dependency to BushelMachineViews
• Update HarvestBinKit to depend on BushelHarvestProtocol from BushelKit
• Integrate modules into BushelApp product
• Verify module structure and dependencies

Dependencies

Requires: None (foundational phase)
Blocks:

• Phase 1: Remote Access
• Phase 2: System Profiling
• Phase 3: VirtioSocket Communication
• Phase 4: Command Protocol
• Phase 5: Integration Features
• Phase 6: UI & Polish

Implementation Tasks

BushelKit - Shared Protocol Module

• Create BushelHarvestProtocol target in BushelKit

  • Location: Packages/BushelKit/Sources/BushelHarvestProtocol/
  • Dependencies: BushelFoundation, BushelLogging

• Implement protocol files:

  • CommandProtocol.swift - Message format and command type definitions
  • MessageTypes.swift - Request/response/event message structures
  • SecurityTypes.swift - Authentication and authorization types
  • HarvestCommand.swift - Command definitions and payload structures

• Export BushelHarvestProtocol as BushelKit product

  • Update Packages/BushelKit/Package.swift
  • Add .library(name: "BushelHarvestProtocol", targets: ["BushelHarvestProtocol"])

BushelApp - Host-Side Modules

• Create BushelHarvestHostCore target using PackageDSL

  • Location: Create Packages/BushelApp/Package/Sources/Targets/BushelHarvestHostCore.swift
  • Dependencies: BushelFoundation, BushelLogging, BushelHarvestProtocol (from BushelKit), BushelGuestProfile, BushelMachine

• Create BushelHarvestHost target using PackageDSL

  • Location: Create Packages/BushelApp/Package/Sources/Targets/BushelHarvestHost.swift
  • Dependencies: BushelFoundation, BushelLogging, BushelHarvestProtocol (from BushelKit), BushelHarvestHostCore, BushelMachine, BushelServiceClient

• Update BushelMachineViews target to depend on BushelHarvestHost

  • Location: Edit Packages/BushelApp/Package/Sources/Targets/BushelMachineViews.swift
  • Add dependency: BushelHarvestHost()

• Create source directories:

  • Packages/BushelApp/Sources/BushelHarvestHostCore/
  • Packages/BushelApp/Sources/BushelHarvestHost/

• Create placeholder files to verify structure:

  • BushelHarvestHostCore/VMDiscoveryService.swift (empty protocol)
  • BushelHarvestHostCore/HarvestConnectionManager.swift (empty protocol)
  • BushelHarvestHostCore/HarvestAuthenticationService.swift (empty protocol)
  • BushelHarvestHost/HarvestManager.swift (empty protocol)
  • BushelHarvestHost/CommandDispatcher.swift (empty protocol)
  • BushelHarvestHost/HarvestCommandService.swift (empty protocol)

HarvestBinKit - Guest-Side Dependencies

• Update HarvestBinKit Package.swift to depend on BushelHarvestProtocol
  • Location: Packages/HarvestBin/Packages/HarvestBinKit/Package.swift
  • Add dependency: .package(path: "../../../../BushelKit")
  • Add target dependency: .product(name: "BushelHarvestProtocol", package: "BushelKit")

Package Generation

• Regenerate BushelApp Package.swift

  • Run: make generate-packages
  • Verify all new targets appear in generated Package.swift

• Regenerate Xcode project

  • Run: make xcodeproject
  • Verify new modules appear in Xcode project navigator

Integration

• Integrate modules into BushelApp product

  • Modules are automatically discovered by PackageDSL through dependency traversal
  • Verify BushelHarvestHost is accessible to BushelMachineViews

• Verify build succeeds

  • Build BushelApp scheme in Xcode
  • Ensure no compilation errors

Success Criteria

• BushelHarvestProtocol module exists in BushelKit with all protocol files
• BushelHarvestProtocol is exported as a BushelKit product
• BushelHarvestHostCore target is defined and has source directory
• BushelHarvestHost target is defined and has source directory
• BushelMachineViews depends on BushelHarvestHost
• HarvestBinKit depends on BushelHarvestProtocol from BushelKit
• Package.swift regeneration succeeds without errors
• Xcode project regeneration succeeds without errors
• BushelApp scheme builds successfully
• All placeholder files compile (empty protocols/classes)
• Module dependency graph is correct (verified via Xcode project)

Technical Details

Module Dependency Graph

BushelMachineViews (includes Harvest UI)
  └── BushelHarvestHost
        ├── BushelHarvestHostCore
        │     ├── BushelHarvestProtocol (BushelKit - shared)
        │     ├── BushelGuestProfile (BushelKit)
        │     └── BushelMachine (BushelKit)
        └── BushelServiceClient

HarvestBinKit (guest-side)
  └── BushelHarvestProtocol (BushelKit - shared)

PackageDSL Target Definition Example

// Packages/BushelApp/Package/Sources/Targets/BushelHarvestHostCore.swift
struct BushelHarvestHostCore: Target {
  var dependencies: any Dependencies {
    BushelFoundation()
    BushelLogging()
    BushelHarvestProtocol() // From BushelKit
    BushelGuestProfile()
    BushelMachine()
  }
}

BushelHarvestProtocol Example Structure

// CommandProtocol.swift
public protocol HarvestCommand: Codable, Sendable {
  var action: String { get }
  var category: CommandCategory { get }
  var payload: [String: Any] { get }
}

public enum CommandCategory: String, Codable, Sendable {
  case system
  case file
  case network
  case clipboard
  case remote
}

Testing

• Verify BushelKit builds independently with new protocol module
• Verify BushelApp builds with new Harvest modules
• Verify HarvestBinKit can import BushelHarvestProtocol
• Verify no circular dependencies exist
• Verify PackageDSL correctly discovers all modules

References

• Package Architecture
• Host Implementation Guide
• Guest Implementation Guide
• Module Definitions

Notes

• This phase establishes the foundation for all Harvest functionality
• No actual functionality is implemented, only structure
• Protocol definitions should be minimal and can be expanded in later phases
• Focus on getting the module structure correct before adding implementation
• Ensure shared protocol is truly shared (both host and guest use same definitions)

---

Related Issues:

• Main implementation: brightdigit/Bushel#285

[leogdion]

✅ Phase 0 Implementation Complete

Status Update: The Phase 0 module foundation work has been completed and merged.

✅ Completed Work

BushelKit - Shared Module:

• ✅ BushelHarvestCore module created (note: named BushelHarvestCore instead of BushelHarvestProtocol)
• ✅ Shared protocol definitions and command types
• ✅ Exported as BushelKit product
• ✅ Used by both BushelApp (host-side) and HarvestBin (guest-side)

Evidence:

• Used in BushelApp: Packages/BushelApp/Sources/BushelHarvestHost/ (imports BushelHarvestCore)
• Used in HarvestBin: Packages/HarvestBinKit/Package.swift (depends on BushelHarvestCore from BushelKit)
• PackageDSL definition: Packages/BushelApp/Package/Sources/Dependencies/BushelKit/BushelHarvestCore.swift

Related Issues

Main Repo (brightdigit/Bushel):

• #285 - Phase 0: Module Foundation ✅ CLOSED
• #286 - Phase 1: Remote Access ✅ CLOSED
• #306 - Phase 1.5: HarvestBin Integration 🚧 IN PROGRESS

HarvestBin Subrepo:

• #6 - Phase 1: Remote Access - Being updated

---

This issue can be closed as the foundational module structure is complete and in use.

[leogdion]

✅ Closing Issue #154 - Phase 0 Module Foundation Complete

All foundational module structure has been implemented and is in use.

✅ Delivered

• BushelHarvestCore module created in BushelKit
• Shared protocol definitions and command types
• Exported as BushelKit product
• Integrated into both BushelApp (host-side) and HarvestBin (guest-side)
• PackageDSL definitions complete

Evidence

• Used throughout BushelHarvestHost implementation (32 files)
• HarvestBinKit depends on BushelHarvestCore
• All modules build and compile successfully

---

Status: Phase 0 complete ✅ | Enabled Phase 1 implementation