[PR #39] [MERGED] docs: add AGENTS.md with Swift build/test guidance #41

New issue

Closed

opened 2026-10-26 22:34:18 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-26 22:34:18 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/Comfy-Org/comfy-swift-sdk/pull/39
Author: @mattmillerai
Created: 7/10/2026
Status: ✅ Merged
Merged: 7/16/2026
Merged by: @mattmillerai

Base: main ← Head: matt/be-2803-agents-md

📝 Commits (1)

4015229 docs: add AGENTS.md with Swift build/test guidance

📊 Changes

1 file changed (+63 additions, -0 deletions)

View changed files

➕ AGENTS.md (+63 -0)

📄 Description

ELI-5

Robots that write code for this repo had no cheat-sheet telling them how to
build and test it — so they might reach for npm/format:check (wrong
ecosystem) or trip over the iOS-only bits. This adds a short AGENTS.md at the
root that says: it's a Swift Package, verify with swift build +
swift test --no-parallel, everything runs on the Mac host, guard iOS-only API
behind #if os(iOS), respect the import boundary, and self-review before
opening a PR (it's a public repo).

What & why

New root AGENTS.md — the repo previously had no agent doc. Contents:

Build & test with the Swift toolchain, not npm. swift build +
swift test --no-parallel, from the package root. Explicitly calls out that
there is no package.json / npm scripts / format:check. The --no-parallel
requirement and its rationale mirror .github/workflows/ci.yml.
macOS host / no simulator. The package targets macOS 14, so build and test
run on the Mac host with no iOS simulator or device — and any iOS-only API
must be guarded behind #if os(iOS) so the macOS build still compiles.
Import boundary. Documents that the core ComfySwiftSDK target is limited
to Foundation / CryptoKit / os, enforced by ImportBoundaryTests, and
notes the ComfyAuthKit target is intentionally exempt.
Public-repo caution + self-review before opening a PR.

Verification

swift build — green (verified locally).
Docs-only change (one new Markdown file, no source touched), so it cannot
affect compilation or the test suite. CI (swift build + swift test --no-parallel on macos-15) is the outer gate.
Every factual claim in the doc was checked against the repo: the
--no-parallel rationale against ci.yml, the import allowlist and its
Sources/ComfySwiftSDK/-only scope against ImportBoundaryTests, and the
platform matrix against Package.swift.

Notes / judgment calls

CI already exists. The task framing assumed "no CI yet," but the repo now
has CI workflows (ci.yml, a cursor-review workflow, and others). The doc
reflects reality — it says CI runs the same swift build + swift test --no-parallel — while still emphasizing self-review, since automated review
coverage here is light.
Toolchain nuance. The test target imports the Swift Testing framework,
which ships with the Swift 6 / Xcode 16 toolchain; the doc notes a new-enough
toolchain is needed. "No simulator" refers to not needing an iOS simulator,
not to not needing a Swift toolchain at all.
iOS-only example. Uses UIKit / UIApplication rather than
ASWebAuthenticationSession, since the latter is available on macOS too.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/Comfy-Org/comfy-swift-sdk/pull/39 **Author:** [@mattmillerai](https://github.com/mattmillerai) **Created:** 7/10/2026 **Status:** ✅ Merged **Merged:** 7/16/2026 **Merged by:** [@mattmillerai](https://github.com/mattmillerai) **Base:** `main` ← **Head:** `matt/be-2803-agents-md` --- ### 📝 Commits (1) - [`4015229`](https://github.com/Comfy-Org/comfy-swift-sdk/commit/4015229c5f3b79c3b357958613df460d0adc9c9b) docs: add AGENTS.md with Swift build/test guidance ### 📊 Changes **1 file changed** (+63 additions, -0 deletions) <details> <summary>View changed files</summary> ➕ `AGENTS.md` (+63 -0) </details> ### 📄 Description ## ELI-5 Robots that write code for this repo had no cheat-sheet telling them how to build and test it — so they might reach for `npm`/`format:check` (wrong ecosystem) or trip over the iOS-only bits. This adds a short `AGENTS.md` at the root that says: it's a Swift Package, verify with `swift build` + `swift test --no-parallel`, everything runs on the Mac host, guard iOS-only API behind `#if os(iOS)`, respect the import boundary, and self-review before opening a PR (it's a public repo). ## What & why New root `AGENTS.md` — the repo previously had no agent doc. Contents: - **Build & test with the Swift toolchain, not npm.** `swift build` + `swift test --no-parallel`, from the package root. Explicitly calls out that there is no `package.json` / npm scripts / `format:check`. The `--no-parallel` requirement and its rationale mirror `.github/workflows/ci.yml`. - **macOS host / no simulator.** The package targets macOS 14, so build and test run on the Mac host with no iOS simulator or device — and any iOS-only API must be guarded behind `#if os(iOS)` so the macOS build still compiles. - **Import boundary.** Documents that the core `ComfySwiftSDK` target is limited to `Foundation` / `CryptoKit` / `os`, enforced by `ImportBoundaryTests`, and notes the `ComfyAuthKit` target is intentionally exempt. - **Public-repo caution + self-review** before opening a PR. ## Verification - `swift build` — green (verified locally). - Docs-only change (one new Markdown file, no source touched), so it cannot affect compilation or the test suite. CI (`swift build` + `swift test --no-parallel` on macos-15) is the outer gate. - Every factual claim in the doc was checked against the repo: the `--no-parallel` rationale against `ci.yml`, the import allowlist and its `Sources/ComfySwiftSDK/`-only scope against `ImportBoundaryTests`, and the platform matrix against `Package.swift`. ## Notes / judgment calls - **CI already exists.** The task framing assumed "no CI yet," but the repo now has CI workflows (`ci.yml`, a cursor-review workflow, and others). The doc reflects reality — it says CI runs the same `swift build` + `swift test --no-parallel` — while still emphasizing self-review, since automated review coverage here is light. - **Toolchain nuance.** The test target imports the Swift Testing framework, which ships with the Swift 6 / Xcode 16 toolchain; the doc notes a new-enough toolchain is needed. "No simulator" refers to not needing an iOS simulator, not to not needing a Swift toolchain at all. - **iOS-only example.** Uses `UIKit` / `UIApplication` rather than `ASWebAuthenticationSession`, since the latter is available on macOS too. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-26 22:34:18 +00:00