specli 0.0.1

package/src/cli/positional.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "bun:test";
+import type { ActionShapeForCli } from "./positional.ts";
+import { deriveFlags, derivePositionals } from "./positional.ts";
+
+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.ts";
+
+export type ActionShapeForCli = {
+	pathArgs: string[];
+	params: ParamSpec[];
+};
+
+export type PositionalArg = {
+	name: string;
+	required: boolean;
+	description?: string;
+	type: import("./schema-shape.ts").ParamType;
+	format?: string;
+	enum?: string[];
+};
+
+export type FlagsIndex = {
+	flags: Array<
+		Pick<
+			import("./params.ts").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.ts";
+import type { NormalizedOperation } from "./types.ts";
+
+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.ts";
+import type {
+	JsonSchema,
+	NormalizedOperation,
+	NormalizedRequestBody,
+} from "./types.ts";
+import { isJsonSchema } from "./types.ts";
+
+export type RequestBodyContent = {
+	contentType: string;
+	required: boolean;
+	schemaType: import("./schema-shape.ts").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,31 @@
+import type { AuthScheme } from "../../auth-schemes.ts";
+
+export type AuthInputs = {
+	profileAuthScheme?: string;
+	flagAuthScheme?: string;
+};
+
+export function resolveAuthScheme(
+	authSchemes: AuthScheme[],
+	required: import("../../auth-requirements.ts").AuthSummary,
+	inputs: AuthInputs,
+): string | undefined {
+	// Explicit flag wins (but may still be validated later when applying).
+	if (inputs.flagAuthScheme) return inputs.flagAuthScheme;
+
+	if (
+		inputs.profileAuthScheme &&
+		authSchemes.some((s) => s.key === inputs.profileAuthScheme)
+	) {
+		return inputs.profileAuthScheme;
+	}
+
+	// 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;
+
+	return undefined;
+}

package/src/cli/runtime/body.ts

@@ -0,0 +1,24 @@
+import { YAML } from "bun";
+
+export type BodyInput =
+	| { kind: "none" }
+	| { kind: "data"; data: string }
+	| { kind: "file"; path: string };
+
+export async function loadBody(
+	input: BodyInput,
+): Promise<{ raw: string; json?: unknown } | undefined> {
+	if (input.kind === "none") return undefined;
+	if (input.kind === "data") return { raw: input.data };
+
+	const text = await Bun.file(input.path).text();
+	return { raw: text };
+}
+
+export function parseBodyAsJsonOrYaml(text: string): unknown {
+	const trimmed = text.trimStart();
+	if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+		return JSON.parse(text);
+	}
+	return YAML.parse(text);
+}

package/src/cli/runtime/collect.ts

@@ -0,0 +1,6 @@
+export function collectRepeatable(
+	value: string,
+	previous: string[] | undefined,
+): string[] {
+	return [...(previous ?? []), value];
+}

package/src/cli/runtime/context.ts

@@ -0,0 +1,62 @@
+import { listAuthSchemes } from "../auth-schemes.ts";
+import { deriveCapabilities } from "../capabilities.ts";
+import { buildCommandsIndex } from "../command-index.ts";
+import { buildCommandModel } from "../command-model.ts";
+import { planOperations } from "../naming.ts";
+import { indexOperations } from "../operations.ts";
+import { buildSchemaOutput } from "../schema.ts";
+import { listServers } from "../server.ts";
+import { loadSpec } from "../spec-loader.ts";
+
+export type BuildRuntimeContextOptions = {
+	spec?: string;
+	embeddedSpecText?: string;
+};
+
+export async function buildRuntimeContext(options: BuildRuntimeContextOptions) {
+	const loaded = await loadSpec({
+		spec: options.spec,
+		embeddedSpecText: options.embeddedSpecText,
+	});
+
+	const operations = indexOperations(loaded.doc);
+	const servers = listServers(loaded.doc);
+	const authSchemes = listAuthSchemes(loaded.doc);
+	const planned = planOperations(operations);
+	const commands = buildCommandModel(planned, {
+		specId: loaded.id,
+		globalSecurity: loaded.doc.security,
+		authSchemes,
+	});
+	const commandsIndex = buildCommandsIndex(commands);
+	const capabilities = deriveCapabilities({
+		doc: loaded.doc,
+		servers,
+		authSchemes,
+		operations,
+		commands,
+	});
+
+	const schema = buildSchemaOutput(
+		loaded,
+		operations,
+		planned,
+		servers,
+		authSchemes,
+		commands,
+		commandsIndex,
+		capabilities,
+	);
+
+	return {
+		loaded,
+		operations,
+		servers,
+		authSchemes,
+		planned,
+		commands,
+		commandsIndex,
+		capabilities,
+		schema,
+	};
+}

package/src/cli/runtime/execute.ts

@@ -0,0 +1,138 @@
+import type { CommandAction } from "../command-model.ts";
+
+import { buildRequest } from "./request.ts";
+
+export type ExecuteInput = {
+	action: CommandAction;
+	positionalValues: string[];
+	flagValues: Record<string, unknown>;
+	globals: import("./request.ts").RuntimeGlobals;
+	servers: import("../server.ts").ServerInfo[];
+	authSchemes: import("../auth-schemes.ts").AuthScheme[];
+	specId: string;
+};
+
+export async function executeAction(input: ExecuteInput): Promise<void> {
+	try {
+		const { request, curl } = await buildRequest({
+			specId: input.specId,
+			action: input.action,
+			positionalValues: input.positionalValues,
+			flagValues: input.flagValues,
+			globals: input.globals,
+			servers: input.servers,
+			authSchemes: input.authSchemes,
+		});
+
+		if (input.globals.curl || input.globals.ocCurl) {
+			process.stdout.write(`${curl}\n`);
+			return;
+		}
+
+		if (input.globals.dryRun || input.globals.ocDryRun) {
+			process.stdout.write(`${request.method} ${request.url}\n`);
+			for (const [k, v] of request.headers.entries()) {
+				process.stdout.write(`${k}: ${v}\n`);
+			}
+			if (request.body) {
+				const text = await request.clone().text();
+				if (text) process.stdout.write(`\n${text}\n`);
+			}
+			return;
+		}
+
+		const timeoutMs = input.globals.timeout
+			? Number(input.globals.timeout)
+			: input.globals.ocTimeout
+				? Number(input.globals.ocTimeout)
+				: undefined;
+		let timeout: Timer | undefined;
+		let controller: AbortController | undefined;
+		if (timeoutMs && Number.isFinite(timeoutMs) && timeoutMs > 0) {
+			controller = new AbortController();
+			timeout = setTimeout(() => controller?.abort(), timeoutMs);
+		}
+
+		try {
+			const res = await fetch(request, { signal: controller?.signal });
+			const contentType = res.headers.get("content-type") ?? "";
+			const status = res.status;
+
+			const text = await res.text();
+			let body: unknown = text;
+			let parsedJson: unknown | undefined;
+
+			if (contentType.includes("json")) {
+				try {
+					parsedJson = text ? JSON.parse(text) : null;
+					body = parsedJson;
+				} catch {
+					// keep as text
+				}
+			}
+
+			if (!res.ok) {
+				if (input.globals.json) {
+					process.stdout.write(
+						`${JSON.stringify({
+							status,
+							body,
+							headers:
+								input.globals.headers || input.globals.ocHeaders
+									? Object.fromEntries(res.headers.entries())
+									: undefined,
+						})}\n`,
+					);
+				} else {
+					process.stderr.write(`HTTP ${status}\n`);
+					process.stderr.write(
+						`${typeof body === "string" ? body : JSON.stringify(body, null, 2)}\n`,
+					);
+				}
+				process.exitCode = 1;
+				return;
+			}
+
+			if (input.globals.json) {
+				const payload: unknown =
+					input.globals.status ||
+					input.globals.headers ||
+					input.globals.ocStatus ||
+					input.globals.ocHeaders
+						? {
+								status:
+									input.globals.status || input.globals.ocStatus
+										? status
+										: undefined,
+								headers:
+									input.globals.headers || input.globals.ocHeaders
+										? Object.fromEntries(res.headers.entries())
+										: undefined,
+								body,
+							}
+						: body;
+
+				process.stdout.write(`${JSON.stringify(payload)}\n`);
+				return;
+			}
+
+			// default (human + agent readable)
+			if (typeof parsedJson !== "undefined") {
+				process.stdout.write(`${JSON.stringify(parsedJson, null, 2)}\n`);
+			} else {
+				process.stdout.write(text);
+				if (!text.endsWith("\n")) process.stdout.write("\n");
+			}
+		} finally {
+			if (timeout) clearTimeout(timeout);
+		}
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		if (input.globals.json) {
+			process.stdout.write(`${JSON.stringify({ error: message })}\n`);
+		} else {
+			process.stderr.write(`error: ${message}\n`);
+		}
+		process.exitCode = 1;
+	}
+}