ts-procedures 6.0.2 → 6.2.0

package/build/codegen/test-helpers/golden.test.js

@@ -0,0 +1,76 @@
+import { describe, expect, it, afterEach } from 'vitest';
+import { mkdtempSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { assertGoldenOrUpdate } from './golden.js';
+let tmpDir;
+afterEach(() => {
+    if (tmpDir != null) {
+        rmSync(tmpDir, { recursive: true, force: true });
+        tmpDir = undefined;
+    }
+});
+function makeTmp() {
+    tmpDir = mkdtempSync(join(tmpdir(), 'tsp-golden-'));
+    return tmpDir;
+}
+describe('assertGoldenOrUpdate', () => {
+    it('asserts byte-equality against golden when produced matches (with hash splice)', async () => {
+        const dir = makeTmp();
+        const goldenPath = join(dir, 'expected.txt');
+        writeFileSync(goldenPath, 'hello\n// Source hash: <PLACEHOLDER>\nworld\n', 'utf-8');
+        const produced = 'hello\n// Source hash: abc123def456\nworld\n';
+        await expect(assertGoldenOrUpdate(produced, goldenPath)).resolves.toBeUndefined();
+    });
+    it('throws when produced does not match golden', async () => {
+        const dir = makeTmp();
+        const goldenPath = join(dir, 'expected.txt');
+        writeFileSync(goldenPath, 'expected content\n', 'utf-8');
+        const produced = 'different content\n';
+        await expect(assertGoldenOrUpdate(produced, goldenPath)).rejects.toThrow();
+    });
+    it('writes a portable golden when UPDATE_GOLDENS=1', async () => {
+        const original = process.env.UPDATE_GOLDENS;
+        process.env.UPDATE_GOLDENS = '1';
+        try {
+            const dir = makeTmp();
+            const goldenPath = join(dir, 'expected.txt');
+            const produced = 'hello\n// Source hash: deadbeef1234\nworld\n';
+            await assertGoldenOrUpdate(produced, goldenPath);
+            const written = readFileSync(goldenPath, 'utf-8');
+            expect(written).toBe('hello\n// Source hash: <PLACEHOLDER>\nworld\n');
+        }
+        finally {
+            if (original === undefined)
+                delete process.env.UPDATE_GOLDENS;
+            else
+                process.env.UPDATE_GOLDENS = original;
+        }
+    });
+    it('handles produced output without a source-hash line', async () => {
+        const dir = makeTmp();
+        const goldenPath = join(dir, 'expected.txt');
+        writeFileSync(goldenPath, 'plain content\n', 'utf-8');
+        // No source hash; splice is a no-op on both sides.
+        await expect(assertGoldenOrUpdate('plain content\n', goldenPath)).resolves.toBeUndefined();
+    });
+    it('regenerate mode handles produced output without a source-hash line', async () => {
+        const original = process.env.UPDATE_GOLDENS;
+        process.env.UPDATE_GOLDENS = '1';
+        try {
+            const dir = makeTmp();
+            const goldenPath = join(dir, 'expected.txt');
+            const produced = 'no hash line here\n';
+            await assertGoldenOrUpdate(produced, goldenPath);
+            const written = readFileSync(goldenPath, 'utf-8');
+            expect(written).toBe('no hash line here\n');
+        }
+        finally {
+            if (original === undefined)
+                delete process.env.UPDATE_GOLDENS;
+            else
+                process.env.UPDATE_GOLDENS = original;
+        }
+    });
+});
+//# sourceMappingURL=golden.test.js.map

package/build/codegen/test-helpers/golden.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"golden.test.js","sourceRoot":"","sources":["../../../src/codegen/test-helpers/golden.test.ts"],"names":[],"mappings":"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"}

package/docs/codegen-kotlin.md

@@ -0,0 +1,176 @@
+# Kotlin Codegen Setup Guide
+
+Generated by `ts-procedures-codegen --target kotlin`. One `.kt` file per scope; types are nested under route objects (`Users.GetUser.Response`, `Users.GetUser.Body.Address`).
+
+## Quickstart
+
+```bash
+npx ts-procedures-codegen \
+  --target kotlin \
+  --kotlin-package com.example.api \
+  --url https://api.example.com/_ts-procedures.json \
+  --out ./src/main/kotlin/com/example/api
+```
+
+Each scope produces one file (e.g. `Users.kt`). Access generated types as `Users.GetUser.Response`, `Users.GetUser.Body.GuestBody`, `Users.GetUser.Errors.NotFound`.
+
+## Gradle setup
+
+The default `--kotlin-serializer kotlinx` mode emits `@Serializable` data classes. Add the kotlinx-serialization plugin and runtime:
+
+```kotlin
+// build.gradle.kts
+plugins {
+    kotlin("jvm") version "<your-kotlin-version>"
+    kotlin("plugin.serialization") version "<your-kotlin-version>"
+}
+
+dependencies {
+    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:<version>")
+}
+```
+
+(`kotlinx-serialization-core` is a transitive dependency of `-json`; you don't need to declare it explicitly.)
+
+**JVM only.** Kotlin Multiplatform is not yet supported. If you need KMP-portable types, fall back to `--kotlin-serializer none` or post-process the emitted code.
+
+## Contextual serializers
+
+`format: date-time`, `format: uuid`, `format: uri`, `format: date`, `format: time` map to JVM stdlib types (`java.time.Instant`, `java.util.UUID`, etc.) annotated with `@Contextual`. Kotlinx-serialization does not know how to serialize these natively — register contextual serializers in your `Json` configuration:
+
+```kotlin
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.modules.SerializersModule
+import kotlinx.serialization.modules.contextual
+
+val json = Json {
+    serializersModule = SerializersModule {
+        contextual(java.time.Instant::class, InstantSerializer)
+        contextual(java.util.UUID::class, UUIDSerializer)
+        contextual(java.net.URI::class, URISerializer)
+        // ...etc for any format you use
+    }
+}
+```
+
+The serializers themselves are your responsibility (we don't ship them — the choice between ISO-8601 strings, epoch milliseconds, etc. is application-specific). Public Gist-quality implementations are widely available; we recommend ISO-8601 to match the server.
+
+## Discriminated unions
+
+A schema with a `oneOf` whose variants share a const-valued discriminator (e.g. `kind: "guest" | "registered"`) emits as a sealed interface:
+
+```kotlin
+@Serializable
+@JsonClassDiscriminator("kind")
+sealed interface Body {
+    @Serializable
+    @SerialName("guest")
+    data class GuestBody(val displayName: String) : Body
+
+    @Serializable
+    @SerialName("registered")
+    data class RegisteredBody(val email: String, val name: String) : Body
+}
+```
+
+The discriminator field (`kind`) is **erased** from each variant under `--kotlin-serializer kotlinx` — `@SerialName` carries it on the wire. With `--kotlin-serializer none` the discriminator field is retained.
+
+`@JsonClassDiscriminator` is read automatically by the kotlinx `Json` instance — no extra config needed.
+
+## JSON-key sanitization
+
+Kebab-case and snake-case JSON keys become camelCase property names with `@SerialName` auto-emitted so the wire format stays correct:
+
+```kotlin
+@Serializable
+data class Response(
+    @SerialName("created-at")
+    @Contextual
+    val createdAt: java.time.Instant,
+)
+```
+
+Reserved Kotlin words get a trailing underscore (`class` → `class_`).
+
+## Switching off kotlinx (Moshi, Gson, hand-written)
+
+`--kotlin-serializer none` emits plain `data class` types with no `@Serializable` annotation. You're then responsible for adapter setup:
+
+- **Reflection-based libraries** (Gson) work without further changes.
+- **Codegen-based** (Moshi with codegen) need their own annotation layer added.
+- Sealed interfaces still emit; the discriminator field is **retained** in variants under `none` mode.
+
+## Error types
+
+Each route that declares errors gets a nested `Errors` object containing one `@Serializable data class` per error name:
+
+```kotlin
+object Users {
+    object GetUser {
+        // ... method, path, types ...
+        object Errors {
+            @Serializable
+            data class NotFound(
+                val name: String = "NotFound",
+                val message: String,
+            )
+        }
+    }
+}
+```
+
+Access generated error types as `Users.GetUser.Errors.NotFound`.
+
+**No runtime dispatch.** Unlike the TypeScript target, the Kotlin target ships **types only** — there is no error registry, no `instanceof`-style lookup, no `dispatchTypedError`. Mobile consumers catch HTTP failures themselves and inspect `body.name` (which is a regular `String` field, not a type-system discriminator) to decide which error data class to deserialize against:
+
+```kotlin
+suspend fun loadUser(id: String): Result<Users.GetUser.Response> {
+    val response = httpClient.request(method = Users.GetUser.method, path = "...")
+    return when {
+        response.status == 200 -> Result.success(json.decodeFromString(response.body))
+        response.status == 404 -> {
+            val err = json.decodeFromString<Users.GetUser.Errors.NotFound>(response.body)
+            Result.failure(NotFoundException(err.message))
+        }
+        else -> Result.failure(IOException("HTTP ${response.status}"))
+    }
+}
+```
+
+Choosing the dispatch strategy (status-code based, body.name based, sealed-class hierarchy of your own, etc.) is intentionally left to consumers.
+
+## Untagged unions
+
+ajsc v7.2's Kotlin emitter silently produces an empty `@Serializable data class` for any untagged `oneOf` schema, regardless of whether `--unsupported-unions fallback` is set. There is no "throws on default" mode for Kotlin (that's Swift behavior). The `--unsupported-unions` flag is currently a no-op for the Kotlin target.
+
+For example, the schema `oneOf: [{ type: 'string' }, { type: 'integer' }]` with `rootTypeName: 'Mixed'` produces:
+
+```kotlin
+@Serializable
+data class Mixed()
+```
+
+Imports: `kotlinx.serialization.Serializable`.
+
+**Practical implication.** This empty data class won't round-trip your data — calling `Json.decodeFromString<Mixed>("\"hello\"")` will fail because `Mixed` has no payload. **Untagged unions in your schema cannot be consumed via the generated Kotlin types.** Workarounds:
+
+1. **Add a discriminator** to your server-side schema so it becomes a tagged union (sealed interface emission — see "Discriminated unions" section above).
+2. **Hand-write a `KSerializer<T>` `companion object`** in a sibling file that resolves the union at deserialization time.
+3. **Strip the union field at the codegen boundary** — pre-process the envelope to replace untagged `oneOf` with a single permissive type (e.g. `JsonElement`).
+
+We track this as an ajsc upstream limitation; if it's resolved in a future ajsc release, this section will be updated.
+
+## Documented limitations
+
+The following ajsc behaviors are intentional and documented; they are **not bugs**:
+
+- `additionalProperties: { type: T }` is silently dropped with a `/** Note: schema permits additional keys of type T — not modeled. */` KDoc note. If your contract uses extra keys, add a sibling `Map<String, T>` field by hand or write a custom `KSerializer`.
+- Tuples with 4 or more positional types throw (`Pair`/`Triple` only). Refactor to a struct schema upstream.
+- Schema-level `examples` and `not` / `patternProperties` are not modeled (the latter throw with a path-bearing error).
+
+## Reference
+
+- Spec: [`docs/superpowers/specs/2026-04-25-ajsc-v7-kotlin-polish-design.md`](./superpowers/specs/2026-04-25-ajsc-v7-kotlin-polish-design.md)
+- For iOS / macOS / Apple-platform consumers, see [`docs/codegen-swift.md`](./codegen-swift.md) — same types-only design with Swift-specific flags and `Codable` 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 "Kotlin target") and the spec linked above. (`--help` is not currently implemented; pass invalid/missing args to see error messages with usage hints.)

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.)