@tronsfey/openapi2cli 1.0.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cli-openapi contributors
+
+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,173 @@
+English | [中文](./README.zh.md)
+
+# openapi2cli
+
+Generate a fully typed [Commander.js](https://github.com/tj/commander.js) CLI project from an OpenAPI 3.x specification — in one command.
+
+## Features
+
+- Parse OAS 3.x specs from a **file path or URL** (full `$ref` resolution)
+- Group operations by **tag** → Commander subcommand groups; untagged operations become top-level commands
+- Generate **TypeScript source** with correct types, required/optional flags, enum `.choices()` validation
+- **5 auth schemes** auto-detected from OAS security definitions: Bearer, API Key, HTTP Basic, OAuth2 Client Credentials, custom dynamic token provider
+- **SSE streaming** via `eventsource-parser` (Node.js-native, used by Anthropic SDK) — full SSE spec support, `[DONE]` sentinel handling
+- **Pagination** via `--all-pages` (follows `Link: rel="next"` response headers)
+- **JMESPath filtering** via `--query` on every command
+- **CJK command names** — Chinese/Japanese/Korean operationIds auto-converted to pinyin
+- **OpenAPI extensions**: `x-cli-name`, `x-cli-aliases`, `x-cli-ignore`, `x-cli-token-url`
+- Generates **bilingual docs**: `README.md` (English) + `README.zh.md` (Chinese) + `SKILL.md` (Claude Code skill descriptor)
+- Global `--endpoint`, `--format` (json/yaml/table), and `--verbose` on every generated CLI
+
+## Installation
+
+```bash
+npm install -g openapi2cli
+```
+
+## Usage
+
+```bash
+# From a local file
+openapi2cli --oas ./openapi.yaml --name my-api --output ./my-api-cli
+
+# From a URL
+openapi2cli --oas https://petstore3.swagger.io/api/v3/openapi.json --name petstore --output ./petstore-cli
+```
+
+Build and link the generated project:
+
+```bash
+cd my-api-cli
+npm install && npm run build && npm link
+my-api --help
+```
+
+## Example
+
+See [`examples/github-cli/`](./examples/github-cli/) for a complete generated CLI targeting the GitHub REST API:
+
+```bash
+cd examples/github-cli
+npm install && npm run build
+node dist/index.js repos get-repo --owner octocat --repo Hello-World
+node dist/index.js repos list-repo-issues --owner octocat --repo Hello-World --state open
+node dist/index.js users get-user --username octocat
+```
+
+## Generated Project Structure
+
+```
+<output>/
+├── bin/<name>            # executable shebang wrapper
+├── src/
+│   ├── index.ts          # Commander root program + global options
+│   ├── commands/
+│   │   └── <tag>.ts      # one file per OAS tag
+│   └── lib/
+│       └── api-client.ts # axios client with auth + SSE streaming
+├── README.md             # English usage guide
+├── README.zh.md          # Chinese usage guide
+├── SKILL.md              # Claude Code skill descriptor
+├── package.json
+└── tsconfig.json
+```
+
+Runtime dependencies in the generated project: `axios`, `chalk`, `commander`, `eventsource-parser`, `jmespath`, `yaml`, `ora`.
+
+## Authentication
+
+The generator inspects the first security scheme in the OAS document and emits the appropriate auth code. Set the matching environment variable before running the CLI:
+
+| Scheme | Env var(s) | Notes |
+|--------|-----------|-------|
+| Bearer | `<NAME>_TOKEN` | `Authorization: Bearer …` |
+| API Key | `<NAME>_API_KEY` | Header or query param name from OAS |
+| HTTP Basic | `<NAME>_CREDENTIALS` | `user:password` → Base64 |
+| OAuth2 Client Credentials | `<NAME>_CLIENT_ID`, `<NAME>_CLIENT_SECRET`, `<NAME>_SCOPES` | Token fetched once at startup, cached for process lifetime |
+| Dynamic (`x-cli-token-url`) | custom env vars defined in the extension | JSON body POSTed to the token URL |
+
+`<NAME>` is the CLI name in SCREAMING_SNAKE_CASE (e.g. `my-api` → `MY_API`).
+
+## OpenAPI Extensions
+
+Add these vendor extensions to your OAS document to control CLI generation:
+
+| Extension | Placement | Effect |
+|-----------|-----------|--------|
+| `x-cli-name: "my-name"` | operation | Override the auto-generated command name |
+| `x-cli-aliases: ["a"]` | operation | Add Commander aliases to the command |
+| `x-cli-ignore: true` | operation | Exclude the operation from the generated CLI |
+| `x-cli-token-url: "https://…"` | securityScheme | Custom token endpoint for dynamic auth |
+
+## Global Options
+
+Every generated CLI exposes these options on all commands:
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--endpoint <url>` | Override the base API URL | spec server URL |
+| `--format <fmt>` | Output format: `json`, `yaml`, `table` | `json` |
+| `--verbose` | Log HTTP method + URL before each request | `false` |
+| `--query <expr>` | JMESPath expression to filter the response | — |
+| `--all-pages` | Auto-paginate via `Link: rel="next"` headers | `false` |
+
+## Request Body
+
+For `POST`, `PUT`, `PATCH` commands use `--data`:
+
+```bash
+# Inline JSON
+my-api widgets create --data '{"name": "foo", "color": "blue"}'
+
+# From a file
+my-api widgets create --data @./payload.json
+```
+
+## Output Formats
+
+```bash
+# Default: pretty-printed JSON
+my-api repos list
+
+# Table view (great for arrays)
+my-api repos list --format table
+
+# YAML
+my-api repos list --format yaml
+
+# JMESPath filter
+my-api repos list --query '[].name'
+
+# Pipe to jq
+my-api repos list | jq '.[].full_name'
+
+# Save to file
+my-api repos list > repos.json
+```
+
+## Streaming (SSE)
+
+Operations that return `text/event-stream` are detected automatically from the OAS response content type. The generated CLI pipes each SSE data payload to stdout, one per line:
+
+```bash
+my-api completions create --model gpt-4o --stream
+```
+
+The generated client uses `eventsource-parser` with the native `fetch` API. It supports multi-line `data:` payloads, named `event:` types, and silently drops `[DONE]` sentinels used by OpenAI-compatible APIs.
+
+## CLI Options
+
+```
+openapi2cli [options]
+
+Options:
+  --oas <path|url>   Path or URL to the OpenAPI 3.x spec (required)
+  --name <name>      CLI executable name (required)
+  --output <dir>     Output directory (required)
+  --overwrite        Overwrite existing output directory
+  -h, --help         Display help
+```
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,173 @@
+[English](./README.md) | 中文
+
+# openapi2cli
+
+一条命令，将 OpenAPI 3.x 规范生成为完整的 [Commander.js](https://github.com/tj/commander.js) TypeScript CLI 项目。
+
+## 功能特性
+
+- 支持从**文件路径或 URL** 解析 OAS 3.x 规范（完整 `$ref` 解析）
+- 按 **tag** 分组操作，生成 Commander 子命令组；未分组的操作注册为顶层命令
+- 生成带完整类型标注的 **TypeScript 源码**，支持必填/可选参数、枚举 `.choices()` 校验
+- **5 种认证方案**自动从 OAS 安全定义中检测：Bearer、API Key、HTTP Basic、OAuth2 Client Credentials、自定义动态 Token
+- **SSE 流式输出**基于 `eventsource-parser`，支持自动重连和 `[DONE]` 哨兵处理
+- **自动分页**：`--all-pages` 参数，自动跟随 `Link: rel="next"` 响应头翻页
+- **JMESPath 过滤**：每条命令均支持 `--query` 参数
+- **中文命令名支持**：中/日/韩 operationId 自动转换为拼音
+- **OpenAPI 扩展**：`x-cli-name`、`x-cli-aliases`、`x-cli-ignore`、`x-cli-token-url`
+- 自动生成**双语文档**：`README.md`（英文）+ `README.zh.md`（中文）+ `SKILL.md`（Claude Code 技能描述文件）
+- 所有生成的 CLI 均内置全局选项：`--endpoint`、`--format`（json/yaml/table）、`--verbose`
+
+## 安装
+
+```bash
+npm install -g openapi2cli
+```
+
+## 使用方法
+
+```bash
+# 从本地文件生成
+openapi2cli --oas ./openapi.yaml --name my-api --output ./my-api-cli
+
+# 从 URL 生成
+openapi2cli --oas https://petstore3.swagger.io/api/v3/openapi.json --name petstore --output ./petstore-cli
+```
+
+构建并链接生成的项目：
+
+```bash
+cd my-api-cli
+npm install && npm run build && npm link
+my-api --help
+```
+
+## 示例
+
+参见 [`examples/github-cli/`](./examples/github-cli/)，这是一个针对 GitHub REST API 的完整生成示例：
+
+```bash
+cd examples/github-cli
+npm install && npm run build
+node dist/index.js repos get-repo --owner octocat --repo Hello-World
+node dist/index.js repos list-repo-issues --owner octocat --repo Hello-World --state open
+node dist/index.js users get-user --username octocat
+```
+
+## 生成项目结构
+
+```
+<output>/
+├── bin/<name>            # 可执行文件 shebang 包装器
+├── src/
+│   ├── index.ts          # Commander 根程序 + 全局选项
+│   ├── commands/
+│   │   └── <tag>.ts      # 每个 OAS tag 对应一个文件
+│   └── lib/
+│       └── api-client.ts # 带认证 + SSE 流式支持的 axios 客户端
+├── README.md             # 英文使用文档
+├── README.zh.md          # 中文使用文档
+├── SKILL.md              # Claude Code 技能描述文件
+├── package.json
+└── tsconfig.json
+```
+
+生成项目的运行时依赖：`axios`、`chalk`、`commander`、`eventsource-parser`、`jmespath`、`yaml`、`ora`。
+
+## 认证方式
+
+生成器自动检测 OAS 文档中的第一个安全方案，并生成对应的认证代码。运行 CLI 前设置相应的环境变量：
+
+| 方案 | 环境变量 | 说明 |
+|------|---------|------|
+| Bearer | `<NAME>_TOKEN` | `Authorization: Bearer …` |
+| API Key | `<NAME>_API_KEY` | Header 或 Query 参数，名称取自 OAS |
+| HTTP Basic | `<NAME>_CREDENTIALS` | `用户名:密码` → Base64 编码 |
+| OAuth2 Client Credentials | `<NAME>_CLIENT_ID`、`<NAME>_CLIENT_SECRET`、`<NAME>_SCOPES` | 启动时自动换取 Token，进程内缓存 |
+| 动态 Token（`x-cli-token-url`） | 扩展字段中定义的自定义环境变量 | 以 JSON Body 请求 Token 端点 |
+
+`<NAME>` 为 CLI 名称的大写下划线形式（如 `my-api` → `MY_API`）。
+
+## OpenAPI 扩展
+
+在 OAS 文档中添加以下厂商扩展，可控制 CLI 生成行为：
+
+| 扩展字段 | 位置 | 效果 |
+|----------|------|------|
+| `x-cli-name: "my-name"` | operation | 覆盖自动生成的命令名 |
+| `x-cli-aliases: ["a"]` | operation | 为命令添加 Commander 别名 |
+| `x-cli-ignore: true` | operation | 从生成的 CLI 中排除该操作 |
+| `x-cli-token-url: "https://…"` | securityScheme | 自定义动态认证 Token 端点 |
+
+## 全局选项
+
+所有生成的 CLI 的每条命令均支持以下全局选项：
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `--endpoint <url>` | 覆盖 API 基础地址 | OAS 规范中的 server URL |
+| `--format <fmt>` | 输出格式：`json`、`yaml`、`table` | `json` |
+| `--verbose` | 打印每次请求的 HTTP 方法和 URL | `false` |
+| `--query <expr>` | JMESPath 表达式，过滤响应结果 | — |
+| `--all-pages` | 自动翻页（跟随 `Link: rel="next"` 响应头） | `false` |
+
+## 请求体
+
+`POST`、`PUT`、`PATCH` 命令使用 `--data` 传入请求体：
+
+```bash
+# 内联 JSON
+my-api widgets create --data '{"name": "foo", "color": "blue"}'
+
+# 从文件读取
+my-api widgets create --data @./payload.json
+```
+
+## 输出格式
+
+```bash
+# 默认：格式化 JSON
+my-api repos list
+
+# 表格视图（适合数组类型数据）
+my-api repos list --format table
+
+# YAML 格式
+my-api repos list --format yaml
+
+# JMESPath 过滤
+my-api repos list --query '[].name'
+
+# 配合 jq 过滤
+my-api repos list | jq '.[].full_name'
+
+# 保存到文件
+my-api repos list > repos.json
+```
+
+## 流式输出（SSE）
+
+响应内容类型为 `text/event-stream` 的操作会被自动识别。生成的 CLI 将每个 SSE 数据载荷输出到 stdout，每行一条：
+
+```bash
+my-api completions create --model gpt-4o --stream
+```
+
+生成的客户端使用 `eventsource-parser`，支持多行 `data:` 载荷、命名 `event:` 类型，并静默丢弃 OpenAI 兼容 API 常用的 `[DONE]` 哨兵。
+
+## 命令行选项
+
+```
+openapi2cli [options]
+
+选项：
+  --oas <path|url>   OpenAPI 3.x 规范的文件路径或 URL（必填）
+  --name <name>      CLI 可执行文件名称（必填）
+  --output <dir>     输出目录（必填）
+  --overwrite        覆盖已存在的输出目录
+  -h, --help         显示帮助信息
+```
+
+## 许可证
+
+MIT

package/bin/openapi2cli

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/index.js');

package/dist/analyzer/schema-analyzer.d.ts

@@ -0,0 +1,4 @@
+import { OpenAPIV3 } from 'openapi-types';
+import { CommandStructure } from '../types/index';
+export declare function analyzeSchema(api: OpenAPIV3.Document, cliName: string): CommandStructure;
+//# sourceMappingURL=schema-analyzer.d.ts.map

package/dist/analyzer/schema-analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-analyzer.d.ts","sourceRoot":"","sources":["../../src/analyzer/schema-analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAI1C,OAAO,EAGL,gBAAgB,EAQjB,MAAM,gBAAgB,CAAC;AAkBxB,wBAAgB,aAAa,CAAC,GAAG,EAAE,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAkBxF"}