specli 0.0.1 → 0.0.3

package/README.md

@@ -1,6 +1,6 @@
-# opencli
+# specli
 
-OpenCLI turns an OpenAPI spec into a non-interactive, “curl replacement” CLI.
+specli turns an OpenAPI spec into a non-interactive, “curl replacement” CLI.
 
 It has two modes:
 
@@ -21,7 +21,7 @@ It works well for a large chunk of “typical” OpenAPI 3.x REST specs:
 - 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-*`).
+- Body field flags matching OpenAPI schema properties (including nested objects with dot notation).
 - Auth injection for common schemes (bearer/basic/apiKey).
 - A deterministic `__schema` output for introspection.
 
@@ -38,25 +38,25 @@ bun install
 Inspect what commands will be generated:
 
 ```bash
-bunx opencli exec ./fixtures/openapi.json __schema
+bunx specli exec ./fixtures/openapi.json __schema
 ```
 
 Machine-readable schema output:
 
 ```bash
-bunx opencli exec ./fixtures/openapi.json __schema --json
+bunx specli exec ./fixtures/openapi.json __schema --json
 ```
 
 Minimal schema output (best for large specs):
 
 ```bash
-bunx opencli exec ./fixtures/openapi.json __schema --json --min
+bunx specli exec ./fixtures/openapi.json __schema --json --min
 ```
 
 Run a generated operation:
 
 ```bash
-bunx opencli exec ./fixtures/openapi.json contacts list --oc-curl
+bunx specli exec ./fixtures/openapi.json contacts list --curl
 ```
 
 ## Build a Standalone Executable
@@ -65,27 +65,27 @@ 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
+bunx specli 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
+bunx specli 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
+bunx specli 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
+bunx specli 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 \
+bunx specli 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:
+The compiled binary is a root CLI - no `specli` prefix needed:
 
 ```bash
 ./dist/copper contacts list
@@ -100,10 +100,10 @@ Notes:
 
 ## CLI Shape
 
-OpenCLI generates commands of the form:
+specli generates commands of the form:
 
 ```
-opencli <resource> <action> [...positionals] [options]
+specli <resource> <action> [...positionals] [options]
 ```
 
 - `resource` comes from `tags[0]`, `operationId` prefix, or the first path segment (heuristics).
@@ -119,7 +119,7 @@ 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`)
+- `--profile <name>`: profile name (config under `~/.config/specli`)
 
 Auth selection + credentials:
 
@@ -189,9 +189,9 @@ Array parameters are treated as repeatable flags and appended to the query strin
 All of these become `?tag=a&tag=b`:
 
 ```bash
-opencli ... --tag a --tag b
-opencli ... --tag a,b
-opencli ... --tag '["a","b"]'
+specli ... --tag a --tag b
+specli ... --tag a,b
+specli ... --tag '["a","b"]'
 ```
 
 Implementation notes:
@@ -201,79 +201,69 @@ Implementation notes:
 
 ## Request Bodies
 
-### Selecting the Body Input
+### Body Field Flags
 
-If an operation has a `requestBody`, you may provide a body via:
+When an operation has a `requestBody` and the preferred schema is a JSON object, specli generates convenience flags that match the property names:
 
-- `--data <string>`
-- `--file <path>`
-- Expanded `--body-*` flags (JSON-only; see below)
+- For `string|number|integer`: `--<prop> <value>`
+- For `boolean`: `--<prop>` (presence sets it to `true`)
+- For nested objects: `--<parent>.<child> <value>` (dot notation)
 
-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:
+Example (from `fixtures/openapi-body.json`):
 
-- query/header/cookie params
-- JSON request bodies when a requestBody schema is available
+```bash
+bunx specli exec ./fixtures/openapi-body.json contacts create --name "Ada" --curl
+```
 
-Validation errors are formatted into a readable multiline message. For `required` errors, the message is normalized to:
+Produces a JSON body:
 
-- `/<path> missing required property '<name>'`
+```json
+{"name":"Ada"}
+```
 
-### Expanded JSON Body Flags (`--body-*`)
+#### Nested Objects
 
-When an operation has a `requestBody` and the preferred schema is a JSON object with scalar properties, OpenCLI generates convenience flags:
+Nested object properties use dot notation. For a schema like:
 
-- For `string|number|integer`: `--body-<prop> <value>`
-- For `boolean`: `--body-<prop>` (presence sets it to `true`)
+```json
+{
+  "type": "object",
+  "properties": {
+    "name": { "type": "string" },
+    "address": {
+      "type": "object",
+      "properties": {
+        "street": { "type": "string" },
+        "city": { "type": "string" }
+      }
+    }
+  }
+}
+```
 
-Example (from `fixtures/openapi-body.json`):
+You can use:
 
 ```bash
-bunx opencli exec ./fixtures/openapi-body.json contacts create --body-name "Ada" --oc-curl
+mycli contacts create --name "Ada" --address.street "123 Main St" --address.city "NYC"
 ```
 
-Produces a JSON body:
+Which produces:
 
 ```json
-{"name":"Ada"}
+{"name":"Ada","address":{"street":"123 Main St","city":"NYC"}}
 ```
 
 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).
+- Body field flags are only supported for JSON bodies.
+- Required fields in the schema are checked with friendly error messages:
+  - `Missing required body field 'name'. Provide --name.`
+- If a body field flag would conflict with an operation parameter flag or `--curl`, the operation parameter takes precedence.
+- Numeric coercion uses `Number(...)` / `parseInt(...)`.
 
 ## Servers
 
-OpenCLI resolves the request base URL in this order:
+specli resolves the request base URL in this order:
 
 1. `--server <url>`
 2. profile `server` (if `--profile` is set and the profile has a server)
@@ -288,7 +278,7 @@ If the chosen server URL has template variables (e.g. `https://{region}.api.exam
 
 ### Supported Scheme Kinds
 
-From `components.securitySchemes`, OpenCLI recognizes:
+From `components.securitySchemes`, specli recognizes:
 
 - HTTP bearer (`type: http`, `scheme: bearer`)
 - HTTP basic (`type: http`, `scheme: basic`)
@@ -312,7 +302,7 @@ This “only if present in current spec” behavior prevents accidental auth lea
 Bearer-like schemes (`http-bearer`, `oauth2`, `openIdConnect`):
 
 - `--bearer-token <token>` or `--oauth-token <token>`
-- or a profile token stored via `opencli auth token ...`
+- or a profile token stored via `specli auth token ...`
 
 Basic auth:
 
@@ -328,8 +318,8 @@ 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`
+- Read preference: `~/.config/specli/profiles.json`, else `~/.config/specli/profiles.yaml` if present
+- Writes always go to: `~/.config/specli/profiles.json`
 
 Secrets:
 
@@ -338,14 +328,14 @@ Secrets:
 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
+specli profile list
+specli profile set --name dev --server https://api.example.com --auth bearerAuth --default
+specli profile use --name dev
+specli profile rm --name dev
+
+specli auth token --name dev --set "..."
+specli auth token --name dev --get
+specli auth token --name dev --delete
 ```
 
 ## Output Behavior
@@ -395,7 +385,7 @@ Prints the method, URL, headers, and body that would be sent without sending the
 
 ## `__schema`
 
-`opencli __schema` reports:
+`specli __schema` reports:
 
 - OpenAPI title/version
 - spec source + computed spec id + fingerprint
@@ -440,15 +430,15 @@ 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
+bunx specli exec <URL> __schema --json --min > /dev/null
+bunx specli exec <URL> <some-resource> <some-action> --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.
+Note: Kubernetes publishes a Swagger 2.0 document (`swagger.json`) which is not OpenAPI 3.x. specli 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:
+specli is intentionally v1-simple; common gaps for real-world specs:
 
 - OpenAPI 3.x only (Swagger 2.0 not supported).
 - Parameter serialization is simplified:

package/cli.ts

@@ -8,7 +8,7 @@ function collect(value: string, previous: string[] = []): string[] {
 
 const program = new Command();
 
-program.name("opencli").description("Generate CLIs from OpenAPI specs");
+program.name("specli").description("Generate CLIs from OpenAPI specs");
 
 // ─────────────────────────────────────────────────────────────
 // exec command - runs spec dynamically
@@ -51,21 +51,15 @@ program
 	.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 <url>", "Default server URL (embedded)")
 	.option(
 		"--server-var <k=v>",
-		"Default server variable (repeatable)",
+		"Default server variable (repeatable, embedded)",
 		collect,
 		[],
 	)
-	.option("--auth <scheme>", "Default auth scheme")
+	.option("--auth <scheme>", "Default auth scheme (embedded)")
 	.action(async (spec, options) => {
 		const { compileCommand } = await import("./src/cli/compile.ts");
 		await compileCommand(spec, options);

package/package.json

@@ -2,10 +2,16 @@
 	"name": "specli",
 	"module": "index.ts",
 	"type": "module",
-	"version": "0.0.1",
+	"version": "0.0.3",
 	"bin": {
-		"opencli": "./cli.ts"
+		"specli": "./cli.ts"
 	},
+	"files": [
+		"cli.ts",
+		"index.ts",
+		"src",
+		"!**/*.test.ts"
+	],
 	"scripts": {
 		"lint": "biome ci",
 		"lint:check": "biome check --write --unsafe",

package/src/cli/compile.ts

@@ -8,7 +8,6 @@ export type CompileOptions = {
 	bytecode?: boolean;
 	dotenv?: boolean; // --no-dotenv sets this to false
 	bunfig?: boolean; // --no-bunfig sets this to false
-	execArgv?: string[];
 	define?: string[];
 	server?: string;
 	serverVar?: string[];
@@ -37,23 +36,6 @@ export async function compileCommand(
 		? (options.target as Bun.Build.Target)
 		: (`bun-${process.platform}-${process.arch}` as Bun.Build.Target);
 
-	// Build embedded execArgv for runtime defaults
-	const embeddedExecArgv: string[] = [];
-	if (options.server) {
-		embeddedExecArgv.push(`--server=${options.server}`);
-	}
-	if (options.serverVar) {
-		for (const pair of options.serverVar) {
-			embeddedExecArgv.push(`--server-var=${pair}`);
-		}
-	}
-	if (options.auth) {
-		embeddedExecArgv.push(`--auth=${options.auth}`);
-	}
-
-	// User-provided exec-argv
-	const compileExecArgv = options.execArgv ?? [];
-
 	// Parse --define pairs
 	const define: Record<string, string> = {};
 	if (options.define) {
@@ -78,14 +60,6 @@ export async function compileCommand(
 		buildArgs.push("--define", `${k}=${v}`);
 	}
 
-	const execArgv =
-		embeddedExecArgv.length || compileExecArgv.length
-			? [...embeddedExecArgv, ...compileExecArgv]
-			: [];
-	for (const arg of execArgv) {
-		buildArgs.push("--compile-exec-argv", arg);
-	}
-
 	if (options.dotenv === false) buildArgs.push("--no-compile-autoload-dotenv");
 	if (options.bunfig === false) buildArgs.push("--no-compile-autoload-bunfig");
 
@@ -97,8 +71,11 @@ export async function compileCommand(
 		stderr: "pipe",
 		env: {
 			...process.env,
-			OPENCLI_EMBED_SPEC: spec,
-			OPENCLI_CLI_NAME: name,
+			SPECLI_SPEC: spec,
+			SPECLI_NAME: name,
+			SPECLI_SERVER: options.server ?? "",
+			SPECLI_SERVER_VARS: options.serverVar?.join(",") ?? "",
+			SPECLI_AUTH: options.auth ?? "",
 		},
 	});
 

package/src/cli/derive-name.ts

@@ -12,7 +12,7 @@ const RESERVED_NAMES = [
  * Priority:
  *   1. info.title (kebab-cased, sanitized)
  *   2. Host from spec URL (if URL provided)
- *   3. Fallback to "opencli"
+ *   3. Fallback to "specli"
  */
 export async function deriveBinaryName(spec: string): Promise<string> {
 	try {
@@ -48,7 +48,7 @@ export async function deriveBinaryName(spec: string): Promise<string> {
 	}
 
 	// Fallback
-	return "opencli";
+	return "specli";
 }
 
 async function loadSpecText(spec: string): Promise<string> {

package/src/cli/exec.ts

@@ -26,7 +26,7 @@ export async function execCommand(
 	// [node, script, --spec, <spec>, ...options, ...remainingArgs]
 	const argv = [
 		process.argv[0] ?? "bun",
-		process.argv[1] ?? "opencli",
+		process.argv[1] ?? "specli",
 		"--spec",
 		spec,
 	];

package/src/cli/main.ts

@@ -18,13 +18,16 @@ import { stableStringify } from "./stable-json.ts";
 type MainOptions = {
 	embeddedSpecText?: string;
 	cliName?: string;
+	server?: string;
+	serverVars?: string[];
+	auth?: string;
 };
 
 export async function main(argv: string[], options: MainOptions = {}) {
 	const program = new Command();
 
 	program
-		.name(options.cliName ?? "opencli")
+		.name(options.cliName ?? "specli")
 		.description("Generate a CLI from an OpenAPI spec")
 		.option("--spec <urlOrPath>", "OpenAPI URL or file path")
 		.option("--server <url>", "Override server/base URL")
@@ -39,31 +42,10 @@ export async function main(argv: string[], options: MainOptions = {}) {
 		.option("--username <username>", "Basic auth username")
 		.option("--password <password>", "Basic auth password")
 		.option("--api-key <key>", "API key value")
-		.option("--profile <name>", "Profile name (stored under ~/.config/opencli)")
+		.option("--profile <name>", "Profile name (stored under ~/.config/specli)")
 		.option("--json", "Machine-readable output")
 		.showHelpAfterError();
 
-	// Provide namespaced variants for flags which may collide with operation flags.
-	// (Some real-world APIs define parameters named "accept", etc.)
-	program
-		.option(
-			"--oc-header <header>",
-			"Extra header (repeatable, namespaced)",
-			collectRepeatable,
-		)
-		.option("--oc-accept <type>", "Override Accept header (namespaced)")
-		.option("--oc-status", "Include status in --json output (namespaced)")
-		.option("--oc-headers", "Include headers in --json output (namespaced)")
-		.option("--oc-dry-run", "Print request without sending (namespaced)")
-		.option("--oc-curl", "Print curl command without sending (namespaced)")
-		.option("--oc-timeout <ms>", "Request timeout in milliseconds (namespaced)")
-		.option("--oc-data <data>", "Inline request body (namespaced)")
-		.option("--oc-file <path>", "Request body from file (namespaced)")
-		.option(
-			"--oc-content-type <type>",
-			"Override Content-Type (defaults from OpenAPI) (namespaced)",
-		);
-
 	// If user asks for help and we have no embedded spec and no --spec, show minimal help.
 	const spec = getArgValue(argv, "--spec");
 	const wantsHelp = hasAnyArg(argv, ["-h", "--help"]);
@@ -83,7 +65,7 @@ export async function main(argv: string[], options: MainOptions = {}) {
 
 	const profileCmd = program
 		.command("profile")
-		.description("Manage OpenCLI profiles");
+		.description("Manage specli profiles");
 
 	profileCmd
 		.command("list")
@@ -318,9 +300,7 @@ export async function main(argv: string[], options: MainOptions = {}) {
 					const args = op.pathArgs.length
 						? ` ${op.pathArgs.map((a) => `<${a}>`).join(" ")}`
 						: "";
-					process.stdout.write(
-						`- opencli ${op.resource} ${op.action}${args}\n`,
-					);
+					process.stdout.write(`- specli ${op.resource} ${op.action}${args}\n`);
 				}
 			}
 		});
@@ -330,6 +310,11 @@ export async function main(argv: string[], options: MainOptions = {}) {
 		authSchemes: ctx.authSchemes,
 		commands: ctx.commands,
 		specId: ctx.loaded.id,
+		embeddedDefaults: {
+			server: options.server,
+			serverVars: options.serverVars,
+			auth: options.auth,
+		},
 	});
 
 	await program.parseAsync(argv);

package/src/cli/runtime/auth/resolve.ts

@@ -1,8 +1,9 @@
 import type { AuthScheme } from "../../auth-schemes.ts";
 
 export type AuthInputs = {
-	profileAuthScheme?: string;
 	flagAuthScheme?: string;
+	profileAuthScheme?: string;
+	embeddedAuthScheme?: string;
 };
 
 export function resolveAuthScheme(
@@ -10,7 +11,7 @@ export function resolveAuthScheme(
 	required: import("../../auth-requirements.ts").AuthSummary,
 	inputs: AuthInputs,
 ): string | undefined {
-	// Explicit flag wins (but may still be validated later when applying).
+	// Priority: CLI flag > profile > embedded default
 	if (inputs.flagAuthScheme) return inputs.flagAuthScheme;
 
 	if (
@@ -20,6 +21,13 @@ export function resolveAuthScheme(
 		return inputs.profileAuthScheme;
 	}
 
+	if (
+		inputs.embeddedAuthScheme &&
+		authSchemes.some((s) => s.key === inputs.embeddedAuthScheme)
+	) {
+		return inputs.embeddedAuthScheme;
+	}
+
 	// If operation requires exactly one scheme, choose it.
 	const alts = required.alternatives;
 	if (alts.length === 1 && alts[0]?.length === 1) return alts[0][0]?.key;