SwiftUI with a Swift package core tested by swift test in CI

# AGENTS.md: SwiftUI app with a tested Swift package core

An iOS and macOS app in SwiftUI. Screens are thin views over `@Observable` view models that live in a local Swift
package (`Packages/`), built in the Swift 6 language mode and tested with Swift Testing. Check `Package.swift` for
tools version and platforms before using an API.

## Commands (run in the package folder)
- Lint: `swift format lint --strict --recursive Sources Tests Package.swift`. Fix: `swift format --in-place --recursive Sources Tests`.
- Build and test: `swift build --build-tests` then `swift test --parallel`. This works on Linux and macOS.
- Views (macOS only): `xcodebuild -scheme <Package> -destination 'generic/platform=iOS Simulator' build`.
- Done means: lint clean, `swift test` green with a test for the behaviour you changed, and the summary says
  whether the views were compiled.

## Rules
- Use the `swiftui-testable-feature` skill when adding a screen or changing view logic.
- View models are `@MainActor @Observable final class` with `private(set)` state and no SwiftUI import.
  Logic lives there, not in `body`.
- Side effects (network, disk, clock) go through `Sendable` protocols injected in `init`. Tests use actor fakes.
- New tests use Swift Testing (`@Test`, `#expect`), with `arguments:` for input tables.
- Fix strict concurrency errors properly. Never add `@unchecked Sendable`, `nonisolated(unsafe)` or
  `@preconcurrency` to silence them.
- No force unwraps or `try!` outside tests. No new package dependencies without saying so.
- Do not change signing, entitlements, bundle identifiers or the Xcode project's build settings unless asked.

# CLAUDE.md

@AGENTS.md

## Claude Code notes

- Skills from this loadout live in `.claude/skills/`: `swiftui-testable-feature`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "SwiftUI with a Swift package core tested by swift test in CI" v1.0.0 — https://loadout.jnw-it.com/loadouts/swiftui-swift-test-ci/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes

- Skills from this loadout live in `.agents/skills/`: `swiftui-testable-feature`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "SwiftUI with a Swift package core tested by swift test in CI" v1.0.0 — https://loadout.jnw-it.com/loadouts/swiftui-swift-test-ci/ -->

---
name: swiftui-testable-feature
description: Build a SwiftUI feature with its state and logic in a Swift package view model that swift test covers on Linux and macOS, with a thin view on top. Use when adding a screen, changing view logic, or writing Swift tests.
---

# SwiftUI feature with a testable core

SwiftUI views are hard to test and only build on Apple platforms. So the view stays thin, and everything worth
testing lives in an `@Observable` view model inside a Swift package that builds and tests anywhere, including
a cheap Linux CI runner.

## Layout

```
Packages/NotesCore/
  Package.swift                      swift-tools-version 6.2, Swift 6 language mode
  Sources/NotesCore/Note.swift       value types + the client protocol (Sendable)
  Sources/NotesCore/NotesModel.swift @MainActor @Observable view model, no SwiftUI import
  Sources/NotesCore/NotesView.swift  the view, wrapped in #if canImport(SwiftUI)
  Tests/NotesCoreTests/...           Swift Testing (@Suite, @Test, #expect)
```

The app target (Xcode project) depends on the package and only creates the model with the real client.

## Rules for the view model

- `@MainActor @Observable final class`, with `private(set)` state. The view reads it and calls methods.
- State is an enum (`idle`, `loading`, `loaded`, `failed(message)`), not several booleans that can disagree.
- Every side effect goes through a `Sendable` protocol passed into `init` (network, disk, clock). Time comes
  from an injected `now` closure, so tests are deterministic.
- Derived values (sorting, filtering, validation) are computed properties or methods on the model, not code
  in `body`.
- Errors become a user-facing message in state. Never swallow them into an empty list.
- No `import SwiftUI`, `UIKit` or `AppKit` in the model file.

## Rules for the view

- Wrap the file in `#if canImport(SwiftUI)` so the package still builds on Linux.
- Own the model with `@State`, pass it down as a plain property, bind with `$model.field`.
- Load in `.task { await model.load() }`, refresh with `.refreshable`.
- No business logic in the view: if you want to test it, move it into the model.

## Tests

- Swift Testing, not XCTest, for new tests: `@Suite`, `@Test("sentence")`, `#expect`, and
  `#expect(throws:)`. Use `arguments:` for tables of inputs instead of copy-pasted tests.
- Mark the suite `@MainActor` to call the model directly.
- Fakes are `actor`s that implement the client protocol and record calls. No mocking frameworks.
- Each behaviour has a test: happy path, each error, edge input (blank, too long, whitespace), and that
  invalid input never reaches the client.

## Commands (from the package folder)

```bash
swift format lint --strict --recursive Sources Tests Package.swift   # config: references/swift-format.json as .swift-format
swift build --build-tests
swift test --parallel
```

On a Mac, also build for the simulator so the views compile:
`xcodebuild -scheme NotesCore -destination 'generic/platform=iOS Simulator' build`.
CI runs both (see `references/swift-ci.yml`): Linux in the `swift:6.4.1-noble` container, macOS with Xcode 26.6.

## Done means

- Lint is clean and `swift test` passes, with a new or changed `@Test` for the behaviour you touched.
- Strict concurrency errors are fixed, not silenced: no `@unchecked Sendable`, `nonisolated(unsafe)` or
  `@preconcurrency` added to get a build through.
- The summary says whether the views were built on macOS or only the core was tested on Linux.

## References

`references/Package.swift`, `references/Note.swift`, `references/NotesModel.swift`,
`references/NotesView.swift`, `references/NotesModelTests.swift` (six tests, nine cases),
`references/swift-format.json`, `references/swift-ci.yml`.

// swift-tools-version: 6.2
import PackageDescription

let package = Package(
    name: "NotesCore",
    platforms: [.iOS(.v18), .macOS(.v15)],
    products: [
        .library(name: "NotesCore", targets: ["NotesCore"])
    ],
    targets: [
        .target(name: "NotesCore"),
        .testTarget(name: "NotesCoreTests", dependencies: ["NotesCore"]),
    ],
    swiftLanguageModes: [.v6]
)

import Foundation

public struct Note: Identifiable, Equatable, Sendable, Codable {
    public let id: UUID
    public var title: String
    public var body: String
    public var updatedAt: Date

    public init(id: UUID = UUID(), title: String, body: String, updatedAt: Date) {
        self.id = id
        self.title = title
        self.body = body
        self.updatedAt = updatedAt
    }
}

/// The only way the view model reaches the network or disk. Tests pass a fake.
public protocol NotesClient: Sendable {
    func fetchNotes() async throws -> [Note]
    func save(_ note: Note) async throws -> Note
}

public enum NotesError: Error, Equatable, Sendable {
    case offline
    case server(status: Int)
    case invalidTitle
}

import Foundation
import Observation

/// View state for the notes screen. Owns no SwiftUI types, so it builds and tests on Linux.
@MainActor
@Observable
public final class NotesModel {
    public enum State: Equatable {
        case idle
        case loading
        case loaded([Note])
        case failed(String)
    }

    public private(set) var state: State = .idle
    public var searchText = ""

    private let client: any NotesClient
    private let now: @Sendable () -> Date

    public init(client: any NotesClient, now: @escaping @Sendable () -> Date = Date.init) {
        self.client = client
        self.now = now
    }

    /// Notes to show: newest first, filtered by the search text (title or body, case-insensitive).
    public var visibleNotes: [Note] {
        guard case .loaded(let notes) = state else { return [] }
        let query = searchText.trimmingCharacters(in: .whitespacesAndNewlines)
        let filtered =
            query.isEmpty
            ? notes
            : notes.filter { $0.title.localizedCaseInsensitiveContains(query) || $0.body.localizedCaseInsensitiveContains(query) }
        return filtered.sorted { $0.updatedAt > $1.updatedAt }
    }

    public func load() async {
        if case .loading = state { return }
        state = .loading
        do {
            state = .loaded(try await client.fetchNotes())
        } catch {
            state = .failed(Self.message(for: error))
        }
    }

    /// Validates, saves through the client, and replaces or appends the saved note.
    public func save(title: String, body: String, id: UUID? = nil) async throws {
        let trimmed = title.trimmingCharacters(in: .whitespacesAndNewlines)
        guard !trimmed.isEmpty, trimmed.count <= 120 else { throw NotesError.invalidTitle }
        let saved = try await client.save(Note(id: id ?? UUID(), title: trimmed, body: body, updatedAt: now()))
        guard case .loaded(var notes) = state else {
            state = .loaded([saved])
            return
        }
        if let index = notes.firstIndex(where: { $0.id == saved.id }) {
            notes[index] = saved
        } else {
            notes.append(saved)
        }
        state = .loaded(notes)
    }

    static func message(for error: any Error) -> String {
        switch error {
        case NotesError.offline: "You're offline. Pull to try again."
        case NotesError.server(let status): "The server returned an error (\(status))."
        default: "Something went wrong."
        }
    }
}

#if canImport(SwiftUI)
import SwiftUI

/// Thin view: reads model state, forwards user intent. No logic worth testing lives here.
public struct NotesView: View {
    @State private var model: NotesModel

    public init(model: NotesModel) {
        _model = State(initialValue: model)
    }

    public var body: some View {
        NavigationStack {
            content
                .navigationTitle("Notes")
                .searchable(text: $model.searchText)
                .refreshable { await model.load() }
                .task { await model.load() }
        }
    }

    @ViewBuilder private var content: some View {
        switch model.state {
        case .idle, .loading:
            ProgressView()
        case .failed(let message):
            ContentUnavailableView("Couldn't load notes", systemImage: "wifi.slash", description: Text(message))
        case .loaded:
            List(model.visibleNotes) { note in
                VStack(alignment: .leading) {
                    Text(note.title).font(.headline)
                    Text(note.body).font(.subheadline).lineLimit(2)
                }
            }
        }
    }
}
#endif

import Foundation
import Testing

@testable import NotesCore

/// Fake client: canned results, records saves. An actor, so it is Sendable without locks.
actor FakeNotesClient: NotesClient {
    var notes: [Note]
    var fetchError: NotesError?
    private(set) var saved: [Note] = []

    init(notes: [Note] = [], fetchError: NotesError? = nil) {
        self.notes = notes
        self.fetchError = fetchError
    }

    func fetchNotes() async throws -> [Note] {
        if let fetchError { throw fetchError }
        return notes
    }

    func save(_ note: Note) async throws -> Note {
        saved.append(note)
        return note
    }
}

let day: TimeInterval = 86_400
let fixed = Date(timeIntervalSince1970: 1_790_000_000)

func note(_ title: String, _ body: String = "", daysAgo: Double) -> Note {
    Note(title: title, body: body, updatedAt: fixed.addingTimeInterval(-daysAgo * day))
}

@MainActor
@Suite("NotesModel")
struct NotesModelTests {
    @Test("load shows notes newest first")
    func loadSortsNewestFirst() async {
        let client = FakeNotesClient(notes: [note("Old", daysAgo: 3), note("New", daysAgo: 0), note("Mid", daysAgo: 1)])
        let model = NotesModel(client: client, now: { fixed })
        await model.load()
        #expect(model.visibleNotes.map(\.title) == ["New", "Mid", "Old"])
    }

    @Test(
        "a failed load shows a message, not an empty list",
        arguments: [
            (NotesError.offline, "You're offline. Pull to try again."),
            (NotesError.server(status: 503), "The server returned an error (503)."),
        ])
    func loadFailure(error: NotesError, message: String) async {
        let model = NotesModel(client: FakeNotesClient(fetchError: error), now: { fixed })
        await model.load()
        #expect(model.state == .failed(message))
        #expect(model.visibleNotes.isEmpty)
    }

    @Test("search matches title or body, case-insensitively, ignoring spaces")
    func search() async {
        let client = FakeNotesClient(notes: [
            note("Groceries", "milk, eggs", daysAgo: 0), note("Ideas", "Buy MILK frother", daysAgo: 1), note("Trip", daysAgo: 2),
        ])
        let model = NotesModel(client: client, now: { fixed })
        await model.load()
        model.searchText = "  milk "
        #expect(model.visibleNotes.map(\.title) == ["Groceries", "Ideas"])
    }

    @Test("save trims the title, stamps the time and appends")
    func saveAppends() async throws {
        let client = FakeNotesClient(notes: [note("First", daysAgo: 1)])
        let model = NotesModel(client: client, now: { fixed })
        await model.load()
        try await model.save(title: "  Second  ", body: "b")
        #expect(model.visibleNotes.map(\.title) == ["Second", "First"])
        let saved = await client.saved
        #expect(saved.count == 1)
        #expect(saved.first?.updatedAt == fixed)
    }

    @Test("save with an existing id replaces that note")
    func saveReplaces() async throws {
        let existing = note("Draft", daysAgo: 2)
        let model = NotesModel(client: FakeNotesClient(notes: [existing]), now: { fixed })
        await model.load()
        try await model.save(title: "Final", body: "done", id: existing.id)
        #expect(model.visibleNotes.count == 1)
        #expect(model.visibleNotes.first?.title == "Final")
    }

    @Test("blank or over-long titles are rejected before the client is called", arguments: ["", "   ", String(repeating: "x", count: 121)])
    func invalidTitle(title: String) async {
        let client = FakeNotesClient()
        let model = NotesModel(client: client, now: { fixed })
        await #expect(throws: NotesError.invalidTitle) {
            try await model.save(title: title, body: "")
        }
        #expect(await client.saved.isEmpty)
    }
}

{
  "version": 1,
  "indentation": { "spaces": 4 },
  "lineLength": 140,
  "indentConditionalCompilationBlocks": false,
  "rules": {
    "AllPublicDeclarationsHaveDocumentation": false,
    "NeverForceUnwrap": true,
    "NeverUseForceTry": true,
    "NeverUseImplicitlyUnwrappedOptionals": true,
    "OrderedImports": true,
    "UseLetInEveryBoundCaseVariable": true
  }
}

# .github/workflows/swift.yml
# Linux: format lint and swift test for the core package (fast, cheap, no Xcode).
# macOS: build the package for macOS and the iOS simulator, so the SwiftUI views compile too.
name: Swift

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

jobs:
  linux:
    runs-on: ubuntu-24.04
    container: swift:6.4.1-noble
    timeout-minutes: 15
    defaults:
      run:
        working-directory: Packages/NotesCore
    steps:
      - uses: actions/checkout@v7
      - run: swift format lint --strict --recursive Sources Tests Package.swift
      - run: swift build --build-tests
      - run: swift test --parallel

  macos:
    runs-on: macos-26
    timeout-minutes: 30
    defaults:
      run:
        working-directory: Packages/NotesCore
    steps:
      - uses: actions/checkout@v7
      - run: sudo xcode-select -s /Applications/Xcode_26.6.app
      - run: swift test --parallel
      - name: Build for the iOS simulator (compiles the SwiftUI views)
        run: xcodebuild -scheme NotesCore -destination 'generic/platform=iOS Simulator' -skipPackagePluginValidation build