openapi-multitarget-codegen 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,394 @@
+# openapi-multitarget-codegen
+
+OpenAPI 스펙을 입력으로 받아 아래 3가지 타깃의 코드를 생성하는 **npm 배포용 CLI 패키지**입니다.
+
+1. **TypeScript Kubb**
+2. **Python 타입 코드**
+3. **LangGraph 도구 코드**
+
+이 패키지는 특정 프로젝트 구조를 전제하지 않습니다.
+
+- 입력 스펙 경로는 `--input`으로 받습니다.
+- 출력 루트 경로는 `--output`으로 받습니다.
+- 생성 타깃은 `--target`으로 받습니다.
+
+즉, `openapi/openapi.yaml`, `generated/...` 같은 하드코딩된 경로에 묶이지 않고 사용할 수 있게 만드는 것이 목적입니다.
+
+---
+
+## 설치
+
+### dev dependency
+
+```bash
+npm install -D openapi-multitarget-codegen
+```
+
+또는:
+
+```bash
+pnpm add -D openapi-multitarget-codegen
+```
+
+### 전역 설치
+
+```bash
+npm install -g openapi-multitarget-codegen
+```
+
+---
+
+## 문서
+
+- OpenAPI 작성 가이드: [`docs/openapi-authoring-guide.md`](docs/openapi-authoring-guide.md)
+- 예제 스펙: [`openapi/openapi.example.yaml`](openapi/openapi.example.yaml)
+
+---
+
+## GitHub
+
+- Repository: `https://github.com/kht2199/openapi-multitarget-codegen`
+- Issues: `https://github.com/kht2199/openapi-multitarget-codegen/issues`
+
+---
+
+## 지원 타깃
+
+### 1) `kubb`
+OpenAPI 스펙으로부터 TypeScript 타입 및 fetch client를 생성합니다.
+
+### 2) `python`
+OpenAPI 스펙으로부터 Python 타입 코드를 생성합니다.
+기본 출력 모델 타입은 `pydantic_v2.BaseModel`입니다.
+
+### 3) `langgraph`
+OpenAPI operation을 기준으로 LangGraph/LangChain StructuredTool 초안 코드를 생성합니다.
+
+중요:
+- **LangGraph는 정식 지원 타깃입니다.**
+- 하지만 구현이 특정 파일 경로나 특정 프로젝트 레이아웃에 하드코딩되어서는 안 됩니다.
+- 이 CLI는 LangGraph 타깃도 다른 타깃과 동일하게 인자 기반으로 생성합니다.
+
+---
+
+## CLI 사용법
+
+```bash
+openapi-multitarget-codegen generate --input <spec> --output <dir> --target <name>
+```
+
+### 공통 옵션
+
+- `--input <path>`: OpenAPI 파일 경로 (`.yaml`, `.yml`, `.json`)
+- `--output <dir>`: 생성 결과를 쓸 출력 루트 디렉터리
+- `--target <name>`: 생성 타깃 (`kubb`, `python`, `langgraph`)
+  - 여러 개를 생성하려면 `--target`을 반복해서 넘깁니다.
+- `--clean`: 출력 루트를 먼저 비웁니다.
+
+### 추가 옵션
+
+- `--python-model-type <type>`
+  - 기본값: `pydantic_v2.BaseModel`
+- `--kubb-output-dir <path>`
+  - 기본값: `<output>/kubb`
+  - 상대 경로는 `--output` 기준으로 해석됩니다.
+- `--python-output-file <path>`
+  - 기본값: `<output>/python/models.py`
+  - 상대 경로는 `--output` 기준으로 해석됩니다.
+- `--langgraph-output-dir <path>`
+  - 기본값: `<output>/langgraph`
+  - 상대 경로는 `--output` 기준으로 해석됩니다.
+- `--langgraph-file <name>`
+  - 기본값: `langgraph_tools.py`
+- `--kubb-client <client>`
+  - 기본값: `fetch`
+
+---
+
+## 빠른 OpenAPI 작성 템플릿
+
+아래 템플릿은 이 CLI로 Kubb / Python / LangGraph 생성을 시작할 때 최소한으로 복붙해 쓸 수 있는 예시입니다.
+더 자세한 기준은 [`docs/openapi-authoring-guide.md`](docs/openapi-authoring-guide.md)를 참고하세요.
+
+```yaml
+openapi: 3.0.3
+info:
+  title: Example API
+  version: 0.1.0
+servers:
+  - url: https://api.example.com
+paths:
+  /items:
+    get:
+      operationId: listItems
+      summary: List items
+      description: Retrieve the current item catalog.
+      responses:
+        '200':
+          description: Successful item list response
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Item'
+    post:
+      operationId: createItem
+      summary: Create item
+      description: Create a new catalog item from the supplied payload.
+      requestBody:
+        required: true
+        description: Item payload to create.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateItemRequest'
+      responses:
+        '200':
+          description: Item created successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Item'
+  /items/{itemId}:
+    get:
+      operationId: getItem
+      summary: Get item by id
+      description: Retrieve one catalog item using its identifier.
+      parameters:
+        - in: path
+          name: itemId
+          required: true
+          description: Unique item identifier.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Matching item response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Item'
+components:
+  schemas:
+    Item:
+      type: object
+      description: Catalog item returned by the API.
+      required: [id, name]
+      properties:
+        id:
+          type: string
+          description: Stable item identifier.
+        name:
+          type: string
+          description: Display name of the item.
+        description:
+          type: string
+          description: Optional human-readable item details.
+    CreateItemRequest:
+      type: object
+      description: Payload for creating a catalog item.
+      required: [name]
+      properties:
+        name:
+          type: string
+          description: Name to assign to the new item.
+        description:
+          type: string
+          description: Optional explanatory text for the new item.
+```
+
+체크 포인트:
+- 각 operation에 `operationId`, `summary`, `description`을 넣기
+- response `description`을 비워두지 않기
+- parameter/property마다 `description`을 넣기
+- request/response schema는 가능하면 `components.schemas`로 분리하기
+
+---
+
+## 예시
+
+### Kubb만 생성
+
+```bash
+openapi-multitarget-codegen generate \
+  --input ./specs/openapi.yaml \
+  --output ./generated \
+  --target kubb
+```
+
+예시 출력 위치 (`--output ./generated`를 준 경우):
+- `./generated/kubb/...`
+
+### Python 타입만 생성
+
+```bash
+openapi-multitarget-codegen generate \
+  --input ./specs/openapi.yaml \
+  --output ./generated \
+  --target python \
+  --python-model-type pydantic_v2.BaseModel
+```
+
+예시 출력 위치 (`--output ./generated`를 준 경우):
+- `./generated/python/models.py`
+
+### 출력 경로까지 세분화해서 생성
+
+```bash
+openapi-multitarget-codegen generate \
+  --input ./specs/openapi.yaml \
+  --output ./generated \
+  --target kubb \
+  --target python \
+  --target langgraph \
+  --kubb-output-dir ./sdk/ts \
+  --python-output-file ./sdk/python/api_models.py \
+  --langgraph-output-dir ./agent/tools \
+  --langgraph-file catalog_tools.py
+```
+
+위 예시는 다음처럼 생성됩니다.
+- `./generated/sdk/ts/...`
+- `./generated/sdk/python/api_models.py`
+- `./generated/agent/tools/catalog_tools.py`
+
+### LangGraph 코드만 생성
+
+```bash
+openapi-multitarget-codegen generate \
+  --input ./specs/openapi.yaml \
+  --output ./generated \
+  --target langgraph
+```
+
+예시 출력 위치 (`--output ./generated`를 준 경우):
+- `./generated/langgraph/langgraph_tools.py`
+
+### 여러 타깃 동시 생성
+
+```bash
+openapi-multitarget-codegen generate \
+  --input ./specs/openapi.yaml \
+  --output ./generated \
+  --target kubb \
+  --target python \
+  --target langgraph \
+  --clean
+```
+
+예시 출력 위치 (`--output ./generated`를 준 경우):
+- `./generated/kubb/...`
+- `./generated/python/models.py`
+- `./generated/langgraph/langgraph_tools.py`
+
+---
+
+## 스펙 유효성 확인
+
+```bash
+openapi-multitarget-codegen check-spec --input ./specs/openapi.yaml
+```
+
+이 명령은 다음을 검사합니다.
+- 파일 존재 여부
+- `openapi` 필드 존재 여부
+- `paths` 객체 존재 여부
+
+---
+
+## 현재 출력 정책
+
+출력 루트는 `--output`으로 받고, 아무 추가 옵션이 없으면 기본값은 아래와 같습니다.
+
+- `kubb` → `<output>/kubb`
+- `python` → `<output>/python/models.py`
+- `langgraph` → `<output>/langgraph/<langgraph-file>`
+
+필요하면 아래 옵션으로 타깃별 경로를 더 세분화할 수 있습니다.
+
+- `--kubb-output-dir`
+- `--python-output-file`
+- `--langgraph-output-dir`
+
+상대 경로는 모두 `--output` 기준으로 해석되고, 절대 경로도 지원합니다.
+
+---
+
+## 현재 구현 특징
+
+### Kubb
+- 임시 Kubb config를 생성해서 실행합니다.
+- 입력 스펙 경로와 출력 경로를 동적으로 주입합니다.
+- 기본 client는 `fetch`입니다.
+
+### Python
+- `uvx --from datamodel-code-generator datamodel-codegen ...` 기반으로 실행합니다.
+- 모델 타입은 `--python-model-type`으로 바꿀 수 있습니다.
+
+### LangGraph
+- OpenAPI operation을 순회하면서 StructuredTool 초안 코드를 생성합니다.
+- path/query/body를 분리해서 처리하는 기본 골격을 포함합니다.
+- 출력 파일명은 `--langgraph-file`로 조절할 수 있습니다.
+
+---
+
+## 왜 이 패키지가 필요한가
+
+실무에서는 같은 OpenAPI 스펙을 기준으로 여러 언어/프레임워크용 코드를 동시에 만들고 싶을 때가 많습니다.
+
+예를 들면:
+- 프론트엔드는 TypeScript client가 필요하고
+- Python 서버/스크립트는 타입 모델이 필요하고
+- 에이전트 계층은 LangGraph 도구 코드가 필요할 수 있습니다.
+
+이 패키지는 그런 상황에서 OpenAPI를 단일 source of truth로 두고, 여러 타깃을 하나의 CLI 인터페이스로 정리하는 데 목적이 있습니다.
+
+---
+
+## 예제 검증 스크립트
+
+저장소에는 예제 스펙 기반 검증 스크립트가 들어 있습니다.
+
+```bash
+npm run check:example-spec
+npm run generate:example:kubb
+npm run generate:example:python
+npm run generate:example:langgraph
+npm run generate:example:all
+```
+
+예제 출력은 `./.tmp-output` 아래에 생성됩니다.
+
+---
+
+## 런타임 요구사항
+
+- Node.js 20+
+- npm 또는 pnpm
+- Python 3.11+
+- `uvx` 사용 가능 환경 (`python` 타깃용, 예: `brew install uv`)
+
+LangGraph 생성 결과를 실제로 실행하려면 별도로 아래 Python 패키지가 필요할 수 있습니다.
+- `httpx`
+- `pydantic`
+- `langchain-core`
+
+---
+
+## 아직 남아 있는 확장 포인트
+
+향후 아래 항목은 더 발전시킬 수 있습니다.
+
+- Kubb의 React Query / Zod / MSW 확장 옵션
+- Python 출력의 dataclass / TypedDict preset 단순화
+- LangGraph naming / auth / filtering 전략 옵션화
+- spec lint/report 전용 명령 추가
+- dry-run / overwrite 정책 옵션
+- npm publish용 release workflow 정리
+
+---
+
+## 한 줄 요약
+
+**openapi-multitarget-codegen은 OpenAPI 스펙을 입력받아 Kubb, Python 타입, LangGraph 코드를 생성하는 인자 기반 npm CLI 패키지입니다.**

package/openapi/openapi.example.yaml

@@ -0,0 +1,85 @@
+openapi: 3.0.3
+info:
+  title: Example API
+  version: 0.1.0
+servers:
+  - url: https://api.example.com
+paths:
+  /items:
+    get:
+      operationId: listItems
+      summary: List items
+      description: Retrieve the current item catalog.
+      responses:
+        '200':
+          description: Successful item list response
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Item'
+    post:
+      operationId: createItem
+      summary: Create item
+      description: Create a new catalog item from the supplied payload.
+      requestBody:
+        required: true
+        description: Item payload to create.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateItemRequest'
+      responses:
+        '200':
+          description: Item created successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Item'
+  /items/{itemId}:
+    get:
+      operationId: getItem
+      summary: Get item by id
+      description: Retrieve one catalog item using its identifier.
+      parameters:
+        - in: path
+          name: itemId
+          required: true
+          description: Unique item identifier.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Matching item response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Item'
+components:
+  schemas:
+    Item:
+      type: object
+      description: Catalog item returned by the API.
+      required: [id, name]
+      properties:
+        id:
+          type: string
+          description: Stable item identifier.
+        name:
+          type: string
+          description: Display name of the item.
+        description:
+          type: string
+          description: Optional human-readable item details.
+    CreateItemRequest:
+      type: object
+      description: Payload for creating a catalog item.
+      required: [name]
+      properties:
+        name:
+          type: string
+          description: Name to assign to the new item.
+        description:
+          type: string
+          description: Optional explanatory text for the new item.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "openapi-multitarget-codegen",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "OpenAPI-based multi-target code generation CLI for Kubb, Python types, and LangGraph tools",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kht2199/openapi-multitarget-codegen.git"
+  },
+  "homepage": "https://github.com/kht2199/openapi-multitarget-codegen#readme",
+  "bugs": {
+    "url": "https://github.com/kht2199/openapi-multitarget-codegen/issues"
+  },
+  "bin": {
+    "openapi-multitarget-codegen": "src/cli.mjs"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "openapi/openapi.example.yaml"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "clean": "rimraf .tmp-output",
+    "check:example-spec": "node ./src/cli.mjs check-spec --input ./openapi/openapi.example.yaml",
+    "generate:example:kubb": "node ./src/cli.mjs generate --input ./openapi/openapi.example.yaml --output ./.tmp-output --target kubb --clean",
+    "generate:example:python": "node ./src/cli.mjs generate --input ./openapi/openapi.example.yaml --output ./.tmp-output --target python --clean",
+    "generate:example:langgraph": "node ./src/cli.mjs generate --input ./openapi/openapi.example.yaml --output ./.tmp-output --target langgraph --clean",
+    "generate:example:all": "node ./src/cli.mjs generate --input ./openapi/openapi.example.yaml --output ./.tmp-output --target kubb --target python --target langgraph --clean"
+  },
+  "dependencies": {
+    "@kubb/cli": "^3.12.0",
+    "@kubb/core": "^3.12.0",
+    "@kubb/plugin-client": "^3.12.0",
+    "@kubb/plugin-oas": "^3.12.0",
+    "@kubb/plugin-ts": "^3.12.0",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "rimraf": "^6.0.1"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,735 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { createRequire } from 'node:module'
+import { fileURLToPath } from 'node:url'
+import yaml from 'js-yaml'
+
+const require = createRequire(import.meta.url)
+const CLI_FILE = fileURLToPath(import.meta.url)
+const PACKAGE_ROOT = path.resolve(path.dirname(CLI_FILE), '..')
+
+function main() {
+  const { command, options } = parseArgs(process.argv.slice(2))
+
+  try {
+    if (!command || command === 'help' || options.help) {
+      printHelp()
+      process.exit(0)
+    }
+
+    if (command === 'check-spec') {
+      const input = requireOption(options, 'input')
+      validateOpenApiFile(path.resolve(input))
+      console.log(`✓ valid OpenAPI spec: ${path.resolve(input)}`)
+      process.exit(0)
+    }
+
+    if (command !== 'generate') {
+      throw new Error(`Unsupported command: ${command}`)
+    }
+
+    const input = path.resolve(requireOption(options, 'input'))
+    const output = path.resolve(requireOption(options, 'output'))
+    const targets = normalizeTargets(options.target)
+    const pythonModelType = options['python-model-type'] || 'pydantic_v2.BaseModel'
+    const kubbOutputDir = options['kubb-output-dir']
+    const pythonOutputFile = options['python-output-file']
+    const langgraphOutputDir = options['langgraph-output-dir']
+    const langgraphFileName = options['langgraph-file'] || 'langgraph_tools.py'
+    const kubbClient = options['kubb-client'] || 'fetch'
+    const clean = Boolean(options.clean)
+
+    validateOpenApiFile(input)
+
+    if (clean) {
+      guardCleanPath(output)
+    }
+    if (clean && fs.existsSync(output)) {
+      fs.rmSync(output, { recursive: true, force: true })
+    }
+    fs.mkdirSync(output, { recursive: true })
+
+    for (const target of targets) {
+      if (target === 'kubb') {
+        runKubb({ input, outputRoot: output, outputDir: kubbOutputDir, client: kubbClient })
+      } else if (target === 'python') {
+        runPython({ input, outputRoot: output, outputFile: pythonOutputFile, modelType: pythonModelType })
+      } else if (target === 'langgraph') {
+        runLangGraph({ input, outputRoot: output, outputDir: langgraphOutputDir, fileName: langgraphFileName })
+      } else {
+        throw new Error(`Unsupported target: ${target}`)
+      }
+    }
+  } catch (error) {
+    console.error(`✗ ${error.message}`)
+    process.exit(1)
+  }
+}
+
+function parseArgs(argv) {
+  const args = [...argv]
+  const first = args[0]
+  const command = !first || first.startsWith('--') ? undefined : args.shift()
+  const options = {}
+
+  while (args.length > 0) {
+    const token = args.shift()
+    if (!token.startsWith('--')) {
+      continue
+    }
+
+    const key = token.slice(2)
+    if (key === 'help' || key === 'clean') {
+      options[key] = true
+      continue
+    }
+
+    const value = args.shift()
+    if (!value || value.startsWith('--')) {
+      throw new Error(`Missing value for --${key}`)
+    }
+
+    if (key === 'target') {
+      if (!options.target) options.target = []
+      options.target.push(value)
+    } else {
+      options[key] = value
+    }
+  }
+
+  return { command, options }
+}
+
+function normalizeTargets(targetValue) {
+  const values = Array.isArray(targetValue) ? targetValue : targetValue ? [targetValue] : []
+  if (values.length === 0) {
+    throw new Error('At least one --target is required (kubb | python | langgraph)')
+  }
+  return values
+}
+
+function requireOption(options, key) {
+  const value = options[key]
+  if (!value) {
+    throw new Error(`--${key} is required`)
+  }
+  return value
+}
+
+function validateOpenApiFile(specPath) {
+  if (!fs.existsSync(specPath)) {
+    throw new Error(`OpenAPI spec not found: ${specPath}`)
+  }
+
+  const text = fs.readFileSync(specPath, 'utf8')
+  let data
+  try {
+    data = yaml.load(text)
+  } catch {
+    data = JSON.parse(text)
+  }
+
+  if (!data || typeof data !== 'object') {
+    throw new Error(`Invalid OpenAPI spec: ${specPath}`)
+  }
+  if (!data.openapi) {
+    throw new Error(`Missing 'openapi' field: ${specPath}`)
+  }
+  if (!data.paths || typeof data.paths !== 'object') {
+    throw new Error(`Missing 'paths' object: ${specPath}`)
+  }
+
+  return data
+}
+
+function runKubb({ input, outputRoot, outputDir, client }) {
+  const kubbOutputDir = resolveOutputPath(outputRoot, outputDir, path.join('kubb'))
+  fs.mkdirSync(kubbOutputDir, { recursive: true })
+
+  const tempConfigPath = path.join(os.tmpdir(), `.openapi-multitarget-codegen-kubb-${Date.now()}.config.mjs`)
+  const configSource = `
+import { createRequire } from 'node:module'
+
+const require = createRequire(${JSON.stringify(path.join(PACKAGE_ROOT, 'package.json'))})
+const { defineConfig } = require('@kubb/core')
+const { pluginOas } = require('@kubb/plugin-oas')
+const { pluginTs } = require('@kubb/plugin-ts')
+const { pluginClient } = require('@kubb/plugin-client')
+
+export default defineConfig({
+  root: '.',
+  input: {
+    path: ${JSON.stringify(input)},
+  },
+  output: {
+    path: ${JSON.stringify(kubbOutputDir)},
+    clean: true,
+  },
+  plugins: [
+    pluginOas(),
+    pluginTs({
+      output: {
+        path: './types',
+      },
+    }),
+    pluginClient({
+      output: {
+        path: './client',
+      },
+      client: ${JSON.stringify(client)},
+    }),
+  ],
+})
+`
+  fs.writeFileSync(tempConfigPath, configSource)
+
+  try {
+    const result = spawnSync(process.execPath, [resolveBinScript('@kubb/cli'), 'generate', '--config', tempConfigPath], {
+      stdio: 'inherit',
+    })
+
+    if (result.status !== 0) {
+      throw new Error('Kubb generation failed')
+    }
+  } finally {
+    cleanupTempFile(tempConfigPath)
+  }
+
+  console.log(`✓ generated kubb output -> ${kubbOutputDir}`)
+}
+
+function runPython({ input, outputRoot, outputFile, modelType }) {
+  ensureCommandAvailable('uvx', 'Python type generation requires uvx. Install uv first, for example: brew install uv')
+
+  const resolvedOutputFile = resolveOutputPath(outputRoot, outputFile, path.join('python', 'models.py'))
+  const pythonOutputDir = path.dirname(resolvedOutputFile)
+  fs.mkdirSync(pythonOutputDir, { recursive: true })
+
+  const result = spawnSync('uvx', [
+    '--from', 'datamodel-code-generator',
+    'datamodel-codegen',
+    '--input', input,
+    '--output', resolvedOutputFile,
+    '--output-model-type', modelType,
+  ], {
+    stdio: 'inherit',
+  })
+
+  if (result.status !== 0) {
+    throw new Error('Python type generation failed')
+  }
+
+  console.log(`✓ generated python output -> ${resolvedOutputFile}`)
+}
+
+function runLangGraph({ input, outputRoot, outputDir, fileName }) {
+  const langgraphOutputDir = resolveOutputPath(outputRoot, outputDir, path.join('langgraph'))
+  const outputFile = path.join(langgraphOutputDir, fileName)
+  fs.mkdirSync(langgraphOutputDir, { recursive: true })
+
+  const doc = validateOpenApiFile(input)
+  const paths = doc.paths ?? {}
+  const components = doc.components ?? {}
+  const operations = []
+
+  for (const [route, methods] of Object.entries(paths)) {
+    for (const [method, op] of Object.entries(methods ?? {})) {
+      const lower = method.toLowerCase()
+      if (!['get', 'post', 'put', 'patch', 'delete'].includes(lower)) continue
+
+      const operationId = op?.operationId || `${lower}_${route.replace(/[^a-zA-Z0-9]+/g, '_').replace(/^_+|_+$/g, '')}`
+      const parameters = [...(op?.parameters ?? [])].map((param) => simplifyParameter(resolveSchemaObject(param, components), components))
+      const requestBodySchema = resolveRequestBodySchema(op?.requestBody, components)
+      const requestBody = requestBodySchema ? simplifySchema(requestBodySchema, components) : null
+      const responseSummary = summarizePrimaryResponse(op?.responses, components)
+      const authRequired = hasSecurityRequirement(op?.security, doc.security)
+
+      operations.push({
+        method: lower,
+        route,
+        operationId,
+        summary: op?.summary || op?.description || `${lower.toUpperCase()} ${route}`,
+        description: op?.description || op?.summary || `${lower.toUpperCase()} ${route}`,
+        parameters,
+        requestBody,
+        responseSummary,
+        authRequired,
+      })
+    }
+  }
+
+  const operationDefs = toPythonLiteral(operations)
+  const sourceNote = path.basename(input)
+
+  const file = `"""
+AUTO-GENERATED FILE.
+Source: ${sourceNote}
+Purpose: LangGraph/LangChain StructuredTool draft generated from OpenAPI.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+
+import httpx
+from langchain_core.tools import StructuredTool
+from pydantic import BaseModel, Field, create_model
+
+OPENAPI_TYPE_MAP: dict[str, Any] = {
+    "string": str,
+    "integer": int,
+    "number": float,
+    "boolean": bool,
+    "object": dict,
+    "array": list,
+}
+
+OPERATION_DEFS = ${operationDefs}
+
+
+def _python_type(openapi_type: str | None) -> Any:
+    return OPENAPI_TYPE_MAP.get(openapi_type or "string", str)
+
+
+def _build_args_schema(operation_id: str, parameters: list[dict[str, Any]], body_schema: dict[str, Any] | None) -> type[BaseModel] | None:
+    fields: dict[str, Any] = {}
+
+    for param in parameters:
+        name = param.get("name")
+        if not name:
+            continue
+        py_type = _python_type(param.get("type"))
+        param_location = param.get("in") or "parameter"
+        description = param.get("description") or f"{param_location} parameter: {name}"
+        required = bool(param.get("required", False))
+        if required:
+            fields[name] = (py_type, Field(description=description))
+        else:
+            fields[name] = (Optional[py_type], Field(default=None, description=description))
+
+    if body_schema:
+        properties = body_schema.get("properties", {}) or {}
+        required_props = set(body_schema.get("required", []) or [])
+        for prop_name, prop_schema in properties.items():
+            py_type = _python_type(prop_schema.get("type"))
+            description = prop_schema.get("description") or f"request body field: {prop_name}"
+            if prop_name in required_props:
+                fields[prop_name] = (py_type, Field(description=description))
+            else:
+                fields[prop_name] = (Optional[py_type], Field(default=None, description=description))
+
+    if not fields:
+        return create_model(f"{operation_id}_args")
+
+    return create_model(f"{operation_id}_args", **fields)
+
+
+def _summarize_args(parameters: list[dict[str, Any]], body_schema: dict[str, Any] | None) -> list[str]:
+    parts: list[str] = []
+    path_names = [param["name"] for param in parameters if param.get("in") == "path" and param.get("name")]
+    query_names = [param["name"] for param in parameters if param.get("in") == "query" and param.get("name")]
+    body_names = list((body_schema or {}).get("properties", {}).keys())
+
+    if path_names:
+        parts.append("path: " + ", ".join(path_names))
+    if query_names:
+        parts.append("query: " + ", ".join(query_names))
+    if body_names:
+        parts.append("body: " + ", ".join(body_names))
+    return parts
+
+
+def _operation_kind(method: str) -> str:
+    upper = method.upper()
+    if upper == "GET":
+        return "Read operation"
+    if upper == "POST":
+        return "Create operation"
+    if upper in {"PUT", "PATCH"}:
+        return "Update operation"
+    if upper == "DELETE":
+        return "Delete operation"
+    return "HTTP operation"
+
+
+
+def _summarize_response(response_summary: dict[str, Any] | None) -> str:
+    if not response_summary:
+        return ""
+    status = response_summary.get("status")
+    schema_type = response_summary.get("type")
+    description = response_summary.get("description") or ""
+    parts = []
+    if status:
+        parts.append(f"Returns status {status}")
+    else:
+        parts.append("Returns a response")
+    if schema_type:
+        parts[-1] += f" with {schema_type} payload"
+    if description:
+        parts[-1] += f" ({description})"
+    return parts[0] + "."
+
+
+
+def _clean_sentence(text: str) -> str:
+    return text.strip().rstrip(".?!")
+
+
+
+def _build_tool_description(defn: dict[str, Any]) -> str:
+    operation_id = defn["operationId"]
+    route = defn["route"]
+    method = defn["method"].upper()
+    summary = _clean_sentence(defn.get("description") or defn.get("summary") or operation_id)
+    parameters = list(defn.get("parameters") or [])
+    body_schema = defn.get("requestBody")
+    response_summary = defn.get("responseSummary")
+    auth_required = bool(defn.get("authRequired"))
+    arg_summary = _summarize_args(parameters, body_schema)
+    parts = [f"{method} {route} - {summary}.", _operation_kind(method) + "."]
+    if arg_summary:
+        parts.append(f"Inputs: {'; '.join(arg_summary)}.")
+    if response_summary:
+        parts.append(_summarize_response(response_summary))
+    if auth_required:
+        parts.append("Authentication required.")
+    return " ".join(part.strip() for part in parts if part).strip()
+
+
+def _make_tool(defn: dict[str, Any], base_url: str) -> StructuredTool:
+    operation_id = defn["operationId"]
+    description = _build_tool_description(defn)
+    route = defn["route"]
+    method = defn["method"]
+    parameters = list(defn.get("parameters") or [])
+    body_schema = defn.get("requestBody")
+
+    def _render_url(kwargs: dict[str, Any]) -> str:
+        rendered_path = route
+        for param in parameters:
+            if param.get("in") != "path":
+                continue
+            name = param.get("name")
+            value = kwargs.get(name)
+            if name and value is not None:
+                rendered_path = rendered_path.replace("{" + name + "}", str(value))
+        return base_url.rstrip("/") + rendered_path
+
+    def _query_params(kwargs: dict[str, Any]) -> dict[str, Any]:
+        return {
+            param["name"]: kwargs.get(param["name"])
+            for param in parameters
+            if param.get("in") == "query" and kwargs.get(param.get("name")) is not None
+        }
+
+    def _request_body(kwargs: dict[str, Any]) -> dict[str, Any]:
+        path_names = {param["name"] for param in parameters if param.get("in") == "path" and param.get("name")}
+        query_names = {param["name"] for param in parameters if param.get("in") == "query" and param.get("name")}
+        return {
+            key: value
+            for key, value in kwargs.items()
+            if value is not None and key not in path_names and key not in query_names
+        }
+
+    def _call_sync(**kwargs: Any) -> str:
+        url = _render_url(kwargs)
+        try:
+            with httpx.Client(timeout=30.0) as client:
+                if method == "get":
+                    response = client.get(url, params=_query_params(kwargs))
+                elif method == "post":
+                    response = client.post(url, params=_query_params(kwargs), json=_request_body(kwargs))
+                elif method == "put":
+                    response = client.put(url, params=_query_params(kwargs), json=_request_body(kwargs))
+                elif method == "patch":
+                    response = client.patch(url, params=_query_params(kwargs), json=_request_body(kwargs))
+                elif method == "delete":
+                    response = client.delete(url, params=_query_params(kwargs))
+                else:
+                    return f"Unsupported HTTP method: {method}"
+
+            if response.is_success:
+                return _format_response(response)
+            return f"Request failed with status {response.status_code}: {response.text}"
+        except Exception as exc:  # noqa: BLE001
+            return f"Tool call error: {exc}"
+
+    async def _call_async(**kwargs: Any) -> str:
+        url = _render_url(kwargs)
+        try:
+            async with httpx.AsyncClient(timeout=30.0) as client:
+                if method == "get":
+                    response = await client.get(url, params=_query_params(kwargs))
+                elif method == "post":
+                    response = await client.post(url, params=_query_params(kwargs), json=_request_body(kwargs))
+                elif method == "put":
+                    response = await client.put(url, params=_query_params(kwargs), json=_request_body(kwargs))
+                elif method == "patch":
+                    response = await client.patch(url, params=_query_params(kwargs), json=_request_body(kwargs))
+                elif method == "delete":
+                    response = await client.delete(url, params=_query_params(kwargs))
+                else:
+                    return f"Unsupported HTTP method: {method}"
+
+            if response.is_success:
+                return _format_response(response)
+            return f"Request failed with status {response.status_code}: {response.text}"
+        except Exception as exc:  # noqa: BLE001
+            return f"Tool call error: {exc}"
+
+    _call_sync.__doc__ = description
+    _call_async.__doc__ = description
+
+    args_schema = _build_args_schema(operation_id, parameters, body_schema)
+    return StructuredTool.from_function(
+        func=_call_sync,
+        coroutine=_call_async,
+        name=operation_id,
+        description=description,
+        return_direct=False,
+        args_schema=args_schema,
+    )
+
+
+def _format_response(response: httpx.Response) -> str:
+    content_type = response.headers.get("content-type", "")
+    if "application/json" in content_type:
+        try:
+            return json.dumps(response.json(), ensure_ascii=False)
+        except Exception:  # noqa: BLE001
+            return response.text
+    return response.text
+
+
+def get_generated_tools(base_url: str) -> list[StructuredTool]:
+    return [_make_tool(defn, base_url=base_url) for defn in OPERATION_DEFS]
+
+
+def list_generated_tool_defs() -> list[dict[str, Any]]:
+    return [
+        {
+            "name": defn["operationId"],
+            "method": defn["method"].upper(),
+            "path": defn["route"],
+            "description": _build_tool_description(defn),
+        }
+        for defn in OPERATION_DEFS
+    ]
+`
+
+  fs.writeFileSync(outputFile, file)
+  console.log(`✓ generated langgraph output -> ${outputFile}`)
+}
+
+function resolveBinScript(moduleName) {
+  const packageJsonPath = require.resolve(`${moduleName}/package.json`)
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'))
+  const binField = packageJson.bin
+  const relativeBinPath = typeof binField === 'string'
+    ? binField
+    : typeof binField === 'object' && binField !== null
+      ? Object.values(binField)[0]
+      : null
+
+  if (!relativeBinPath) {
+    throw new Error(`Unable to resolve bin entry for ${moduleName}`)
+  }
+
+  return path.join(path.dirname(packageJsonPath), relativeBinPath)
+}
+
+function cleanupTempFile(filePath) {
+  try {
+    fs.unlinkSync(filePath)
+  } catch {
+    // ignore cleanup errors
+  }
+}
+
+function ensureCommandAvailable(command, installHint) {
+  const result = spawnSync(command, ['--version'], { stdio: 'ignore' })
+  if (result.error?.code === 'ENOENT') {
+    throw new Error(installHint)
+  }
+}
+
+function resolveOutputPath(outputRoot, candidatePath, defaultRelativePath) {
+  if (!candidatePath) {
+    return path.join(outputRoot, defaultRelativePath)
+  }
+  return path.isAbsolute(candidatePath)
+    ? path.resolve(candidatePath)
+    : path.resolve(outputRoot, candidatePath)
+}
+
+function toPythonLiteral(value, indent = 0) {
+  const spaces = '  '.repeat(indent)
+  const childSpaces = '  '.repeat(indent + 1)
+
+  if (value === null) return 'None'
+  if (value === true) return 'True'
+  if (value === false) return 'False'
+  if (typeof value === 'string') return JSON.stringify(value)
+  if (typeof value === 'number') return Number.isFinite(value) ? String(value) : 'None'
+  if (Array.isArray(value)) {
+    if (value.length === 0) return '[]'
+    return `[\n${value.map((item) => `${childSpaces}${toPythonLiteral(item, indent + 1)}`).join(',\n')}\n${spaces}]`
+  }
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value)
+    if (entries.length === 0) return '{}'
+    return `{\n${entries.map(([key, item]) => `${childSpaces}${JSON.stringify(key)}: ${toPythonLiteral(item, indent + 1)}`).join(',\n')}\n${spaces}}`
+  }
+  return 'None'
+}
+
+function guardCleanPath(outputPath) {
+  const resolved = path.resolve(outputPath)
+  const currentWorkingDirectory = process.cwd()
+  const homeDirectory = process.env.HOME ? path.resolve(process.env.HOME) : null
+
+  if (resolved === path.parse(resolved).root) {
+    throw new Error('--clean cannot target the filesystem root')
+  }
+  if (resolved === currentWorkingDirectory) {
+    throw new Error('--clean cannot target the current working directory directly')
+  }
+  if (homeDirectory && resolved === homeDirectory) {
+    throw new Error('--clean cannot target the home directory')
+  }
+}
+
+function summarizePrimaryResponse(responses, components) {
+  if (!responses || typeof responses !== 'object') return null
+
+  const preferredStatuses = ['200', '201', '202', '204', 'default']
+  const responseEntries = Object.entries(responses)
+  const chosenEntry = preferredStatuses
+    .map((status) => responseEntries.find(([code]) => code === status))
+    .find(Boolean) ?? responseEntries[0]
+
+  if (!chosenEntry) return null
+
+  const [status, response] = chosenEntry
+  const responseObj = resolveSchemaObject(response, components) ?? response
+  const content = responseObj?.content ?? {}
+  const schema = content['application/json']?.schema
+    ?? content['application/*+json']?.schema
+    ?? content['*/*']?.schema
+  const schemaObj = schema ? resolveSchemaObject(schema, components) : null
+  const schemaType = schemaObj ? (schemaObj.type ?? inferSchemaType(schemaObj)) : null
+
+  return {
+    status,
+    description: responseObj?.description || '',
+    type: schemaType,
+  }
+}
+
+function hasSecurityRequirement(operationSecurity, globalSecurity) {
+  if (Array.isArray(operationSecurity)) {
+    return operationSecurity.length > 0
+  }
+  if (Array.isArray(globalSecurity)) {
+    return globalSecurity.length > 0
+  }
+  return false
+}
+
+function resolveRequestBodySchema(requestBody, components) {
+  if (!requestBody) return null
+  const bodyObj = resolveSchemaObject(requestBody, components)
+  const schema = bodyObj?.content?.['application/json']?.schema
+    ?? bodyObj?.content?.['application/*+json']?.schema
+    ?? bodyObj?.content?.['*/*']?.schema
+  if (!schema) return null
+  return resolveSchemaObject(schema, components)
+}
+
+function resolveSchemaObject(obj, components) {
+  if (!obj || typeof obj !== 'object') return obj
+  if (obj.$ref) {
+    const ref = obj.$ref
+    if (ref.startsWith('#/components/schemas/')) {
+      const key = ref.split('/').pop()
+      return resolveSchemaObject(components?.schemas?.[key], components)
+    }
+    if (ref.startsWith('#/components/requestBodies/')) {
+      const key = ref.split('/').pop()
+      return resolveSchemaObject(components?.requestBodies?.[key], components)
+    }
+    if (ref.startsWith('#/components/parameters/')) {
+      const key = ref.split('/').pop()
+      return resolveSchemaObject(components?.parameters?.[key], components)
+    }
+  }
+  return obj
+}
+
+function simplifyParameter(param, components) {
+  const p = resolveSchemaObject(param, components) ?? {}
+  const schema = resolveSchemaObject(p.schema ?? {}, components) ?? {}
+  return {
+    name: p.name,
+    in: p.in,
+    required: Boolean(p.required),
+    description: p.description ?? schema.description ?? '',
+    type: schema.type ?? inferSchemaType(schema),
+  }
+}
+
+function simplifySchema(schema, components) {
+  const resolved = resolveSchemaObject(schema, components) ?? {}
+  const properties = {}
+  for (const [name, propSchema] of Object.entries(resolved.properties ?? {})) {
+    const prop = resolveSchemaObject(propSchema, components) ?? {}
+    properties[name] = {
+      type: prop.type ?? inferSchemaType(prop),
+      description: prop.description ?? '',
+    }
+  }
+  return {
+    type: resolved.type ?? 'object',
+    required: resolved.required ?? [],
+    properties,
+  }
+}
+
+function inferSchemaType(schema) {
+  if (!schema || typeof schema !== 'object') return 'string'
+  if (schema.type) return schema.type
+  if (schema.properties) return 'object'
+  if (schema.items) return 'array'
+  return 'string'
+}
+
+function printHelp() {
+  console.log(`openapi-multitarget-codegen
+
+Usage:
+  openapi-multitarget-codegen generate --input <spec> --output <dir> --target <kubb|python|langgraph> [--target ...]
+  openapi-multitarget-codegen check-spec --input <spec>
+
+Options:
+  --input <path>                OpenAPI file path (.yaml or .json)
+  --output <dir>                Output root directory
+  --target <name>               Generation target (repeatable)
+  --python-model-type <type>    Python output model type (default: pydantic_v2.BaseModel)
+  --kubb-output-dir <path>      Kubb output directory (default: <output>/kubb)
+  --python-output-file <path>   Python output file (default: <output>/python/models.py)
+  --langgraph-output-dir <path> LangGraph output directory (default: <output>/langgraph)
+  --langgraph-file <name>       LangGraph output filename (default: langgraph_tools.py)
+  --kubb-client <client>        Kubb client type (default: fetch)
+  --clean                       Remove output root before generation
+  --help                        Show help
+`)
+}
+
+main()
+