ts-procedures 8.3.0 → 8.5.0

package/src/client/resolve-options.ts

@@ -1,5 +1,6 @@
 import type {
   AdapterRequest,
+  ClientHeadersInit,
   ProcedureCallDefaults,
   ProcedureCallOptions,
   RequestMeta,
@@ -79,15 +80,28 @@ export function resolveSignal(
 }
 
 /**
- * Merges headers with precedence: default < per-call. Returns undefined if
- * no headers would be set.
+ * Resolves a `ClientHeadersInit` value: a static record passes through, a
+ * function is invoked and (if async) awaited — re-evaluated on every call so
+ * values like a rotating bearer token never go stale.
  */
-export function resolveHeaders(
+async function resolveHeadersValue(
+  h: ClientHeadersInit | undefined,
+): Promise<Record<string, string> | undefined> {
+  if (h == null) return undefined
+  return typeof h === 'function' ? await h() : h
+}
+
+/**
+ * Merges headers with precedence: default < per-call. Function-valued headers
+ * are evaluated (and awaited) per call. Returns undefined if no headers would
+ * be set.
+ */
+export async function resolveHeaders(
   defaults: ProcedureCallDefaults | undefined,
   options: ProcedureCallOptions | undefined,
-): Record<string, string> | undefined {
-  const defaultHeaders = defaults?.headers
-  const callHeaders = options?.headers
+): Promise<Record<string, string> | undefined> {
+  const defaultHeaders = await resolveHeadersValue(defaults?.headers)
+  const callHeaders = await resolveHeadersValue(options?.headers)
 
   if (!defaultHeaders && !callHeaders) return undefined
 
@@ -137,13 +151,13 @@ export interface ApplyRequestOptionsResult {
  * the error classifier in Task 6) can distinguish timeout from user abort without
  * losing provenance after `AbortSignal.any` collapses the originals.
  */
-export function applyRequestOptions(
+export async function applyRequestOptions(
   request: AdapterRequest,
   defaults: ProcedureCallDefaults | undefined,
   options: ProcedureCallOptions | undefined,
-): ApplyRequestOptionsResult {
+): Promise<ApplyRequestOptionsResult> {
   const signalSources = resolveSignalSources(defaults, options)
-  const resolvedHeaders = resolveHeaders(defaults, options)
+  const resolvedHeaders = await resolveHeaders(defaults, options)
   const meta = resolveMeta(defaults, options)
 
   const headers =

package/src/client/stream.ts

@@ -186,7 +186,7 @@ export async function executeStream<TYield, TReturn = void>(
   let request = buildAdapterRequest(descriptor, resolvedBasePath)
 
   // 2. Apply request-level options (headers, signal, timeout, meta)
-  const applied = applyRequestOptions(request, defaults, options)
+  const applied = await applyRequestOptions(request, defaults, options)
   request = applied.request
   const signalSources = applied.signalSources
 

package/src/client/types.ts

@@ -193,16 +193,32 @@ export interface TypedStream<TYield, TReturn = void> extends AsyncIterable<TYiel
  *   signal are provided, they're combined — whichever aborts first wins.
  * - `timeout`: Timeout in milliseconds. Combined with `signal` the same way.
  *   A per-call `timeout: 0` disables an inherited default timeout.
- * - `headers`: Extra headers merged into the request. Per-call keys win over
- *   default keys. Still subject to further mutation by `onBeforeRequest` hooks.
+ * - `headers`: Extra headers merged into the request, as a static record OR a
+ *   (possibly async) function evaluated per request. Per-call keys win over
+ *   default keys. Use the function form for values that change between calls
+ *   (e.g. a rotating bearer token) so they don't go stale. Still subject to
+ *   further mutation by `onBeforeRequest` hooks.
  * - `basePath`: Override the base path for this call. Per-call > default > config.
  * - `meta`: Per-request metadata typed via the {@link RequestMeta} interface.
  *   Merged shallowly (per-call keys win over default keys).
  */
+/**
+ * Request headers as a static record OR a (possibly async) function evaluated
+ * per request. Use the function form for values that change between calls — e.g.
+ * a rotating bearer token: `headers: () => ({ Authorization: `Bearer ${session.token}` })`.
+ * A static record captured at construction goes stale; a function is re-evaluated each call.
+ *
+ * Named `ClientHeadersInit` (not `HeadersInit`) to avoid shadowing the DOM lib's
+ * global `HeadersInit`, which has a different shape.
+ */
+export type ClientHeadersInit =
+  | Record<string, string>
+  | (() => Record<string, string> | Promise<Record<string, string>>)
+
 export interface ProcedureCallDefaults {
   signal?: AbortSignal
   timeout?: number
-  headers?: Record<string, string>
+  headers?: ClientHeadersInit
   basePath?: string
   meta?: RequestMeta
 }
@@ -302,6 +318,21 @@ export interface CreateClientConfig<TScopes> {
    * matches, falls back to `ClientHttpError` (transport error shape).
    */
   errorRegistry?: ErrorRegistry
+  /**
+   * Returns the current bearer token, re-evaluated per request (so a rotating
+   * token never goes stale). Wired internally to the `Authorization: Bearer
+   * <token>` header — a `null`/`undefined` token omits the header entirely.
+   *
+   * This is sugar over a function-valued `defaults.headers`; it composes with
+   * `defaults.headers` (both are applied, auth last) and is still subject to
+   * per-call `headers` and `onBeforeRequest`, which run after and can override.
+   *
+   * @example
+   * ```ts
+   * createClient({ adapter, basePath, auth: () => session.token, scopes })
+   * ```
+   */
+  auth?: () => string | null | undefined | Promise<string | null | undefined>
 }
 
 // ── Result Types ─────────────────────────────────────────

package/src/codegen/__fixtures__/make-envelope.ts

@@ -0,0 +1,89 @@
+import type {
+  APIHttpRouteDoc,
+  DocEnvelope,
+  ErrorDoc,
+  HeaderDoc,
+  HttpMethod,
+  RPCHttpRouteDoc,
+} from '../../implementations/types.js'
+
+/**
+ * Typed builders for codegen test envelopes.
+ *
+ * These return real {@link DocEnvelope}/route-doc shapes with no `as unknown as`
+ * casts — the JSON Schema slots are `Record<string, unknown>`, so any plain
+ * schema object drops in directly. Callers pass small typed param objects and
+ * the builders fill in sensible defaults (method, empty `errors`, etc.).
+ */
+
+export interface MakeApiRouteOptions {
+  name: string
+  scope?: string
+  method?: HttpMethod
+  /** Full resolved path. Defaults to `/${name}` when omitted. */
+  fullPath?: string
+  /** Route path (without pathPrefix). Defaults to `fullPath`. */
+  path?: string
+  successStatus?: number
+  errors?: string[]
+  jsonSchema?: APIHttpRouteDoc['jsonSchema']
+}
+
+/** Build a typed `kind: 'api'` route doc. */
+export function makeApiRoute(opts: MakeApiRouteOptions): APIHttpRouteDoc {
+  const fullPath = opts.fullPath ?? `/${opts.name}`
+  return {
+    kind: 'api',
+    name: opts.name,
+    scope: opts.scope,
+    method: opts.method ?? 'get',
+    path: opts.path ?? fullPath,
+    fullPath,
+    successStatus: opts.successStatus,
+    errors: opts.errors ?? [],
+    jsonSchema: opts.jsonSchema ?? {},
+  }
+}
+
+export interface MakeRpcRouteOptions {
+  name: string
+  scope?: string | string[]
+  version?: number
+  /** Route path. Defaults to `/${name}` when omitted. */
+  path?: string
+  errors?: string[]
+  jsonSchema?: RPCHttpRouteDoc['jsonSchema']
+}
+
+/** Build a typed `kind: 'rpc'` route doc. */
+export function makeRpcRoute(opts: MakeRpcRouteOptions): RPCHttpRouteDoc {
+  return {
+    kind: 'rpc',
+    name: opts.name,
+    scope: opts.scope ?? 'default',
+    version: opts.version ?? 1,
+    path: opts.path ?? `/${opts.name}`,
+    method: 'post',
+    errors: opts.errors ?? [],
+    jsonSchema: opts.jsonSchema ?? {},
+  }
+}
+
+export interface MakeEnvelopeOptions {
+  basePath?: string
+  headers?: HeaderDoc[]
+  errors?: ErrorDoc[]
+}
+
+/** Wrap route docs in a typed {@link DocEnvelope} with sensible defaults. */
+export function makeEnvelope(
+  routes: DocEnvelope['routes'],
+  opts: MakeEnvelopeOptions = {},
+): DocEnvelope {
+  return {
+    basePath: opts.basePath ?? '/api',
+    headers: opts.headers ?? [],
+    errors: opts.errors ?? [],
+    routes,
+  }
+}

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

@@ -1,6 +1,7 @@
 import { describe, it, expect } from 'vitest'
 import { vi } from 'vitest'
-import { parseArgs, loadConfigFile, extractConfigPath, printPostRunHints, warnIfKotlinNoOpFlags, type CodegenConfig } from './cli.js'
+import { parseArgs, loadConfigFile, extractConfigPath, printPostRunHints, warnIfKotlinNoOpFlags, shouldShowHelp, type CodegenConfig } from './cli.js'
+import { formatHelp } from './flag-specs.js'
 
 describe('parseArgs', () => {
   it('parses --url and --out', () => {
@@ -432,6 +433,23 @@ describe('cli — unsupported-unions flag', () => {
   })
 })
 
+describe('--help handling', () => {
+  it('shouldShowHelp true for --help, -h, and bare (no args)', () => {
+    expect(shouldShowHelp(['--help'])).toBe(true)
+    expect(shouldShowHelp(['-h'])).toBe(true)
+    expect(shouldShowHelp([])).toBe(true)
+  })
+  it('shouldShowHelp false when real flags are present', () => {
+    expect(shouldShowHelp(['--url', 'http://x', '--out', 'gen'])).toBe(false)
+  })
+  it('help text covers the full flag surface', () => {
+    const help = formatHelp()
+    expect(help).toContain('--watch')
+    expect(help).toContain('--enum-style')
+    expect(help).toContain('--target')
+  })
+})
+
 describe('cli — printPostRunHints', () => {
   it('prints a setup-guide pointer for the kotlin target', () => {
     const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
@@ -518,3 +536,49 @@ describe('cli — warnIfKotlinNoOpFlags', () => {
     }
   })
 })
+
+describe('--share-models', () => {
+  it('defaults shareModels to true', () => {
+    expect(parseArgs(['--out', 'g', '--url', 'u']).shareModels).toBe(true)
+  })
+  it('--no-share-models sets it false', () => {
+    expect(parseArgs(['--out', 'g', '--url', 'u', '--no-share-models']).shareModels).toBe(false)
+  })
+  it('--share-models sets it true (overriding a config false)', () => {
+    expect(parseArgs(['--out', 'g', '--url', 'u', '--share-models'], { shareModels: false } as CodegenConfig).shareModels).toBe(true)
+  })
+  it('reads shareModels:false from config when no flag given', () => {
+    expect(parseArgs(['--out', 'g', '--url', 'u'], { shareModels: false } as CodegenConfig).shareModels).toBe(false)
+  })
+  it('reads sharedTypesImport from config', () => {
+    const cfg = { sharedTypesImport: { 'urn:msg': { module: '@shared/schemas', name: 'Message' } } }
+    expect(parseArgs(['--out', 'g', '--url', 'u'], cfg as CodegenConfig).sharedTypesImport).toEqual(cfg.sharedTypesImport)
+  })
+})
+
+describe('--shared-models-module and --strict-shared-models', () => {
+  it('parses --shared-models-module into sharedModelsModule', () => {
+    const parsed = parseArgs(['--out', 'gen', '--file', 'e.json', '--shared-models-module', '@app/schemas'])
+    expect(parsed.sharedModelsModule).toBe('@app/schemas')
+  })
+
+  it('parses --strict-shared-models as a boolean (default false)', () => {
+    expect(parseArgs(['--out', 'gen', '--file', 'e.json']).strictSharedModels).toBe(false)
+    expect(
+      parseArgs(['--out', 'gen', '--file', 'e.json', '--strict-shared-models']).strictSharedModels,
+    ).toBe(true)
+  })
+
+  it('CLI --shared-models-module overrides a config value', () => {
+    const parsed = parseArgs(
+      ['--out', 'gen', '--file', 'e.json', '--shared-models-module', '@cli/pkg'],
+      { sharedModelsModule: '@config/pkg' },
+    )
+    expect(parsed.sharedModelsModule).toBe('@cli/pkg')
+  })
+
+  it('strictSharedModels is seeded from config when the flag is absent', () => {
+    const parsed = parseArgs(['--out', 'gen', '--file', 'e.json'], { strictSharedModels: true })
+    expect(parsed.strictSharedModels).toBe(true)
+  })
+})

package/src/codegen/bin/cli.ts

@@ -4,6 +4,8 @@ import { resolve } from 'node:path'
 import { createHash } from 'node:crypto'
 import { generateClient, type GenerateClientOptions } from '../index.js'
 import type { AjscOptions } from '../emit-types.js'
+import type { SharedTypesImportMap } from '../collect-models.js'
+import { KNOWN_FLAGS, formatHelp } from './flag-specs.js'
 
 // ---------------------------------------------------------------------------
 // Types
@@ -26,6 +28,10 @@ export interface CodegenConfig {
   kotlin?: { package: string; serializer?: 'kotlinx' | 'none' }
   swift?: { serializer?: 'codable' | 'none'; accessLevel?: 'public' | 'internal' }
   unsupportedUnions?: 'throw' | 'fallback'
+  shareModels?: boolean
+  sharedTypesImport?: SharedTypesImportMap
+  sharedModelsModule?: string
+  strictSharedModels?: boolean
 }
 
 export interface ParsedArgs {
@@ -45,6 +51,10 @@ export interface ParsedArgs {
   kotlin?: { package: string; serializer?: 'kotlinx' | 'none' }
   swift?: { serializer?: 'codable' | 'none'; accessLevel?: 'public' | 'internal' }
   unsupportedUnions?: 'throw' | 'fallback'
+  shareModels: boolean
+  sharedTypesImport?: SharedTypesImportMap
+  sharedModelsModule?: string
+  strictSharedModels: boolean
 }
 
 // ---------------------------------------------------------------------------
@@ -73,30 +83,9 @@ export async function loadConfigFile(configPath?: string): Promise<CodegenConfig
 }
 
 // ---------------------------------------------------------------------------
-// Flag catalog + did-you-mean
+// did-you-mean (the flag catalog now lives in ./flag-specs.ts)
 // ---------------------------------------------------------------------------
 
-/**
- * Every flag `parseArgs` recognises. Kept in one place so the unknown-flag
- * error can suggest the closest match for typos like `--targt` → `--target`.
- *
- * The list is also load-bearing: any new branch added to the parse loop
- * MUST also be added here, or the loop will throw on the very flag it just
- * accepted. (Kept literal — small enough that DRY-ing it isn't worth it.)
- */
-const KNOWN_FLAGS = [
-  '--url', '--file', '--out', '--watch', '--interval',
-  '--enum-style', '--depluralize', '--array-item-naming', '--uncountable-words',
-  '--jsdoc', '--no-jsdoc',
-  '--client-import-path', '--dry-run',
-  '--namespace-types', '--no-namespace-types',
-  '--self-contained', '--no-self-contained',
-  '--service-name', '--clean-out-dir', '--no-clean-out-dir',
-  '--target', '--kotlin-package', '--kotlin-serializer',
-  '--swift-serializer', '--swift-access-level',
-  '--unsupported-unions', '--config',
-] as const
-
 /**
  * Levenshtein distance between two strings — small ad-hoc implementation
  * tuned for short flag names. We don't pull a dep just for typo suggestions.
@@ -183,6 +172,10 @@ export function parseArgs(argv: string[], config?: CodegenConfig): ParsedArgs {
   let swiftSerializer: 'codable' | 'none' | undefined = config?.swift?.serializer
   let swiftAccessLevel: 'public' | 'internal' | undefined = config?.swift?.accessLevel
   let unsupportedUnions: 'throw' | 'fallback' | undefined = config?.unsupportedUnions
+  let shareModels = config?.shareModels ?? true
+  const sharedTypesImport = config?.sharedTypesImport
+  let sharedModelsModule: string | undefined = config?.sharedModelsModule
+  let strictSharedModels = config?.strictSharedModels ?? false
   let configPath: string | undefined
 
   for (let i = 0; i < argv.length; i++) {
@@ -269,6 +262,14 @@ export function parseArgs(argv: string[], config?: CodegenConfig): ParsedArgs {
       } else {
         throw new Error(`Invalid --unsupported-unions value: ${val ?? '(missing)'} (expected 'throw' or 'fallback')`)
       }
+    } else if (arg === '--share-models') {
+      shareModels = true
+    } else if (arg === '--no-share-models') {
+      shareModels = false
+    } else if (arg === '--shared-models-module') {
+      sharedModelsModule = argv[++i]
+    } else if (arg === '--strict-shared-models') {
+      strictSharedModels = true
     } else if (arg === '--config') {
       configPath = argv[++i]
     } else if (arg !== undefined && arg.startsWith('--')) {
@@ -343,6 +344,10 @@ export function parseArgs(argv: string[], config?: CodegenConfig): ParsedArgs {
         }
       : {}),
     ...(unsupportedUnions !== undefined ? { unsupportedUnions } : {}),
+    shareModels,
+    ...(sharedTypesImport !== undefined ? { sharedTypesImport } : {}),
+    ...(sharedModelsModule !== undefined ? { sharedModelsModule } : {}),
+    strictSharedModels,
   }
 }
 
@@ -430,6 +435,11 @@ async function runWithWatch(parsed: ParsedArgs): Promise<void> {
         ...(parsed.unsupportedUnions !== undefined ? { unsupportedUnions: parsed.unsupportedUnions } : {}),
         ...(parsed.swift?.serializer !== undefined ? { swiftSerializer: parsed.swift.serializer } : {}),
         ...(parsed.swift?.accessLevel !== undefined ? { swiftAccessLevel: parsed.swift.accessLevel } : {}),
+        shareModels: parsed.shareModels,
+        ...(parsed.sharedTypesImport !== undefined ? { sharedTypesImport: parsed.sharedTypesImport } : {}),
+        ...(parsed.sharedModelsModule !== undefined ? { sharedModelsModule: parsed.sharedModelsModule } : {}),
+        strictSharedModels: parsed.strictSharedModels,
+        logger: (message: string) => { console.log(message) },
         ...kotlinWiring,
         ...swiftWiring,
       })
@@ -488,8 +498,22 @@ export function warnIfKotlinNoOpFlags(parsed: {
   }
 }
 
+/**
+ * True when the CLI should print usage and exit 0: an explicit --help/-h, or a
+ * bare invocation with no args. --help is handled here (not in parseArgs) so it
+ * never reaches the unknown-flag branch and never appears in did-you-mean.
+ */
+export function shouldShowHelp(argv: string[]): boolean {
+  if (argv.length === 0) return true
+  return argv.includes('--help') || argv.includes('-h')
+}
+
 async function main(): Promise<void> {
   const argv = process.argv.slice(2)
+  if (shouldShowHelp(argv)) {
+    console.log(formatHelp())
+    process.exit(0)
+  }
   const configPath = extractConfigPath(argv)
   const config = await loadConfigFile(configPath)
   if (config != null) {
@@ -544,6 +568,11 @@ async function main(): Promise<void> {
       ...(parsed.unsupportedUnions !== undefined ? { unsupportedUnions: parsed.unsupportedUnions } : {}),
       ...(parsed.swift?.serializer !== undefined ? { swiftSerializer: parsed.swift.serializer } : {}),
       ...(parsed.swift?.accessLevel !== undefined ? { swiftAccessLevel: parsed.swift.accessLevel } : {}),
+      shareModels: parsed.shareModels,
+      ...(parsed.sharedTypesImport !== undefined ? { sharedTypesImport: parsed.sharedTypesImport } : {}),
+      ...(parsed.sharedModelsModule !== undefined ? { sharedModelsModule: parsed.sharedModelsModule } : {}),
+      strictSharedModels: parsed.strictSharedModels,
+      logger: (message: string) => { console.log(message) },
       ...kotlinWiring,
       ...swiftWiring,
     })

package/src/codegen/bin/flag-specs.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect } from 'vitest'
+import { FLAG_SPECS, KNOWN_FLAGS, formatHelp } from './flag-specs.js'
+
+describe('flag-specs', () => {
+  it('derives KNOWN_FLAGS from the spec table', () => {
+    expect(KNOWN_FLAGS).toContain('--url')
+    expect(KNOWN_FLAGS).toContain('--service-name')
+    expect(KNOWN_FLAGS).toContain('--target')
+    for (const spec of FLAG_SPECS) expect(KNOWN_FLAGS).toContain(spec.name)
+  })
+
+  it('formatHelp lists every flag with its description, grouped', () => {
+    const help = formatHelp()
+    expect(help).toMatch(/Usage: ts-procedures-codegen/)
+    for (const spec of FLAG_SPECS) {
+      expect(help).toContain(spec.name)
+      expect(help).toContain(spec.description)
+    }
+    expect(help).toMatch(/Source/)
+    expect(help).toMatch(/Targets/)
+  })
+
+  it('does not list --help/-h as a real codegen flag in KNOWN_FLAGS', () => {
+    expect(KNOWN_FLAGS).not.toContain('--help')
+    expect(KNOWN_FLAGS).not.toContain('-h')
+  })
+
+  it('catalogs the shared-models convention + strict flags', () => {
+    expect(KNOWN_FLAGS).toContain('--shared-models-module')
+    expect(KNOWN_FLAGS).toContain('--strict-shared-models')
+  })
+
+  it('documents the new flags in --help output', () => {
+    const help = formatHelp()
+    expect(help).toContain('--shared-models-module')
+    expect(help).toContain('--strict-shared-models')
+  })
+})

package/src/codegen/bin/flag-specs.ts

@@ -0,0 +1,71 @@
+export interface FlagSpec {
+  name: string
+  arg?: string
+  description: string
+  group: 'Source' | 'Output' | 'Codegen' | 'Targets' | 'Misc'
+  default?: string
+}
+
+export const FLAG_SPECS: readonly FlagSpec[] = [
+  // Source
+  { name: '--url', arg: '<url>', description: 'Fetch the doc envelope from a running server', group: 'Source' },
+  { name: '--file', arg: '<path>', description: 'Read the doc envelope from a JSON file (see writeDocEnvelope)', group: 'Source' },
+  { name: '--config', arg: '<path>', description: 'Load options from a JSON config file', group: 'Source' },
+  // Output
+  { name: '--out', arg: '<dir>', description: 'Output directory for generated files', group: 'Output' },
+  { name: '--dry-run', description: 'Print what would be written without touching disk', group: 'Output' },
+  { name: '--clean-out-dir', description: 'Prune orphaned generator-owned files before writing', group: 'Output', default: 'on' },
+  { name: '--no-clean-out-dir', description: 'Disable orphan pruning', group: 'Output' },
+  { name: '--watch', description: 'Regenerate on envelope change', group: 'Output' },
+  { name: '--interval', arg: '<ms>', description: 'Poll interval for --watch (default 3000)', group: 'Output' },
+  // Codegen
+  { name: '--service-name', arg: '<name>', description: 'Service identifier driving generated names', group: 'Codegen', default: 'Api' },
+  { name: '--namespace-types', description: 'Wrap types in nested namespaces', group: 'Codegen', default: 'on' },
+  { name: '--no-namespace-types', description: 'Flat type names', group: 'Codegen' },
+  { name: '--self-contained', description: 'Bundle the client runtime into the output dir', group: 'Codegen', default: 'on' },
+  { name: '--no-self-contained', description: 'Import the client runtime from ts-procedures/client', group: 'Codegen' },
+  { name: '--client-import-path', arg: '<path>', description: 'Override the client runtime import path', group: 'Codegen' },
+  { name: '--share-models', description: 'Hoist $id-bearing schemas into a shared _models.ts', group: 'Codegen', default: 'on' },
+  { name: '--no-share-models', description: 'Inline every type per route (legacy behaviour)', group: 'Codegen' },
+  { name: '--shared-models-module', arg: '<module>', description: 'Re-export every $id model from one module (convention; sharedTypesImport overrides)', group: 'Codegen' },
+  { name: '--strict-shared-models', description: 'Fail if any $id model would be generated as a local twin', group: 'Codegen' },
+  { name: '--jsdoc', description: 'Emit JSDoc on generated types', group: 'Codegen', default: 'on' },
+  { name: '--no-jsdoc', description: 'Suppress JSDoc', group: 'Codegen' },
+  { name: '--enum-style', arg: '<union|enum>', description: 'How to emit enums (namespace mode)', group: 'Codegen' },
+  { name: '--depluralize', description: 'Depluralize extracted array-item type names', group: 'Codegen' },
+  { name: '--array-item-naming', arg: '<name|false>', description: 'Naming for extracted array-item types', group: 'Codegen' },
+  { name: '--uncountable-words', arg: '<csv>', description: 'Words exempt from depluralization', group: 'Codegen' },
+  // Targets
+  { name: '--target', arg: '<ts|kotlin|swift>', description: 'Output language', group: 'Targets', default: 'ts' },
+  { name: '--kotlin-package', arg: '<pkg>', description: 'Package for Kotlin output (required for --target kotlin)', group: 'Targets' },
+  { name: '--kotlin-serializer', arg: '<kotlinx|none>', description: 'Kotlin serialization annotations', group: 'Targets', default: 'kotlinx' },
+  { name: '--swift-serializer', arg: '<codable|none>', description: 'Swift Codable conformance', group: 'Targets', default: 'codable' },
+  { name: '--swift-access-level', arg: '<public|internal>', description: 'Swift access level', group: 'Targets', default: 'public' },
+  { name: '--unsupported-unions', arg: '<throw|fallback>', description: 'Behaviour for untagged oneOf schemas', group: 'Targets', default: 'throw' },
+]
+
+export const KNOWN_FLAGS: readonly string[] = FLAG_SPECS.map((s) => s.name)
+
+const GROUP_ORDER: FlagSpec['group'][] = ['Source', 'Output', 'Codegen', 'Targets', 'Misc']
+
+export function formatHelp(): string {
+  const lines: string[] = []
+  lines.push('Usage: ts-procedures-codegen --out <dir> (--url <url> | --file <path>) [options]')
+  lines.push('')
+  lines.push('Generate a typed client from a ts-procedures doc envelope.')
+  lines.push('')
+  const col = Math.max(...FLAG_SPECS.map((s) => (s.name + (s.arg ? ' ' + s.arg : '')).length)) + 2
+  for (const group of GROUP_ORDER) {
+    const specs = FLAG_SPECS.filter((s) => s.group === group)
+    if (specs.length === 0) continue
+    lines.push(`${group}:`)
+    for (const s of specs) {
+      const left = s.name + (s.arg ? ' ' + s.arg : '')
+      const def = s.default ? ` (default: ${s.default})` : ''
+      lines.push(`  ${left.padEnd(col)}${s.description}${def}`)
+    }
+    lines.push('')
+  }
+  lines.push('  -h, --help      Show this help and exit')
+  return lines.join('\n')
+}

package/src/codegen/collect-models.test.ts

@@ -0,0 +1,68 @@
+import { it, expect } from 'vitest'
+import { collectModels, resolveModelImports } from './collect-models.js'
+
+const message = { type: 'object', $id: 'urn:msg', title: 'Message', properties: { id: { type: 'string' } } }
+
+it('collects each $id subschema once, named from title', () => {
+  const routes = [
+    { jsonSchema: { response: message } },
+    { jsonSchema: { body: { type: 'object', properties: { msg: message } } } },
+  ] as any
+  const models = collectModels(routes)
+  expect(models.map((m) => m.name)).toEqual(['Message'])
+  expect(models[0]?.id).toBe('urn:msg')
+})
+
+it('throws on $id collision with divergent body', () => {
+  const a = { type: 'object', $id: 'urn:x', title: 'X', properties: { a: { type: 'string' } } }
+  const b = { type: 'object', $id: 'urn:x', title: 'X', properties: { b: { type: 'number' } } }
+  expect(() => collectModels([{ jsonSchema: { response: a } }, { jsonSchema: { body: b } }] as any)).toThrow(/urn:x/)
+})
+
+it('disambiguates distinct $ids that derive the same name', () => {
+  const m1 = { type: 'object', $id: 'urn:a/message', title: 'Message', properties: { a: { type: 'string' } } }
+  const m2 = { type: 'object', $id: 'urn:b/message', title: 'Message', properties: { b: { type: 'string' } } }
+  const models = collectModels([{ jsonSchema: { response: m1 } }, { jsonSchema: { body: m2 } }] as any)
+  expect(models.map((m) => m.name).sort()).toEqual(['Message', 'Message2'])
+})
+
+it('ignores schemas without $id', () => {
+  const routes = [{ jsonSchema: { response: { type: 'object', title: 'Loose', properties: {} } } }] as any
+  expect(collectModels(routes)).toEqual([])
+})
+
+it('does NOT throw for ordinary schemas without the reserved prefix', () => {
+  const routes = [
+    { jsonSchema: { response: { type: 'object', properties: { kind: { const: 'message' }, status: { enum: ['ok', 'error'] } } } } },
+  ] as any
+  expect(() => collectModels(routes)).not.toThrow()
+})
+
+it('resolveModelImports tags mapped models and leaves others generated', () => {
+  const models = [{ id: 'urn:msg', name: 'Message', schema: {} as any }]
+  const mapped = resolveModelImports(models, {
+    sharedTypesImport: { 'urn:msg': { module: '@shared/schemas', name: 'Message' } },
+  })
+  expect(mapped[0]?.import).toEqual({ module: '@shared/schemas', name: 'Message' })
+  expect(resolveModelImports(models)[0]?.import).toBeUndefined()
+})
+
+it('resolveModelImports falls back to sharedModelsModule when no map entry matches', () => {
+  const models = [{ id: 'urn:msg', name: 'Message', schema: {} as any }]
+  const resolved = resolveModelImports(models, { sharedModelsModule: '@app/schemas' })
+  expect(resolved[0]?.import).toEqual({ module: '@app/schemas', name: 'Message' })
+})
+
+it('resolveModelImports: explicit map entry wins over the convention', () => {
+  const models = [{ id: 'urn:msg', name: 'Message', schema: {} as any }]
+  const resolved = resolveModelImports(models, {
+    sharedTypesImport: { 'urn:msg': { module: '@override/pkg', name: 'Msg' } },
+    sharedModelsModule: '@app/schemas',
+  })
+  expect(resolved[0]?.import).toEqual({ module: '@override/pkg', name: 'Msg' })
+})
+
+it('resolveModelImports: empty-string convention is treated as unset (generated locally)', () => {
+  const models = [{ id: 'urn:msg', name: 'Message', schema: {} as any }]
+  expect(resolveModelImports(models, { sharedModelsModule: '' })[0]?.import).toBeUndefined()
+})