ts-procedures 8.1.1 → 8.2.1

package/agent_config/claude-code/skills/ts-procedures-swift/SKILL.md

@@ -1,119 +0,0 @@
----
-name: ts-procedures-swift
-description: "Swift client codegen for ts-procedures — generate types-only Swift source from a ts-procedures DocEnvelope for iOS/macOS/Apple-platform consumers. Use when the user mentions Swift, iOS, macOS, Apple platforms, Codable, or asks how to generate non-TypeScript types from a ts-procedures server."
-user-invocable: false
----
-
-# ts-procedures — Swift Client Codegen
-
-You are assisting a developer who needs to generate Swift types from a `ts-procedures` server's `DocEnvelope`. The Swift target is **types-only** — no runtime, no adapter, no error registry. iOS / macOS / Apple-platform consumers own the HTTP layer.
-
-## When this skill applies
-
-- The user mentions Swift, iOS, macOS, watchOS, tvOS, visionOS, Apple platforms, `Codable`, `URLSession`, or `--target swift`.
-- The user wants to share API types between a `ts-procedures` server and a Swift consumer.
-- The user is debugging Swift codegen output, SPM/Xcode integration, `JSONDecoder` configuration, or `Codable` conformance issues.
-
-If the user is generating a **TypeScript** client, redirect them to the main `ts-procedures` skill. For **Kotlin/Android** consumers, redirect to `ts-procedures-kotlin`.
-
-## Quickstart
-
-```bash
-npx ts-procedures-codegen \
-  --target swift \
-  --url https://api.example.com/_ts-procedures.json \
-  --out ./Sources/MyApp/Generated
-```
-
-One `.swift` file per scope. Types accessed as `Users.GetUser.Response`, `Users.GetUser.PathParams`, `Users.GetUser.Response.Address` (nested structs via `inlineTypes: true`), `Users.GetUser.Errors.NotFound`.
-
-**Note:** unlike the Kotlin target, no `--swift-package` flag exists or is required. Swift modules are defined by Xcode/SPM targets.
-
-## CLI flags (Swift-specific)
-
-| Flag | Default | Purpose |
-|---|---|---|
-| `--target swift` | `ts` | Switch to the Swift codegen path |
-| `--swift-serializer <codable\|none>` | `codable` | `codable` emits `: Codable` + `CodingKeys`; `none` emits plain structs (consumer handles serialization) |
-| `--swift-access-level <public\|internal>` | `public` | Threads through to ajsc's `accessLevel`; use `internal` when generated types shouldn't appear in module ABI |
-| `--unsupported-unions <throw\|fallback>` | `throw` | **Functional for Swift** (unlike Kotlin where it's a no-op) — `fallback` emits a self-contained `AnyCodable` helper for untagged `anyOf`/`oneOf` |
-
-`--array-item-naming`, `--depluralize`, `--uncountable-words` also apply to the Swift target.
-
-## Output shape (what consumers see)
-
-```swift
-import Foundation
-
-public enum Users {
-    public enum GetUser {
-        public static let method = "GET"
-        public static let pathTemplate = "/users/{id}"
-        public static func path(_ p: PathParams) -> String { return "/users/\(p.id)" }
-
-        public struct PathParams: Codable {
-            public let id: String
-        }
-
-        public struct Response: Codable {
-            public let id: String
-            public let createdAt: Date
-            public let address: Address
-
-            enum CodingKeys: String, CodingKey {
-                case id
-                case createdAt = "created-at"
-                case address
-            }
-
-            public struct Address: Codable {
-                public let street: String
-                public let city: String
-            }
-        }
-
-        public enum Errors {
-            public struct NotFound: Codable {
-                public let name: String
-                public let message: String
-            }
-        }
-    }
-}
-```
-
-For routes without path params, `path` is a `static let`, not a function. Namespaces are caseless `enum`s (the standard Swift idiom — uninstantiable, zero runtime cost).
-
-## Consumer-side setup the dev MUST do
-
-The generated code requires these on the Apple-platform side. **Don't let the user assume the codegen handles them.**
-
-1. **Drop generated files into your SPM target or Xcode source group.** Any target containing the generated dir picks them up — no special build config. SPM globs sources recursively; for Xcode, use **File → Add Files to "<TargetName>"…** and ensure target membership is checked.
-
-2. **Configure `JSONDecoder.dateDecodingStrategy = .iso8601`.** **Required** if the schema uses any `format: date-time` field (which become `Foundation.Date`). Without this, decoding fails with `DecodingError.typeMismatch`. Symmetric: set `JSONEncoder.dateEncodingStrategy = .iso8601` for request bodies.
-
-3. **HTTP transport is the consumer's choice.** `URLSession` (with `async/await`) is the default recommendation — it's built-in and works on all Apple platforms with no dependencies. Alamofire / other libraries are fine but never required.
-
-4. **No runtime dispatch.** Error types are emitted as nested structs (`Users.GetUser.Errors.NotFound`), but there's no registry, no `instanceof`-style lookup, no `dispatchTypedError`. Consumers catch HTTP failures themselves and dispatch on status code or `body.name` (a regular `String` field, not a type-system discriminator) to decide which error struct to decode against. To make error structs throwable, declare a one-line `extension X.Errors.NotFound: Error {}` in user code (keep it out of the generated file so re-runs don't clobber it). This is by design; don't suggest implementing a registry.
-
-The full setup guide lives at `docs/codegen-swift.md` in the `ts-procedures` repo.
-
-## Documented limitations to flag during reviews
-
-- **`format: date` and `format: time` map to `String`.** Foundation has no native date-only or time-only type. Parse with `DateFormatter` if a typed value is needed.
-- **`type: integer` maps to `Int64`** (not `Int`). 32-bit Apple platforms exist; `Int64` guarantees range parity.
-- **`type: number` maps to `Double`.** For monetary values, convert to `Decimal` at the parse boundary.
-- **Heterogeneous tuples throw under `Codable`.** Swift tuples aren't `Codable`. Schemas with positional-tuple `items: [...]` arrays throw at codegen time. Refactor to a struct schema upstream.
-- **`additionalProperties: { type: T }` is silently dropped** with a doc-comment. Add a sibling `[String: T]` field by hand if your contract uses extra keys.
-- **`not` and `patternProperties` throw at codegen time.** Simplify the schema upstream.
-- **Untagged `oneOf` throws by default.** Add a discriminator, or pass `--unsupported-unions fallback` to emit `AnyCodable`-typed values (loses static typing).
-
-## Anti-patterns
-
-- **Suggesting the Swift target ships a networking layer or HTTP adapter.** It does not — consumers own `URLSession`/etc. entirely.
-- **Recommending Alamofire as required.** `URLSession` + `async/await` is fine and ships with the OS. Alamofire is a personal-preference choice, not a dependency of the generated code.
-- **Conflating `--swift-serializer none` with "no setup needed".** `none` removes `Codable` conformance and `CodingKeys` — the consumer then needs their own serialization plan (hand-rolled, SwiftyJSON, etc.). It's strictly *more* setup, not less.
-- **Treating `--unsupported-unions fallback` as a no-op for Swift.** Unlike Kotlin (where it's silently dropped), the Swift target actually emits an `AnyCodable` helper that round-trips correctly. Use it when needed.
-- **Suggesting backwards compatibility with Swift 4 / pre-async-await.** Assume Swift 5.5+ (the async/await era). Sample dispatch code in docs uses `async throws`.
-- **Suggesting the codegen emits `: Error` conformance on error structs.** It doesn't (`Codable` only) — consumers add a one-line extension. Don't ask for this to be added to the codegen; it would force users into a particular error model.
-- **Mixing `--target swift` flags into a TypeScript-target invocation.** The flags are silently ignored; no harm, but the user is probably running the wrong target.