Add Provider

2 · Golden tests first (red)

Modules/Providers/Tests/<Name>DefinitionTests.swift runs the real definition through the real Provider over stubbed connections with StubbedProvider (Tests/Support/Connections.swift). They fail first because <id>.json doesn't exist.

@MainActor
@Suite
struct AcmeDefinitionTests {
    @Test
    func `should read Acme from its API by default`() throws {
        let acme = try ProviderFactory.builtIn("acme")
        #expect(acme.dataSources.map(\.kind) == ["api"])
        #expect(acme.defaultDataSource == "api")
    }

    @Test
    func `should show the session window when the API answers`() async throws {
        let stub = try StubbedProvider(providerId: "acme")
        defer { stub.cleanUp() }
        stub.environment = ["ACME_API_KEY": "test-key"]
        stub.answerHTTP(#"{"session":{"used_percent":30,"reset_at":1735000000}}"#)

        let usage = try await stub.make("acme").refreshPlain()

        #expect(usage.quota(for: .session)?.percentRemaining == 70)
        #expect(usage.quota(for: .session)?.resetsAt == Date(timeIntervalSince1970: 1735000000))
    }

    @Test
    func `should say the key is missing when the API has no key`() async throws {
        let stub = try StubbedProvider(providerId: "acme")
        defer { stub.cleanUp() }
        let acme = try stub.make("acme")

        await #expect(throws: UsageError.authenticationRequired) { try await acme.refresh(acme.defaultAccount) }
        #expect(acme.defaultAccount.lastFailedStep == .lookup)
    }
}

Assert on state: the usage, lastError, lastFailedStep, answeredBy, and files written back. Don't verify() calls. Cover every fixture from step 1.

3 · Write the definition (green)

Add <id>.json until the golden tests pass. ProviderFactory.builtIn validates it: kinds are unique, and the default and every fallback name an existing kind.

4 · When the language can't say it

Don't write vendor code. Find the generic shape of the need, for example "a list filtered by a field" or "money in minor units", and add it to DataSources test-first in Modules/DataSources/Tests/. Then use it from the JSON. ENGINE_DESIGN §1 lists the pieces each provider needed. Add your row there.

Only a format no rule can read, like a terminal UI screen, gets a mapping script, <id>-<what>.js. Test it through Swift with real captured screens (see ClaudeUsageScreenTests).

5 · Give it a look and a place

There is nothing to register: the file being in Resources/Providers/ makes it a provider. "order" places it in the default lineup (the built-ins use 10, 20, … 270); leave it out to come after the rest, by name. The person's own order still wins. DetectionTests lists the built-ins in order — add your id there.

Every provider gets the same Engine: settings, the vault, the login shell (for a lookup with "loginShell": true), the cloud ports (for a cloudWatch fetch), the guest-passes runner (for "guestPasses": {}). Ask for one in the JSON; never pass one in Swift.

Its name, symbol and colours are profile.look in the JSON — no switch id table to edit. Add the icon image to the asset catalog under look.icon (references/provider-icon-guide.md). Settings need no new protocol: the data source choice is dataSourceKind(forProvider:), and an on/off setting a definition names (for example fallback.enabledBySetting) is isOn(_:forProvider:).

6 · Docs and release note

• docs/providers/<id>/README.md (what users see, setup, errors) and design.md (sources, fields, gotchas).
• A row in the Providers table of the root README.md — name, what it tracks, a link to its docs/providers/<id>/README.md — placed by its "order", so the table follows the default lineup.
• A tile in the landing page's providers grid (website/public/index.html, <div class="pv" data-id="<id>" …>), in lineup order, and every count on the page raised by one — npm test in website/ reads the definitions and fails until both match.
• One line under ## [Unreleased] in CHANGELOG.md.
• python3 scripts/gen-docs.py && python3 scripts/check-docs.py --strict.

Keeping what people saved

Every built-in provider is already a definition; when you change one, keep every saved value working. The data source choice is <id>.probeMode, and a setting foo is read from <id>.foo. A value kept somewhere else gets a row, never a branch:

• a setting under another key → JSONSettingsRepository.legacySettingKeys
• a setting in UserDefaults → JSONSettingsRepository.legacyDefaultsKeys (a saved number or list reads as text)
• a secret in UserDefaults or an older Keychain item → ProviderVault.legacyKeys

Each moves to its new place the first time it's saved, and each needs a test.

Checklist

• Real fixtures captured (success and every failure), research in design.md
• Golden tests written first and failing
• <id>.json makes them pass; no vendor-named Swift anywhere
• Any new mapping/fetch/lookup ability added generically to DataSources, test-first, and listed in ENGINE_DESIGN §1
• "order" set if it has a place in the default lineup, and its id in DetectionTests
• profile.look filled in and the icon added to the asset catalog
• Provider docs, its row in the root README.md Providers table, its landing-page tile and counts (npm test in website/), and the CHANGELOG line written; docs check passes
• tuist test green