specli 0.0.17 → 0.0.18

package/src/cli/operations.ts

@@ -0,0 +1,152 @@
+import type {
+	NormalizedOperation,
+	NormalizedParameter,
+	NormalizedRequestBody,
+	OpenApiDoc,
+} from "./types.js";
+
+function operationKey(method: string, path: string): string {
+	return `${method.toUpperCase()} ${path}`;
+}
+
+const HTTP_METHODS = [
+	"get",
+	"post",
+	"put",
+	"patch",
+	"delete",
+	"options",
+	"head",
+	"trace",
+] as const;
+
+type RawParameter = {
+	in?: string;
+	name?: string;
+	required?: boolean;
+	description?: string;
+	schema?: unknown;
+};
+
+type RawRequestBody = {
+	required?: boolean;
+	content?: Record<string, { schema?: unknown } | undefined>;
+};
+
+type RawOperation = {
+	operationId?: string;
+	tags?: string[];
+	summary?: string;
+	description?: string;
+	deprecated?: boolean;
+	security?: OpenApiDoc["security"];
+	parameters?: RawParameter[];
+	requestBody?: RawRequestBody;
+};
+
+type RawPathItem = {
+	parameters?: RawParameter[];
+} & Partial<Record<(typeof HTTP_METHODS)[number], RawOperation>>;
+
+function normalizeParam(p: RawParameter): NormalizedParameter | undefined {
+	if (!p || typeof p !== "object") return undefined;
+	const loc = p.in;
+	const name = p.name;
+	if (
+		loc !== "path" &&
+		loc !== "query" &&
+		loc !== "header" &&
+		loc !== "cookie"
+	) {
+		return undefined;
+	}
+	if (!name) return undefined;
+
+	return {
+		in: loc,
+		name,
+		required: Boolean(p.required || loc === "path"),
+		description: p.description,
+		schema: p.schema,
+	};
+}
+
+function mergeParameters(
+	pathParams: RawParameter[] | undefined,
+	opParams: RawParameter[] | undefined,
+): NormalizedParameter[] {
+	const merged = new Map<string, NormalizedParameter>();
+
+	for (const p of pathParams ?? []) {
+		const normalized = normalizeParam(p);
+		if (!normalized) continue;
+		merged.set(`${normalized.in}:${normalized.name}`, normalized);
+	}
+
+	for (const p of opParams ?? []) {
+		const normalized = normalizeParam(p);
+		if (!normalized) continue;
+		merged.set(`${normalized.in}:${normalized.name}`, normalized);
+	}
+
+	return [...merged.values()];
+}
+
+function normalizeRequestBody(
+	rb: RawRequestBody | undefined,
+): NormalizedRequestBody | undefined {
+	if (!rb) return undefined;
+
+	const content = rb.content ?? {};
+	const contentTypes = Object.keys(content);
+	const schemasByContentType: Record<string, unknown | undefined> = {};
+
+	for (const contentType of contentTypes) {
+		schemasByContentType[contentType] = content[contentType]?.schema;
+	}
+
+	return {
+		required: Boolean(rb.required),
+		contentTypes,
+		schemasByContentType,
+	};
+}
+
+export function indexOperations(doc: OpenApiDoc): NormalizedOperation[] {
+	const out: NormalizedOperation[] = [];
+	const paths = doc.paths ?? {};
+
+	for (const [path, rawPathItem] of Object.entries(paths)) {
+		if (!rawPathItem || typeof rawPathItem !== "object") continue;
+
+		const pathItem = rawPathItem as RawPathItem;
+
+		for (const method of HTTP_METHODS) {
+			const op = pathItem[method];
+			if (!op) continue;
+
+			const parameters = mergeParameters(pathItem.parameters, op.parameters);
+			const normalizedMethod = method.toUpperCase();
+			out.push({
+				key: operationKey(normalizedMethod, path),
+				method: normalizedMethod,
+				path,
+				operationId: op.operationId,
+				tags: op.tags ?? [],
+				summary: op.summary,
+				description: op.description,
+				deprecated: op.deprecated,
+				security: (op.security ?? doc.security) as OpenApiDoc["security"],
+				parameters,
+				requestBody: normalizeRequestBody(op.requestBody),
+			});
+		}
+	}
+
+	out.sort((a, b) => {
+		if (a.path !== b.path) return a.path.localeCompare(b.path);
+		return a.method.localeCompare(b.method);
+	});
+
+	return out;
+}

package/src/cli/params.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from "bun:test";
+
+import { deriveParamSpecs } from "./params.js";
+import type { NormalizedOperation } from "./types.js";
+
+describe("deriveParamSpecs", () => {
+	test("derives basic types + flags", () => {
+		const op: NormalizedOperation = {
+			key: "GET /contacts",
+			method: "GET",
+			path: "/contacts",
+			tags: [],
+			parameters: [
+				{
+					in: "query",
+					name: "limit",
+					required: false,
+					schema: {
+						type: "integer",
+						format: "int32",
+						enum: ["1", "2"],
+					},
+				},
+				{
+					in: "header",
+					name: "X-Request-Id",
+					required: false,
+					schema: { type: "string" },
+				},
+			],
+		};
+
+		const specs = deriveParamSpecs(op);
+		expect(specs).toHaveLength(2);
+
+		const limit = specs.find((p) => p.name === "limit");
+		expect(limit?.kind).toBe("flag");
+		expect(limit?.flag).toBe("--limit");
+		expect(limit?.type).toBe("integer");
+		expect(limit?.format).toBe("int32");
+		expect(limit?.enum).toEqual(["1", "2"]);
+
+		const reqId = specs.find((p) => p.name === "X-Request-Id");
+		expect(reqId?.kind).toBe("flag");
+		expect(reqId?.flag).toBe("--x-request-id");
+		expect(reqId?.type).toBe("string");
+	});
+
+	test("derives array item types", () => {
+		const op: NormalizedOperation = {
+			key: "GET /things",
+			method: "GET",
+			path: "/things",
+			tags: [],
+			parameters: [
+				{
+					in: "query",
+					name: "ids",
+					required: false,
+					schema: { type: "array", items: { type: "integer" } },
+				},
+			],
+		};
+
+		const specs = deriveParamSpecs(op);
+		expect(specs).toHaveLength(1);
+		expect(specs[0]?.type).toBe("array");
+		expect(specs[0]?.itemType).toBe("integer");
+	});
+});

package/src/cli/params.ts

@@ -0,0 +1,71 @@
+import {
+	getSchemaEnumStrings,
+	getSchemaFormat,
+	getSchemaType,
+} from "./schema-shape.js";
+import { kebabCase } from "./strings.js";
+import type { NormalizedOperation, NormalizedParameter } from "./types.js";
+
+export type ParamType = import("./schema-shape.js").ParamType;
+
+export type ParamSpec = {
+	kind: "positional" | "flag";
+	in: NormalizedParameter["in"];
+	name: string;
+	flag: string;
+	required: boolean;
+	description?: string;
+	type: ParamType;
+	format?: string;
+	enum?: string[];
+
+	// Arrays
+	itemType?: ParamType;
+	itemFormat?: string;
+	itemEnum?: string[];
+
+	// Original schema for Ajv validation and future advanced flag expansion.
+	schema?: import("./types.js").JsonSchema;
+};
+
+export function deriveParamSpecs(op: NormalizedOperation): ParamSpec[] {
+	const out: ParamSpec[] = [];
+
+	for (const p of op.parameters) {
+		const flag = `--${kebabCase(p.name)}`;
+		const type = getSchemaType(p.schema);
+		const schemaObj =
+			p.schema && typeof p.schema === "object"
+				? (p.schema as import("./types.js").JsonSchema)
+				: undefined;
+
+		const itemsSchema =
+			schemaObj && type === "array" && typeof schemaObj.items === "object"
+				? (schemaObj.items as unknown)
+				: undefined;
+
+		out.push({
+			kind: p.in === "path" ? "positional" : "flag",
+			in: p.in,
+			name: p.name,
+			flag,
+			required: p.required,
+			description: p.description,
+			type,
+			format: getSchemaFormat(p.schema),
+			enum: getSchemaEnumStrings(p.schema),
+			itemType: type === "array" ? getSchemaType(itemsSchema) : undefined,
+			itemFormat: type === "array" ? getSchemaFormat(itemsSchema) : undefined,
+			itemEnum:
+				type === "array" ? getSchemaEnumStrings(itemsSchema) : undefined,
+			schema: schemaObj,
+		});
+	}
+
+	out.sort((a, b) => {
+		if (a.in !== b.in) return a.in.localeCompare(b.in);
+		return a.name.localeCompare(b.name);
+	});
+
+	return out;
+}

package/src/cli/pluralize.ts

@@ -0,0 +1,41 @@
+const IRREGULAR: Record<string, string> = {
+	person: "people",
+	man: "men",
+	woman: "women",
+	child: "children",
+	tooth: "teeth",
+	foot: "feet",
+	mouse: "mice",
+	goose: "geese",
+};
+
+const UNCOUNTABLE = new Set([
+	"metadata",
+	"information",
+	"equipment",
+	"money",
+	"series",
+	"species",
+]);
+
+export function pluralize(word: string): string {
+	const w = word.trim();
+	if (!w) return w;
+
+	const lower = w.toLowerCase();
+	if (UNCOUNTABLE.has(lower)) return lower;
+	if (IRREGULAR[lower]) return IRREGULAR[lower];
+
+	// already plural-ish
+	if (lower.endsWith("s")) return lower;
+
+	if (/[bcdfghjklmnpqrstvwxyz]y$/.test(lower)) {
+		return lower.replace(/y$/, "ies");
+	}
+
+	if (/(ch|sh|x|z)$/.test(lower)) {
+		return `${lower}es`;
+	}
+
+	return `${lower}s`;
+}

package/src/cli/positional.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "bun:test";
+import type { ActionShapeForCli } from "./positional.js";
+import { deriveFlags, derivePositionals } from "./positional.js";
+
+describe("derivePositionals", () => {
+	test("returns ordered positionals from pathArgs", () => {
+		const action: ActionShapeForCli = {
+			pathArgs: ["id"],
+			params: [
+				{
+					kind: "positional",
+					in: "path",
+					name: "id",
+					flag: "--id",
+					required: true,
+					type: "string",
+				},
+			],
+		};
+
+		const pos = derivePositionals(action);
+		expect(pos).toEqual([
+			{
+				name: "id",
+				required: true,
+				type: "string",
+				format: undefined,
+				enum: undefined,
+				description: undefined,
+			},
+		]);
+	});
+});
+
+describe("deriveFlags", () => {
+	test("returns only flag params", () => {
+		const action: ActionShapeForCli = {
+			pathArgs: [],
+			params: [
+				{
+					kind: "flag",
+					in: "query",
+					name: "limit",
+					flag: "--limit",
+					required: false,
+					type: "integer",
+				},
+			],
+		};
+
+		const flags = deriveFlags(action);
+		expect(flags.flags).toEqual([
+			{
+				in: "query",
+				name: "limit",
+				flag: "--limit",
+				required: false,
+				description: undefined,
+				type: "integer",
+				format: undefined,
+				enum: undefined,
+			},
+		]);
+	});
+});

package/src/cli/positional.ts

@@ -0,0 +1,75 @@
+import type { ParamSpec } from "./params.js";
+
+export type ActionShapeForCli = {
+	pathArgs: string[];
+	params: ParamSpec[];
+};
+
+export type PositionalArg = {
+	name: string;
+	required: boolean;
+	description?: string;
+	type: import("./schema-shape.js").ParamType;
+	format?: string;
+	enum?: string[];
+};
+
+export type FlagsIndex = {
+	flags: Array<
+		Pick<
+			import("./params.js").ParamSpec,
+			| "in"
+			| "name"
+			| "flag"
+			| "required"
+			| "description"
+			| "type"
+			| "format"
+			| "enum"
+			| "itemType"
+			| "itemFormat"
+			| "itemEnum"
+		>
+	>;
+};
+
+export function derivePositionals(action: ActionShapeForCli): PositionalArg[] {
+	const byName = new Map<string, PositionalArg>();
+
+	// Use pathArgs order; match metadata from params when available.
+	for (const name of action.pathArgs) {
+		const p = action.params.find(
+			(x: ParamSpec) => x.in === "path" && x.name === name,
+		);
+		byName.set(name, {
+			name,
+			required: true,
+			description: p?.description,
+			type: p?.type ?? "unknown",
+			format: p?.format,
+			enum: p?.enum,
+		});
+	}
+
+	return [...byName.values()];
+}
+
+export function deriveFlags(action: ActionShapeForCli): FlagsIndex {
+	return {
+		flags: action.params
+			.filter((p: ParamSpec) => p.kind === "flag")
+			.map((p: ParamSpec) => ({
+				in: p.in,
+				name: p.name,
+				flag: p.flag,
+				required: p.required,
+				description: p.description,
+				type: p.type,
+				format: p.format,
+				enum: p.enum,
+				itemType: p.itemType,
+				itemFormat: p.itemFormat,
+				itemEnum: p.itemEnum,
+			})),
+	};
+}

package/src/cli/request-body.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "bun:test";
+
+import { deriveRequestBodyInfo } from "./request-body.js";
+import type { NormalizedOperation } from "./types.js";
+
+describe("deriveRequestBodyInfo", () => {
+	test("summarizes content types and convenience flags", () => {
+		const op: NormalizedOperation = {
+			key: "POST /contacts",
+			method: "POST",
+			path: "/contacts",
+			tags: [],
+			parameters: [],
+			requestBody: {
+				required: true,
+				contentTypes: ["application/x-www-form-urlencoded", "application/json"],
+				schemasByContentType: {
+					"application/json": { type: "object" },
+					"application/x-www-form-urlencoded": { type: "object" },
+				},
+			},
+		};
+
+		const info = deriveRequestBodyInfo(op);
+		expect(info?.required).toBe(true);
+		expect(info?.hasJson).toBe(true);
+		expect(info?.hasFormUrlEncoded).toBe(true);
+		expect(info?.hasMultipart).toBe(false);
+		expect(info?.content.map((c) => c.contentType)).toEqual([
+			"application/json",
+			"application/x-www-form-urlencoded",
+		]);
+		expect(info?.preferredSchema).toEqual({ type: "object" });
+	});
+});

package/src/cli/request-body.ts

@@ -0,0 +1,94 @@
+import {
+	getSchemaEnumStrings,
+	getSchemaFormat,
+	getSchemaType,
+} from "./schema-shape.js";
+import type {
+	JsonSchema,
+	NormalizedOperation,
+	NormalizedRequestBody,
+} from "./types.js";
+import { isJsonSchema } from "./types.js";
+
+export type RequestBodyContent = {
+	contentType: string;
+	required: boolean;
+	schemaType: import("./schema-shape.js").ParamType;
+	schemaFormat?: string;
+	schemaEnum?: string[];
+};
+
+export type RequestBodyInfo = {
+	required: boolean;
+	content: RequestBodyContent[];
+	// Convenience flags for later arg generation.
+	hasJson: boolean;
+	hasFormUrlEncoded: boolean;
+	hasMultipart: boolean;
+
+	// Phase 1 planning: supported generic body inputs.
+	bodyFlags: string[];
+	preferredContentType?: string;
+
+	// Original JSON Schema (for expanded flags + validation)
+	preferredSchema?: JsonSchema;
+};
+
+function getRequestBody(
+	op: NormalizedOperation,
+): NormalizedRequestBody | undefined {
+	return op.requestBody;
+}
+
+export function deriveRequestBodyInfo(
+	op: NormalizedOperation,
+): RequestBodyInfo | undefined {
+	const rb = getRequestBody(op);
+	if (!rb) return undefined;
+
+	const content: RequestBodyContent[] = [];
+	for (const contentType of rb.contentTypes) {
+		const schema = rb.schemasByContentType[contentType];
+		content.push({
+			contentType,
+			required: rb.required,
+			schemaType: getSchemaType(schema),
+			schemaFormat: getSchemaFormat(schema),
+			schemaEnum: getSchemaEnumStrings(schema),
+		});
+	}
+
+	content.sort((a, b) => a.contentType.localeCompare(b.contentType));
+
+	const hasJson = content.some((c) => c.contentType.includes("json"));
+	const hasFormUrlEncoded = content.some(
+		(c) => c.contentType === "application/x-www-form-urlencoded",
+	);
+	const hasMultipart = content.some((c) =>
+		c.contentType.startsWith("multipart/"),
+	);
+
+	const bodyFlags = ["--data", "--file"]; // always available when requestBody exists
+
+	const preferredContentType =
+		content.find((c) => c.contentType === "application/json")?.contentType ??
+		content.find((c) => c.contentType.includes("json"))?.contentType ??
+		content[0]?.contentType;
+
+	const preferredSchema = preferredContentType
+		? rb.schemasByContentType[preferredContentType]
+		: undefined;
+
+	return {
+		required: rb.required,
+		content,
+		hasJson,
+		hasFormUrlEncoded,
+		hasMultipart,
+		bodyFlags,
+		preferredContentType,
+		preferredSchema: isJsonSchema(preferredSchema)
+			? preferredSchema
+			: undefined,
+	};
+}

package/src/cli/runtime/argv.ts

@@ -0,0 +1,14 @@
+export function getArgValue(argv: string[], key: string): string | undefined {
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (!a) continue;
+
+		if (a === key) return argv[i + 1];
+		if (a.startsWith(`${key}=`)) return a.slice(key.length + 1);
+	}
+	return undefined;
+}
+
+export function hasAnyArg(argv: string[], names: string[]): boolean {
+	return argv.some((a) => a && names.includes(a));
+}

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

@@ -0,0 +1,59 @@
+import type { AuthScheme } from "../../auth-schemes.js";
+
+export type AuthInputs = {
+	flagAuthScheme?: string;
+	profileAuthScheme?: string;
+	embeddedAuthScheme?: string;
+	hasStoredToken?: boolean;
+};
+
+const BEARER_COMPATIBLE_KINDS = new Set([
+	"http-bearer",
+	"oauth2",
+	"openIdConnect",
+]);
+
+export function resolveAuthScheme(
+	authSchemes: AuthScheme[],
+	required: import("../../auth-requirements.js").AuthSummary,
+	inputs: AuthInputs,
+): string | undefined {
+	// Priority: CLI flag > profile > embedded default
+	if (inputs.flagAuthScheme) return inputs.flagAuthScheme;
+
+	if (
+		inputs.profileAuthScheme &&
+		authSchemes.some((s) => s.key === inputs.profileAuthScheme)
+	) {
+		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;
+
+	// Otherwise if there is only one scheme in spec, pick it.
+	if (authSchemes.length === 1) return authSchemes[0]?.key;
+
+	// If user has a stored token and operation accepts a bearer-compatible scheme,
+	// automatically pick the first one that matches.
+	if (inputs.hasStoredToken && alts.length > 0) {
+		for (const alt of alts) {
+			if (alt.length !== 1) continue;
+			const key = alt[0]?.key;
+			const scheme = authSchemes.find((s) => s.key === key);
+			if (scheme && BEARER_COMPATIBLE_KINDS.has(scheme.kind)) {
+				return key;
+			}
+		}
+	}
+
+	return undefined;
+}