specli 0.0.1

package/src/cli/runtime/request.ts

@@ -0,0 +1,487 @@
+import type { AuthScheme } from "../auth-schemes.ts";
+import type { CommandAction } from "../command-model.ts";
+
+import { resolveAuthScheme } from "./auth/resolve.ts";
+import { loadBody, parseBodyAsJsonOrYaml } from "./body.ts";
+import { parseHeaderInput } from "./headers.ts";
+import { getToken } from "./profile/secrets.ts";
+import { getProfile, readProfiles } from "./profile/store.ts";
+import { resolveServerUrl } from "./server-url.ts";
+import { applyTemplate } from "./template.ts";
+import {
+	createAjv,
+	deriveValidationSchemas,
+	formatAjvErrors,
+} from "./validate/index.ts";
+
+export type RuntimeGlobals = {
+	spec?: string;
+	server?: string;
+	serverVar?: string[];
+
+	// Common runtime flags (may conflict with operation flags).
+	header?: string[];
+	accept?: string;
+	contentType?: string;
+	data?: string;
+	file?: string;
+	timeout?: string;
+	dryRun?: boolean;
+	curl?: boolean;
+	status?: boolean;
+	headers?: boolean;
+
+	// Namespaced variants for the runtime flags above.
+	ocHeader?: string[];
+	ocAccept?: string;
+	ocContentType?: string;
+	ocData?: string;
+	ocFile?: string;
+	ocTimeout?: string;
+	ocDryRun?: boolean;
+	ocCurl?: boolean;
+	ocStatus?: boolean;
+	ocHeaders?: boolean;
+
+	json?: boolean;
+
+	auth?: string;
+	bearerToken?: string;
+	oauthToken?: string;
+	username?: string;
+	password?: string;
+	apiKey?: string;
+
+	profile?: string;
+};
+
+function parseKeyValuePairs(
+	pairs: string[] | undefined,
+): Record<string, string> {
+	const out: Record<string, string> = {};
+	for (const pair of pairs ?? []) {
+		const idx = pair.indexOf("=");
+		if (idx === -1)
+			throw new Error(`Invalid pair '${pair}', expected name=value`);
+		const name = pair.slice(0, idx).trim();
+		const value = pair.slice(idx + 1).trim();
+		if (!name) throw new Error(`Invalid pair '${pair}', missing name`);
+		out[name] = value;
+	}
+	return out;
+}
+
+function _parseTimeoutMs(value: string | undefined): number | undefined {
+	if (!value) return undefined;
+	const n = Number(value);
+	if (!Number.isFinite(n) || n <= 0)
+		throw new Error("--timeout must be a positive number");
+	return n;
+}
+
+function pickAuthSchemeKey(
+	action: CommandAction,
+	globals: RuntimeGlobals,
+): string | undefined {
+	if (globals.auth) return globals.auth;
+
+	// If operation declares a single requirement set with a single scheme, default to it.
+	const req = action.auth.alternatives;
+	if (req.length === 1 && req[0]?.length === 1) {
+		return req[0][0]?.key;
+	}
+
+	return undefined;
+}
+
+function applyAuth(
+	headers: Headers,
+	url: URL,
+	action: CommandAction,
+	globals: RuntimeGlobals,
+	authSchemes: AuthScheme[],
+): { headers: Headers; url: URL } {
+	const schemeKey = pickAuthSchemeKey(action, globals);
+	if (!schemeKey) return { headers, url };
+
+	const scheme = authSchemes.find((s) => s.key === schemeKey);
+	if (!scheme) {
+		throw new Error(
+			`Unknown auth scheme '${schemeKey}'. Available: ${authSchemes
+				.map((s) => s.key)
+				.join(", ")}`,
+		);
+	}
+
+	if (
+		scheme.kind === "http-bearer" ||
+		scheme.kind === "oauth2" ||
+		scheme.kind === "openIdConnect"
+	) {
+		const token = globals.bearerToken ?? globals.oauthToken;
+		if (!token)
+			throw new Error("Missing token. Provide --bearer-token <token>.");
+		headers.set("Authorization", `Bearer ${token}`);
+		return { headers, url };
+	}
+
+	if (scheme.kind === "http-basic") {
+		if (!globals.username) throw new Error("Missing --username for basic auth");
+		if (!globals.password) throw new Error("Missing --password for basic auth");
+		const raw = `${globals.username}:${globals.password}`;
+		const encoded = Buffer.from(raw, "utf8").toString("base64");
+		headers.set("Authorization", `Basic ${encoded}`);
+		return { headers, url };
+	}
+
+	if (scheme.kind === "api-key") {
+		if (!scheme.name)
+			throw new Error(`apiKey scheme '${scheme.key}' missing name`);
+		if (!scheme.in)
+			throw new Error(`apiKey scheme '${scheme.key}' missing location`);
+		if (!globals.apiKey) throw new Error("Missing --api-key for apiKey auth");
+
+		if (scheme.in === "header") {
+			headers.set(scheme.name, globals.apiKey);
+		}
+		if (scheme.in === "query") {
+			url.searchParams.set(scheme.name, globals.apiKey);
+		}
+		if (scheme.in === "cookie") {
+			const existing = headers.get("Cookie");
+			const part = `${scheme.name}=${globals.apiKey}`;
+			headers.set("Cookie", existing ? `${existing}; ${part}` : part);
+		}
+
+		return { headers, url };
+	}
+
+	return { headers, url };
+}
+
+export type BuildRequestInput = {
+	specId: string;
+	action: CommandAction;
+	positionalValues: string[];
+	flagValues: Record<string, unknown>;
+	globals: RuntimeGlobals;
+	servers: import("../server.ts").ServerInfo[];
+	authSchemes: AuthScheme[];
+};
+
+export async function buildRequest(
+	input: BuildRequestInput,
+): Promise<{ request: Request; curl: string }> {
+	const profilesFile = await readProfiles();
+	const profile = getProfile(profilesFile, input.globals.profile);
+
+	const serverVars = parseKeyValuePairs(input.globals.serverVar);
+	const serverUrl = resolveServerUrl({
+		serverOverride: input.globals.server ?? profile?.server,
+		servers: input.servers,
+		serverVars,
+	});
+
+	// Path params: action.positionals order matches templated params order.
+	const pathVars: Record<string, string> = {};
+	for (let i = 0; i < input.action.positionals.length; i++) {
+		const pos = input.action.positionals[i];
+		const raw = input.action.pathArgs[i];
+		const value = input.positionalValues[i];
+		if (typeof raw === "string" && typeof value === "string") {
+			pathVars[raw] = value;
+		}
+		// Use cli name too as fallback
+		if (pos?.name && typeof value === "string") {
+			pathVars[pos.name] = value;
+		}
+	}
+
+	const path = applyTemplate(input.action.path, pathVars, { encode: true });
+
+	const url = new URL(
+		path,
+		serverUrl.endsWith("/") ? serverUrl : `${serverUrl}/`,
+	);
+
+	const headers = new Headers();
+	const accept = input.globals.accept ?? input.globals.ocAccept;
+	if (accept) headers.set("Accept", accept);
+
+	// Collect declared params for validation.
+	const queryValues: Record<string, unknown> = {};
+	const headerValues: Record<string, unknown> = {};
+	const cookieValues: Record<string, unknown> = {};
+
+	for (const p of input.action.params) {
+		if (p.kind !== "flag") continue;
+		const optValue = input.flagValues[optionKeyFromFlag(p.flag)];
+		if (typeof optValue === "undefined") continue;
+
+		if (p.in === "query") {
+			queryValues[p.name] = optValue;
+		}
+		if (p.in === "header") {
+			headerValues[p.name] = optValue;
+		}
+		if (p.in === "cookie") {
+			cookieValues[p.name] = optValue;
+		}
+	}
+
+	// Validate params (query/header/cookie) using Ajv.
+	const schemas = deriveValidationSchemas(input.action);
+	const ajv = createAjv();
+
+	if (schemas.querySchema) {
+		const validate = ajv.compile(schemas.querySchema);
+		if (!validate(queryValues)) {
+			throw new Error(formatAjvErrors(validate.errors));
+		}
+	}
+	if (schemas.headerSchema) {
+		const validate = ajv.compile(schemas.headerSchema);
+		if (!validate(headerValues)) {
+			throw new Error(formatAjvErrors(validate.errors));
+		}
+	}
+	if (schemas.cookieSchema) {
+		const validate = ajv.compile(schemas.cookieSchema);
+		if (!validate(cookieValues)) {
+			throw new Error(formatAjvErrors(validate.errors));
+		}
+	}
+
+	// Apply params -> query/header/cookie
+	for (const [name, value] of Object.entries(queryValues)) {
+		if (Array.isArray(value)) {
+			for (const item of value) {
+				url.searchParams.append(name, String(item));
+			}
+			continue;
+		}
+		url.searchParams.set(name, String(value));
+	}
+	for (const [name, value] of Object.entries(headerValues)) {
+		headers.set(name, String(value));
+	}
+	for (const [name, value] of Object.entries(cookieValues)) {
+		const existing = headers.get("Cookie");
+		const part = `${name}=${String(value)}`;
+		headers.set("Cookie", existing ? `${existing}; ${part}` : part);
+	}
+
+	const extraHeaders = [
+		...(input.globals.header ?? []),
+		...(input.globals.ocHeader ?? []),
+	].map(parseHeaderInput);
+	for (const { name, value } of extraHeaders) {
+		headers.set(name, value);
+	}
+
+	let body: string | undefined;
+	if (input.action.requestBody) {
+		const data = input.globals.data ?? input.globals.ocData;
+		const file = input.globals.file ?? input.globals.ocFile;
+
+		const hasData = typeof data === "string";
+		const hasFile = typeof file === "string";
+
+		const rawBodyFlags =
+			typeof input.flagValues.__body === "object" && input.flagValues.__body
+				? (input.flagValues.__body as Record<string, unknown>)
+				: {};
+
+		const bodyFlags: Record<string, unknown> = Object.fromEntries(
+			Object.entries(rawBodyFlags).filter(
+				([, v]) => typeof v !== "undefined" && v !== false,
+			),
+		);
+
+		const hasExpandedBody = Object.keys(bodyFlags).length > 0;
+
+		if (hasData && hasFile) throw new Error("Use only one of --data or --file");
+		if (hasExpandedBody && (hasData || hasFile)) {
+			throw new Error("Use either --data/--file or --body-* flags (not both)");
+		}
+
+		const contentType =
+			input.globals.contentType ??
+			input.globals.ocContentType ??
+			input.action.requestBody.preferredContentType;
+		if (contentType) headers.set("Content-Type", contentType);
+
+		const schema = input.action.requestBodySchema;
+
+		if (!hasExpandedBody && !hasData && !hasFile) {
+			if (input.action.requestBody.required) {
+				throw new Error(
+					"Missing request body. Provide --data, --file, or --body-* flags.",
+				);
+			}
+		} else if (hasExpandedBody) {
+			if (!contentType?.includes("json")) {
+				throw new Error(
+					"Expanded body flags are only supported for JSON request bodies. Use --content-type application/json or --data/--file.",
+				);
+			}
+
+			// Friendly "missing required field" errors for expanded flags.
+			if (schema?.required && Array.isArray(schema.required)) {
+				for (const name of schema.required) {
+					const n = String(name);
+					const key = `body${n[0]?.toUpperCase()}${n.slice(1)}`;
+					if (!(key in bodyFlags)) {
+						throw new Error(
+							`Missing required body field '${n}'. Provide --body-${n} or use --data/--file.`,
+						);
+					}
+				}
+			}
+
+			const built: Record<string, unknown> = {};
+			for (const [k, v] of Object.entries(bodyFlags)) {
+				if (!k.startsWith("body")) continue;
+				const name = k.slice("body".length);
+				const propName = name.length
+					? name[0]?.toLowerCase() + name.slice(1)
+					: "";
+				if (!propName) continue;
+
+				const propSchema =
+					schema && schema.type === "object" && schema.properties
+						? (schema.properties as Record<string, unknown>)[propName]
+						: undefined;
+				const t =
+					propSchema && typeof propSchema === "object"
+						? (propSchema as { type?: unknown }).type
+						: "string";
+
+				if (t === "boolean") {
+					built[propName] = true;
+				} else if (t === "integer") {
+					built[propName] = Number.parseInt(String(v), 10);
+				} else if (t === "number") {
+					built[propName] = Number(String(v));
+				} else {
+					built[propName] = String(v);
+				}
+			}
+
+			if (schema) {
+				const validate = ajv.compile(schema);
+				if (!validate(built)) {
+					throw new Error(formatAjvErrors(validate.errors));
+				}
+			}
+
+			body = JSON.stringify(built);
+		} else if (hasData) {
+			if (contentType?.includes("json")) {
+				const parsed = parseBodyAsJsonOrYaml(data as string);
+
+				if (schema) {
+					const validate = ajv.compile(schema);
+					if (!validate(parsed)) {
+						throw new Error(formatAjvErrors(validate.errors));
+					}
+				}
+
+				body = JSON.stringify(parsed);
+			} else {
+				body = data as string;
+			}
+		} else if (hasFile) {
+			const loaded = await loadBody({
+				kind: "file",
+				path: file as string,
+			});
+			if (contentType?.includes("json")) {
+				const parsed = parseBodyAsJsonOrYaml(loaded?.raw ?? "");
+
+				if (schema) {
+					const validate = ajv.compile(schema);
+					if (!validate(parsed)) {
+						throw new Error(formatAjvErrors(validate.errors));
+					}
+				}
+
+				body = JSON.stringify(parsed);
+			} else {
+				body = loaded?.raw;
+			}
+		}
+	} else {
+		if (
+			typeof (input.globals.data ?? input.globals.ocData) === "string" ||
+			typeof (input.globals.file ?? input.globals.ocFile) === "string"
+		) {
+			throw new Error("This operation does not accept a request body");
+		}
+	}
+
+	// Profile-aware auth resolution (flags override profile).
+	const resolvedAuthScheme = resolveAuthScheme(
+		input.authSchemes,
+		input.action.auth,
+		{
+			flagAuthScheme: input.globals.auth,
+			profileAuthScheme: profile?.authScheme,
+		},
+	);
+
+	const tokenFromProfile =
+		profile?.name && resolvedAuthScheme
+			? await getToken(input.specId, profile.name)
+			: null;
+
+	const globalsWithProfileAuth: RuntimeGlobals = {
+		...input.globals,
+		auth: resolvedAuthScheme,
+		bearerToken:
+			input.globals.bearerToken ??
+			input.globals.oauthToken ??
+			tokenFromProfile ??
+			undefined,
+	};
+
+	const final = applyAuth(
+		headers,
+		url,
+		input.action,
+		globalsWithProfileAuth,
+		input.authSchemes,
+	);
+
+	const req = new Request(final.url.toString(), {
+		method: input.action.method,
+		headers: final.headers,
+		body,
+	});
+
+	const curl = buildCurl(req, body);
+	return { request: req, curl };
+}
+
+function buildCurl(req: Request, body: string | undefined): string {
+	const parts: string[] = ["curl", "-sS", "-X", req.method];
+	for (const [k, v] of req.headers.entries()) {
+		parts.push("-H", shellQuote(`${k}: ${v}`));
+	}
+	if (typeof body === "string") {
+		parts.push("--data", shellQuote(body));
+	}
+	parts.push(shellQuote(req.url));
+	return parts.join(" ");
+}
+
+function shellQuote(value: string): string {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+function optionKeyFromFlag(flag: string): string {
+	// Commander uses camelCase property names derived from long flag.
+	// Example: --x-request-id -> xRequestId
+	const name = flag.replace(/^--/, "");
+	return name.replace(/-([a-z])/g, (_, c) => String(c).toUpperCase());
+}

package/src/cli/runtime/server-url.ts

@@ -0,0 +1,44 @@
+import type { ServerInfo } from "../server.ts";
+
+import { applyTemplate, extractTemplateVars } from "./template.ts";
+
+export type ResolveServerInput = {
+	serverOverride?: string;
+	servers: ServerInfo[];
+	serverVars: Record<string, string>;
+};
+
+export function resolveServerUrl(input: ResolveServerInput): string {
+	const base = input.serverOverride ?? input.servers[0]?.url;
+	if (!base) {
+		throw new Error(
+			"No server URL found. Provide --server <url> or define servers in the OpenAPI spec.",
+		);
+	}
+
+	const names = extractTemplateVars(base);
+	if (!names.length) return base;
+
+	const vars: Record<string, string> = {};
+	for (const name of names) {
+		const provided = input.serverVars[name];
+		if (typeof provided === "string") {
+			vars[name] = provided;
+			continue;
+		}
+
+		// If spec has default for this var, use it.
+		const match = input.servers.find((s) => s.url === base);
+		const v = match?.variables.find((x) => x.name === name);
+		if (typeof v?.default === "string") {
+			vars[name] = v.default;
+			continue;
+		}
+
+		throw new Error(
+			`Missing server variable '${name}'. Provide --server-var ${name}=...`,
+		);
+	}
+
+	return applyTemplate(base, vars);
+}

package/src/cli/runtime/template.ts

@@ -0,0 +1,26 @@
+export function extractTemplateVars(template: string): string[] {
+	const out: string[] = [];
+	const re = /\{([^}]+)\}/g;
+	while (true) {
+		const match = re.exec(template);
+		if (!match) break;
+		out.push((match[1] ?? "").trim());
+	}
+	return out.filter(Boolean);
+}
+
+export function applyTemplate(
+	template: string,
+	vars: Record<string, string>,
+	options?: { encode?: boolean },
+): string {
+	const encode = options?.encode ?? false;
+	return template.replace(/\{([^}]+)\}/g, (_, rawName) => {
+		const name = String(rawName).trim();
+		const value = vars[name];
+		if (typeof value !== "string") {
+			throw new Error(`Missing template variable: ${name}`);
+		}
+		return encode ? encodeURIComponent(value) : value;
+	});
+}

package/src/cli/runtime/validate/ajv.ts

@@ -0,0 +1,13 @@
+import Ajv from "ajv";
+import addFormats from "ajv-formats";
+
+export function createAjv() {
+	const ajv = new Ajv({
+		allErrors: true,
+		strict: false,
+		coerceTypes: false,
+	});
+
+	addFormats(ajv);
+	return ajv;
+}

package/src/cli/runtime/validate/coerce.ts

@@ -0,0 +1,71 @@
+import { InvalidArgumentError } from "commander";
+
+import type { ParamType } from "../../schema-shape.ts";
+
+export function coerceValue(raw: string, type: ParamType): unknown {
+	if (type === "string" || type === "unknown") return raw;
+
+	if (type === "boolean") {
+		// Commander boolean options are handled without a value; keep for completeness.
+		if (raw === "true") return true;
+		if (raw === "false") return false;
+		throw new InvalidArgumentError(`Expected boolean, got '${raw}'`);
+	}
+
+	if (type === "integer") {
+		const n = Number.parseInt(raw, 10);
+		if (!Number.isFinite(n))
+			throw new InvalidArgumentError(`Expected integer, got '${raw}'`);
+		return n;
+	}
+
+	if (type === "number") {
+		const n = Number(raw);
+		if (!Number.isFinite(n))
+			throw new InvalidArgumentError(`Expected number, got '${raw}'`);
+		return n;
+	}
+
+	// For now, accept objects as JSON strings.
+	if (type === "object") {
+		try {
+			return JSON.parse(raw);
+		} catch {
+			throw new InvalidArgumentError(
+				`Expected JSON object, got '${raw}'. Use --data/--file for complex bodies.`,
+			);
+		}
+	}
+
+	// Arrays should usually be passed as repeatable flags or comma-separated,
+	// but allow JSON arrays too.
+	if (type === "array") {
+		return coerceArrayInput(raw, "string");
+	}
+
+	return raw;
+}
+
+export function coerceArrayInput(raw: string, itemType: ParamType): unknown[] {
+	const trimmed = raw.trim();
+	if (!trimmed) return [];
+
+	if (trimmed.startsWith("[")) {
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(trimmed);
+		} catch {
+			throw new InvalidArgumentError(`Expected JSON array, got '${raw}'`);
+		}
+		if (!Array.isArray(parsed)) {
+			throw new InvalidArgumentError(`Expected JSON array, got '${raw}'`);
+		}
+		return parsed.map((v) => coerceValue(String(v), itemType));
+	}
+
+	return trimmed
+		.split(",")
+		.map((s) => s.trim())
+		.filter(Boolean)
+		.map((s) => coerceValue(s, itemType));
+}

package/src/cli/runtime/validate/error.ts

@@ -0,0 +1,29 @@
+import type { ErrorObject } from "ajv";
+
+export function formatAjvErrors(
+	errors: ErrorObject[] | null | undefined,
+): string {
+	if (!errors?.length) return "Invalid input";
+
+	return errors
+		.map((e) => {
+			const path = e.instancePath || e.schemaPath || "";
+
+			if (
+				e.keyword === "required" &&
+				e.params &&
+				typeof e.params === "object" &&
+				"missingProperty" in e.params
+			) {
+				const missing = String(
+					(e.params as { missingProperty?: unknown }).missingProperty,
+				);
+				const where = e.instancePath || "/";
+				return `${where} missing required property '${missing}'`.trim();
+			}
+
+			const msg = e.message || "invalid";
+			return `${path} ${msg}`.trim();
+		})
+		.join("\n");
+}

package/src/cli/runtime/validate/index.ts

@@ -0,0 +1,4 @@
+export * from "./ajv.ts";
+export * from "./coerce.ts";
+export * from "./error.ts";
+export * from "./schema.ts";