ts-procedures 6.1.0 → 6.2.0

package/docs/codegen-swift.md

@@ -0,0 +1,314 @@
+# Swift Codegen Setup Guide
+
+Generated by `ts-procedures-codegen --target swift`. One `.swift` file per scope; types are nested under route enum namespaces (`Users.GetUser.Response`, `Users.GetUser.Response.Address`, `Users.GetUser.Errors.NotFound`).
+
+## Quickstart
+
+```bash
+npx ts-procedures-codegen \
+  --target swift \
+  --url https://api.example.com/_ts-procedures.json \
+  --out ./Sources/MyApp/Generated
+```
+
+Each scope produces one file (e.g. `Users.swift`). Access generated types as `Users.GetUser.Response`, `Users.GetUser.PathParams`, `Users.GetUser.Errors.NotFound`.
+
+Unlike the Kotlin target, **no package/module flag is required.** Swift modules are defined by Xcode/SPM targets, not by file-level declarations.
+
+## Swift Package Manager / Xcode integration
+
+The generated files are plain `.swift` source — drop them into any target's source directory and they compile as-is. There is no required configuration.
+
+### Swift Package Manager
+
+Point a target's `path:` (or `sources:`) at the directory you generated into:
+
+```swift
+// Package.swift
+let package = Package(
+    name: "MyApp",
+    products: [.library(name: "MyApp", targets: ["MyApp"])],
+    targets: [
+        .target(
+            name: "MyApp",
+            path: "Sources/MyApp"
+            // Generated files live under Sources/MyApp/Generated/ and
+            // are picked up automatically by SPM's recursive source globbing.
+        ),
+    ]
+)
+```
+
+If you keep the generated dir as its own target, declare it as a dependency of any target that needs to call the API:
+
+```swift
+.target(name: "MyAppAPI", path: "Sources/MyApp/Generated"),
+.target(name: "MyApp",    dependencies: ["MyAppAPI"]),
+```
+
+### Xcode (project-based)
+
+In Xcode: **File → Add Files to "<TargetName>"…**, select the generated directory, and ensure the target membership checkbox is set. Re-running codegen overwrites the files in place; Xcode picks up the changes on next build.
+
+## JSONDecoder configuration
+
+**This is required.** Schemas with `format: date-time` are emitted as `Foundation.Date`. Decoding fails (`DecodingError.typeMismatch`) unless you tell `JSONDecoder` how to parse the wire format:
+
+```swift
+let decoder = JSONDecoder()
+decoder.dateDecodingStrategy = .iso8601
+```
+
+For symmetric encoding (e.g. when sending request bodies):
+
+```swift
+let encoder = JSONEncoder()
+encoder.dateEncodingStrategy = .iso8601
+```
+
+The server emits ISO-8601 strings by default; `.iso8601` is the matching strategy on the Swift side. If your server emits epoch-millis or another format, swap to `.millisecondsSince1970` / `.formatted(_:)` / `.custom(_:)` accordingly.
+
+`format: uuid` and `format: uri` map to `Foundation.UUID` / `Foundation.URL`, both of which are `Codable` natively and need no extra configuration.
+
+## Sample output
+
+Given a `users` scope with a single `GetUser` route declaring path params, a response with a nested `Address`, and a `NotFound` error:
+
+```swift
+// Source hash: 9a1b3c…
+// Generated by ts-procedures-codegen — do not edit.
+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 name: String
+            /// ISO-8601 — set JSONDecoder.dateDecodingStrategy = .iso8601
+            public let createdAt: Date
+            public let address: Address
+
+            enum CodingKeys: String, CodingKey {
+                case id, name
+                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
+            }
+        }
+    }
+}
+```
+
+Routes without path params get `public static let path = "/users"` (a constant, not a function).
+
+## Discriminated unions
+
+A `oneOf` whose variants share a const-valued discriminator (e.g. `kind: "guest" | "registered"`) emits as a Swift `enum` with associated values. Because Swift's standard `Codable` has no built-in tagged-union support, ajsc emits a hand-rolled `init(from:)` / `encode(to:)` that dispatches on the discriminator field:
+
+```swift
+public enum Body: Codable {
+    case guest(Guest)
+    case registered(Registered)
+
+    public struct Guest: Codable {
+        public let displayName: String
+    }
+
+    public struct Registered: Codable {
+        public let email: String
+        public let name: String
+    }
+
+    private enum DiscriminatorKeys: String, CodingKey { case kind }
+
+    public init(from decoder: Decoder) throws {
+        let c = try decoder.container(keyedBy: DiscriminatorKeys.self)
+        let kind = try c.decode(String.self, forKey: .kind)
+        switch kind {
+        case "guest":      self = .guest(try Guest(from: decoder))
+        case "registered": self = .registered(try Registered(from: decoder))
+        default: throw DecodingError.dataCorruptedError(
+            forKey: .kind, in: c,
+            debugDescription: "Unknown discriminator: \(kind)")
+        }
+    }
+
+    public func encode(to encoder: Encoder) throws {
+        switch self {
+        case .guest(let v):      try v.encode(to: encoder)
+        case .registered(let v): try v.encode(to: encoder)
+        }
+    }
+}
+```
+
+**Nothing for the consumer to configure.** The discriminator handling is baked into the generated code — `JSONDecoder().decode(Body.self, from: data)` works directly.
+
+The discriminator field (`kind`) is **retained** on each variant struct (unlike the Kotlin target, which erases it via `@SerialName`). This is a Codable necessity: the variant struct's `init(from:)` is invoked with the same decoder that just read the discriminator, so the field has to be present in the variant's shape too.
+
+## JSON-key sanitization
+
+Kebab-case and snake-case JSON keys become camelCase Swift property names; ajsc auto-emits a nested `enum CodingKeys: String, CodingKey` to map between them:
+
+```swift
+public struct Response: Codable {
+    public let createdAt: Date
+    public let userName: String
+
+    enum CodingKeys: String, CodingKey {
+        case createdAt = "created-at"
+        case userName  = "user_name"
+    }
+}
+```
+
+Reserved Swift keywords get backtick-escaped: a JSON key `class` becomes `` `class` `` on the Swift side (still valid as a property name; the surrounding code references it as `value.`class`).
+
+## Switching off Codable (`--swift-serializer none`)
+
+`--swift-serializer none` emits plain structs **without `Codable` conformance and without `CodingKeys`**:
+
+```swift
+public struct Response {
+    public let id: String
+    public let createdAt: Date
+}
+```
+
+Use cases:
+
+- You're using **SwiftyJSON**, **Argo**, or another non-Codable serialization library.
+- You want to hand-roll `Codable` conformance in extensions (e.g. to centralize `dateDecodingStrategy` per type, or to handle a Codable-incompatible shape).
+- You're integrating with an Objective-C bridge that doesn't speak `Codable`.
+
+With `none`, the consumer is fully responsible for serialization. CodingKeys are NOT emitted — kebab/snake-case keys aren't sanitized at all on the wire side, so you'll need to handle that mapping yourself.
+
+## `--swift-access-level public | internal`
+
+Defaults to `public`. Pass `--swift-access-level internal` when the generated types are consumed only within a single module (e.g. an app target that talks to one backend) and you don't want them appearing in the module's public ABI.
+
+```bash
+npx ts-procedures-codegen --target swift --swift-access-level internal --url ... --out ...
+```
+
+The flag threads through to ajsc's `accessLevel` option and applies uniformly to every emitted type, the namespace enums, and the static `method` / `path` / `pathTemplate` declarations.
+
+## Error types
+
+Each route that declares errors gets a nested `Errors` enum (caseless namespace) containing one `Codable` struct per error name:
+
+```swift
+public enum Users {
+    public enum GetUser {
+        // ... method, path, types ...
+        public enum Errors {
+            public struct NotFound: Codable {
+                public let name: String
+                public let message: String
+            }
+        }
+    }
+}
+```
+
+Access generated error types as `Users.GetUser.Errors.NotFound`.
+
+**No runtime dispatch.** Like the Kotlin target, the Swift target ships **types only** — there is no error registry, no `instanceof`-style lookup, no `dispatchTypedError`. Consumers catch HTTP failures themselves and dispatch on status code or `body.name`:
+
+```swift
+func loadUser(id: String) async throws -> Users.GetUser.Response {
+    var req = URLRequest(url: URL(string: "https://api.example.com" + Users.GetUser.path(.init(id: id)))!)
+    req.httpMethod = Users.GetUser.method
+
+    let (data, response) = try await URLSession.shared.data(for: req)
+    guard let http = response as? HTTPURLResponse else {
+        throw URLError(.badServerResponse)
+    }
+
+    let decoder = JSONDecoder()
+    decoder.dateDecodingStrategy = .iso8601
+
+    switch http.statusCode {
+    case 200:
+        return try decoder.decode(Users.GetUser.Response.self, from: data)
+    case 404:
+        throw try decoder.decode(Users.GetUser.Errors.NotFound.self, from: data)
+    default:
+        throw URLError(.badServerResponse)
+    }
+}
+```
+
+For the error structs to also conform to `Error`, declare a single-line empty extension in your own code (kept out of generated files so codegen overwrites are safe):
+
+```swift
+extension Users.GetUser.Errors.NotFound: Error {}
+```
+
+Choosing the dispatch strategy (status-code, `body.name`, your own `enum APIError: Error { case ... }` wrapper, etc.) is intentionally left to consumers.
+
+## Untagged unions
+
+**Unlike the Kotlin target, `--unsupported-unions fallback` actually works on Swift.** ajsc emits a self-contained `AnyCodable` helper struct directly inside the generated file (no external dependency, no separate runtime to install) to model schemas that use untagged `anyOf` / `oneOf` with no shared discriminator.
+
+Default: `--unsupported-unions throw` — codegen raises an error with the schema path of the offending union, so you can fix it at the source.
+
+```bash
+# Opt in to the fallback. Generated code becomes:
+npx ts-procedures-codegen --target swift --unsupported-unions fallback --url ... --out ...
+```
+
+```swift
+public struct AnyCodable: Codable {
+    public let value: Any
+    // ... init(from:), encode(to:) handle Bool/Int/Double/String/Array/Dictionary/null
+}
+
+public struct MixedField: Codable {
+    public let value: AnyCodable  // was: oneOf: [{ type: 'string' }, { type: 'integer' }]
+}
+```
+
+You lose static typing on the union'd value — consumers introspect at runtime. **Prefer adding a discriminator** to the server-side schema if at all possible; the `fallback` mode is an escape hatch for third-party / locked schemas you can't change.
+
+## Documented limitations
+
+The following ajsc behaviors are intentional and documented; they are **not bugs**:
+
+- **`format: date` and `format: time` map to `String`.** Swift's Foundation has no native date-only or time-only type (`Date` is a point-in-time, not a calendar date). Parse manually with `DateFormatter` if you need a typed value.
+- **`type: integer` maps to `Int64`** (not `Int`). Reason: 32-bit Apple platforms (older watchOS, some embedded targets) have 32-bit `Int`. `Int64` guarantees range parity with the JSON Schema integer type.
+- **`type: number` maps to `Double`.** For monetary or other precision-sensitive values, decode into `Double` and convert to `Decimal` at the boundary:
+  ```swift
+  let amount = Decimal(response.totalPrice)
+  ```
+  This is a one-time conversion at the parse boundary; subsequent arithmetic on `Decimal` is precision-safe.
+- **`additionalProperties: { type: T }` is silently dropped** with a `/// Note: schema permits additional keys of type T — not modeled.` doc-comment. Add a sibling `[String: T]` field by hand or write a custom `init(from:)` if your contract uses extra keys.
+- **Heterogeneous tuples throw under Codable.** Swift tuples are not `Codable`. Schemas with positional-tuple `items: [...]` arrays throw at codegen time. Refactor to a struct schema upstream.
+- **`not` and `patternProperties` keywords throw at codegen time** with a path-bearing error message. These don't have idiomatic Swift mappings; the schema needs simplification at the source.
+- **Schema-level `examples` are not modeled.** They're documentation-only on the server side; consumers don't see them.
+
+## Reference
+
+- Spec: [`docs/superpowers/specs/2026-04-25-swift-codegen-design.md`](./superpowers/specs/2026-04-25-swift-codegen-design.md)
+- For Kotlin / Android consumers, see [`docs/codegen-kotlin.md`](./codegen-kotlin.md) — same types-only design with Kotlin-specific flags and `kotlinx.serialization` setup notes.
+- ajsc README: `node_modules/ajsc/README.md` (or [npmjs.com/package/ajsc](https://www.npmjs.com/package/ajsc))
+- ts-procedures-codegen CLI flags: see `CLAUDE.md` (search for "Swift target") and the spec linked above. (`--help` is not currently implemented; pass invalid/missing args to see error messages with usage hints.)

package/docs/superpowers/specs/2026-04-24-kotlin-swift-codegen-design.md

@@ -1,6 +1,6 @@
 # Kotlin & Swift Codegen for ts-procedures
 
-**Status:** Design
+**Status:** Shipped (both targets — Kotlin and Swift)
 **Date:** 2026-04-24
 **Author:** Cory Robinson
 **Implementation order:** Kotlin first, Swift second.

package/docs/superpowers/specs/2026-04-25-ajsc-v7-kotlin-polish-design.md

@@ -1,6 +1,6 @@
 # ajsc v7.2 Kotlin Codegen Polish
 
-**Status:** Design
+**Status:** Shipped
 **Date:** 2026-04-25
 **Author:** Cory Robinson
 **Supersedes parts of:** [`2026-04-24-kotlin-swift-codegen-design.md`](./2026-04-24-kotlin-swift-codegen-design.md) — Kotlin sections only. Swift sections of the prior design remain in force and unscheduled.

package/docs/superpowers/specs/2026-04-25-swift-codegen-design.md

@@ -0,0 +1,264 @@
+# Swift Codegen Target — Design & Implementation Plan
+
+Date: 2026-04-25
+Branch: codegen-kotlin-swift
+Status: shipped
+
+## Outcome
+
+Implemented as designed: `--target swift`, `--swift-serializer`, `--swift-access-level`, full integration test against `users-golden.swift`, plus a `swiftc -parse` e2e gated by `swiftc` availability. One post-implementation deviation worth noting: the originally-spec'd files in `src/codegen/targets/swift/` were later supplemented by an extracted `src/codegen/targets/_shared/` directory of language-agnostic utilities (`path-utils`, `pick-defined`, `indent`, `pascal-case`, `route-slots`, `error-schemas`, `write-files`, `target-run`). The Swift run module (`src/codegen/targets/swift/run.ts`) and the Kotlin run module both consume `_shared/` so the dispatcher in `src/codegen/pipeline.ts` stays thin (~94 lines).
+
+## Goal
+
+Add a `--target swift` codegen target to `ts-procedures-codegen` that emits idiomatic, types-only Swift source from a `DocEnvelope`. Design mirrors the existing Kotlin target so iOS / Apple-platform consumers get parity DX with Android consumers — both targets are types-only, no runtime, no error registry, no HTTP adapter.
+
+## Non-goals
+
+- HTTP client, networking, async/await wrappers (consumers own this).
+- SSE / streams (skipped, same as Kotlin).
+- Hooks, per-call options, error dispatch logic.
+- Swift Package Manager scaffolding (consumers create `Package.swift` themselves).
+- Module declarations (Swift modules are defined by Xcode/SPM targets, not per-file like Kotlin packages).
+- ObjC interop, `@objc` annotations.
+
+## Output shape
+
+One `.swift` file per scope. Idiomatic Swift namespacing via **caseless enums** (the standard Swift idiom for namespaces — uninstantiable, zero runtime cost):
+
+```swift
+// Source hash: <md5>
+// Generated by ts-procedures-codegen — do not edit.
+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 name: String
+            /// ISO-8601 — set JSONDecoder.dateDecodingStrategy = .iso8601
+            public let createdAt: Date
+            public let address: Address
+
+            enum CodingKeys: String, CodingKey {
+                case id, name
+                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
+            }
+        }
+    }
+}
+```
+
+Routes without path params get `public static let path = "/users"` (constant, not function).
+
+## CLI surface
+
+New flag: `--target swift` (extends current `'ts' | 'kotlin'` union to `'ts' | 'kotlin' | 'swift'`).
+
+Swift-specific flags:
+
+| Flag | Default | Notes |
+|---|---|---|
+| `--swift-serializer <codable\|none>` | `codable` | Emits `: Codable`/`CodingKeys`. `none` for plain structs (consumer handles serialization). |
+| `--swift-access-level <public\|internal>` | `public` | Threads through to ajsc `accessLevel`. |
+
+Reused (apply to all targets): `--unsupported-unions`, `--array-item-naming`, `--depluralize`, `--uncountable-words`.
+
+**Important:** Unlike Kotlin, `--unsupported-unions fallback` actually works on Swift — ajsc emits a self-contained `AnyCodable` helper struct. Do NOT add the kotlin-style "no-op warning" for Swift.
+
+**No `--swift-package` flag.** Swift has no file-level package/module declaration; modules are defined by SPM/Xcode targets. This is a deliberate DX win — one fewer required arg vs Kotlin.
+
+## Config file shape
+
+```json
+{
+  "target": "swift",
+  "swift": {
+    "serializer": "codable",
+    "accessLevel": "public"
+  }
+}
+```
+
+## File layout
+
+```
+src/codegen/targets/swift/
+├── ajsc-adapter.ts             # SwiftEmitter interface + production wrapper around ajsc.emitSwift
+├── ajsc-adapter.test.ts
+├── format-swift.ts             # header, imports, indent, pickDefined helpers
+├── format-swift.test.ts
+├── emit-route-swift.ts         # per-route emitter (PathParams, Query, Body, Response, Errors)
+├── emit-route-swift.test.ts
+├── emit-scope-swift.ts         # per-scope emitter (wraps routes in nested enum namespace)
+├── emit-scope-swift.test.ts
+├── integration.test.ts         # golden-file end-to-end with stub emitter
+├── e2e-compile.test.ts         # SKIPPED by default — runs swiftc to validate generated output
+└── __fixtures__/
+    ├── users-envelope.json     # copy of kotlin fixture (same input)
+    └── users-golden.swift
+```
+
+## Architectural decisions
+
+### 1. Namespacing via caseless enums
+
+Swift idiom: `public enum Users {}` for namespace. Better than `struct Users {}` (no init, no instantiation possible, zero runtime cost). Better than nested `class` (reference type, unnecessary).
+
+### 2. Static members for path/method
+
+Inside an enum namespace, all members must be `static`. So:
+```swift
+public static let method = "GET"
+public static let pathTemplate = "/users/{id}"
+public static func path(_ p: PathParams) -> String { return "/users/\(p.id)" }
+```
+
+(Kotlin uses `const val` and top-level `fun`; Swift uses `public static let` and `public static func`.)
+
+### 3. ajsc options threaded
+
+Per route slot we call `emitSwift(slotSchema, { rootTypeName, inlineTypes: true, ...passthrough })`. Passthrough: `serializer`, `accessLevel`, `unsupportedUnions`, `arrayItemNaming`, `depluralize`, `uncountableWords`.
+
+`inlineTypes: true` is critical — same as Kotlin. Without it, nested object types extract to siblings and clutter the namespace.
+
+### 4. Imports merge per file
+
+ajsc returns imports per emit call (typically `["Foundation"]` only when Date/UUID/URL is in the schema). We dedupe + sort and emit once at the top of the scope file.
+
+### 5. No errors file, no index file
+
+Mirrors Kotlin: errors are nested as `enum Errors { struct NotFound: Codable { ... } }` per route. No `_errors.swift`, no barrel/index, no factories.
+
+### 6. Path interpolation
+
+Swift string interpolation is `\(expr)` (backslash + paren). Path builder template:
+```swift
+public static func path(_ p: PathParams) -> String { return "/users/\(p.id)" }
+```
+
+For no-params: `public static let path = "/users"`.
+
+### 7. Source hash header
+
+`// Source hash: <md5>` as second line (after the optional `// Generated by ...` line). Same as kotlin/ts.
+
+### 8. Stream skipping
+
+Same as Kotlin — skip stream routes with a single console log per scope.
+
+### 9. Reserved word + identifier sanitization
+
+ajsc handles this via `sanitizeSwiftIdentifier` (already verified in ajsc/swift exports). Property and case names are already sanitized in ajsc's output. Our route/scope names use PascalCase already; we don't need to re-sanitize.
+
+### 10. Self-contained emitter (no extra runtime files)
+
+Like Kotlin: zero runtime files emitted. ajsc handles `AnyCodable` inline when `unsupportedUnions: 'fallback'` is set — we don't emit a separate helper file.
+
+## Pipeline integration
+
+`src/codegen/pipeline.ts` gets a third branch parallel to kotlin:
+
+```ts
+if (options.target === 'kotlin') { ... }
+if (options.target === 'swift') {
+  if (options.swiftEmitter == null) throw new Error(...)
+  // ... build errorSchemas, iterate groups, call emitSwiftScope, write files
+}
+```
+
+Naming inside `PipelineOptions`:
+- `target?: 'ts' | 'kotlin' | 'swift'`
+- `swiftSerializer?: 'codable' | 'none'`
+- `swiftAccessLevel?: 'public' | 'internal'`
+- `swiftEmitter?: SwiftEmitter` (test-injection hook, mirrors `kotlinEmitter`)
+
+Reused: `unsupportedUnions` (already on options).
+
+## CLI integration
+
+`src/codegen/bin/cli.ts`:
+
+1. Extend `target` parser to accept `'swift'`.
+2. Add flags: `--swift-serializer`, `--swift-access-level`.
+3. Add `swift?: { serializer?, accessLevel? }` to `CodegenConfig` and `ParsedArgs`.
+4. No package validation (Swift has no required field).
+5. Extend `printPostRunHints` for swift target → link `docs/codegen-swift.md`.
+6. Watch-mode: resolve swift emitter once at startup, parallel to kotlin.
+7. Do NOT add a Swift no-op-flag warning for `--unsupported-unions` (it works on Swift).
+
+## Tests
+
+Mirror the Kotlin test layout:
+
+1. **`ajsc-adapter.test.ts`** — stub creator + production resolver (mocking `ajsc` module to assert error messages when missing or `emitSwift` is undefined).
+2. **`format-swift.test.ts`** — `swiftHeader`, `swiftImports` dedupe+sort, `indent`, `pickDefined`.
+3. **`emit-route-swift.test.ts`** — path-builder for params/no-params, slot order (PathParams, Query, Body, Response), Errors namespace, stream-skipping.
+4. **`emit-scope-swift.test.ts`** — PascalCase scope name, file-name `Foo.swift`, imports dedupe across routes, empty scope, option threading.
+5. **`integration.test.ts`** — golden-file test using the `users-envelope.json` fixture and a hand-stubbed emitter, byte-identical against `users-golden.swift`.
+6. **`e2e-compile.test.ts`** — `it.skipIf(no swiftc)` — invokes `swiftc -parse` on the generated file to verify syntactic correctness. Skipped by default; only runs when `swiftc` is on `PATH`.
+
+Tests inject `createStubSwiftEmitter()` so output is deterministic and independent of ajsc's per-version evolution. The E2E compile test is the only one that exercises real ajsc.
+
+## Documentation
+
+1. **`docs/codegen-swift.md`** — full setup guide:
+   - Quickstart example
+   - SPM/Xcode integration (target setup, file inclusion)
+   - JSONDecoder configuration (`.iso8601` for Date)
+   - Sample output
+   - Discriminated unions (Swift uses `init(from:)` / `encode(to:)`)
+   - JSON-key sanitization (CodingKeys)
+   - `--swift-serializer none` (when consumers want plain structs for SwiftJSON or hand-rolled coding)
+   - Error types (nested under `Errors`)
+   - Untagged unions (`fallback` works on Swift, emits `AnyCodable`)
+   - Documented limitations
+
+2. **`CLAUDE.md`** — add Swift target paragraph parallel to Kotlin; emphasize differences (`--unsupported-unions fallback` works for Swift; no `--swift-package` requirement).
+
+3. **`agent_config/claude-code/skills/ts-procedures-swift/SKILL.md`** — parallel to `ts-procedures-kotlin/SKILL.md`. Cross-link both kotlin and swift skills from the main `ts-procedures` skill.
+
+## Implementation phases
+
+**Phase 1 (foundation):** ajsc-adapter, format helpers, emit-route, emit-scope (+ unit tests for each). Single sub-agent.
+
+**Phase 2 (integration):** Wire into pipeline.ts, index.ts, cli.ts. Add integration test with golden file. Single sub-agent depending on Phase 1.
+
+**Phase 3 (docs+skill, parallel with Phase 1/2):** Write `docs/codegen-swift.md`, update CLAUDE.md, create agent_config skill. Single sub-agent independent of code.
+
+**Phase 4 (verify):** `npm run build && npm test && npm run lint`. Inspect generated golden file. Confirm CLI invocation works.
+
+## Risk / open questions
+
+- **swiftc on dev machines** — E2E test is skipped by default to avoid CI failures. Same pattern as kotlin's `e2e-compile.test.ts`.
+- **`type: integer` → `Int64`** — Swift idiom is `Int` for general use; `Int64` is heavier visually. Accept ajsc's choice for now (can revisit if mobile devs request `Int`).
+- **`type: number` → `Double`** — for monetary values, mobile devs should use `Decimal`. Document the workaround in `docs/codegen-swift.md`.
+- **CodingKeys are mandatory** when keys differ — ajsc emits these automatically. We just have to make sure our golden file includes them and tests don't lock them away.
+
+## Success criteria
+
+- `npm test` passes (all kotlin tests still pass, new swift tests pass).
+- `npm run build` succeeds.
+- `npm run lint` clean.
+- Manual run: `npx ts-procedures-codegen --target swift --url ... --out ...` produces a valid `Users.swift` (or whatever scope) that compiles with `swiftc -parse`.
+- Docs and skill files committed; `agent_config/postinstall` will distribute them on next install.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-procedures",
-  "version": "6.1.0",
+  "version": "6.2.0",
   "description": "A TypeScript RPC framework that creates type-safe, schema-validated procedure calls with a single function definition. Define your procedures once and get full type inference, runtime validation, and framework integration hooks.",
   "main": "build/exports.js",
   "types": "build/exports.d.ts",
@@ -78,7 +78,7 @@
     "framework"
   ],
   "optionalDependencies": {
-    "ajsc": "7.2",
+    "ajsc": "7.2.0",
     "express": "^5.2.1",
     "hono": "^4.7.4"
   },