openapi-multitarget-codegen 0.1.0 → 0.1.1

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,22 @@ 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 스키마 검증이 아니라, 파일 존재 여부와 기본 구조(`openapi`, `paths`)를 확인하는 최소 검사입니다.
+- 즉, 정식 lint/validation을 대체하지는 않습니다.
 
 ### 추가 옵션
 
@@ -92,6 +118,7 @@ openapi-multitarget-codegen generate --input <spec> --output <dir> --target <nam
 - `--kubb-output-dir <path>`
   - 기본값: `<output>/kubb`
   - 상대 경로는 `--output` 기준으로 해석됩니다.
+  - `--kubb-config`와 함께 사용할 수 없습니다.
 - `--python-output-file <path>`
   - 기본값: `<output>/python/models.py`
   - 상대 경로는 `--output` 기준으로 해석됩니다.
@@ -102,6 +129,44 @@ 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 구성으로 생성합니다.
+   - 현재 포함된 핵심 의존성:
+     - `@kubb/cli`
+     - `@kubb/core`
+     - `@kubb/plugin-oas`
+     - `@kubb/plugin-ts`
+     - `@kubb/plugin-client`
+2. **native config pass-through 모드**
+   - `--kubb-config`를 주면 사용자의 기존 Kubb config를 그대로 사용합니다.
+   - Kubb의 실제 입력/출력/플러그인 설정은 config 파일 내용을 따릅니다.
+   - 다만 이 래퍼 CLI는 `--input`, `--output`을 계속 요구합니다.
+   - `--input`은 OpenAPI 파일 사전 검증에 사용되고, `--output`은 `--clean` 기준 루트입니다.
+   - 이 모드에서는 `--kubb-output-dir`, `--kubb-client`를 함께 사용할 수 없습니다.
+   - 이 경우 추가 Kubb 플러그인은 소비자 프로젝트에서 직접 설치/관리하는 것을 권장합니다.
+
+즉, 이 패키지는 **기본 preset에 필요한 핵심 Kubb 플러그인만 포함**하고, 나머지 Kubb 생태계는 **기존 Kubb CLI/config를 그대로 통과시키는 방향**을 따릅니다.
+
+> 주의: `--clean`은 항상 `--output` 루트를 먼저 삭제합니다. `--kubb-config` 모드에서는 실제 Kubb 출력 위치가 config 내부 설정과 다를 수 있으므로 신중하게 사용하세요.
 
 ---
 
@@ -211,7 +276,7 @@ components:
 ### Kubb만 생성
 
 ```bash
-openapi-multitarget-codegen generate \
+npx openapi-multitarget-codegen generate \
   --input ./specs/openapi.yaml \
   --output ./generated \
   --target kubb
@@ -220,23 +285,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 +335,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 +352,7 @@ openapi-multitarget-codegen generate \
 ### 여러 타깃 동시 생성
 
 ```bash
-openapi-multitarget-codegen generate \
+npx openapi-multitarget-codegen generate \
   --input ./specs/openapi.yaml \
   --output ./generated \
   --target kubb \
@@ -287,7 +371,7 @@ openapi-multitarget-codegen generate \
 ## 스펙 유효성 확인
 
 ```bash
-openapi-multitarget-codegen check-spec --input ./specs/openapi.yaml
+npx openapi-multitarget-codegen check-spec --input ./specs/openapi.yaml
 ```
 
 이 명령은 다음을 검사합니다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openapi-multitarget-codegen",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "OpenAPI-based multi-target code generation CLI for Kubb, Python types, and LangGraph tools",
   "license": "MIT",
@@ -33,14 +33,15 @@
     "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",
+    "@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

@@ -32,17 +32,22 @@ 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 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 +60,14 @@ 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,
+        })
       } else if (target === 'python') {
         runPython({ input, outputRoot: output, outputFile: pythonOutputFile, modelType: pythonModelType })
       } else if (target === 'langgraph') {
@@ -82,20 +94,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
     }
@@ -146,7 +167,29 @@ function validateOpenApiFile(specPath) {
   return data
 }
 
-function runKubb({ input, outputRoot, outputDir, client }) {
+function runKubb({ input, outputRoot, outputDir, client, configPath, extraArgs = [] }) {
+  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 })
 
@@ -568,6 +611,36 @@ 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']],
+  ].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 +790,23 @@ 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)
   --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
 `)
 }