Skip to content

HANDOFF_2026-02-03.md

Latest commit

聽

History

History
70 lines (54 loc) 路 3.02 KB

HANDOFF_2026-02-03.md

File metadata and controls

70 lines (54 loc) 路 3.02 KB
Raw

Handoff: Flying Dutchman (Feb 3, 2026)

To: Next Agent / Engineer From: Architect Agent Date: 2026-02-03 Status: 馃煛 Mid-Refactoring (Modularization)

1. Project Context

We are building Flying Dutchman, a native macOS container engine (OrbStack competitor) using Apple's 2026 Containerization.framework.

Current Architectural State:

  • Migration: We just migrated from a standard SPM structure to a Tuist Modular Architecture (TMA).
  • Layers:
    • Projects/Core: Shared, Persistence.
    • Projects/Domain: ContainerKit, NetworkKit, MachineKit (Virtualization), KubeKit.
    • Projects/Product: App, CLI, Engine.
  • Build System: Tuist is the source of truth (tuist generate). Package.swift exists for legacy/CI compatibility but points to old paths (needs update or ignore).

2. Recent Accomplishments

  1. Phase 3.1 Completed: Linux Machines are fully functional with SSH (Citadel), stable MAC addresses, and IP detection (ARPScanner).
  2. Phase 3.2 Kubernetes: Core provisioning works (VM-based k3s). fd k8s create --vm and kubeconfig are implemented.
  3. Phase 4.1 Menu Bar: Implemented MenuBarExtra and MenuBarView.
  4. Tuist Migration: Codebase physically moved to Projects/ directory structure. Workspace.swift created.

3. Pending Tasks (Immediate Priority)

A. Finish Modularization (The "Feature Extraction")

We have a detailed plan in openspec/plans/feature_extraction.md. The App (Projects/Product/App) is still a monolith containing all Views. Action:

  1. Move DesignSystem and Components to Projects/Core.
  2. Extract features (Containers, Images, Settings, etc.) into Projects/Features/.
  3. Update Project.swift files to wire dependencies.

B. Verify Build

We haven't run tuist generate or swift build since the massive file move. Action:

  1. Run tuist generate. Fix any circular dependency or path errors.
  2. Fix Package.swift if we want to keep it (update paths to Projects/...).

C. Domain Routing Polish

*.k8s.fd.local domain routing is the last item for full Phase 3.2 completion.

4. Critical Files

  • Plan: openspec/plans/feature_extraction.md (Read this first!)
  • Architecture: openspec/TECH_DEBT_REFACTORING.md
  • Workspace: Workspace.swift
  • Logic: Projects/Domain/ContainerKit/Sources/VirtualizationRuntime.swift (VM Logic)

5. Command Cheat Sheet

# Generate project
tuist generate

# Run Engine (Daemon)
swift run --package-path Projects/Product/Engine FlyingDutchmanEngine

# Run CLI
swift run --package-path Projects/Product/CLI FlyingDutchmanCLI

6. Known "Gotchas"

  • Imports: We moved files. Imports like import Shared might need to change to import Core if we renamed the module (we kept it Shared for now).
  • Entitlements: VM logic requires com.apple.security.virtualization entitlement. Ensure Tuist applies this to the Engine target.

Next Step: Execute the Feature Extraction plan to decouple the UI.