specli 0.0.1

package/src/cli/auth-schemes.ts

@@ -0,0 +1,187 @@
+import { kebabCase } from "./strings.ts";
+import type { OpenApiDoc } from "./types.ts";
+
+export type AuthSchemeKind =
+	| "http-bearer"
+	| "http-basic"
+	| "api-key"
+	| "oauth2"
+	| "openIdConnect"
+	| "unknown";
+
+export type AuthScheme = {
+	key: string;
+	kind: AuthSchemeKind;
+	name?: string;
+	in?: "header" | "query" | "cookie";
+	scheme?: string;
+	bearerFormat?: string;
+	description?: string;
+
+	// oauth2/openid only (subset of spec, enough to derive flags + docs)
+	oauthFlows?: OAuthFlows;
+	openIdConnectUrl?: string;
+};
+
+export type OAuthFlow = {
+	authorizationUrl?: string;
+	tokenUrl?: string;
+	refreshUrl?: string;
+	scopes: string[];
+};
+
+export type OAuthFlows = Partial<
+	Record<
+		"implicit" | "password" | "clientCredentials" | "authorizationCode",
+		OAuthFlow
+	>
+>;
+
+type RawOAuthFlow = {
+	authorizationUrl?: unknown;
+	tokenUrl?: unknown;
+	refreshUrl?: unknown;
+	scopes?: unknown;
+};
+
+type RawOAuthFlows = {
+	implicit?: RawOAuthFlow;
+	password?: RawOAuthFlow;
+	clientCredentials?: RawOAuthFlow;
+	authorizationCode?: RawOAuthFlow;
+};
+
+type RawSecurityScheme = {
+	type?: string;
+	description?: string;
+	name?: string;
+	in?: string;
+	scheme?: string;
+	bearerFormat?: string;
+	flows?: RawOAuthFlows;
+	openIdConnectUrl?: string;
+};
+
+function parseOAuthFlow(flow: RawOAuthFlow | undefined): OAuthFlow | undefined {
+	if (!flow) return undefined;
+	const scopesObj = flow.scopes;
+	const scopes =
+		scopesObj && typeof scopesObj === "object" && !Array.isArray(scopesObj)
+			? Object.keys(scopesObj as Record<string, unknown>)
+			: [];
+
+	return {
+		authorizationUrl:
+			typeof flow.authorizationUrl === "string"
+				? flow.authorizationUrl
+				: undefined,
+		tokenUrl: typeof flow.tokenUrl === "string" ? flow.tokenUrl : undefined,
+		refreshUrl:
+			typeof flow.refreshUrl === "string" ? flow.refreshUrl : undefined,
+		scopes: scopes.sort(),
+	};
+}
+
+function parseOAuthFlows(
+	flows: RawOAuthFlows | undefined,
+): OAuthFlows | undefined {
+	if (!flows) return undefined;
+	const out: OAuthFlows = {};
+
+	const implicit = parseOAuthFlow(flows.implicit);
+	if (implicit) out.implicit = implicit;
+
+	const password = parseOAuthFlow(flows.password);
+	if (password) out.password = password;
+
+	const clientCredentials = parseOAuthFlow(flows.clientCredentials);
+	if (clientCredentials) out.clientCredentials = clientCredentials;
+
+	const authorizationCode = parseOAuthFlow(flows.authorizationCode);
+	if (authorizationCode) out.authorizationCode = authorizationCode;
+
+	return Object.keys(out).length ? out : undefined;
+}
+
+export function listAuthSchemes(doc: OpenApiDoc): AuthScheme[] {
+	const schemes = doc.components?.securitySchemes;
+	if (!schemes || typeof schemes !== "object") return [];
+
+	const out: AuthScheme[] = [];
+
+	for (const [key, raw] of Object.entries(schemes)) {
+		if (!raw || typeof raw !== "object") continue;
+		const s = raw as RawSecurityScheme;
+
+		const type = s.type;
+		if (type === "http") {
+			const scheme = (s.scheme ?? "").toLowerCase();
+			if (scheme === "bearer") {
+				out.push({
+					key,
+					kind: "http-bearer",
+					scheme: scheme,
+					bearerFormat: s.bearerFormat,
+					description: s.description,
+				});
+			} else if (scheme === "basic") {
+				out.push({
+					key,
+					kind: "http-basic",
+					scheme: scheme,
+					description: s.description,
+				});
+			} else {
+				out.push({
+					key,
+					kind: "unknown",
+					scheme: s.scheme,
+					description: s.description,
+				});
+			}
+			continue;
+		}
+
+		if (type === "apiKey") {
+			const where = s.in;
+			const loc =
+				where === "header" || where === "query" || where === "cookie"
+					? where
+					: undefined;
+			out.push({
+				key,
+				kind: "api-key",
+				name: s.name,
+				in: loc,
+				description: s.description,
+			});
+			continue;
+		}
+
+		if (type === "oauth2") {
+			out.push({
+				key,
+				kind: "oauth2",
+				description: s.description,
+				oauthFlows: parseOAuthFlows(s.flows),
+			});
+			continue;
+		}
+
+		if (type === "openIdConnect") {
+			out.push({
+				key,
+				kind: "openIdConnect",
+				description: s.description,
+				openIdConnectUrl: s.openIdConnectUrl,
+			});
+			continue;
+		}
+
+		out.push({ key, kind: "unknown", description: s.description });
+	}
+
+	// Stable order.
+	out.sort((a, b) => kebabCase(a.key).localeCompare(kebabCase(b.key)));
+	return out;
+}

package/src/cli/capabilities.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from "bun:test";
+import type { AuthScheme } from "./auth-schemes.ts";
+import { deriveCapabilities } from "./capabilities.ts";
+import type { CommandModel } from "./command-model.ts";
+import type { ServerInfo } from "./server.ts";
+import type { NormalizedOperation, OpenApiDoc } from "./types.ts";
+
+describe("deriveCapabilities", () => {
+	test("reports requestBody + server vars", () => {
+		const doc: OpenApiDoc = {
+			openapi: "3.0.3",
+			security: [{ bearerAuth: [] }],
+		};
+
+		const servers: ServerInfo[] = [
+			{
+				url: "https://{region}.api.example.com",
+				variables: [],
+				variableNames: ["region"],
+			},
+		];
+
+		const authSchemes: AuthScheme[] = [
+			{ key: "bearerAuth", kind: "http-bearer" },
+		];
+
+		const operations: NormalizedOperation[] = [
+			{
+				key: "POST /contacts",
+				method: "POST",
+				path: "/contacts",
+				tags: [],
+				parameters: [],
+				requestBody: {
+					required: true,
+					contentTypes: ["application/json"],
+					schemasByContentType: { "application/json": { type: "object" } },
+				},
+			},
+		];
+
+		const commands: CommandModel = {
+			resources: [
+				{
+					resource: "contacts",
+					actions: [
+						{
+							id: "x",
+							key: "POST /contacts",
+							action: "create",
+							pathArgs: [],
+							method: "POST",
+							path: "/contacts",
+							tags: [],
+							style: "rest",
+							positionals: [],
+							flags: [],
+							params: [],
+							auth: { alternatives: [] },
+							requestBody: {
+								required: true,
+								content: [
+									{
+										contentType: "application/json",
+										required: true,
+										schemaType: "object",
+									},
+								],
+								hasJson: true,
+								hasFormUrlEncoded: false,
+								hasMultipart: false,
+								bodyFlags: ["--data", "--file"],
+								preferredContentType: "application/json",
+							},
+						},
+					],
+				},
+			],
+		};
+
+		const caps = deriveCapabilities({
+			doc,
+			servers,
+			authSchemes,
+			operations,
+			commands,
+		});
+		expect(caps.servers.hasVariables).toBe(true);
+		expect(caps.operations.hasRequestBodies).toBe(true);
+		expect(caps.commands.hasRequestBodies).toBe(true);
+		expect(caps.auth.hasSecurityRequirements).toBe(true);
+		expect(caps.auth.kinds).toEqual(["http-bearer"]);
+	});
+});

package/src/cli/capabilities.ts

@@ -0,0 +1,88 @@
+import type { AuthScheme, AuthSchemeKind } from "./auth-schemes.ts";
+import type { CommandModel } from "./command-model.ts";
+import type { ServerInfo } from "./server.ts";
+import type {
+	NormalizedOperation,
+	OpenApiDoc,
+	SecurityRequirement,
+} from "./types.ts";
+
+export type Capabilities = {
+	servers: {
+		count: number;
+		hasVariables: boolean;
+	};
+	auth: {
+		count: number;
+		kinds: AuthSchemeKind[];
+		hasSecurityRequirements: boolean;
+	};
+	operations: {
+		count: number;
+		hasRequestBodies: boolean;
+	};
+	commands: {
+		countResources: number;
+		countActions: number;
+		hasRequestBodies: boolean;
+	};
+};
+
+function uniqueSorted<T>(items: T[], compare: (a: T, b: T) => number): T[] {
+	const out = [...items];
+	out.sort(compare);
+	return out.filter((v, i) => i === 0 || compare(out[i - 1] as T, v) !== 0);
+}
+
+function hasSecurity(requirements: SecurityRequirement[] | undefined): boolean {
+	if (!requirements?.length) return false;
+
+	// Treat any non-empty array as "auth exists", even if it contains `{}` to mean optional.
+	return true;
+}
+
+export function deriveCapabilities(input: {
+	doc: OpenApiDoc;
+	servers: ServerInfo[];
+	authSchemes: AuthScheme[];
+	operations: NormalizedOperation[];
+	commands?: CommandModel;
+}): Capabilities {
+	const serverHasVars = input.servers.some((s) => s.variableNames.length > 0);
+
+	const authKinds = uniqueSorted(
+		input.authSchemes.map((s) => s.kind),
+		(a, b) => a.localeCompare(b),
+	);
+
+	const hasSecurityRequirements =
+		hasSecurity(input.doc.security) ||
+		input.operations.some((op) => hasSecurity(op.security));
+
+	const opHasBodies = input.operations.some((op) => Boolean(op.requestBody));
+
+	const cmdResources = input.commands?.resources ?? [];
+	const cmdActions = cmdResources.flatMap((r) => r.actions);
+	const cmdHasBodies = cmdActions.some((a) => Boolean(a.requestBody));
+
+	return {
+		servers: {
+			count: input.servers.length,
+			hasVariables: serverHasVars,
+		},
+		auth: {
+			count: input.authSchemes.length,
+			kinds: authKinds,
+			hasSecurityRequirements,
+		},
+		operations: {
+			count: input.operations.length,
+			hasRequestBodies: opHasBodies,
+		},
+		commands: {
+			countResources: cmdResources.length,
+			countActions: cmdActions.length,
+			hasRequestBodies: cmdHasBodies,
+		},
+	};
+}

package/src/cli/command-id.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from "bun:test";
+
+import { buildCommandId } from "./command-id.ts";
+
+describe("buildCommandId", () => {
+	test("includes spec/resource/action/op", () => {
+		expect(
+			buildCommandId({
+				specId: "contacts-api",
+				resource: "contacts",
+				action: "get",
+				operationKey: "GET /contacts/{id}",
+			}),
+		).toBe("contacts-api:contacts:get:get-contacts-id");
+	});
+
+	test("disambiguates by operationKey", () => {
+		const a = buildCommandId({
+			specId: "x",
+			resource: "contacts",
+			action: "list",
+			operationKey: "GET /contacts",
+		});
+		const b = buildCommandId({
+			specId: "x",
+			resource: "contacts",
+			action: "list",
+			operationKey: "GET /contacts/search",
+		});
+		expect(a).not.toBe(b);
+	});
+});

package/src/cli/command-id.ts

@@ -0,0 +1,16 @@
+import { kebabCase } from "./strings.ts";
+
+export type CommandIdParts = {
+	specId: string;
+	resource: string;
+	action: string;
+	operationKey: string;
+};
+
+export function buildCommandId(parts: CommandIdParts): string {
+	// operationKey is the ultimate disambiguator, but we keep the id readable.
+	// Example:
+	//   contacts-api:contacts:get:GET-/contacts/{id}
+	const op = kebabCase(parts.operationKey.replace(/\s+/g, "-"));
+	return `${parts.specId}:${kebabCase(parts.resource)}:${kebabCase(parts.action)}:${op}`;
+}

package/src/cli/command-index.ts

@@ -0,0 +1,19 @@
+import type { CommandAction, CommandModel } from "./command-model.ts";
+
+export type CommandsIndex = {
+	byId: Record<string, CommandAction>;
+};
+
+export function buildCommandsIndex(
+	commands: CommandModel | undefined,
+): CommandsIndex {
+	const byId: Record<string, CommandAction> = {};
+
+	for (const resource of commands?.resources ?? []) {
+		for (const action of resource.actions) {
+			byId[action.id] = action;
+		}
+	}
+
+	return { byId };
+}

package/src/cli/command-model.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+
+import { buildCommandModel } from "./command-model.ts";
+import type { PlannedOperation } from "./naming.ts";
+
+describe("buildCommandModel", () => {
+	test("groups operations by resource", () => {
+		const planned: PlannedOperation[] = [
+			{
+				key: "GET /contacts",
+				method: "GET",
+				path: "/contacts",
+				tags: ["Contacts"],
+				parameters: [],
+				resource: "contacts",
+				action: "list",
+				canonicalAction: "list",
+				pathArgs: [],
+				style: "rest",
+			},
+			{
+				key: "GET /contacts/{id}",
+				method: "GET",
+				path: "/contacts/{id}",
+				tags: ["Contacts"],
+				parameters: [],
+				resource: "contacts",
+				action: "get",
+				canonicalAction: "get",
+				pathArgs: ["id"],
+				style: "rest",
+			},
+		];
+
+		const model = buildCommandModel(planned, { specId: "contacts-api" });
+		expect(model.resources).toHaveLength(1);
+		expect(model.resources[0]?.resource).toBe("contacts");
+		expect(model.resources[0]?.actions).toHaveLength(2);
+		expect(model.resources[0]?.actions.map((a) => a.action)).toEqual([
+			"get",
+			"list",
+		]);
+	});
+});

package/src/cli/command-model.ts

@@ -0,0 +1,128 @@
+import type { AuthSummary } from "./auth-requirements.ts";
+import { summarizeAuth } from "./auth-requirements.ts";
+import type { AuthScheme } from "./auth-schemes.ts";
+import { buildCommandId } from "./command-id.ts";
+import type { PlannedOperation } from "./naming.ts";
+import type { ParamSpec } from "./params.ts";
+import { deriveParamSpecs } from "./params.ts";
+import { deriveFlags, derivePositionals } from "./positional.ts";
+import type { RequestBodyInfo } from "./request-body.ts";
+import { deriveRequestBodyInfo } from "./request-body.ts";
+import type { SecurityRequirement } from "./types.ts";
+
+export type CommandAction = {
+	id: string;
+	key: string;
+	action: string;
+	// Derived path arguments. These become positionals later.
+	pathArgs: string[];
+	method: string;
+	path: string;
+	operationId?: string;
+	tags: string[];
+	summary?: string;
+	description?: string;
+	deprecated?: boolean;
+	style: PlannedOperation["style"];
+
+	// Derived CLI shape (Phase 1 output; Phase 2 will wire these into commander)
+	positionals: Array<import("./positional.ts").PositionalArg>;
+	flags: Array<
+		Pick<
+			import("./params.ts").ParamSpec,
+			| "in"
+			| "name"
+			| "flag"
+			| "required"
+			| "description"
+			| "type"
+			| "format"
+			| "enum"
+			| "itemType"
+			| "itemFormat"
+			| "itemEnum"
+		>
+	>;
+
+	// Full raw params list (useful for debugging and future features)
+	params: ParamSpec[];
+
+	auth: AuthSummary;
+	requestBody?: RequestBodyInfo;
+	requestBodySchema?: import("./types.ts").JsonSchema;
+};
+
+export type CommandResource = {
+	resource: string;
+	actions: CommandAction[];
+};
+
+export type CommandModel = {
+	resources: CommandResource[];
+};
+
+export type BuildCommandModelOptions = {
+	specId: string;
+	globalSecurity?: SecurityRequirement[];
+	authSchemes?: AuthScheme[];
+};
+
+export function buildCommandModel(
+	planned: PlannedOperation[],
+	options: BuildCommandModelOptions,
+): CommandModel {
+	const byResource = new Map<string, CommandAction[]>();
+
+	for (const op of planned) {
+		const list = byResource.get(op.resource) ?? [];
+		const params = deriveParamSpecs(op);
+		const positionals = derivePositionals({ pathArgs: op.pathArgs, params });
+		const flags = deriveFlags({ pathArgs: op.pathArgs, params });
+
+		list.push({
+			id: buildCommandId({
+				specId: options.specId,
+				resource: op.resource,
+				action: op.action,
+				operationKey: op.key,
+			}),
+			key: op.key,
+			action: op.action,
+			pathArgs: op.pathArgs,
+			method: op.method,
+			path: op.path,
+			operationId: op.operationId,
+			tags: op.tags,
+			summary: op.summary,
+			description: op.description,
+			deprecated: op.deprecated,
+			style: op.style,
+			params,
+			positionals,
+			flags: flags.flags,
+			auth: summarizeAuth(
+				op.security,
+				options.globalSecurity,
+				options.authSchemes ?? [],
+			),
+			requestBody: deriveRequestBodyInfo(op),
+			requestBodySchema: deriveRequestBodyInfo(op)?.preferredSchema,
+		});
+		byResource.set(op.resource, list);
+	}
+
+	const resources: CommandResource[] = [];
+
+	for (const [resource, actions] of byResource.entries()) {
+		actions.sort((a, b) => {
+			if (a.action !== b.action) return a.action.localeCompare(b.action);
+			if (a.path !== b.path) return a.path.localeCompare(b.path);
+			return a.method.localeCompare(b.method);
+		});
+		resources.push({ resource, actions });
+	}
+
+	resources.sort((a, b) => a.resource.localeCompare(b.resource));
+
+	return { resources };
+}