@tronsfey/openapi2cli 1.0.10 → 1.0.12

package/README.md

@@ -2,36 +2,107 @@ 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.
+Two modes in one tool:
+
+1. **Generate** — scaffold a fully typed Commander.js CLI project from an OpenAPI 3.x spec
+2. **Run** — proxy an OpenAPI spec directly from the command line, no code generation needed
+
+## Architecture
+
+```mermaid
+flowchart TD
+    CLI["CLI Entry · src/index.ts"]
+
+    CLI -->|"generate"| GEN["generate action"]
+    CLI -->|"run"| RUN["run action"]
+    CLI -->|"completion"| CMP["completer.ts\nbash / zsh / fish"]
+    CLI -->|"__completions"| HID["hidden: dynamic\ngroup & op listing"]
+
+    GEN --> PARSE["parseOASWithCache()\nsrc/cache.ts"]
+    GEN --> ANA["analyzeSchema()\nanalyzer/schema-analyzer.ts"]
+    GEN --> GENP["generateProject()\ngenerator/command-generator.ts"]
+    GENP --> TMPL["renderTemplate()\ngenerator/template-engine.ts\n+ Handlebars *.hbs"]
+
+    RUN --> CACHE["parseOASWithCache()\nsrc/cache.ts"]
+    RUN --> ANA2["analyzeSchema()"]
+    RUN --> PR["proxyRun()\nrunner/proxy-runner.ts"]
+
+    PR -->|"no op"| LIST["listOperations()"]
+    PR -->|"with op"| BOP["buildOperationsProgram()"]
+    BOP --> REG["registerOperation()"]
+    REG --> EXE["executeOperation()"]
+    EXE --> HC["createRuntimeClient()\nrunner/http-client.ts"]
+    HC -->|"REST"| AX["axios\n+ timeout + retry\n+ keep-alive"]
+    HC -->|"SSE"| SSE["fetch()\n+ AbortController"]
+    EXE --> FMT["formatOutput()\nrunner/output.ts"]
+    FMT --> OUT["JSON / YAML / Table\n+ JMESPath filter"]
+
+    CACHE --> DISK["~/.cache/openapi2cli/\nSHA-256 keyed, 1 h TTL"]
+    CACHE --> PARSE2["parseOAS()\nparser/oas-parser.ts"]
+    PARSE2 --> SP["swagger-parser\n$ref resolution + validation"]
+
+    ANA --> AUTH["extractAuthConfig()\nauth/auth-provider.ts"]
+    HID --> CACHE
+    HID --> ANA2
+```
 
 ## 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
+- **5 auth schemes** auto-detected from OAS security definitions (generate mode) or via CLI flags (run mode)
+- **SSE streaming** via `eventsource-parser` — 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
+npm install -g @tronsfey/openapi2cli
 ```
 
 ## Usage
 
+### Run mode (proxy — no code generation)
+
+Call any OpenAPI endpoint directly. Auth is passed as CLI flags:
+
+```bash
+# List available operations
+openapi2cli run --oas ./openapi.yaml
+
+# Bearer token
+openapi2cli run --oas ./openapi.yaml --bearer ghp_xxx repos get-repo --owner octocat --repo Hello-World
+
+# API key
+openapi2cli run --oas ./openapi.yaml --api-key sk-xxx --api-key-header X-Api-Key pets list-pets
+
+# HTTP Basic
+openapi2cli run --oas ./openapi.yaml --basic user:pass users get-user --username alice
+
+# Extra headers
+openapi2cli run --oas ./openapi.yaml --header "X-Request-Id: abc123" --header "X-Tenant: acme" ...
+
+# Override base URL
+openapi2cli run --oas ./openapi.yaml --endpoint https://staging.example.com --bearer xxx ...
+
+# Output options (per operation)
+openapi2cli run --oas ./openapi.yaml repos list-repo-issues --owner octocat --repo Hello-World \
+  --format table --query '[].title' --all-pages
+```
+
+### Generate mode (scaffold a typed CLI project)
+
 ```bash
 # From a local file
-openapi2cli --oas ./openapi.yaml --name my-api --output ./my-api-cli
+openapi2cli generate --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
+openapi2cli generate --oas https://petstore3.swagger.io/api/v3/openapi.json --name petstore --output ./petstore-cli
 ```
 
 Build and link the generated project:
@@ -155,19 +226,93 @@ 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
+## Shell Completion
+
+Enable tab-completion in your shell by sourcing the generated script once:
+
+```bash
+# Bash — add to ~/.bashrc
+eval "$(openapi2cli completion bash)"
+
+# Zsh — add to ~/.zshrc
+eval "$(openapi2cli completion zsh)"
 
+# Fish
+openapi2cli completion fish > ~/.config/fish/completions/openapi2cli.fish
 ```
-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
+Completion covers:
+- Top-level commands (`generate`, `run`, `completion`)
+- All flags for `generate` and `run`
+- **Dynamic operation names** — after `run --oas <spec>` the completion script
+  calls `openapi2cli __completions` to look up group and operation names from
+  the spec at completion time
+
+## CLI Reference
+
+```
+openapi2cli generate [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
+  --no-cache             Bypass spec cache (always re-fetch remote specs)
+  --cache-ttl <seconds>  Cache TTL in seconds (default: 3600)
+  -h, --help             Display help
+
+openapi2cli run [options] [group] [operation] [operation-options]
+
+  --oas <path|url>           OpenAPI 3.x spec (required)
+  --bearer <token>           Authorization: Bearer <token>
+  --api-key <key>            API key value
+  --api-key-header <header>  Header name for the API key (default: X-Api-Key)
+  --basic <user:pass>        HTTP Basic credentials
+  --header <Name: Value>     Extra header, repeatable
+  --endpoint <url>           Override base URL from the spec
+  --timeout <ms>             Request timeout in milliseconds (default: 30000)
+  --retries <n>              Max retry attempts for 5xx/network errors (default: 3)
+  --no-cache                 Bypass spec cache (always re-fetch remote specs)
+  --cache-ttl <seconds>      Cache TTL in seconds (default: 3600)
+  -h, --help                 Display help
+
+  Per-operation output flags (after the operation name):
+  --format json|yaml|table   Output format (default: json)
+  --query <jmespath>         Filter response with a JMESPath expression
+  --all-pages                Auto-paginate via Link rel="next" headers
+  --verbose                  Print HTTP method + URL to stderr
+```
+
+### Spec Caching
+
+Remote OAS specs are cached in `~/.cache/openapi2cli/` with a 1-hour TTL by default,
+making repeated `run` invocations near-instant after the first load.
+
+```bash
+# Force a fresh fetch (bypass cache)
+openapi2cli run --oas https://api.example.com/openapi.json --no-cache ...
+
+# Extend cache TTL to 24 hours
+openapi2cli run --oas https://api.example.com/openapi.json --cache-ttl 86400 ...
+```
+
+### Stability Flags
+
+```bash
+# Set a 60-second timeout for slow APIs
+openapi2cli run --oas ./spec.yaml --timeout 60000 items list-items
+
+# Disable retries (fail immediately on errors)
+openapi2cli run --oas ./spec.yaml --retries 0 items list-items
+
+# Aggressive retry for flaky staging environments
+openapi2cli run --oas ./spec.yaml --retries 5 items list-items
 ```
 
+Retries use exponential backoff (500 ms → 1 s → 2 s) and only apply to retryable
+errors: network failures (`ECONNREFUSED`, `ETIMEDOUT`, `ECONNRESET`) and HTTP 429, 500,
+502, 503, 504. Non-retryable 4xx errors (401, 403, 404, 422 …) fail immediately.
+
 ## License
 
 MIT

package/README.zh.md

@@ -2,36 +2,107 @@
 
 # openapi2cli
 
-一条命令，将 OpenAPI 3.x 规范生成为完整的 [Commander.js](https://github.com/tj/commander.js) TypeScript CLI 项目。
+两种模式，一个工具：
+
+1. **generate（生成）** — 将 OpenAPI 3.x 规范脚手架为完整的 TypeScript CLI 项目
+2. **run（直接代理）** — 无需生成代码，直接在命令行调用 OpenAPI 接口
+
+## 架构图
+
+```mermaid
+flowchart TD
+    CLI["CLI 入口 · src/index.ts"]
+
+    CLI -->|"generate"| GEN["generate 动作"]
+    CLI -->|"run"| RUN["run 动作"]
+    CLI -->|"completion"| CMP["completer.ts\nbash / zsh / fish"]
+    CLI -->|"__completions"| HID["隐藏命令：动态\n获取命令组和操作名"]
+
+    GEN --> PARSE["parseOASWithCache()\nsrc/cache.ts"]
+    GEN --> ANA["analyzeSchema()\nanalyzer/schema-analyzer.ts"]
+    GEN --> GENP["generateProject()\ngenerator/command-generator.ts"]
+    GENP --> TMPL["renderTemplate()\ngenerator/template-engine.ts\n+ Handlebars *.hbs"]
+
+    RUN --> CACHE["parseOASWithCache()\nsrc/cache.ts"]
+    RUN --> ANA2["analyzeSchema()"]
+    RUN --> PR["proxyRun()\nrunner/proxy-runner.ts"]
+
+    PR -->|"无操作名"| LIST["listOperations()"]
+    PR -->|"有操作名"| BOP["buildOperationsProgram()"]
+    BOP --> REG["registerOperation()"]
+    REG --> EXE["executeOperation()"]
+    EXE --> HC["createRuntimeClient()\nrunner/http-client.ts"]
+    HC -->|"REST"| AX["axios\n+ 超时 + 重试\n+ keep-alive"]
+    HC -->|"SSE"| SSE["fetch()\n+ AbortController"]
+    EXE --> FMT["formatOutput()\nrunner/output.ts"]
+    FMT --> OUT["JSON / YAML / 表格\n+ JMESPath 过滤"]
+
+    CACHE --> DISK["~/.cache/openapi2cli/\nSHA-256 键，1 小时 TTL"]
+    CACHE --> PARSE2["parseOAS()\nparser/oas-parser.ts"]
+    PARSE2 --> SP["swagger-parser\n$ref 解析 + 校验"]
+
+    ANA --> AUTH["extractAuthConfig()\nauth/auth-provider.ts"]
+    HID --> CACHE
+    HID --> ANA2
+```
 
 ## 功能特性
 
 - 支持从**文件路径或 URL** 解析 OAS 3.x 规范（完整 `$ref` 解析）
 - 按 **tag** 分组操作，生成 Commander 子命令组；未分组的操作注册为顶层命令
 - 生成带完整类型标注的 **TypeScript 源码**，支持必填/可选参数、枚举 `.choices()` 校验
-- **5 种认证方案**自动从 OAS 安全定义中检测：Bearer、API Key、HTTP Basic、OAuth2 Client Credentials、自定义动态 Token
-- **SSE 流式输出**基于 `eventsource-parser`，支持自动重连和 `[DONE]` 哨兵处理
+- **5 种认证方案**：生成模式从 OAS 安全定义自动检测；run 模式通过命令行参数传入
+- **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`
+- 自动生成**双语文档**：`README.md`（英文）+ `README.zh.md`（中文）+ `SKILL.md`
 
 ## 安装
 
 ```bash
-npm install -g openapi2cli
+npm install -g @tronsfey/openapi2cli
 ```
 
 ## 使用方法
 
+### run 模式（直接代理，无需生成代码）
+
+授权信息通过命令行参数传入：
+
+```bash
+# 列出所有可用操作
+openapi2cli run --oas ./openapi.yaml
+
+# Bearer Token
+openapi2cli run --oas ./openapi.yaml --bearer ghp_xxx repos get-repo --owner octocat --repo Hello-World
+
+# API Key
+openapi2cli run --oas ./openapi.yaml --api-key sk-xxx --api-key-header X-Api-Key pets list-pets
+
+# HTTP Basic
+openapi2cli run --oas ./openapi.yaml --basic user:pass users get-user --username alice
+
+# 自定义请求头（可多次指定）
+openapi2cli run --oas ./openapi.yaml --header "X-Request-Id: abc123" --header "X-Tenant: acme" ...
+
+# 覆盖 Base URL
+openapi2cli run --oas ./openapi.yaml --endpoint https://staging.example.com --bearer xxx ...
+
+# 输出选项（在操作名称之后指定）
+openapi2cli run --oas ./openapi.yaml repos list-repo-issues --owner octocat --repo Hello-World \
+  --format table --query '[].title' --all-pages
+```
+
+### generate 模式（生成完整 CLI 项目）
+
 ```bash
 # 从本地文件生成
-openapi2cli --oas ./openapi.yaml --name my-api --output ./my-api-cli
+openapi2cli generate --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
+openapi2cli generate --oas https://petstore3.swagger.io/api/v3/openapi.json --name petstore --output ./petstore-cli
 ```
 
 构建并链接生成的项目：
@@ -155,19 +226,89 @@ my-api completions create --model gpt-4o --stream
 
 生成的客户端使用 `eventsource-parser`，支持多行 `data:` 载荷、命名 `event:` 类型，并静默丢弃 OpenAI 兼容 API 常用的 `[DONE]` 哨兵。
 
-## 命令行选项
+## Shell 自动补全
+
+在 shell 中一次性 source 生成的补全脚本，即可启用 Tab 补全：
+
+```bash
+# Bash — 添加到 ~/.bashrc
+eval "$(openapi2cli completion bash)"
+
+# Zsh — 添加到 ~/.zshrc
+eval "$(openapi2cli completion zsh)"
+
+# Fish
+openapi2cli completion fish > ~/.config/fish/completions/openapi2cli.fish
+```
+
+支持补全：
+- 顶层命令（`generate`、`run`、`completion`）
+- `generate` 和 `run` 的所有参数
+- **动态操作名称** — 在 `run --oas <spec>` 之后，补全脚本会调用
+  `openapi2cli __completions` 从规范中实时查找命令组和操作名称
+
+## 命令行参考
+
+```
+openapi2cli generate [options]
+
+  --oas <path|url>       OpenAPI 3.x 规范的文件路径或 URL（必填）
+  --name <name>          CLI 可执行文件名称（必填）
+  --output <dir>         输出目录（必填）
+  --overwrite            覆盖已存在的输出目录
+  --no-cache             跳过规范缓存（始终重新拉取远端规范）
+  --cache-ttl <seconds>  缓存 TTL（秒），默认 3600
+  -h, --help             显示帮助信息
+
+openapi2cli run [options] [group] [operation] [operation-options]
+
+  --oas <path|url>           OpenAPI 3.x 规范（必填）
+  --bearer <token>           Authorization: Bearer <token>
+  --api-key <key>            API Key 值
+  --api-key-header <header>  API Key 的请求头名称（默认：X-Api-Key）
+  --basic <user:pass>        HTTP Basic 凭证
+  --header <Name: Value>     自定义请求头，可多次指定
+  --endpoint <url>           覆盖规范中的 Base URL
+  --timeout <ms>             请求超时（毫秒），默认 30000
+  --retries <n>              5xx/网络错误的最大重试次数，默认 3
+  --no-cache                 跳过规范缓存（始终重新拉取远端规范）
+  --cache-ttl <seconds>      缓存 TTL（秒），默认 3600
+  -h, --help                 显示帮助信息
+
+  操作级输出选项（在操作名称之后指定）：
+  --format json|yaml|table   输出格式（默认：json）
+  --query <jmespath>         JMESPath 表达式，过滤响应
+  --all-pages                自动翻页（跟随 Link rel="next" 响应头）
+  --verbose                  向 stderr 打印 HTTP 方法和 URL
+```
+
+### 规范缓存
+
+远端 OAS 规范默认缓存到 `~/.cache/openapi2cli/`，TTL 1 小时。
+首次加载后，后续调用几乎无延迟。
+
+```bash
+# 强制重新拉取（跳过缓存）
+openapi2cli run --oas https://api.example.com/openapi.json --no-cache ...
 
+# 延长缓存到 24 小时
+openapi2cli run --oas https://api.example.com/openapi.json --cache-ttl 86400 ...
 ```
-openapi2cli [options]
 
-选项：
-  --oas <path|url>   OpenAPI 3.x 规范的文件路径或 URL（必填）
-  --name <name>      CLI 可执行文件名称（必填）
-  --output <dir>     输出目录（必填）
-  --overwrite        覆盖已存在的输出目录
-  -h, --help         显示帮助信息
+### 稳定性选项
+
+```bash
+# 为慢速 API 设置 60 秒超时
+openapi2cli run --oas ./spec.yaml --timeout 60000 items list-items
+
+# 禁用重试（出错立即失败）
+openapi2cli run --oas ./spec.yaml --retries 0 items list-items
 ```
 
+重试使用指数退避（500 ms → 1 s → 2 s），仅对可重试错误生效：
+网络故障（`ECONNREFUSED`、`ETIMEDOUT`、`ECONNRESET`）及 HTTP 429、500、502、503、504。
+非可重试的 4xx 错误（401、403、404、422 等）立即失败。
+
 ## 许可证
 
 MIT

package/dist/cache.d.ts

@@ -0,0 +1,23 @@
+/**
+ * OAS Spec Caching — src/cache.ts
+ *
+ * Wraps parseOAS() with a disk-based cache in ~/.cache/openapi2cli/.
+ * Only remote URLs are cached (local files are cheap to read directly).
+ * Cache keys are SHA-256 hashes of the input URL.
+ * TTL: configurable, default 3600 seconds (1 hour).
+ */
+import { OpenAPIV3 } from 'openapi-types';
+/**
+ * Parse an OpenAPI spec with optional disk caching.
+ *
+ * - Local file paths:  always calls parseOAS() directly (never cached).
+ * - Remote URLs:       checks ~/.cache/openapi2cli/<sha256>.json first;
+ *                      re-fetches if the file is older than ttlMs or noCache is true.
+ */
+export declare function parseOASWithCache(input: string, opts?: {
+    noCache?: boolean;
+    ttlMs?: number;
+}): Promise<OpenAPIV3.Document>;
+/** Remove all cached specs (useful for `--no-cache` debug workflows). */
+export declare function clearCache(): Promise<void>;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAc1C;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,MAAM,EACb,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/C,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,CA4B7B;AAED,yEAAyE;AACzE,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAEhD"}

package/dist/cache.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * OAS Spec Caching — src/cache.ts
+ *
+ * Wraps parseOAS() with a disk-based cache in ~/.cache/openapi2cli/.
+ * Only remote URLs are cached (local files are cheap to read directly).
+ * Cache keys are SHA-256 hashes of the input URL.
+ * TTL: configurable, default 3600 seconds (1 hour).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseOASWithCache = parseOASWithCache;
+exports.clearCache = clearCache;
+const crypto = __importStar(require("crypto"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const fse = __importStar(require("fs-extra"));
+const oas_parser_1 = require("./parser/oas-parser");
+const CACHE_DIR = path.join(os.homedir(), '.cache', 'openapi2cli');
+const DEFAULT_TTL_MS = 3600000; // 1 hour
+function cacheKey(input) {
+    return crypto.createHash('sha256').update(input).digest('hex');
+}
+function cacheFile(input) {
+    return path.join(CACHE_DIR, `${cacheKey(input)}.json`);
+}
+/**
+ * Parse an OpenAPI spec with optional disk caching.
+ *
+ * - Local file paths:  always calls parseOAS() directly (never cached).
+ * - Remote URLs:       checks ~/.cache/openapi2cli/<sha256>.json first;
+ *                      re-fetches if the file is older than ttlMs or noCache is true.
+ */
+async function parseOASWithCache(input, opts = {}) {
+    const isUrl = /^https?:\/\//.test(input);
+    // Local files: skip cache entirely
+    if (!isUrl)
+        return (0, oas_parser_1.parseOAS)(input);
+    const ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
+    const file = cacheFile(input);
+    if (!opts.noCache) {
+        try {
+            const stat = await fse.stat(file);
+            if (Date.now() - stat.mtimeMs < ttl) {
+                return (await fse.readJSON(file));
+            }
+        }
+        catch {
+            // File does not exist or is unreadable — proceed to fetch
+        }
+    }
+    const doc = await (0, oas_parser_1.parseOAS)(input);
+    try {
+        await fse.ensureDir(CACHE_DIR);
+        await fse.writeJSON(file, doc);
+    }
+    catch {
+        // Cache write failure is non-fatal — proceed with the parsed doc
+    }
+    return doc;
+}
+/** Remove all cached specs (useful for `--no-cache` debug workflows). */
+async function clearCache() {
+    await fse.emptyDir(CACHE_DIR);
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BH,8CA+BC;AAGD,gCAEC;AA7DD,+CAAiC;AACjC,uCAAyB;AACzB,2CAA6B;AAC7B,8CAAgC;AAEhC,oDAA+C;AAE/C,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC;AACnE,MAAM,cAAc,GAAG,OAAS,CAAC,CAAC,SAAS;AAE3C,SAAS,QAAQ,CAAC,KAAa;IAC7B,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACjE,CAAC;AAED,SAAS,SAAS,CAAC,KAAa;IAC9B,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,iBAAiB,CACrC,KAAa,EACb,OAA8C,EAAE;IAEhD,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAEzC,mCAAmC;IACnC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAA,qBAAQ,EAAC,KAAK,CAAC,CAAC;IAEnC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,IAAI,cAAc,CAAC;IACzC,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;IAE9B,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QAClB,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClC,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,OAAO,GAAG,GAAG,EAAE,CAAC;gBACpC,OAAO,CAAC,MAAM,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAuB,CAAC;YAC1D,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,0DAA0D;QAC5D,CAAC;IACH,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,IAAA,qBAAQ,EAAC,KAAK,CAAC,CAAC;IAClC,IAAI,CAAC;QACH,MAAM,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QAC/B,MAAM,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,iEAAiE;IACnE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,yEAAyE;AAClE,KAAK,UAAU,UAAU;IAC9B,MAAM,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;AAChC,CAAC"}

package/dist/completer.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shell completion script generators for openapi2cli.
+ *
+ * Each function returns a string that can be sourced by the user's shell.
+ * Dynamic operation completion (after `run --oas <spec>`) is handled by
+ * calling back into the hidden `__completions` subcommand.
+ */
+export declare function generateBashCompletion(): string;
+export declare function generateZshCompletion(): string;
+export declare function generateFishCompletion(): string;
+//# sourceMappingURL=completer.d.ts.map

package/dist/completer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completer.d.ts","sourceRoot":"","sources":["../src/completer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,wBAAgB,sBAAsB,IAAI,MAAM,CAyE/C;AAID,wBAAgB,qBAAqB,IAAI,MAAM,CAyF9C;AAID,wBAAgB,sBAAsB,IAAI,MAAM,CAsC/C"}