openapi-multitarget-codegen 0.1.0 → 0.1.2

package/README.md

@@ -36,6 +36,26 @@ pnpm add -D openapi-multitarget-codegen
 npm install -g openapi-multitarget-codegen
 ```
 
+### 실행 방법
+
+- dev dependency로 설치했다면 다음 형태로 실행하세요.
+  - `npx openapi-multitarget-codegen ...`
+  - `pnpm exec openapi-multitarget-codegen ...`
+- 전역 설치한 경우에만 `openapi-multitarget-codegen ...` 명령을 직접 사용할 수 있습니다.
+
+### 처음 사용해보기
+
+1. 스펙 최소 구조를 확인합니다.
+2. 단일 타깃으로 먼저 생성해 봅니다.
+3. 필요한 경우 여러 타깃을 한 번에 생성합니다.
+4. Kubb 고급 설정이 필요할 때만 `--kubb-config` 모드로 넘어갑니다.
+
+```bash
+npx openapi-multitarget-codegen check-spec --input ./specs/openapi.yaml
+npx openapi-multitarget-codegen generate --input ./specs/openapi.yaml --output ./generated --target kubb
+npx openapi-multitarget-codegen generate --input ./specs/openapi.yaml --output ./generated --target kubb --target python --target langgraph
+```
+
 ---
 
 ## 문서
@@ -74,16 +94,23 @@ OpenAPI operation을 기준으로 LangGraph/LangChain StructuredTool 초안 코
 ## CLI 사용법
 
 ```bash
-openapi-multitarget-codegen generate --input <spec> --output <dir> --target <name>
+openapi-multitarget-codegen generate --input <spec> --output <dir> --target <kubb|python|langgraph> [--target ...]
+openapi-multitarget-codegen check-spec --input <spec>
 ```
 
 ### 공통 옵션
 
-- `--input <path>`: OpenAPI 파일 경로 (`.yaml`, `.yml`, `.json`)
-- `--output <dir>`: 생성 결과를 쓸 출력 루트 디렉터리
-- `--target <name>`: 생성 타깃 (`kubb`, `python`, `langgraph`)
+- `--input <path>` (필수): OpenAPI 파일 경로 (`.yaml`, `.yml`, `.json`)
+- `--output <dir>` (필수, `generate` 전용): 생성 결과를 쓸 출력 루트 디렉터리
+- `--target <name>` (필수, `generate` 전용): 생성 타깃 (`kubb`, `python`, `langgraph`)
   - 여러 개를 생성하려면 `--target`을 반복해서 넘깁니다.
-- `--clean`: 출력 루트를 먼저 비웁니다.
+- `--clean` (`generate` 전용): 출력 루트를 먼저 비웁니다.
+
+### `check-spec` 범위
+
+- `check-spec`은 파일 존재 여부와 기본 구조(`openapi`, `paths`) 확인에 더해, OpenAPI 문서를 실제로 parse/validate 합니다.
+- unresolved `$ref`, 잘못된 스키마 구조, 문서 수준의 OpenAPI 오류를 조기에 잡는 용도입니다.
+- 다만 **target별 생성기 호환성까지 전부 보장하는 것은 아닙니다.** 즉, `kubb`, `python`, `langgraph` 각각의 세부 제약은 실제 generate 단계에서 추가 확인이 필요할 수 있습니다.
 
 ### 추가 옵션
 
@@ -92,6 +119,13 @@ openapi-multitarget-codegen generate --input <spec> --output <dir> --target <nam
 - `--kubb-output-dir <path>`
   - 기본값: `<output>/kubb`
   - 상대 경로는 `--output` 기준으로 해석됩니다.
+  - `--kubb-config`와 함께 사용할 수 없습니다.
+- `--kubb-format <mode>`
+  - 기본값: `false`
+  - preset 모드에서만 사용합니다.
+  - 허용값: `auto`, `prettier`, `biome`, `oxfmt`, `false`
+  - 기본값 `false`는 Kubb 생성은 유지하되 formatter 미설치로 인한 혼란스러운 메시지를 피하기 위한 설정입니다.
+  - `--kubb-config`와 함께 사용할 수 없습니다.
 - `--python-output-file <path>`
   - 기본값: `<output>/python/models.py`
   - 상대 경로는 `--output` 기준으로 해석됩니다.
@@ -102,6 +136,46 @@ openapi-multitarget-codegen generate --input <spec> --output <dir> --target <nam
   - 기본값: `langgraph_tools.py`
 - `--kubb-client <client>`
   - 기본값: `fetch`
+  - `--kubb-config`와 함께 사용할 수 없습니다.
+- `--kubb-config <path>`
+  - Kubb native config 파일을 그대로 사용합니다.
+  - 이 모드에서는 해당 config 파일이 **Kubb 생성에 관한 입력/출력/플러그인 설정의 source of truth**가 됩니다.
+  - 다만 이 래퍼 CLI 차원에서는 `--input`, `--output`을 계속 요구합니다.
+  - `--input`은 사전 검증에 사용되고, `--output`은 `--clean` 처리 기준 디렉터리입니다.
+  - 이 패키지는 내장 preset을 만들지 않고 `kubb generate --config ...`를 pass-through 합니다.
+- `--kubb-arg <value>`
+  - 반복 가능 옵션입니다.
+  - `--kubb-config`와 함께만 사용할 수 있습니다.
+  - 전달한 값은 `kubb generate` 뒤에 그대로 추가됩니다.
+  - 값이 `--watch`, `--logLevel`처럼 `--`로 시작하면 `--kubb-arg=--watch`처럼 `=` 형식으로 전달하세요.
+
+> 주의: `--kubb-output-dir`, `--python-output-file`, `--langgraph-output-dir`에 주는 상대 경로는 현재 작업 디렉터리가 아니라 `--output` 디렉터리 기준으로 해석됩니다.
+
+### Kubb 사용 정책
+
+이 CLI의 Kubb 지원은 두 가지 모드가 있습니다.
+
+1. **기본 preset 모드**
+   - 이 패키지에 포함된 기본 Kubb 구성으로 생성합니다.
+   - 기본 formatter 설정은 `false`입니다.
+   - formatter를 켜고 싶다면 `--kubb-format auto` 또는 `--kubb-format prettier` 같은 식으로 명시합니다.
+   - 현재 포함된 핵심 의존성:
+     - `@kubb/cli`
+     - `@kubb/core`
+     - `@kubb/plugin-oas`
+     - `@kubb/plugin-ts`
+     - `@kubb/plugin-client`
+2. **native config pass-through 모드**
+   - `--kubb-config`를 주면 사용자의 기존 Kubb config를 그대로 사용합니다.
+   - Kubb의 실제 입력/출력/플러그인/formatter 설정은 config 파일 내용을 따릅니다.
+   - 다만 이 래퍼 CLI는 `--input`, `--output`을 계속 요구합니다.
+   - `--input`은 OpenAPI 파일 사전 검증에 사용되고, `--output`은 `--clean` 기준 루트입니다.
+   - 이 모드에서는 `--kubb-output-dir`, `--kubb-client`, `--kubb-format`을 함께 사용할 수 없습니다.
+   - 이 경우 추가 Kubb 플러그인은 소비자 프로젝트에서 직접 설치/관리하는 것을 권장합니다.
+
+즉, 이 패키지는 **기본 preset에 필요한 핵심 Kubb 플러그인만 포함**하고, 나머지 Kubb 생태계는 **기존 Kubb CLI/config를 그대로 통과시키는 방향**을 따릅니다.
+
+> 주의: `--clean`은 항상 `--output` 루트를 먼저 삭제합니다. `--kubb-config` 모드에서는 실제 Kubb 출력 위치가 config 내부 설정과 다를 수 있으므로 신중하게 사용하세요.
 
 ---
 
@@ -211,7 +285,7 @@ components:
 ### Kubb만 생성
 
 ```bash
-openapi-multitarget-codegen generate \
+npx openapi-multitarget-codegen generate \
   --input ./specs/openapi.yaml \
   --output ./generated \
   --target kubb
@@ -220,23 +294,40 @@ openapi-multitarget-codegen generate \
 예시 출력 위치 (`--output ./generated`를 준 경우):
 - `./generated/kubb/...`
 
+### 기존 Kubb config 그대로 사용
+
+```bash
+npx openapi-multitarget-codegen generate \
+  --input ./specs/openapi.yaml \
+  --output ./generated \
+  --target kubb \
+  --kubb-config ./kubb.config.ts \
+  --kubb-arg=--logLevel \
+  --kubb-arg=info
+```
+
+이 모드에서는 `kubb generate --config ./kubb.config.ts --logLevel info` 형태로 pass-through 됩니다.
+추가 Kubb 플러그인이 필요하면 해당 플러그인은 소비자 프로젝트에서 직접 설치하면 됩니다.
+`--input`, `--output`은 이 래퍼 CLI의 사전 검증 및 `--clean` 기준을 위해 계속 필요하지만, Kubb config 내부의 실제 input/output 설정을 덮어쓰지는 않습니다.
+
 ### Python 타입만 생성
 
 ```bash
-openapi-multitarget-codegen generate \
+npx openapi-multitarget-codegen generate \
   --input ./specs/openapi.yaml \
   --output ./generated \
-  --target python \
-  --python-model-type pydantic_v2.BaseModel
+  --target python
 ```
 
+기본 모델 타입은 `pydantic_v2.BaseModel`이므로 기본값을 그대로 사용할 때는 `--python-model-type`을 생략해도 됩니다.
+
 예시 출력 위치 (`--output ./generated`를 준 경우):
 - `./generated/python/models.py`
 
 ### 출력 경로까지 세분화해서 생성
 
 ```bash
-openapi-multitarget-codegen generate \
+npx openapi-multitarget-codegen generate \
   --input ./specs/openapi.yaml \
   --output ./generated \
   --target kubb \
@@ -253,10 +344,12 @@ openapi-multitarget-codegen generate \
 - `./generated/sdk/python/api_models.py`
 - `./generated/agent/tools/catalog_tools.py`
 
+주의: 위 상대 경로들은 현재 작업 디렉터리가 아니라 `--output ./generated` 기준으로 해석됩니다.
+
 ### LangGraph 코드만 생성
 
 ```bash
-openapi-multitarget-codegen generate \
+npx openapi-multitarget-codegen generate \
   --input ./specs/openapi.yaml \
   --output ./generated \
   --target langgraph
@@ -268,7 +361,7 @@ openapi-multitarget-codegen generate \
 ### 여러 타깃 동시 생성
 
 ```bash
-openapi-multitarget-codegen generate \
+npx openapi-multitarget-codegen generate \
   --input ./specs/openapi.yaml \
   --output ./generated \
   --target kubb \
@@ -287,13 +380,16 @@ openapi-multitarget-codegen generate \
 ## 스펙 유효성 확인
 
 ```bash
-openapi-multitarget-codegen check-spec --input ./specs/openapi.yaml
+npx openapi-multitarget-codegen check-spec --input ./specs/openapi.yaml
 ```
 
 이 명령은 다음을 검사합니다.
 - 파일 존재 여부
-- `openapi` 필드 존재 여부
-- `paths` 객체 존재 여부
+- 기본 구조(`openapi`, `paths`) 존재 여부
+- OpenAPI 문서 parse/validate
+- unresolved `$ref`, 잘못된 스키마 구조 등 문서 수준 오류
+
+다만 이 단계가 `kubb`, `python`, `langgraph` 각 타깃 생성기의 세부 호환성까지 모두 보장하는 것은 아닙니다. 타깃별 제약은 실제 `generate` 단계에서 추가 확인이 필요할 수 있습니다.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openapi-multitarget-codegen",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "OpenAPI-based multi-target code generation CLI for Kubb, Python types, and LangGraph tools",
   "license": "MIT",
@@ -26,6 +26,7 @@
   },
   "scripts": {
     "clean": "rimraf .tmp-output",
+    "test": "node --test tests/*.test.mjs",
     "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",
@@ -33,14 +34,16 @@
     "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",
+    "@apidevtools/swagger-parser": "^12.1.0",
+    "@kubb/cli": "^4.37.2",
+    "@kubb/core": "^4.37.2",
+    "@kubb/plugin-client": "^4.37.2",
+    "@kubb/plugin-oas": "^4.37.2",
+    "@kubb/plugin-ts": "^4.37.2",
     "js-yaml": "^4.1.0"
   },
   "devDependencies": {
+    "prettier": "^3.8.2",
     "rimraf": "^6.0.1"
   }
 }

package/src/cli.mjs

@@ -9,10 +9,11 @@ import { fileURLToPath } from 'node:url'
 import yaml from 'js-yaml'
 
 const require = createRequire(import.meta.url)
+const SwaggerParser = require('@apidevtools/swagger-parser')
 const CLI_FILE = fileURLToPath(import.meta.url)
 const PACKAGE_ROOT = path.resolve(path.dirname(CLI_FILE), '..')
 
-function main() {
+async function main() {
   const { command, options } = parseArgs(process.argv.slice(2))
 
   try {
@@ -23,7 +24,7 @@ function main() {
 
     if (command === 'check-spec') {
       const input = requireOption(options, 'input')
-      validateOpenApiFile(path.resolve(input))
+      await validateOpenApiSpec(path.resolve(input))
       console.log(`✓ valid OpenAPI spec: ${path.resolve(input)}`)
       process.exit(0)
     }
@@ -32,17 +33,23 @@ function main() {
       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 kubbConfigPath = options['kubb-config']
+    const kubbArgs = Array.isArray(options['kubb-arg']) ? options['kubb-arg'] : []
+    const kubbFormat = normalizeKubbFormat(options['kubb-format'])
     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)
 
+    validateKubbOptionCompatibility({ options, targets, kubbConfigPath, kubbArgs })
+
+    const input = path.resolve(requireOption(options, 'input'))
+    const output = path.resolve(requireOption(options, 'output'))
+
     validateOpenApiFile(input)
 
     if (clean) {
@@ -55,7 +62,15 @@ function main() {
 
     for (const target of targets) {
       if (target === 'kubb') {
-        runKubb({ input, outputRoot: output, outputDir: kubbOutputDir, client: kubbClient })
+        runKubb({
+          input,
+          outputRoot: output,
+          outputDir: kubbOutputDir,
+          client: kubbClient,
+          configPath: kubbConfigPath,
+          extraArgs: kubbArgs,
+          format: kubbFormat,
+        })
       } else if (target === 'python') {
         runPython({ input, outputRoot: output, outputFile: pythonOutputFile, modelType: pythonModelType })
       } else if (target === 'langgraph') {
@@ -82,20 +97,29 @@ function parseArgs(argv) {
       continue
     }
 
-    const key = token.slice(2)
+    const inlineEqualsIndex = token.indexOf('=')
+    const key = inlineEqualsIndex >= 0 ? token.slice(2, inlineEqualsIndex) : 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}`)
+    let value
+    if (inlineEqualsIndex >= 0) {
+      value = token.slice(inlineEqualsIndex + 1)
+      if (!value) {
+        throw new Error(`Missing value for --${key}`)
+      }
+    } else {
+      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)
+    if (key === 'target' || key === 'kubb-arg') {
+      if (!options[key]) options[key] = []
+      options[key].push(value)
     } else {
       options[key] = value
     }
@@ -112,6 +136,20 @@ function normalizeTargets(targetValue) {
   return values
 }
 
+function normalizeKubbFormat(value) {
+  if (!value) {
+    return false
+  }
+
+  const normalized = String(value).toLowerCase()
+  const allowed = new Set(['auto', 'prettier', 'biome', 'oxfmt', 'false'])
+  if (!allowed.has(normalized)) {
+    throw new Error("--kubb-format must be one of: auto, prettier, biome, oxfmt, false")
+  }
+
+  return normalized === 'false' ? false : normalized
+}
+
 function requireOption(options, key) {
   const value = options[key]
   if (!value) {
@@ -125,6 +163,10 @@ function validateOpenApiFile(specPath) {
     throw new Error(`OpenAPI spec not found: ${specPath}`)
   }
 
+  return loadOpenApiFile(specPath)
+}
+
+function loadOpenApiFile(specPath) {
   const text = fs.readFileSync(specPath, 'utf8')
   let data
   try {
@@ -146,7 +188,52 @@ function validateOpenApiFile(specPath) {
   return data
 }
 
-function runKubb({ input, outputRoot, outputDir, client }) {
+async function validateOpenApiSpec(specPath) {
+  validateOpenApiFile(specPath)
+
+  try {
+    await SwaggerParser.validate(specPath)
+  } catch (error) {
+    const details = []
+    const primaryMessage = error?.message || 'OpenAPI validation failed'
+    details.push(primaryMessage)
+
+    const parserDetails = Array.isArray(error?.details) ? error.details : []
+    for (const detail of parserDetails.slice(0, 5)) {
+      const pathText = detail?.path ? `${detail.path}: ` : ''
+      const messageText = detail?.message || detail?.toString?.() || ''
+      if (messageText) {
+        details.push(`${pathText}${messageText}`)
+      }
+    }
+
+    throw new Error(`OpenAPI validation failed:\n- ${details.join('\n- ')}`)
+  }
+}
+
+function runKubb({ input, outputRoot, outputDir, client, configPath, extraArgs = [], format }) {
+  if (configPath) {
+    const resolvedConfigPath = path.resolve(configPath)
+    if (!fs.existsSync(resolvedConfigPath)) {
+      throw new Error(`Kubb config not found: ${resolvedConfigPath}`)
+    }
+
+    const result = spawnSync(
+      process.execPath,
+      [resolveBinScript('@kubb/cli'), 'generate', '--config', resolvedConfigPath, ...extraArgs],
+      {
+        stdio: 'inherit',
+      },
+    )
+
+    if (result.status !== 0) {
+      throw new Error('Kubb generation failed')
+    }
+
+    console.log(`✓ generated kubb output via config -> ${resolvedConfigPath}`)
+    return
+  }
+
   const kubbOutputDir = resolveOutputPath(outputRoot, outputDir, path.join('kubb'))
   fs.mkdirSync(kubbOutputDir, { recursive: true })
 
@@ -168,6 +255,7 @@ export default defineConfig({
   output: {
     path: ${JSON.stringify(kubbOutputDir)},
     clean: true,
+    format: ${format === false ? 'false' : JSON.stringify(format)},
   },
   plugins: [
     pluginOas(),
@@ -568,6 +656,37 @@ function resolveOutputPath(outputRoot, candidatePath, defaultRelativePath) {
     : path.resolve(outputRoot, candidatePath)
 }
 
+function validateKubbOptionCompatibility({ options, targets, kubbConfigPath, kubbArgs }) {
+  if (!targets.includes('kubb')) {
+    if (kubbConfigPath) {
+      throw new Error('--kubb-config requires --target kubb')
+    }
+    if (kubbArgs.length > 0) {
+      throw new Error('--kubb-arg requires --target kubb')
+    }
+    return
+  }
+
+  if (kubbArgs.length > 0 && !kubbConfigPath) {
+    throw new Error('--kubb-arg requires --kubb-config')
+  }
+
+  if (!kubbConfigPath) {
+    return
+  }
+
+  const conflicting = [
+    ['kubb-client', options['kubb-client']],
+    ['kubb-output-dir', options['kubb-output-dir']],
+    ['kubb-format', options['kubb-format']],
+  ].filter(([, value]) => value)
+
+  if (conflicting.length > 0) {
+    const names = conflicting.map(([name]) => `--${name}`).join(', ')
+    throw new Error(`${names} cannot be used together with --kubb-config`)
+  }
+}
+
 function toPythonLiteral(value, indent = 0) {
   const spaces = '  '.repeat(indent)
   const childSpaces = '  '.repeat(indent + 1)
@@ -717,17 +836,24 @@ Usage:
   openapi-multitarget-codegen check-spec --input <spec>
 
 Options:
-  --input <path>                OpenAPI file path (.yaml or .json)
+  --input <path>                OpenAPI file path (.yaml, .yml, 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)
+  --kubb-config <path>          Use an existing Kubb config file as the source of truth
+  --kubb-arg <value>            Pass an extra argument to 'kubb generate' (repeatable, requires --kubb-config)
+  --kubb-format <mode>          Kubb formatter for preset mode (default: false; auto|prettier|biome|oxfmt|false)
   --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
+
+Examples:
+  openapi-multitarget-codegen generate --input ./openapi/openapi.example.yaml --output ./.tmp-output --target kubb --clean
+  openapi-multitarget-codegen generate --input ./openapi/openapi.example.yaml --output ./.tmp-output --target kubb --kubb-config ./kubb.config.ts --kubb-arg=--watch
 `)
 }