specli 0.0.1

package/README.md

@@ -0,0 +1,474 @@
+# opencli
+
+OpenCLI turns an OpenAPI spec into a non-interactive, “curl replacement” CLI.
+
+It has two modes:
+
+- **exec**: run commands dynamically from a spec URL/path.
+- **compile**: bundle the spec into a standalone executable.
+
+The guiding constraints:
+
+- Bun-first (no Node runtime needed).
+- Suitable for automation/agents (stable commands, machine output via `--json`).
+- Best-effort validation of inputs against the OpenAPI schema.
+
+## Status / What Works Today
+
+It works well for a large chunk of “typical” OpenAPI 3.x REST specs:
+
+- Multiple servers + server variables.
+- Path/query/header/cookie parameters.
+- Request bodies via `--data` / `--file`.
+- JSON request body parsing + schema validation.
+- Expanded JSON body flags for simple object bodies (`--body-*`).
+- Auth injection for common schemes (bearer/basic/apiKey).
+- A deterministic `__schema` output for introspection.
+
+It is not “universal OpenAPI support” yet. See “Limitations” for important gaps.
+
+## Install
+
+```bash
+bun install
+```
+
+## Quickstart
+
+Inspect what commands will be generated:
+
+```bash
+bunx opencli exec ./fixtures/openapi.json __schema
+```
+
+Machine-readable schema output:
+
+```bash
+bunx opencli exec ./fixtures/openapi.json __schema --json
+```
+
+Minimal schema output (best for large specs):
+
+```bash
+bunx opencli exec ./fixtures/openapi.json __schema --json --min
+```
+
+Run a generated operation:
+
+```bash
+bunx opencli exec ./fixtures/openapi.json contacts list --oc-curl
+```
+
+## Build a Standalone Executable
+
+Use the `compile` command to create a standalone binary with the spec embedded:
+
+```bash
+# compile with auto-derived name (from spec title)
+bunx opencli compile ./path/to/openapi.yaml
+# → ./dist/my-api (derived from info.title)
+
+# compile with explicit name
+bunx opencli compile ./path/to/openapi.yaml --name myapi
+# → ./dist/myapi
+
+# cross-compile (example: linux x64)
+bunx opencli compile https://api.vercel.com/copper/_openapi.json --target bun-linux-x64 --outfile ./dist/copper-linux
+
+# disable runtime config loading for deterministic behavior
+bunx opencli compile ./path/to/openapi.yaml --no-dotenv --no-bunfig
+
+# bake in defaults (these become default flags; runtime flags override)
+bunx opencli compile https://api.vercel.com/copper/_openapi.json \
+  --name copper \
+  --server https://api.vercel.com \
+  --auth VercelOidc
+```
+
+The compiled binary is a root CLI - no `opencli` prefix needed:
+
+```bash
+./dist/copper contacts list
+./dist/copper users get abc123 --json
+```
+
+Notes:
+
+- The spec is embedded at compile-time using a Bun macro.
+- If `--name` is not provided, it is derived from the OpenAPI `info.title` or URL hostname.
+- Runtime flags (e.g., `--server`) override baked-in defaults.
+
+## CLI Shape
+
+OpenCLI generates commands of the form:
+
+```
+opencli <resource> <action> [...positionals] [options]
+```
+
+- `resource` comes from `tags[0]`, `operationId` prefix, or the first path segment (heuristics).
+- `action` is inferred from HTTP method + “has id in path”, or from `operationId` suffix.
+- Name collisions are disambiguated deterministically by suffixing the action name.
+
+Use `__schema` to see the planned mapping for your spec.
+
+## Global Options
+
+Available on the root command:
+
+- `--spec <urlOrPath>`: OpenAPI URL or file path (only needed for compiled binaries to override embedded spec)
+- `--server <url>`: override server/base URL
+- `--server-var <name=value>`: server URL template variable (repeatable)
+- `--profile <name>`: profile name (config under `~/.config/opencli`)
+
+Auth selection + credentials:
+
+- `--auth <scheme>`: pick an auth scheme by key
+- `--bearer-token <token>`: set `Authorization: Bearer <token>`
+- `--oauth-token <token>`: alias of `--bearer-token`
+- `--username <username>` / `--password <password>`: basic auth
+- `--api-key <key>`: value for apiKey auth
+
+Output mode:
+
+- `--json`: machine-readable output (never prints stack traces)
+
+## Per-Operation Common Options
+
+Every generated operation command includes:
+
+- `--header <header>` (repeatable): extra headers; accepts `Name: Value` or `Name=Value`
+- `--accept <type>`: override `Accept` header
+- `--timeout <ms>`: request timeout in milliseconds
+- `--dry-run`: print the request that would be sent (no network call)
+- `--curl`: print an equivalent `curl` command (no network call)
+
+For operations with `requestBody`, it also includes:
+
+- `--data <data>`: inline request body
+- `--file <path>`: read request body from a file
+- `--content-type <type>`: override `Content-Type` (defaults from OpenAPI)
+
+## Parameter Mapping
+
+### Path Parameters
+
+OpenAPI parameters where `in: path` become positional arguments.
+
+- Order is derived from the path template: `/users/{id}/keys/{key_id}` becomes `<id> <key-id>`.
+- Values are URL-encoded when applied to the path.
+
+### Query / Header / Cookie Parameters
+
+OpenAPI parameters where `in: query|header|cookie` become flags.
+
+Flag name rules:
+
+- `--${kebabCase(parameter.name)}`
+- Examples:
+  - `limit` -> `--limit`
+  - `X-Request-Id` -> `--x-request-id`
+
+Required flags:
+
+- If the spec says `required: true`, the CLI flag is marked required (Commander enforces this).
+
+Type coercion:
+
+- `string` -> string
+- `integer` -> `parseInt`
+- `number` -> `Number(...)`
+- `boolean` -> flag presence (no value)
+- `object` -> JSON object literal string, parsed via `JSON.parse`
+- `array` -> see below
+
+### Arrays (Improved UX)
+
+Array parameters are treated as repeatable flags and appended to the query string.
+
+All of these become `?tag=a&tag=b`:
+
+```bash
+opencli ... --tag a --tag b
+opencli ... --tag a,b
+opencli ... --tag '["a","b"]'
+```
+
+Implementation notes:
+
+- The query string is built with repeated keys (`URLSearchParams.append`).
+- Array item types are derived from `schema.items.type` when present (e.g. integer arrays validate and coerce correctly).
+
+## Request Bodies
+
+### Selecting the Body Input
+
+If an operation has a `requestBody`, you may provide a body via:
+
+- `--data <string>`
+- `--file <path>`
+- Expanded `--body-*` flags (JSON-only; see below)
+
+Rules:
+
+- `--data` and `--file` are mutually exclusive.
+- Expanded `--body-*` flags cannot be used with `--data` or `--file`.
+- If `requestBody.required` is true and you provide none of the above, the command fails with:
+  - `Missing request body. Provide --data, --file, or --body-* flags.`
+
+### Content-Type
+
+`Content-Type` is chosen as:
+
+1. `--content-type` (explicit override)
+2. The preferred content type derived from the OpenAPI requestBody (prefers `application/json` when present)
+
+### JSON Parsing + Normalization
+
+If the selected `Content-Type` includes `json`:
+
+- `--data`/`--file` content is parsed as either JSON or YAML
+- the request is sent as normalized JSON (`JSON.stringify(parsed)`)
+
+If `Content-Type` does not include `json`:
+
+- the body is treated as a raw string
+
+### Schema Validation (Ajv)
+
+OpenCLI uses Ajv (best-effort, `strict: false`) to validate:
+
+- query/header/cookie params
+- JSON request bodies when a requestBody schema is available
+
+Validation errors are formatted into a readable multiline message. For `required` errors, the message is normalized to:
+
+- `/<path> missing required property '<name>'`
+
+### Expanded JSON Body Flags (`--body-*`)
+
+When an operation has a `requestBody` and the preferred schema is a JSON object with scalar properties, OpenCLI generates convenience flags:
+
+- For `string|number|integer`: `--body-<prop> <value>`
+- For `boolean`: `--body-<prop>` (presence sets it to `true`)
+
+Example (from `fixtures/openapi-body.json`):
+
+```bash
+bunx opencli exec ./fixtures/openapi-body.json contacts create --body-name "Ada" --oc-curl
+```
+
+Produces a JSON body:
+
+```json
+{"name":"Ada"}
+```
+
+Notes / edge cases:
+
+- Expanded flags are only supported for JSON bodies. If you try to use them without a JSON content type, OpenCLI errors.
+- Required fields in the schema are checked in a “friendly” way for expanded flags:
+  - `Missing required body field 'name'. Provide --body-name or use --data/--file.`
+- Numeric coercion uses `Number(...)` / `parseInt(...)`. Today it does not explicitly reject `NaN` (this is an area to harden).
+
+## Servers
+
+OpenCLI resolves the request base URL in this order:
+
+1. `--server <url>`
+2. profile `server` (if `--profile` is set and the profile has a server)
+3. the first `servers[0].url` in the OpenAPI spec
+
+If the chosen server URL has template variables (e.g. `https://{region}.api.example.com`):
+
+- Provide `--server-var region=us-east-1` (repeatable)
+- If the spec defines a default for that variable, it is used automatically
+
+## Authentication
+
+### Supported Scheme Kinds
+
+From `components.securitySchemes`, OpenCLI recognizes:
+
+- HTTP bearer (`type: http`, `scheme: bearer`)
+- HTTP basic (`type: http`, `scheme: basic`)
+- API key (`type: apiKey`, `in: header|query|cookie`)
+- OAuth2 (`type: oauth2`) (treated as bearer token injection)
+- OpenID Connect (`type: openIdConnect`) (treated as bearer token injection)
+
+### Selecting an Auth Scheme
+
+Scheme selection happens in this order:
+
+1. `--auth <scheme>` (explicit)
+2. profile `authScheme` (only if that key exists in the current spec)
+3. if the operation requires exactly one scheme, it is chosen
+4. if the spec defines exactly one scheme total, it is chosen
+
+This “only if present in current spec” behavior prevents accidental auth leakage between different specs.
+
+### Providing Credentials
+
+Bearer-like schemes (`http-bearer`, `oauth2`, `openIdConnect`):
+
+- `--bearer-token <token>` or `--oauth-token <token>`
+- or a profile token stored via `opencli auth token ...`
+
+Basic auth:
+
+- `--username <username>` and `--password <password>`
+
+API key:
+
+- `--api-key <key>` (injected into the header/query/cookie location declared by the scheme)
+
+## Profiles (Non-Interactive)
+
+Profiles are for automation.
+
+Config file:
+
+- Read preference: `~/.config/opencli/profiles.json`, else `~/.config/opencli/profiles.yaml` if present
+- Writes always go to: `~/.config/opencli/profiles.json`
+
+Secrets:
+
+- Tokens are stored in Bun’s secrets store (`bun.secrets`) under a spec-scoped service name.
+
+Commands:
+
+```bash
+opencli profile list
+opencli profile set --name dev --server https://api.example.com --auth bearerAuth --default
+opencli profile use --name dev
+opencli profile rm --name dev
+
+opencli auth token --name dev --set "..."
+opencli auth token --name dev --get
+opencli auth token --name dev --delete
+```
+
+## Output Behavior
+
+### Default (Human + Agent Readable)
+
+- On success:
+  - if response `content-type` includes `json`, prints pretty JSON
+  - otherwise prints raw text
+- On non-2xx HTTP:
+  - prints `HTTP <status>` and response body
+  - exits with code 1
+- On CLI/validation errors:
+  - prints `error: <message>`
+  - exits with code 1
+
+### `--json` (Machine Readable)
+
+- On success:
+  - if response is JSON, prints the parsed JSON
+  - otherwise prints the raw string
+- With `--status` and/or `--headers`, wraps output:
+
+```json
+{ "status": 200, "headers": { "content-type": "..." }, "body": ... }
+```
+
+- On non-2xx HTTP:
+
+```json
+{ "status": 404, "body": ..., "headers": { ... } }
+```
+
+- On CLI/validation errors:
+
+```json
+{ "error": "..." }
+```
+
+### `--curl`
+
+Prints an equivalent curl invocation without sending the request.
+
+### `--dry-run`
+
+Prints the method, URL, headers, and body that would be sent without sending the request.
+
+## `__schema`
+
+`opencli __schema` reports:
+
+- OpenAPI title/version
+- spec source + computed spec id + fingerprint
+- servers/auth schemes counts
+- list of normalized operations
+- planned command mapping
+
+Flags:
+
+- `--json`: JSON output
+- `--pretty`: pretty JSON
+- `--min`: minimal schema payload (commands + metadata only)
+
+## Recommended Public Specs to Test
+
+A good “real world” smoke test matrix includes:
+
+1. Vercel API (OpenAPI 3.x)
+   - URL: `https://api.vercel.com/copper/_openapi.json`
+   - Focus: real-world parameter naming collisions (e.g. `accept`), large-ish spec
+
+2. GitHub REST API (OpenAPI 3.1, very large)
+   - URL (huge): `https://raw.githubusercontent.com/github/rest-api-description/main/descriptions-next/api.github.com/api.github.com.json`
+   - Focus: size, OAS 3.1, many endpoints, varied parameter shapes
+
+3. DigitalOcean API (OpenAPI 3.0)
+   - URL: `https://raw.githubusercontent.com/digitalocean/openapi/main/specification/DigitalOcean-public.v2.yaml`
+   - Focus: big spec + deref cycles, request bodies, auth schemes
+
+4. Stripe API (OpenAPI 3.x, very complex schemas)
+   - URL: `https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.yaml`
+   - Focus: very heavy schema usage (`anyOf`, large components)
+
+Smoke harness:
+
+- Run the built-in smoke script:
+
+```bash
+bun run smoke:specs
+```
+
+Or run ad-hoc smoke tests:
+
+```bash
+bunx opencli exec <URL> __schema --json --min > /dev/null
+bunx opencli exec <URL> <some-resource> <some-action> --oc-curl
+```
+
+Note: Kubernetes publishes a Swagger 2.0 document (`swagger.json`) which is not OpenAPI 3.x. OpenCLI currently expects `openapi: "3.x"` and will reject Swagger 2.0 specs.
+
+## Limitations (Important)
+
+OpenCLI is intentionally v1-simple; common gaps for real-world specs:
+
+- OpenAPI 3.x only (Swagger 2.0 not supported).
+- Parameter serialization is simplified:
+  - arrays are always encoded as repeated keys (`?tag=a&tag=b`)
+  - does not implement OpenAPI `style` / `explode` / deepObject / etc.
+- Array item types are not tracked yet (arrays treated as string arrays for coercion).
+- Request body convenience flags only support “simple object with scalar properties”.
+- Multipart, binary uploads, and file/form modeling are not implemented.
+- `Content-Type`/`Accept` negotiation is basic (string includes checks for `json`).
+- OAuth2 flows are not implemented (token acquisition is out of scope); oauth2 is treated as bearer token injection.
+
+## Development
+
+Scripts:
+
+- `bun run lint` (Biome CI)
+- `bun run typecheck` (tsgo)
+- `bun test`
+
+Repo entry points:
+
+- `cli.ts`: main CLI entry with `exec` and `compile` subcommands
+- `src/compiled.ts`: entry point for compiled binaries (embedded spec via Bun macro)

package/biome.jsonc

@@ -0,0 +1 @@
+{}

package/bun.lock

@@ -0,0 +1,98 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "opencli",
+      "dependencies": {
+        "@apidevtools/swagger-parser": "^12.1.0",
+        "ajv": "^8.17.1",
+        "ajv-formats": "^3.0.1",
+        "commander": "^14.0.2",
+        "openapi-types": "^12.1.3",
+      },
+      "devDependencies": {
+        "@biomejs/biome": "^2.3.11",
+        "@types/bun": "^1.3.6",
+        "@typescript/native-preview": "^7.0.0-dev.20260120.1",
+      },
+    },
+  },
+  "packages": {
+    "@apidevtools/json-schema-ref-parser": ["@apidevtools/json-schema-ref-parser@14.0.1", "", { "dependencies": { "@types/json-schema": "^7.0.15", "js-yaml": "^4.1.0" } }, "sha512-Oc96zvmxx1fqoSEdUmfmvvb59/KDOnUoJ7s2t7bISyAn0XEz57LCCw8k2Y4Pf3mwKaZLMciESALORLgfe2frCw=="],
+
+    "@apidevtools/openapi-schemas": ["@apidevtools/openapi-schemas@2.1.0", "", {}, "sha512-Zc1AlqrJlX3SlpupFGpiLi2EbteyP7fXmUOGup6/DnkRgjP9bgMM/ag+n91rsv0U1Gpz0H3VILA/o3bW7Ua6BQ=="],
+
+    "@apidevtools/swagger-methods": ["@apidevtools/swagger-methods@3.0.2", "", {}, "sha512-QAkD5kK2b1WfjDS/UQn/qQkbwF31uqRjPTrsCs5ZG9BQGAkjwvqGFjjPqAuzac/IYzpPtRzjCP1WrTuAIjMrXg=="],
+
+    "@apidevtools/swagger-parser": ["@apidevtools/swagger-parser@12.1.0", "", { "dependencies": { "@apidevtools/json-schema-ref-parser": "14.0.1", "@apidevtools/openapi-schemas": "^2.1.0", "@apidevtools/swagger-methods": "^3.0.2", "ajv": "^8.17.1", "ajv-draft-04": "^1.0.0", "call-me-maybe": "^1.0.2" }, "peerDependencies": { "openapi-types": ">=7" } }, "sha512-e5mJoswsnAX0jG+J09xHFYQXb/bUc5S3pLpMxUuRUA2H8T2kni3yEoyz2R3Dltw5f4A6j6rPNMpWTK+iVDFlng=="],
+
+    "@biomejs/biome": ["@biomejs/biome@2.3.11", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.3.11", "@biomejs/cli-darwin-x64": "2.3.11", "@biomejs/cli-linux-arm64": "2.3.11", "@biomejs/cli-linux-arm64-musl": "2.3.11", "@biomejs/cli-linux-x64": "2.3.11", "@biomejs/cli-linux-x64-musl": "2.3.11", "@biomejs/cli-win32-arm64": "2.3.11", "@biomejs/cli-win32-x64": "2.3.11" }, "bin": { "biome": "bin/biome" } }, "sha512-/zt+6qazBWguPG6+eWmiELqO+9jRsMZ/DBU3lfuU2ngtIQYzymocHhKiZRyrbra4aCOoyTg/BmY+6WH5mv9xmQ=="],
+
+    "@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.3.11", "", { "os": "darwin", "cpu": "arm64" }, "sha512-/uXXkBcPKVQY7rc9Ys2CrlirBJYbpESEDme7RKiBD6MmqR2w3j0+ZZXRIL2xiaNPsIMMNhP1YnA+jRRxoOAFrA=="],
+
+    "@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@2.3.11", "", { "os": "darwin", "cpu": "x64" }, "sha512-fh7nnvbweDPm2xEmFjfmq7zSUiox88plgdHF9OIW4i99WnXrAC3o2P3ag9judoUMv8FCSUnlwJCM1B64nO5Fbg=="],
+
+    "@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@2.3.11", "", { "os": "linux", "cpu": "arm64" }, "sha512-l4xkGa9E7Uc0/05qU2lMYfN1H+fzzkHgaJoy98wO+b/7Gl78srbCRRgwYSW+BTLixTBrM6Ede5NSBwt7rd/i6g=="],
+
+    "@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@2.3.11", "", { "os": "linux", "cpu": "arm64" }, "sha512-XPSQ+XIPZMLaZ6zveQdwNjbX+QdROEd1zPgMwD47zvHV+tCGB88VH+aynyGxAHdzL+Tm/+DtKST5SECs4iwCLg=="],
+
+    "@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@2.3.11", "", { "os": "linux", "cpu": "x64" }, "sha512-/1s9V/H3cSe0r0Mv/Z8JryF5x9ywRxywomqZVLHAoa/uN0eY7F8gEngWKNS5vbbN/BsfpCG5yeBT5ENh50Frxg=="],
+
+    "@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@2.3.11", "", { "os": "linux", "cpu": "x64" }, "sha512-vU7a8wLs5C9yJ4CB8a44r12aXYb8yYgBn+WeyzbMjaCMklzCv1oXr8x+VEyWodgJt9bDmhiaW/I0RHbn7rsNmw=="],
+
+    "@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@2.3.11", "", { "os": "win32", "cpu": "arm64" }, "sha512-PZQ6ElCOnkYapSsysiTy0+fYX+agXPlWugh6+eQ6uPKI3vKAqNp6TnMhoM3oY2NltSB89hz59o8xIfOdyhi9Iw=="],
+
+    "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.3.11", "", { "os": "win32", "cpu": "x64" }, "sha512-43VrG813EW+b5+YbDbz31uUsheX+qFKCpXeY9kfdAx+ww3naKxeVkTD9zLIWxUPfJquANMHrmW3wbe/037G0Qg=="],
+
+    "@types/bun": ["@types/bun@1.3.6", "", { "dependencies": { "bun-types": "1.3.6" } }, "sha512-uWCv6FO/8LcpREhenN1d1b6fcspAB+cefwD7uti8C8VffIv0Um08TKMn98FynpTiU38+y2dUO55T11NgDt8VAA=="],
+
+    "@types/json-schema": ["@types/json-schema@7.0.15", "", {}, "sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA=="],
+
+    "@types/node": ["@types/node@25.0.9", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-/rpCXHlCWeqClNBwUhDcusJxXYDjZTyE8v5oTO7WbL8eij2nKhUeU89/6xgjU7N4/Vh3He0BtyhJdQbDyhiXAw=="],
+
+    "@typescript/native-preview": ["@typescript/native-preview@7.0.0-dev.20260120.1", "", { "optionalDependencies": { "@typescript/native-preview-darwin-arm64": "7.0.0-dev.20260120.1", "@typescript/native-preview-darwin-x64": "7.0.0-dev.20260120.1", "@typescript/native-preview-linux-arm": "7.0.0-dev.20260120.1", "@typescript/native-preview-linux-arm64": "7.0.0-dev.20260120.1", "@typescript/native-preview-linux-x64": "7.0.0-dev.20260120.1", "@typescript/native-preview-win32-arm64": "7.0.0-dev.20260120.1", "@typescript/native-preview-win32-x64": "7.0.0-dev.20260120.1" }, "bin": { "tsgo": "bin/tsgo.js" } }, "sha512-nnEf37C9ue7OBRnF2zmV/OCBmV5Y7T/K4mCHa+nxgiXcF/1w8sA0cgdFl+gHQ0mysqUJ+Bu5btAMeWgpLyjrgg=="],
+
+    "@typescript/native-preview-darwin-arm64": ["@typescript/native-preview-darwin-arm64@7.0.0-dev.20260120.1", "", { "os": "darwin", "cpu": "arm64" }, "sha512-r3pWFuR2H7mn6ScwpH5jJljKQqKto0npVuJSk6pRwFwexpTyxOGmJTZJ1V0AWiisaNxU2+CNAqWFJSJYIE/QTg=="],
+
+    "@typescript/native-preview-darwin-x64": ["@typescript/native-preview-darwin-x64@7.0.0-dev.20260120.1", "", { "os": "darwin", "cpu": "x64" }, "sha512-cuC1+wLbUP+Ip2UT94G134fqRdp5w3b3dhcCO6/FQ4yXxvRNyv/WK+upHBUFDaeSOeHgDTyO9/QFYUWwC4If1A=="],
+
+    "@typescript/native-preview-linux-arm": ["@typescript/native-preview-linux-arm@7.0.0-dev.20260120.1", "", { "os": "linux", "cpu": "arm" }, "sha512-vN6OYVySol/kQZjJGmAzd6L30SyVlCgmCXS8WjUYtE5clN0YrzQHop16RK29fYZHMxpkOniVBtRPxUYQANZBlQ=="],
+
+    "@typescript/native-preview-linux-arm64": ["@typescript/native-preview-linux-arm64@7.0.0-dev.20260120.1", "", { "os": "linux", "cpu": "arm64" }, "sha512-zZGvEGY7wcHYefMZ87KNmvjN3NLIhsCMHEpHZiGCS3khKf+8z6ZsanrzCjOTodvL01VPyBzHxV1EtkSxAcLiQg=="],
+
+    "@typescript/native-preview-linux-x64": ["@typescript/native-preview-linux-x64@7.0.0-dev.20260120.1", "", { "os": "linux", "cpu": "x64" }, "sha512-JBfNhWd/asd5MDeS3VgRvE24pGKBkmvLub6tsux6ypr+Yhy+o0WaAEzVpmlRYZUqss2ai5tvOu4dzPBXzZAtFw=="],
+
+    "@typescript/native-preview-win32-arm64": ["@typescript/native-preview-win32-arm64@7.0.0-dev.20260120.1", "", { "os": "win32", "cpu": "arm64" }, "sha512-tTndRtYCq2xwgE0VkTi9ACNiJaV43+PqvBqCxk8ceYi3X36Ve+CCnwlZfZJ4k9NxZthtrAwF/kUmpC9iIYbq1w=="],
+
+    "@typescript/native-preview-win32-x64": ["@typescript/native-preview-win32-x64@7.0.0-dev.20260120.1", "", { "os": "win32", "cpu": "x64" }, "sha512-oZia7hFL6k9pVepfonuPI86Jmyz6WlJKR57tWCDwRNmpA7odxuTq1PbvcYgy1z4+wHF1nnKKJY0PMAiq6ac18w=="],
+
+    "ajv": ["ajv@8.17.1", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g=="],
+
+    "ajv-draft-04": ["ajv-draft-04@1.0.0", "", { "peerDependencies": { "ajv": "^8.5.0" }, "optionalPeers": ["ajv"] }, "sha512-mv00Te6nmYbRp5DCwclxtt7yV/joXJPGS7nM+97GdxvuttCOfgI3K4U25zboyeX0O+myI8ERluxQe5wljMmVIw=="],
+
+    "ajv-formats": ["ajv-formats@3.0.1", "", { "dependencies": { "ajv": "^8.0.0" } }, "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ=="],
+
+    "argparse": ["argparse@2.0.1", "", {}, "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q=="],
+
+    "bun-types": ["bun-types@1.3.6", "", { "dependencies": { "@types/node": "*" } }, "sha512-OlFwHcnNV99r//9v5IIOgQ9Uk37gZqrNMCcqEaExdkVq3Avwqok1bJFmvGMCkCE0FqzdY8VMOZpfpR3lwI+CsQ=="],
+
+    "call-me-maybe": ["call-me-maybe@1.0.2", "", {}, "sha512-HpX65o1Hnr9HH25ojC1YGs7HCQLq0GCOibSaWER0eNpgJ/Z1MZv2mTc7+xh6WOPxbRVcmgbv4hGU+uSQ/2xFZQ=="],
+
+    "commander": ["commander@14.0.2", "", {}, "sha512-TywoWNNRbhoD0BXs1P3ZEScW8W5iKrnbithIl0YH+uCmBd0QpPOA8yc82DS3BIE5Ma6FnBVUsJ7wVUDz4dvOWQ=="],
+
+    "fast-deep-equal": ["fast-deep-equal@3.1.3", "", {}, "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q=="],
+
+    "fast-uri": ["fast-uri@3.1.0", "", {}, "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA=="],
+
+    "js-yaml": ["js-yaml@4.1.1", "", { "dependencies": { "argparse": "^2.0.1" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA=="],
+
+    "json-schema-traverse": ["json-schema-traverse@1.0.0", "", {}, "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug=="],
+
+    "openapi-types": ["openapi-types@12.1.3", "", {}, "sha512-N4YtSYJqghVu4iek2ZUvcN/0aqH1kRDuNqzcycDxhOUpg7GdvLa2F3DgS6yBNhInhv2r/6I0Flkn7CqL8+nIcw=="],
+
+    "require-from-string": ["require-from-string@2.0.2", "", {}, "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw=="],
+
+    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+  }
+}

package/cli.ts

@@ -0,0 +1,74 @@
+#!/usr/bin/env bun
+
+import { Command } from "commander";
+
+function collect(value: string, previous: string[] = []): string[] {
+	return previous.concat([value]);
+}
+
+const program = new Command();
+
+program.name("opencli").description("Generate CLIs from OpenAPI specs");
+
+// ─────────────────────────────────────────────────────────────
+// exec command - runs spec dynamically
+// ─────────────────────────────────────────────────────────────
+program
+	.command("exec <spec>")
+	.description("Execute commands from an OpenAPI spec")
+	.option("--server <url>", "Override server/base URL")
+	.option(
+		"--server-var <name=value>",
+		"Server variable (repeatable)",
+		collect,
+		[],
+	)
+	.option("--auth <scheme>", "Select auth scheme")
+	.option("--bearer-token <token>", "Bearer token")
+	.option("--oauth-token <token>", "OAuth token")
+	.option("--username <username>", "Basic auth username")
+	.option("--password <password>", "Basic auth password")
+	.option("--api-key <key>", "API key value")
+	.option("--profile <name>", "Profile name")
+	.option("--json", "Machine-readable output")
+	.allowUnknownOption()
+	.allowExcessArguments()
+	.action(async (spec, options, command) => {
+		const { execCommand } = await import("./src/cli/exec.ts");
+		await execCommand(spec, options, command.args);
+	});
+
+// ─────────────────────────────────────────────────────────────
+// compile command - creates standalone binary
+// ─────────────────────────────────────────────────────────────
+program
+	.command("compile <spec>")
+	.description("Compile an OpenAPI spec into a standalone CLI binary")
+	.option("--name <name>", "Binary name (default: derived from spec)")
+	.option("--outfile <path>", "Output path (default: ./dist/<name>)")
+	.option("--target <target>", "Bun compile target (e.g. bun-linux-x64)")
+	.option("--minify", "Enable minification")
+	.option("--bytecode", "Enable bytecode compilation")
+	.option("--no-dotenv", "Disable .env autoload")
+	.option("--no-bunfig", "Disable bunfig.toml autoload")
+	.option(
+		"--exec-argv <arg>",
+		"Embedded process.execArgv (repeatable)",
+		collect,
+		[],
+	)
+	.option("--define <k=v>", "Build-time constant (repeatable)", collect, [])
+	.option("--server <url>", "Default server URL (baked in)")
+	.option(
+		"--server-var <k=v>",
+		"Default server variable (repeatable)",
+		collect,
+		[],
+	)
+	.option("--auth <scheme>", "Default auth scheme")
+	.action(async (spec, options) => {
+		const { compileCommand } = await import("./src/cli/compile.ts");
+		await compileCommand(spec, options);
+	});
+
+await program.parseAsync(process.argv);

package/fixtures/openapi-array-items.json

@@ -0,0 +1,22 @@
+{
+	"openapi": "3.0.3",
+	"info": { "title": "Array Items API", "version": "1.0.0" },
+	"servers": [{ "url": "https://api.example.com" }],
+	"paths": {
+		"/things": {
+			"get": {
+				"operationId": "Things.List",
+				"tags": ["Things"],
+				"parameters": [
+					{
+						"in": "query",
+						"name": "ids",
+						"required": false,
+						"schema": { "type": "array", "items": { "type": "integer" } }
+					}
+				],
+				"responses": { "200": { "description": "OK" } }
+			}
+		}
+	}
+}