ts-procedures 6.0.2 → 6.1.0

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

@@ -0,0 +1,314 @@
+# ajsc v7.2 Kotlin Codegen Polish
+
+**Status:** Design
+**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.
+**Scope:** Polish the existing `codegen-kotlin-swift` branch's Kotlin target to align with `ajsc@^7.2.0`. No Swift work in this round.
+
+## Context
+
+The original Kotlin codegen design ([2026-04-24](./2026-04-24-kotlin-swift-codegen-design.md)) anticipated an "ajsc Phase A" delivery exposing `emitKotlin`. ajsc shipped that and more in `7.0` → `7.1` → `7.2`:
+
+- **`7.0`** delivered `emitKotlin` and `emitSwift` with the `EmitResult` shape the prior spec specified.
+- **`7.1`** added `nameRegistry: Set<string>` + `namePrefix: string` to make cross-call dedup tractable when concatenating multiple slot emissions into one namespace.
+- **`7.2`** added `inlineTypes?: boolean` (default `false`). When `true`, nested object types emit as **nested classes inside their parent's body** instead of extracting to top-level siblings. Kotlin's nested-class scoping makes `Body.Address` and `Response.Address` different fully-qualified names — collisions become structurally impossible without any shared state.
+
+The current branch implementation predates `7.1` and `7.2`. It calls `emitKotlin` once per slot with no shared registry, which is a correctness bug for any schema that has structurally-identical sub-objects in two slots (Kotlin emits `data class Address(...)` from both calls → duplicate-class compile error).
+
+This polish round adopts `inlineTypes: true` as the routing strategy, drops dead options from our adapter contract, surfaces `serializer` and `unsupportedUnions` as CLI flags, replaces the trivial test fixture with a realistic one, activates the gated `kotlinc` E2E test, and ships a downstream-consumer setup guide.
+
+## Goals
+
+1. **Correctness**: generated Kotlin compiles for realistic schemas (shared sub-types across slots, discriminated unions, `format: date-time` fields, JSON-key sanitization).
+2. **Clean separation of concerns**: ajsc emits declarations; `ts-procedures` wraps and writes files. No shared state across `emit` calls in our code.
+3. **Easy-to-follow code**: route emitter is a pure function — same inputs, same output, no per-call coordination logic.
+4. **Strong downstream DX**: a typed Android/iOS dev integrating generated output gets a clear setup guide covering Gradle deps, contextual serializers, sealed-interface decoding, and the `serializer: 'none'` escape hatch.
+5. **Forward-compat**: changes are additive on the CLI surface and conservative on defaults so future Swift work and future ajsc releases land cleanly.
+
+## Non-goals
+
+- **Swift target.** Stays deferred. The architecture sketched here generalizes naturally — same per-slot loop, same `inlineTypes: true` strategy — but a separate spec will cover Swift-specific idioms (`Codable`, `AnyCodable` fallback shape, `accessLevel`).
+- **Cross-route shared types.** No `Shared.User` extraction. Each route's types live under its own `object`.
+- **Streaming routes.** Skipped with a single summary log line, as in the original spec.
+- **Hooks, per-call options, error registry, base-URL handling.** All deferred per the prior spec; nothing changes.
+- **Mid-PR changes to TS target output.** The TS codegen path is untouched.
+- **`agent_config/` distribution updates.** Codegen targets are not agent-relevant content.
+
+## Architecture & boundary
+
+The contract between ajsc and `ts-procedures` is unchanged from the original spec: ajsc emits **declarations only** (no `package`, no `import` lines); `ts-procedures` assembles the file (`package` line, deduped imports, scope/route wrappers, source-hash header).
+
+```
+DocEnvelope
+  → resolveEnvelope
+  → groupRoutesByScope
+  → for each scope:
+       → for each route:
+            → for each slot in [pathParams, query, body, response, ...errors]:
+                 emitKotlin(slotSchema, { rootTypeName: slot.name, inlineTypes: true, serializer, unsupportedUnions, ...passthrough })
+            → wrap collected emissions in `object RouteName { method, pathTemplate, path(...) | const path, ...slots, Errors? }`
+       → wrap routes in `object Scope { ... }`
+       → prepend package + source-hash + imports
+       → write Scope.kt
+```
+
+Two architectural decisions:
+
+- **`packageName` opt is not passed to ajsc.** The scope emitter writes `package com.example.api` itself. Keeps the boundary "ajsc gives declarations, we assemble files" intact and avoids any (untested) interaction of v7.2's `packageName` opt with the `code` body.
+- **No shared state across emit calls.** Per-route registry plumbing (`nameRegistry` / `namePrefix`) is **not** used. `inlineTypes: true` makes it unnecessary because nested-class scoping is structural.
+
+## Adapter contract — `KotlinEmitOptions` final shape
+
+```ts
+export interface KotlinEmitOptions {
+  rootTypeName: string                          // required — slot name (Body, Response, NotFound, ...)
+  inlineTypes?: boolean                         // we always pass true
+  serializer?: 'kotlinx' | 'none'               // CLI flag, default 'kotlinx'
+  unsupportedUnions?: 'throw' | 'fallback'      // CLI flag, default 'throw'
+  arrayItemNaming?: string | false              // pass-through (existing CLI flag)
+  depluralize?: boolean                         // pass-through (existing CLI flag)
+  uncountableWords?: string[]                   // pass-through (existing CLI flag)
+}
+```
+
+**Removed from the existing branch's adapter:**
+
+- `inlineTypes` previously typed as a knob — now hardcoded `true` (still on the type but never set by callers other than ourselves).
+- `enumStyle` — TypeScript-only ajsc opt; never honored by `KotlinConverterOpts`.
+
+**Not used by us (but valid in ajsc):** `nameRegistry`, `namePrefix`, `packageName`, `unsupportedUnions: 'fallback'` for already-decided opt-in flow.
+
+The `KotlinEmitter` interface stays `emit(schema, opts) → KotlinEmitResult`. The production resolver collapses to a one-liner:
+
+```ts
+return { emit: (schema, opts) => emitKotlin(schema, opts) }
+```
+
+The stub factory (`createStubKotlinEmitter`) used in unit/integration tests stays the same shape — keyed on `rootTypeName`, returns hand-authored `KotlinEmitResult` objects.
+
+## Per-route emission
+
+`emit-route-kotlin.ts` becomes a pure function — no shared `Set<string>`, no prefix arithmetic:
+
+```
+emitKotlinRoute(route, emitter, errorSchemas, { serializer, unsupportedUnions, ...passthrough }):
+  if route.kind === 'stream' → return { code: '', imports: [], routeName, skipped: true }
+
+  emit lines:
+    `const val method = "<method>"`
+    `const val pathTemplate = "<bracePath>"`
+    `fun path(p: PathParams): String = "<interpolated>"`   if path params present
+    `const val path = "<bracePath>"`                       otherwise
+
+  for each slot in [pathParams, query, body, response]:
+    if slot.schema is null, skip
+    result = emitter.emit(slot.schema, { rootTypeName: slot.name, inlineTypes: true, serializer, unsupportedUnions, ...passthrough })
+    push result.code, result.imports
+
+  for each errorKey in route.errors:
+    if errorSchemas.has(errorKey):
+      result = emitter.emit(errorSchemas.get(errorKey), { rootTypeName: errorKey, inlineTypes: true, serializer, unsupportedUnions, ...passthrough })
+      collect into Errors namespace
+  if any errors emitted, append wrapped `object Errors { ... }`
+
+  return { code, imports, routeName, skipped: false }
+```
+
+Slot emit order is fixed: `pathParams → query → body → response → errors[]`. Deterministic output is required for the source-hash staleness check.
+
+**Stream-skip:** the route emitter returns `skipped: true`; the pipeline collects names and logs **one summary line** at end of run. No per-route warnings during emission.
+
+## Pipeline & CLI
+
+### `PipelineOptions` additions
+
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `target` | `'ts' \| 'kotlin'` | `'ts'` | unchanged |
+| `kotlinPackage` | `string` | — | required when `target === 'kotlin'` |
+| `kotlinSerializer` | `'kotlinx' \| 'none'` | `'kotlinx'` | new |
+| `unsupportedUnions` | `'throw' \| 'fallback'` | `'throw'` | new — top-level (not Kotlin-nested) so name stays stable when Swift lands |
+| `kotlinEmitter` | `KotlinEmitter \| undefined` | — | injected for tests; production CLI resolves via `resolveProductionKotlinEmitter()` |
+
+### CLI flags
+
+| Flag | Maps to | Notes |
+|---|---|---|
+| `--target <ts\|kotlin>` | `target` | unchanged |
+| `--kotlin-package <pkg>` | `kotlinPackage` | unchanged; required when `target=kotlin` |
+| `--kotlin-serializer <kotlinx\|none>` | `kotlinSerializer` | new |
+| `--unsupported-unions <throw\|fallback>` | `unsupportedUnions` | new |
+| `--array-item-naming`, `--depluralize`, `--uncountable-words` | `KotlinEmitOptions` pass-through | existing TS-target flags, now also applied to Kotlin target |
+
+**Silently ignored under `--target ts`:** `--kotlin-serializer`. **Silently ignored under `--target kotlin`:** `--service-name`, `--namespace-types`, `--self-contained`, `--client-import-path`, `--jsdoc` (matches existing behavior).
+
+### Config-file mapping
+
+```json
+{
+  "target": "kotlin",
+  "kotlin": { "package": "com.example.api", "serializer": "kotlinx" },
+  "unsupportedUnions": "throw",
+  "url": "https://api.example.com/_ts-procedures.json",
+  "out": "./generated"
+}
+```
+
+CLI flags override config values. `--kotlin-serializer none` works regardless of imports — ajsc decides.
+
+### Where parsed values land
+
+The existing `parseArgs` returns `ParsedArgs` with `parsed.kotlin.package` for the package flag. The new fields slot in the same way:
+
+| CLI flag | Lands at | Rationale |
+|---|---|---|
+| `--kotlin-serializer` | `parsed.kotlin.serializer` | Kotlin-specific knob — nests under `kotlin` like `package` |
+| `--unsupported-unions` | `parsed.unsupportedUnions` | Top-level — forward-compat for Swift and any future target |
+
+### Behavior under `--target ts`
+
+| Flag | TS-target behavior |
+|---|---|
+| `--kotlin-serializer` | silently ignored (Kotlin-only knob) |
+| `--unsupported-unions` | **threaded through** to TS emit unconditionally — it is a no-op in ajsc's TypeScript converter today, but threading it preserves forward-compat semantics |
+| `--kotlin-package` | silently ignored |
+
+### `--kotlin-inline-types` is intentionally not exposed
+
+Hardcoding `inlineTypes: true` is a deliberate design choice. The flat-types pattern (`nameRegistry` + `namePrefix`) remains supported by ajsc; if a consumer demands it later, an opt-out flag (`--kotlin-flat-types`) can be added additively without breaking existing output.
+
+## Testing strategy
+
+Four layers, each catching a distinct class of breakage. The current branch already has skeletons for three; this round updates assertions to v7.2 reality and adds the fourth (probe).
+
+### Realistic fixture (`__fixtures__/users-envelope.json`)
+
+Single source of truth for the integration golden and the kotlinc E2E. Replaces the existing `{ type: 'object' }` placeholder envelope. Contains:
+
+| Route | Exercises |
+|---|---|
+| `GET /users/:id` (`GetUser`) | path params + nested response object + nested address (two-level nesting → exercises `inlineTypes`) + `format: date-time` field (`@Contextual Instant`) + `created-at` JSON key (auto `@SerialName`) + one error (`NotFound`) |
+| `POST /users` (`CreateUser`) | no path params → `const val path` branch + body with discriminated `oneOf` (sealed interface emission) + one error (`ValidationError`) |
+| `GET /users` (`ListUsers`) | query params + array response + enum field (`status: 'active' \| 'inactive'`) → top-level enum extraction (always extracted regardless of `inlineTypes`) |
+
+Plus envelope-level `errors[]` with two error schemas so the route emitter's filter-by-key logic gets real signal.
+
+### Layer 1 — Unit tests (revised, unconditional, sub-second)
+
+Per-file 1:1 with current layout. Behavioral changes:
+
+- **`format-kotlin.test.ts`** — no changes.
+- **`ajsc-adapter.test.ts`** — drop `inlineTypes`/`enumStyle` from contract test; pin error-message text from `resolveProductionKotlinEmitter()` when `import('ajsc')` fails or `emitKotlin` is missing.
+- **`emit-route-kotlin.test.ts`** — drop registry/prefix assertions; add `expect(passedOpts.inlineTypes).toBe(true)` per slot; verify slot ordering; verify stream routes return `skipped: true` and empty code.
+- **`emit-scope-kotlin.test.ts`** — confirm imports deduped/sorted across all routes in a scope; no namespace-shape changes.
+
+### Layer 2 — Integration test (golden, stub emitter)
+
+`integration.test.ts` runs full `runPipeline` against the realistic fixture with a **stub** emitter returning hand-authored ajsc-style output (nested-class shape) per slot. Asserts byte-identical match against `__fixtures__/users-golden.kt`.
+
+**Why stub for integration:** pins our wrapping logic independent of ajsc version drift. If a future ajsc patch tweaks formatting whitespace, the golden test still passes; the kotlinc E2E catches semantic regressions. Separates "did our pipeline assemble the right file?" from "does ajsc still emit valid Kotlin?"
+
+Golden regenerated via `UPDATE_GOLDENS=1 npx vitest run integration.test.ts`. Source-hash line spliced from actual run.
+
+### Layer 3 — Kotlinc E2E compile test
+
+`e2e-compile.test.ts` runs the pipeline with the **production** ajsc emitter against the realistic fixture, writes output to a tmp dir, invokes `kotlinc` with `kotlinx-serialization-json` on classpath, asserts exit 0.
+
+**Gating:** `it.skipIf(!kotlincAvailable() || process.env.TS_PROCEDURES_KOTLIN_E2E !== '1')`. The ajsc Phase A check is removed — v7.2 is installed.
+
+**What this catches that nothing else does:** silent name-collision regressions, schema patterns producing uncompilable Kotlin (reserved-word edges), missing `@Contextual` annotations, sealed-interface scoping bugs.
+
+### Layer 4 — Probe test for `unsupportedUnions: 'fallback'` Kotlin behavior
+
+The v7.2 handoff specifies the **Swift** fallback shape (`AnyCodable` helper) but does not pin the **Kotlin** fallback shape. We need to know it before documenting the flag.
+
+`probe-unsupported-unions.test.ts` runs the real `emitKotlin` with `{ oneOf: [{ type: 'string' }, { type: 'integer' }] }` and `unsupportedUnions: 'fallback'`. Asserts via `toMatchSnapshot()` — captures whatever ajsc currently emits. The captured snapshot becomes the basis for the consumer doc's "untagged unions" section. If a future ajsc release changes the fallback shape, the snapshot diff surfaces it.
+
+**Gating:** `ajsc` is in `optionalDependencies`, so a contributor running `npm install --omit=optional` won't have it resolvable. The probe gates with the same toolchain-availability pattern as the E2E: `it.skipIf(!ajscResolvable())`. The check tries `import('ajsc')` once at module load and skips if the import throws. No kotlinc needed.
+
+## Downstream consumer documentation
+
+The highest-DX-impact deliverable in this plan. Without it, the first downstream Android dev hits "why won't `Json.decodeFromString` round-trip my `Instant`?" and the codegen feels broken.
+
+### New doc: `docs/codegen-kotlin.md`
+
+Self-contained setup guide. Outline:
+
+| Section | Content |
+|---|---|
+| Quickstart | `npx ts-procedures-codegen --target kotlin --kotlin-package com.example.api ...`; one `Users.kt` per scope; types accessed as `Users.GetUser.Response`, `Users.GetUser.Body.Address` (nested). |
+| Gradle setup | `kotlin("plugin.serialization")` + `kotlinx-serialization-json` dep with current pin; KMP non-support note (JVM only for now). |
+| Contextual serializers | What `@Contextual` means; copy-pasteable `Json { serializersModule = ... }` block; pointers to public Gist-quality serializers for `Instant`, `UUID`, `URI`, `LocalDate`, `LocalTime`. We recommend ISO-8601 to match server. |
+| Discriminated unions | `sealed interface` shape; `@JsonClassDiscriminator` is read automatically — no extra config. Wire format: discriminator field erased from variants under kotlinx mode. |
+| JSON-key sanitization | `first-name` → `firstName` with `@SerialName("first-name")` auto-emitted. Reserved words → trailing underscore. Nothing to configure. |
+| `--kotlin-serializer none` | Emit plain data classes with no annotations. Adapter setup is your own (Moshi, Gson, hand-written). Discriminator field is **retained** in variants under `none` mode. |
+| `--unsupported-unions fallback` | Kotlin fallback shape sourced from the Section "Layer 4" probe snapshot — **not authored speculatively**. Filled in once probe runs. |
+| Documented limitations | `additionalProperties: { type: T }` dropped with KDoc note; tuples >3 throw; `examples` dropped. What to do if you hit them. |
+
+**Distribution:** the doc lives in `docs/` of this repo. The CLI prints a one-line pointer after a successful Kotlin run:
+
+```
+[ts-procedures-codegen] Wrote 3 .kt files to ./generated. Setup guide: https://github.com/<org>/ts-procedures/blob/master/docs/codegen-kotlin.md
+```
+
+Once per invocation. No per-file boilerplate.
+
+### `CLAUDE.md` updates
+
+Small update to the existing "Kotlin target" bullet:
+
+- Output-shape change: `Users.GetUser.Body.Address` (nested) instead of `Users.GetUser.BodyAddress`.
+- New flags: `--kotlin-serializer <kotlinx|none>` (default `kotlinx`), `--unsupported-unions <throw|fallback>` (default `throw`).
+- Pointer to `docs/codegen-kotlin.md` for downstream consumer setup.
+
+## Migration / backwards-compatibility
+
+This polish lands on the unmerged `codegen-kotlin-swift` branch. Kotlin codegen has not shipped to a tagged release yet, so "migration" means "what changes between this branch's current state and the polished state."
+
+| Change | Visible to | Action |
+|---|---|---|
+| Output shape: flat → nested (`Body.Address`) | anyone testing the branch | Re-run codegen; references like `BodyAddress` become `Body.Address` |
+| Two new CLI flags | CLI users | None — defaults preserve prior behavior |
+| Realistic fixture replaces trivial one | reviewers of integration golden | Standard golden regeneration |
+| Unit test reshape | nobody outside this repo | None |
+| `optionalDependencies: ajsc` constraint bumps to `^7.2.0` | `package.json` consumers | npm install resolves it |
+
+When the branch ships, the `feat!` commit explicitly notes the nested-types output shape so downstream consumers reading the changelog know what to expect.
+
+## Risk assessment
+
+- **Risk: ajsc v7.2 emits subtly-different output for one of our fixture cases.** Mitigated by the kotlinc E2E test (compiles real ajsc output) plus the probe snapshot for `unsupportedUnions: 'fallback'`.
+- **Risk: realistic fixture is "realistic enough" but misses a pattern that breaks in production.** Mitigated by the layered test pyramid: unit tests pin our wrapping; integration golden pins file assembly; E2E compile pins ajsc semantics; probe pins ajsc-undocumented behavior. We close the loop in production by the first real consumer's feedback, not by trying to enumerate every schema shape upfront.
+- **Risk: nested-types DX is unintuitive for a shop expecting flat names.** Mitigated by the `--kotlin-flat-types` opt-out path remaining available in ajsc; we can add a CLI flag additively without breaking existing output. The handoff doc explicitly says both modes are supported indefinitely.
+- **Risk: Gradle / contextual-serializer setup is too much friction.** Mitigated by `docs/codegen-kotlin.md` having copy-pasteable blocks and serializer pointers, and by `--kotlin-serializer none` as a one-flag escape if a consumer's ecosystem can't accept the kotlinx Gradle plugin.
+- **Risk: CI does not have `kotlinc` available.** The E2E compile test gates on `TS_PROCEDURES_KOTLIN_E2E=1` and toolchain detection; CI without `kotlinc` skips it. Local runs and at-minimum manual pre-release runs catch what CI doesn't.
+
+## Open questions / explicit deferrals
+
+1. **CI integration of the kotlinc E2E.** Provisioning `kotlinc` + `kotlinx-serialization-json` in CI is a separate, optional decision. This spec ships the test gated; CI activation can follow once a maintainer wants it.
+2. **`UPDATE_GOLDENS=1` ergonomics.** Standard golden-test pattern. If we need richer affordances (per-test golden regeneration, partial-update flags), that's a separate quality-of-life PR.
+3. **Cross-route shared types** — still deferred per original spec.
+4. **Swift target** — still deferred. The architecture designed here generalizes naturally; a separate spec covers Swift idioms.
+5. **`--kotlin-flat-types` opt-out flag** — not exposed in this round. Additive when needed.
+
+## Sequencing (execution-order summary, plan deferred)
+
+This spec drives a single implementation plan. Execution-order intent:
+
+1. `KotlinEmitOptions` shape cleanup (drop `inlineTypes` knob from caller surface, keep hardcoded internally; drop `enumStyle`).
+2. `emit-route-kotlin.ts` → pure function (no registry/prefix); pass `inlineTypes: true`, `serializer`, `unsupportedUnions` per emit; stream routes return `skipped: true`.
+3. Pipeline-level summary log for skipped streams.
+4. CLI: add `--kotlin-serializer`, `--unsupported-unions` flags; thread through.
+5. Realistic fixture replacement; regenerate integration golden.
+6. Probe test for `unsupportedUnions: 'fallback'` Kotlin shape; capture snapshot.
+7. Activate kotlinc E2E (drop ajsc Phase A gate, keep toolchain gate).
+8. `docs/codegen-kotlin.md` authored from v7 handoff + probe snapshot.
+9. CLI prints setup-guide pointer after successful Kotlin run.
+10. `CLAUDE.md` updates.
+
+The corresponding implementation plan is the next deliverable — produced from this spec via the `superpowers:writing-plans` skill, not part of this document.
+
+## Summary
+
+ajsc v7.2 made our originally-planned Kotlin codegen work simpler: `inlineTypes: true` collapses the cross-slot dedup problem by leaning on Kotlin's nested-class scoping. This polish round trims the adapter contract to v7.2's actual surface, adds two CLI flags for ajsc's escape hatches (`--kotlin-serializer`, `--unsupported-unions`), replaces the trivial test fixture with one that exercises real schema patterns, activates the previously-gated kotlinc compile E2E, and ships a downstream-consumer setup guide. Net result: the route emitter becomes a pure function, the integration tests prove real correctness, and the first Android team to integrate has a one-page guide that gets them running without backchannel questions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-procedures",
-  "version": "6.0.2",
+  "version": "6.1.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": "^5.2.4",
+    "ajsc": "7.2",
     "express": "^5.2.1",
     "hono": "^4.7.4"
   },

package/src/codegen/bin/cli.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect } from 'vitest'
-import { parseArgs, loadConfigFile, extractConfigPath, type CodegenConfig } from './cli.js'
+import { vi } from 'vitest'
+import { parseArgs, loadConfigFile, extractConfigPath, printPostRunHints, warnIfKotlinNoOpFlags, type CodegenConfig } from './cli.js'
 
 describe('parseArgs', () => {
   it('parses --url and --out', () => {
@@ -293,3 +294,201 @@ describe('config file support', () => {
     await expect(loadConfigFile('/nonexistent/config.json')).rejects.toThrow('Failed to load config')
   })
 })
+
+describe('cli — kotlin target', () => {
+  it('parses --target kotlin and --kotlin-package from CLI flags', () => {
+    const args = parseArgs(
+      ['--target', 'kotlin', '--kotlin-package', 'com.example.api', '--out', 'out', '--file', 'env.json'],
+    )
+    expect(args.target).toBe('kotlin')
+    expect(args.kotlin?.package).toBe('com.example.api')
+  })
+
+  it('reads kotlin.package from config when no CLI flag is provided', () => {
+    const config: CodegenConfig = {
+      target: 'kotlin',
+      kotlin: { package: 'com.example.api' },
+      outDir: 'out',
+      file: 'env.json',
+    }
+    const args = parseArgs(['--out', 'out', '--file', 'env.json'], config)
+    expect(args.target).toBe('kotlin')
+    expect(args.kotlin?.package).toBe('com.example.api')
+  })
+
+  it('CLI flag overrides config value', () => {
+    const config: CodegenConfig = {
+      target: 'kotlin',
+      kotlin: { package: 'old.pkg' },
+      outDir: 'out',
+      file: 'env.json',
+    }
+    const args = parseArgs(['--kotlin-package', 'new.pkg', '--out', 'out', '--file', 'env.json'], config)
+    expect(args.kotlin?.package).toBe('new.pkg')
+  })
+
+  it('errors when target is kotlin and no package is provided', () => {
+    expect(() =>
+      parseArgs(['--target', 'kotlin', '--out', 'out', '--file', 'env.json']),
+    ).toThrow(/--kotlin-package/)
+  })
+
+  it('--target ts is the default', () => {
+    const args = parseArgs(['--out', 'out', '--file', 'env.json'])
+    expect(args.target ?? 'ts').toBe('ts')
+  })
+})
+
+describe('cli — kotlin-serializer flag', () => {
+  it('parses --kotlin-serializer kotlinx', () => {
+    const args = parseArgs(['--target', 'kotlin', '--kotlin-package', 'p', '--kotlin-serializer', 'kotlinx', '--out', 'o', '--file', 'e.json'])
+    expect(args.kotlin?.serializer).toBe('kotlinx')
+  })
+
+  it('parses --kotlin-serializer none', () => {
+    const args = parseArgs(['--target', 'kotlin', '--kotlin-package', 'p', '--kotlin-serializer', 'none', '--out', 'o', '--file', 'e.json'])
+    expect(args.kotlin?.serializer).toBe('none')
+  })
+
+  it('reads kotlin.serializer from config', () => {
+    const args = parseArgs(['--out', 'o', '--file', 'e.json'], {
+      target: 'kotlin', kotlin: { package: 'p', serializer: 'none' }, outDir: 'o', file: 'e.json',
+    } as CodegenConfig)
+    expect(args.kotlin?.serializer).toBe('none')
+  })
+
+  it('CLI overrides config', () => {
+    const args = parseArgs(['--kotlin-serializer', 'kotlinx', '--out', 'o', '--file', 'e.json'], {
+      target: 'kotlin', kotlin: { package: 'p', serializer: 'none' }, outDir: 'o', file: 'e.json',
+    } as CodegenConfig)
+    expect(args.kotlin?.serializer).toBe('kotlinx')
+  })
+
+  it('throws on invalid value', () => {
+    expect(() => parseArgs(['--target', 'kotlin', '--kotlin-package', 'p', '--kotlin-serializer', 'bogus', '--out', 'o', '--file', 'e.json']))
+      .toThrow(/--kotlin-serializer/)
+  })
+})
+
+describe('cli — unsupported-unions flag', () => {
+  it('parses --unsupported-unions throw', () => {
+    const args = parseArgs(['--unsupported-unions', 'throw', '--out', 'o', '--file', 'e.json'])
+    expect(args.unsupportedUnions).toBe('throw')
+  })
+
+  it('parses --unsupported-unions fallback', () => {
+    const args = parseArgs(['--unsupported-unions', 'fallback', '--out', 'o', '--file', 'e.json'])
+    expect(args.unsupportedUnions).toBe('fallback')
+  })
+
+  it('reads unsupportedUnions from config', () => {
+    const args = parseArgs(['--out', 'o', '--file', 'e.json'], {
+      unsupportedUnions: 'fallback', outDir: 'o', file: 'e.json',
+    } as CodegenConfig)
+    expect(args.unsupportedUnions).toBe('fallback')
+  })
+
+  it('CLI overrides config', () => {
+    const args = parseArgs(['--unsupported-unions', 'throw', '--out', 'o', '--file', 'e.json'], {
+      unsupportedUnions: 'fallback', outDir: 'o', file: 'e.json',
+    } as CodegenConfig)
+    expect(args.unsupportedUnions).toBe('throw')
+  })
+
+  it('throws on invalid value', () => {
+    expect(() => parseArgs(['--unsupported-unions', 'bogus', '--out', 'o', '--file', 'e.json']))
+      .toThrow(/--unsupported-unions/)
+  })
+
+  it('default is undefined when not set', () => {
+    const args = parseArgs(['--out', 'o', '--file', 'e.json'])
+    expect(args.unsupportedUnions).toBeUndefined()
+  })
+})
+
+describe('cli — printPostRunHints', () => {
+  it('prints a setup-guide pointer for the kotlin target', () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    try {
+      printPostRunHints({ target: 'kotlin' })
+      const matched = logSpy.mock.calls.some((c) => String(c[0]).includes('docs/codegen-kotlin.md'))
+      expect(matched).toBe(true)
+    } finally {
+      logSpy.mockRestore()
+    }
+  })
+
+  it('prints nothing for the ts target', () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    try {
+      printPostRunHints({ target: 'ts' })
+      expect(logSpy).not.toHaveBeenCalled()
+    } finally {
+      logSpy.mockRestore()
+    }
+  })
+
+  it('prints nothing when target is undefined (default ts)', () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    try {
+      printPostRunHints({})
+      expect(logSpy).not.toHaveBeenCalled()
+    } finally {
+      logSpy.mockRestore()
+    }
+  })
+})
+
+describe('cli — warnIfKotlinNoOpFlags', () => {
+  it('warns when --unsupported-unions is set with --target kotlin', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      warnIfKotlinNoOpFlags({ target: 'kotlin', unsupportedUnions: 'fallback' })
+      const matched = warnSpy.mock.calls.some((c) => String(c[0]).includes('--unsupported-unions is currently a no-op'))
+      expect(matched).toBe(true)
+    } finally {
+      warnSpy.mockRestore()
+    }
+  })
+
+  it('warns when --unsupported-unions is set to throw with --target kotlin', () => {
+    // Even 'throw' is a no-op since ajsc never throws on Kotlin untagged oneOf.
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      warnIfKotlinNoOpFlags({ target: 'kotlin', unsupportedUnions: 'throw' })
+      expect(warnSpy).toHaveBeenCalled()
+    } finally {
+      warnSpy.mockRestore()
+    }
+  })
+
+  it('does not warn when --unsupported-unions is unset', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      warnIfKotlinNoOpFlags({ target: 'kotlin' })
+      expect(warnSpy).not.toHaveBeenCalled()
+    } finally {
+      warnSpy.mockRestore()
+    }
+  })
+
+  it('does not warn for the ts target even when --unsupported-unions is set', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      warnIfKotlinNoOpFlags({ target: 'ts', unsupportedUnions: 'fallback' })
+      expect(warnSpy).not.toHaveBeenCalled()
+    } finally {
+      warnSpy.mockRestore()
+    }
+  })
+
+  it('does not warn when target is undefined', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      warnIfKotlinNoOpFlags({ unsupportedUnions: 'fallback' })
+      expect(warnSpy).not.toHaveBeenCalled()
+    } finally {
+      warnSpy.mockRestore()
+    }
+  })
+})