kanban-code CLAUDE.md

Kanban Code – Claude Code Guidelines

Build & Test

swift build          # build the app
swift test           # run all tests
make run-app         # build + launch the app

Architecture

• KanbanCodeCore (Sources/KanbanCodeCore/) — pure Swift library, no UI. Domain entities, use cases, adapters.
• KanbanCode (Sources/KanbanCode/) — SwiftUI + AppKit macOS app. Views, toolbar, system tray.
• Deployment target: macOS 26 (swift-tools-version 6.2). No need for #available checks.
• Elm-like unidirectional state — see docs/architecture.md for full details.
  • All state lives in AppState struct (single source of truth).
  • All mutations go through store.dispatch(action) → pure Reducer → async Effects.
  • isLaunching flag on Link prevents background reconciliation from overriding cards mid-launch/resume.
  • Never mutate state directly or write to CoordinationStore from views — always dispatch an action.

Critical: DispatchSource + @MainActor Crashes

SwiftUI Views are @MainActor. In Swift 6, closures formed inside @MainActor methods inherit that isolation. If a DispatchSource event handler runs on a background GCD queue, the runtime asserts and crashes (EXC_BREAKPOINT in _dispatch_assert_queue_fail).

Never do this (crashes at runtime, no compile-time warning):

// Inside a SwiftUI View (which is @MainActor)
func startWatcher() {
    let source = DispatchSource.makeFileSystemObjectSource(fd: fd, eventMask: .write, queue: .global())
    source.setEventHandler {
        // CRASH: this closure inherits @MainActor but runs on a background queue
        NotificationCenter.default.post(name: .myEvent, object: nil)
    }
}

Always do this — extract to a nonisolated context:

// Option A: nonisolated static factory
private nonisolated static func makeSource(fd: Int32) -> DispatchSourceFileSystemObject {
    let source = DispatchSource.makeFileSystemObjectSource(fd: fd, eventMask: .write, queue: .global())
    source.setEventHandler {
        NotificationCenter.default.post(name: .myEvent, object: nil)
    }
    source.resume()
    return source
}

// Option B: nonisolated async function with AsyncStream
private nonisolated func watchFile(path: String) async {
    let source = DispatchSource.makeFileSystemObjectSource(...)
    let events = AsyncStream<Void> { continuation in
        source.setEventHandler { continuation.yield() }
        source.setCancelHandler { continuation.finish() }
        source.resume()
    }
    for await _ in events {
        NotificationCenter.default.post(name: .myEvent, object: nil)
    }
}