ts-procedures 7.0.0 → 7.1.0

package/src/codegen/bin/cli.ts

@@ -72,6 +72,87 @@ export async function loadConfigFile(configPath?: string): Promise<CodegenConfig
   }
 }
 
+// ---------------------------------------------------------------------------
+// Flag catalog + did-you-mean
+// ---------------------------------------------------------------------------
+
+/**
+ * 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.
+ */
+function editDistance(a: string, b: string): number {
+  if (a === b) return 0
+  if (a.length === 0) return b.length
+  if (b.length === 0) return a.length
+  // One row at a time — O(min(a, b)) memory.
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i)
+  for (let i = 1; i <= a.length; i++) {
+    const curr = [i]
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1
+      curr.push(Math.min(curr[j - 1]! + 1, prev[j]! + 1, prev[j - 1]! + cost))
+    }
+    prev = curr
+  }
+  return prev[b.length]!
+}
+
+/**
+ * Returns the known flag closest to `unknown`, or `undefined` when nothing
+ * is a confident enough match. Two heuristics:
+ *
+ *   1. Prefix match — if the unknown flag is a strict prefix of a known one
+ *      (e.g. `--service` → `--service-name`), suggest it. This catches the
+ *      common "wrong segment count" typo regardless of how long the missing
+ *      tail is.
+ *   2. Edit distance ≤ 3 — catches transpositions and small misspellings
+ *      (`--targt` → `--target`). Above 3 the suggestion stops being helpful
+ *      and starts being misleading.
+ */
+function closestKnownFlag(unknown: string): string | undefined {
+  // 1) Prefix match — pick the shortest known flag whose prefix is `unknown`.
+  let prefixMatch: string | undefined
+  for (const flag of KNOWN_FLAGS) {
+    if (flag.startsWith(unknown) && flag !== unknown) {
+      if (prefixMatch == null || flag.length < prefixMatch.length) {
+        prefixMatch = flag
+      }
+    }
+  }
+  if (prefixMatch != null) return prefixMatch
+
+  // 2) Edit-distance fallback.
+  let best: { flag: string; distance: number } | undefined
+  for (const flag of KNOWN_FLAGS) {
+    const distance = editDistance(unknown, flag)
+    if (best == null || distance < best.distance) {
+      best = { flag, distance }
+    }
+  }
+  return best != null && best.distance <= 3 ? best.flag : undefined
+}
+
 // ---------------------------------------------------------------------------
 // parseArgs
 // ---------------------------------------------------------------------------
@@ -190,6 +271,16 @@ export function parseArgs(argv: string[], config?: CodegenConfig): ParsedArgs {
       }
     } else if (arg === '--config') {
       configPath = argv[++i]
+    } else if (arg !== undefined && arg.startsWith('--')) {
+      // Reject unknown flags loudly. Silently ignoring them led to a downstream
+      // bug where a misspelled `--targt` produced an empty envelope with no
+      // user-visible cause. Suggest the closest known flag when the typo is
+      // small enough that the suggestion will be more help than hindrance.
+      const suggestion = closestKnownFlag(arg)
+      const tail = suggestion != null
+        ? ` Did you mean \`${suggestion}\`?`
+        : ' See the README for the supported flag set.'
+      throw new Error(`[ts-procedures-codegen] Unknown CLI flag: ${arg}.${tail}`)
     }
   }
 

package/src/codegen/e2e.test.ts

@@ -1,9 +1,10 @@
 import { describe, it, expect, afterEach } from 'vitest'
 import { generateClient } from './index.js'
-import { mkdirSync, rmSync, readFileSync, existsSync } from 'node:fs'
+import { mkdirSync, rmSync, readFileSync, writeFileSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 import type { DocEnvelope, RPCHttpRouteDoc, APIHttpRouteDoc, StreamHttpRouteDoc, ErrorDoc } from '../implementations/types.js'
+import { runTsc } from './test-helpers/run-tsc.js'
 
 // ---------------------------------------------------------------------------
 // Fixtures
@@ -464,28 +465,20 @@ describe('E2E: generateClient full pipeline', () => {
       tmpDir = makeTmpDir()
       await generateClient({ envelope, outDir: tmpDir, selfContained: true })
 
-      // Write a minimal tsconfig for the generated files
-      const tsconfig = {
-        compilerOptions: {
-          strict: true,
-          target: 'ES2022',
-          module: 'ES2022',
-          moduleResolution: 'bundler',
-          noEmit: true,
-          skipLibCheck: true,
+      runTsc({
+        tmpDir,
+        tsconfigInline: {
+          compilerOptions: {
+            strict: true,
+            target: 'ES2022',
+            module: 'ES2022',
+            moduleResolution: 'bundler',
+            noEmit: true,
+            skipLibCheck: true,
+          },
+          include: ['_types.ts', '_client.ts'],
         },
-        include: ['_types.ts', '_client.ts'],
-      }
-      const { writeFileSync } = await import('node:fs')
-      writeFileSync(join(tmpDir, 'tsconfig.json'), JSON.stringify(tsconfig))
-
-      const { execSync } = await import('node:child_process')
-      // Use the project's tsc binary directly (temp dir has no node_modules)
-      const tscPath = join(process.cwd(), 'node_modules', '.bin', 'tsc')
-      // tsc --noEmit --project tsconfig.json should succeed with exit code 0
-      expect(() => {
-        execSync(`${tscPath} --noEmit --project ${join(tmpDir, 'tsconfig.json')}`, { stdio: 'pipe' })
-      }).not.toThrow()
+      })
     })
 
     it('_types.ts exports RequestMeta (empty interface ready for augmentation)', async () => {
@@ -562,27 +555,22 @@ async function run(): Promise<void> {
 }
 void run
 `
-      const { writeFileSync } = await import('node:fs')
       writeFileSync(join(tmpDir, 'consumer.ts'), consumer)
 
-      const tsconfig = {
-        compilerOptions: {
-          strict: true,
-          target: 'ES2022',
-          module: 'ES2022',
-          moduleResolution: 'bundler',
-          noEmit: true,
-          skipLibCheck: true,
+      runTsc({
+        tmpDir,
+        tsconfigInline: {
+          compilerOptions: {
+            strict: true,
+            target: 'ES2022',
+            module: 'ES2022',
+            moduleResolution: 'bundler',
+            noEmit: true,
+            skipLibCheck: true,
+          },
+          include: ['_types.ts', '_client.ts', 'index.ts', 'users.ts', 'events.ts', '_errors.ts', 'consumer.ts'],
         },
-        include: ['_types.ts', '_client.ts', 'index.ts', 'users.ts', 'events.ts', '_errors.ts', 'consumer.ts'],
-      }
-      writeFileSync(join(tmpDir, 'tsconfig.json'), JSON.stringify(tsconfig))
-
-      const { execSync } = await import('node:child_process')
-      const tscPath = join(process.cwd(), 'node_modules', '.bin', 'tsc')
-      expect(() => {
-        execSync(`${tscPath} --noEmit --project ${join(tmpDir, 'tsconfig.json')}`, { stdio: 'pipe' })
-      }).not.toThrow()
+      })
     })
 
     it('generated .safe callable type-checks against bundled Result/ResultNoTyped types', async () => {
@@ -668,27 +656,22 @@ const _p3 = client.users.ListUsers.safe({})
 const _p3check: Promise<ResultNoTyped<unknown>> = _p3 as Promise<ResultNoTyped<unknown>>
 void _p3check
 `
-      const { writeFileSync } = await import('node:fs')
       writeFileSync(join(tmpDir, 'consumer.ts'), consumer)
 
-      const tsconfig = {
-        compilerOptions: {
-          strict: true,
-          target: 'ES2022',
-          module: 'ES2022',
-          moduleResolution: 'bundler',
-          noEmit: true,
-          skipLibCheck: true,
+      runTsc({
+        tmpDir,
+        tsconfigInline: {
+          compilerOptions: {
+            strict: true,
+            target: 'ES2022',
+            module: 'ES2022',
+            moduleResolution: 'bundler',
+            noEmit: true,
+            skipLibCheck: true,
+          },
+          include: ['_types.ts', '_client.ts', 'index.ts', 'users.ts', '_errors.ts', 'consumer.ts'],
         },
-        include: ['_types.ts', '_client.ts', 'index.ts', 'users.ts', '_errors.ts', 'consumer.ts'],
-      }
-      writeFileSync(join(tmpDir, 'tsconfig.json'), JSON.stringify(tsconfig))
-
-      const { execSync } = await import('node:child_process')
-      const tscPath = join(process.cwd(), 'node_modules', '.bin', 'tsc')
-      expect(() => {
-        execSync(`${tscPath} --noEmit --project ${join(tmpDir, 'tsconfig.json')}`, { stdio: 'pipe' })
-      }).not.toThrow()
+      })
     })
 
     it('augmented RequestMeta rejects wrong types (compile error)', async () => {
@@ -720,29 +703,25 @@ async function run(): Promise<void> {
 }
 void run
 `
-      const { writeFileSync } = await import('node:fs')
       writeFileSync(join(tmpDir, 'consumer.ts'), consumer)
 
-      const tsconfig = {
-        compilerOptions: {
-          strict: true,
-          target: 'ES2022',
-          module: 'ES2022',
-          moduleResolution: 'bundler',
-          noEmit: true,
-          skipLibCheck: true,
+      // With `@ts-expect-error` in place, tsc should pass; if RequestMeta
+      // weren't enforcing the type, `@ts-expect-error` would itself fail
+      // (because there'd be no error to suppress).
+      runTsc({
+        tmpDir,
+        tsconfigInline: {
+          compilerOptions: {
+            strict: true,
+            target: 'ES2022',
+            module: 'ES2022',
+            moduleResolution: 'bundler',
+            noEmit: true,
+            skipLibCheck: true,
+          },
+          include: ['_types.ts', '_client.ts', 'index.ts', 'users.ts', 'events.ts', '_errors.ts', 'consumer.ts'],
         },
-        include: ['_types.ts', '_client.ts', 'index.ts', 'users.ts', 'events.ts', '_errors.ts', 'consumer.ts'],
-      }
-      writeFileSync(join(tmpDir, 'tsconfig.json'), JSON.stringify(tsconfig))
-
-      const { execSync } = await import('node:child_process')
-      const tscPath = join(process.cwd(), 'node_modules', '.bin', 'tsc')
-      // With @ts-expect-error in place, tsc should pass; if RequestMeta wasn't
-      // enforcing the type, @ts-expect-error would fail because there'd be no error.
-      expect(() => {
-        execSync(`${tscPath} --noEmit --project ${join(tmpDir, 'tsconfig.json')}`, { stdio: 'pipe' })
-      }).not.toThrow()
+      })
     })
   })
 
@@ -833,4 +812,47 @@ void run
       expect(content).toContain('export enum Status')
     })
   })
+
+  // ── verbatimModuleSyntax compatibility ─────────────────────────────────────
+  //
+  // Bug repro (downstream): generated client fails to compile under
+  // tsconfigs/strict (which enables `verbatimModuleSyntax: true`) with errors
+  // like:
+  //   error TS1659: 'export import' is not allowed in a 'declaration' file.
+  //   error TS1287: A type-only import can specify a default import or named
+  //                  bindings, but not both.
+  //
+  // The current emitIndexFile uses `export import X = _x.X` to re-export each
+  // scope namespace from inside `export namespace Cp { ... }`. This namespace
+  // alias syntax is incompatible with `verbatimModuleSyntax`. The test below
+  // generates a client and compiles it under that strict mode — no errors.
+
+  describe('verbatimModuleSyntax compatibility (bug repro)', () => {
+    it('generated self-contained client compiles cleanly under verbatimModuleSyntax: true with namespaceTypes', async () => {
+      tmpDir = makeTmpDir()
+      await generateClient({
+        envelope,
+        outDir: tmpDir,
+        selfContained: true,
+        namespaceTypes: true,
+        serviceName: 'Cp',
+      })
+
+      runTsc({
+        tmpDir,
+        tsconfigInline: {
+          compilerOptions: {
+            strict: true,
+            target: 'ES2022',
+            module: 'ES2022',
+            moduleResolution: 'bundler',
+            verbatimModuleSyntax: true,
+            noEmit: true,
+            skipLibCheck: true,
+          },
+          include: ['_types.ts', '_client.ts', 'index.ts', 'users.ts', 'events.ts', '_errors.ts'],
+        },
+      })
+    })
+  })
 })

package/src/codegen/emit-index.ts

@@ -77,8 +77,18 @@ export function emitIndexFile(groups: ScopeGroup[], options?: EmitIndexOptions):
     ].join('\n')
   }
 
+  // Namespace mode puts `bindScope` inside the `${Pascal}` namespace
+  // (`Users.bindScope`); flat mode keeps it as a standalone export
+  // (`bindUsersScope`). Both compile cleanly — the branch picks the right
+  // call shape for the emitted scope file.
   const scopeBindings = groups
-    .map((g) => `    ${g.camelCase}: ${localAlias(g.camelCase)}.bind${toPascalCase(g.camelCase)}Scope(client),`)
+    .map((g) => {
+      const pascal = toPascalCase(g.camelCase)
+      const bindCall = namespaceTypes
+        ? `${localAlias(g.camelCase)}.${pascal}.bindScope(client)`
+        : `${localAlias(g.camelCase)}.bind${pascal}Scope(client)`
+      return `    ${g.camelCase}: ${bindCall},`
+    })
     .join('\n')
 
   const pieces: string[] = [

package/src/codegen/emit-scope.test.ts

@@ -431,9 +431,14 @@ describe('emitScopeFile', () => {
         expect(output).toContain('client.bindCallable<Users.GetUser.Params, Users.GetUser.Response>')
       })
 
-      it('still emits the bind function', async () => {
+      it('emits bindScope as a member of the scope namespace (so the namespace is value+type)', async () => {
         const output = await emitScopeFile(rpcGroup, { namespaceTypes: true })
-        expect(output).toContain('export function bindUsersScope(client: ClientInstance)')
+        // In namespace mode, `bindScope` lives inside the `${pascal}` namespace
+        // (`Users.bindScope`) — making the merged symbol value+type so index.ts
+        // can `export import` it under verbatimModuleSyntax. The standalone
+        // `bindUsersScope` is reserved for flat mode only.
+        expect(output).toMatch(/export namespace Users \{[\s\S]*export function bindScope\(client: ClientInstance\)/)
+        expect(output).not.toContain('export function bindUsersScope')
       })
     })
 
@@ -901,6 +906,171 @@ describe('emitScopeFile .safe sibling on API', () => {
 // Stream callables omit .safe sibling (regression guard for Task 14)
 // ---------------------------------------------------------------------------
 
+// ---------------------------------------------------------------------------
+// Bug repro (downstream): duplicate Scope / Params identifiers in scope namespaces
+// ---------------------------------------------------------------------------
+//
+// Reported as "Duplicate Scope / Params identifiers in keys.ts / schemas.ts".
+// Root cause: ajsc with inlineTypes:false extracts a property named `params`
+// (or `scope`) into a sub-type literally named `Params` (or `Scope`). For RPC
+// routes, formatTypes also adds `export type Params = <body>` for the route's
+// own params channel — collision. For API routes, emitApiRoute injects an
+// additional `export type Params = { ... }` — same collision. Either way,
+// the resulting namespace has two `export type Params` lines and won't compile.
+
+const rpcGroupParamsCollision: ScopeGroup = {
+  scopeKey: 'schemas',
+  camelCase: 'schemas',
+  routes: [
+    {
+      kind: 'rpc',
+      name: 'CreateSchema',
+      path: '/schemas',
+      method: 'post',
+      scope: 'schemas',
+      version: 1,
+      jsonSchema: {
+        // The body has a property literally named `params` whose value is an
+        // object — ajsc with inlineTypes:false will extract `export type Params = {...}`.
+        body: {
+          type: 'object',
+          properties: {
+            params: {
+              type: 'object',
+              properties: { kind: { type: 'string' }, value: { type: 'string' } },
+              required: ['kind'],
+            },
+          },
+          required: ['params'],
+        },
+        response: {
+          type: 'object',
+          properties: { id: { type: 'string' } },
+          required: ['id'],
+        },
+      },
+    } satisfies RPCHttpRouteDoc,
+  ],
+}
+
+const apiGroupScopeCollision: ScopeGroup = {
+  scopeKey: 'keys',
+  camelCase: 'keys',
+  routes: [
+    {
+      kind: 'api',
+      name: 'CreateKey',
+      path: '/keys',
+      method: 'post',
+      fullPath: '/api/keys',
+      scope: 'keys',
+      jsonSchema: {
+        // Body has a property literally named `scope` whose value is an object —
+        // ajsc with inlineTypes:false extracts `export type Scope = {...}`.
+        body: {
+          type: 'object',
+          properties: {
+            scope: {
+              type: 'object',
+              properties: { resource: { type: 'string' }, action: { type: 'string' } },
+              required: ['resource', 'action'],
+            },
+          },
+          required: ['scope'],
+        },
+        // Response also contains a property named `scope`, but with a DIFFERENT
+        // shape (additional `grantedAt` field). ajsc extracts a second
+        // `export type Scope = {...}` whose body string differs from the body's
+        // `Scope`, so the dedup-by-string-equality in formatTypes does not
+        // collapse them — both end up in the namespace.
+        response: {
+          type: 'object',
+          properties: {
+            id: { type: 'string' },
+            scope: {
+              type: 'object',
+              properties: {
+                resource: { type: 'string' },
+                action: { type: 'string' },
+                grantedAt: { type: 'string' },
+              },
+              required: ['resource', 'action', 'grantedAt'],
+            },
+          },
+          required: ['id', 'scope'],
+        },
+      },
+    } satisfies APIHttpRouteDoc,
+  ],
+}
+
+const apiGroupParamsCollision: ScopeGroup = {
+  scopeKey: 'schemas',
+  camelCase: 'schemas',
+  routes: [
+    {
+      kind: 'api',
+      name: 'RegisterSchema',
+      path: '/schemas',
+      method: 'post',
+      fullPath: '/api/schemas',
+      scope: 'schemas',
+      jsonSchema: {
+        // Body has a property literally named `params` — ajsc extracts
+        // `export type Params = {...}`. emitApiRoute then injects an additional
+        // `export type Params = { body: Body }` for the structured channel
+        // params. Two `Params` declarations in the same namespace.
+        body: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            params: {
+              type: 'object',
+              properties: { kind: { type: 'string' } },
+              required: ['kind'],
+            },
+          },
+          required: ['name', 'params'],
+        },
+        response: {
+          type: 'object',
+          properties: { id: { type: 'string' } },
+          required: ['id'],
+        },
+      },
+    } satisfies APIHttpRouteDoc,
+  ],
+}
+
+/** Counts non-overlapping occurrences of `export type ${name} =` in a string. */
+function countTypeDeclarations(source: string, name: string): number {
+  const matches = source.match(new RegExp(`export\\s+type\\s+${name}\\s*=`, 'g'))
+  return matches ? matches.length : 0
+}
+
+describe('emitScopeFile (bug repro: duplicate identifiers in namespace)', () => {
+  it('does not emit two `export type Params` inside a route namespace when the body has a `params` property (RPC)', async () => {
+    const out = await emitScopeFile(rpcGroupParamsCollision, { namespaceTypes: true })
+    // The namespace is `Schemas { CreateSchema { ... } }`. There must be only
+    // one `export type Params` inside the CreateSchema namespace.
+    expect(countTypeDeclarations(out, 'Params')).toBe(1)
+  })
+
+  it('does not emit two `export type Scope` inside a route namespace when body and response have differently-shaped `scope` properties (API)', async () => {
+    const out = await emitScopeFile(apiGroupScopeCollision, { namespaceTypes: true })
+    // Two extracted `Scope` sub-types with differing bodies → string-equality
+    // dedup does not collapse them, both get emitted.
+    expect(countTypeDeclarations(out, 'Scope')).toBe(1)
+  })
+
+  it('does not emit two `export type Params` inside a route namespace when the body has a `params` property (API)', async () => {
+    const out = await emitScopeFile(apiGroupParamsCollision, { namespaceTypes: true })
+    // One extracted `Params` (from body.params property) + one injected `Params`
+    // (the structured channel composer) → collision.
+    expect(countTypeDeclarations(out, 'Params')).toBe(1)
+  })
+})
+
 describe('emitScopeFile streams omit .safe sibling', () => {
   it('does not emit .safe on stream callables', async () => {
     const out = await emitScopeFile(streamGroup, {

package/src/codegen/emit-scope.ts

@@ -8,6 +8,7 @@ import {
   jsonSchemaToTypeString,
   jsonSchemaToTypeBody,
   jsonSchemaToExtractedTypes,
+  renameExtractedTypes,
   type AjscOptions,
   type ExtractedTypeOutput,
 } from './emit-types.js'
@@ -124,11 +125,17 @@ interface FormattedTypes {
  * Converts multiple schemas into type declarations and type references.
  * In flat mode: `export type ${routePascal}${shortName} = <body>`
  * In namespace mode: extracted sub-types + named types inside `export namespace ${routePascal} { ... }`
+ *
+ * `extraReserved` lets the caller pre-reserve identifier names that the route
+ * will inject AFTER formatTypes returns (e.g. emitApiRoute's structured
+ * `Params`). Without this, an ajsc-extracted sub-type could shadow the
+ * injected one and produce duplicate `export type Params` declarations.
  */
 async function formatTypes(
   routePascal: string,
   types: NamedType[],
   ctx: EmitRouteContext,
+  extraReserved?: ReadonlySet<string>,
 ): Promise<FormattedTypes> {
   const declarations: string[] = []
   const refs: Record<string, string> = {}
@@ -137,13 +144,26 @@ async function formatTypes(
     const nsLines: string[] = []
     const seenDeclarations = new Set<string>()
 
+    // Pre-reserve every name the route will declare itself (each shortName +
+    // any caller-supplied extras). Extracted sub-types whose names land in
+    // this set get renamed (e.g. `Params` → `Params_`) by renameExtractedTypes,
+    // and the body string is patched in lockstep so the reference still
+    // resolves. The set is mutated as we go, so a sub-type renamed in schema A
+    // is also reserved against schema B.
+    const taken = new Set<string>(extraReserved ?? [])
+    for (const t of types) {
+      if (t.schema != null) taken.add(t.shortName)
+    }
+
     for (const { shortName, schema } of types) {
       if (schema == null) continue
 
-      const result = await jsonSchemaToExtractedTypes(schema, ctx.ajsc)
-      if (result == null) continue
+      const rawResult = await jsonSchemaToExtractedTypes(schema, ctx.ajsc)
+      if (rawResult == null) continue
 
-      // Collect extracted sub-types (deduplicate across schemas)
+      const result = renameExtractedTypes(rawResult, taken)
+
+      // Collect extracted sub-types (deduplicate across schemas by exact-string)
       for (const decl of result.declarations) {
         if (!seenDeclarations.has(decl)) {
           seenDeclarations.add(decl)
@@ -290,7 +310,14 @@ async function emitApiRoute(route: APIHttpRouteDoc, ctx: EmitRouteContext): Prom
   // Add response
   channelTypes.push({ shortName: 'Response', schema: route.jsonSchema.response })
 
-  const { declarations, refs } = await formatTypes(pascal, channelTypes, ctx)
+  // `Params` is injected into the namespace below (after formatTypes), so
+  // reserve it up-front to keep ajsc-extracted sub-types from shadowing it.
+  const { declarations, refs } = await formatTypes(
+    pascal,
+    channelTypes,
+    ctx,
+    new Set(['Params']),
+  )
 
   // Compose structured Params type from channels
   let paramsTypeName = 'unknown'
@@ -479,17 +506,43 @@ export async function emitScopeFile(
 
   const importsBlock = [clientImports, errorsImport].filter(Boolean).join('\n')
 
-  let typesBlock: string
-  if (namespaceTypes && allTypeDeclarations.length > 0) {
-    typesBlock = `export namespace ${pascal} {\n${allTypeDeclarations.join('\n\n')}\n}\n`
-  } else {
-    typesBlock =
-      allTypeDeclarations.length > 0
-        ? allTypeDeclarations.join('\n') + '\n'
-        : ''
+  const callablesBlock = callables.join('\n\n')
+
+  if (namespaceTypes) {
+    // Namespace mode: types AND `bindScope` live inside `export namespace ${pascal}`.
+    // Putting the function inside the namespace makes the merged symbol
+    // value+type, which lets `index.ts` use `export import ${pascal} = …`
+    // under `verbatimModuleSyntax: true`. (A type-only namespace would trip
+    // TS1269/TS1288.) Consumers call `${Pascal}.bindScope(client)`; the
+    // generated `index.ts` factory wires this internally.
+    const callableLines = indent(callablesBlock, '  ')
+    const namespaceMembers = [
+      ...(allTypeDeclarations.length > 0 ? [allTypeDeclarations.join('\n\n')] : []),
+      [
+        '  /** Binds every callable in this scope to a configured client. */',
+        '  export function bindScope(client: ClientInstance) {',
+        '    return {',
+        callableLines,
+        '    }',
+        '  }',
+      ].join('\n'),
+    ].join('\n\n')
+
+    return [
+      CODEGEN_HEADER,
+      importsBlock,
+      '',
+      `export namespace ${pascal} {`,
+      namespaceMembers,
+      '}',
+      '',
+    ].join('\n')
   }
 
-  const callablesBlock = callables.join('\n\n')
+  // Flat mode: types at module level, `bind${pascal}Scope` standalone.
+  const typesBlock = allTypeDeclarations.length > 0
+    ? allTypeDeclarations.join('\n') + '\n'
+    : ''
 
   return [
     CODEGEN_HEADER,