framna-dk/tartelet

1. What this repo is

Tartelet is a macOS app that manages up to two ephemeral GitHub Actions runners inside Tart virtual machines. The core architectural loop is: clone VM, boot VM, SSH in, register GitHub runner, wait for job, deregister, shut down, delete VM, repeat.

2. Top-level app structure

The Tartelet app target is a thin composition root. AppDelegate.swift, TarteletApp.swift, and Composers.swift wire together the feature packages and platform services. Most behavior lives in Swift packages rather than in the app target itself.

3. Layering pattern across packages

Most subsystems follow a consistent split: *Domain defines protocols, models, and orchestration logic; *Data provides concrete implementations; *UI exists where user-facing configuration is needed. This keeps core behavior testable and lets the app swap implementations at the boundary.

4. Virtual machine orchestration is the centerpiece

Packages/VirtualMachine owns the lifecycle of runner machines. Its domain types (VirtualMachine, VirtualMachineFleet, VirtualMachineState, VirtualMachineEditor) model the fleet and its state transitions. The data layer provides Tart-backed implementations such as TartVirtualMachine, Tart, TartLocator, and TartHomeProvider.

5. How a VM becomes a runner

The VM flow is coordinated through SSH-related abstractions in VirtualMachineDomain/SSH plus runner-specific handlers in GitHubActionsRunner. After boot, the app waits for network/SSH readiness, then runs post-boot setup and GitHub runner setup inside the VM. The handlers are composed so the VM can run generic setup scripts and the GitHub Actions registration flow in sequence.

6. SSH is the execution bridge into the VM

Packages/SSH wraps remote command execution behind SSHClient and SSHConnection abstractions. Packages/VirtualMachine builds on that with VirtualMachineSSHClient, SSHConnectionWaiter, RetryingVirtualMachineIPAddressReader, and TaskSSHConnectionWaiter to handle boot-time uncertainty and delayed availability of the guest.

7. GitHub integration is isolated behind its own package

Packages/GitHub owns authentication and runner registration with GitHub. The domain layer defines GitHubClient, GitHubCredentialsStore, GitHubJWTTokenFactory, GitHubAppAccessToken, and GitHubRunnerRegistrationToken. The data layer uses NetworkingGitHubClient and KeychainGitHubCredentialsStore to talk to GitHub’s API and persist credentials securely.

8. Secrets and key material live in the keychain

Runner registration depends on private keys and GitHub app credentials, so those are stored via Packages/Keychain. The package provides low-level key/password queries plus RSAPrivateKey handling. This is a hard boundary: sensitive GitHub app material is not treated as ordinary app settings.

9. Settings are both persisted and user-configurable

Packages/Settings contains the app’s settings model, storage, and SwiftUI screens. SettingsDomain defines the configuration state, virtual machine selection, GitHub runner settings, and application UI mode; SettingsData persists settings via AppStorageSettingsStore; SettingsUI provides the actual settings scenes and pickers.

10. Menu bar is the primary user surface

Packages/MenuBar supplies the status/menu bar UI. It contains menu bar items and content that likely reflect the current fleet state and expose quick actions. This package is separate from settings, so ongoing fleet control and configuration are decoupled.

11. Logging and diagnostics are file-based

Packages/Logging defines a generic logging interface and a file exporter. FileLogger and FileLogExporter write logs to disk using LogsDirectory and a date provider. This is useful for diagnosing VM boot, SSH, and GitHub registration failures outside the UI.

12. Supporting infrastructure packages

Packages/Shell abstracts local process execution, which is likely used for calling Tart and other command-line tools. Packages/FileSystem abstracts disk access and coordination. Packages/Networking wraps URLSession and response handling for HTTP interactions, primarily serving the GitHub client.

13. Build and repo tooling

The project is organized as an XcodeGen-generated macOS app with multiple Swift packages. SwiftGen generates resource and localization constants, and SwiftLint enforces style in CI. These tools shape the repo, but they do not materially change the runtime architecture.

14. Key architectural boundaries to show in a diagram

The important diagram boundaries are: UI/composition root in the app target; settings and menu bar presentation; VM orchestration; SSH execution into guests; GitHub API/auth; local persistence in keychain and file system; and external dependencies on Tart, GitHub Actions, and the host macOS runtime.