specli 0.0.1

package/src/cli/runtime/generated.ts

@@ -0,0 +1,200 @@
+import { Command } from "commander";
+
+import type { AuthScheme } from "../auth-schemes.ts";
+import type { CommandModel } from "../command-model.ts";
+import type { ServerInfo } from "../server.ts";
+
+import { collectRepeatable } from "./collect.ts";
+import { executeAction } from "./execute.ts";
+import { coerceArrayInput, coerceValue } from "./validate/index.ts";
+
+export type GeneratedCliContext = {
+	servers: ServerInfo[];
+	authSchemes: AuthScheme[];
+	commands: CommandModel;
+	specId: string;
+};
+
+export function addGeneratedCommands(
+	program: Command,
+	context: GeneratedCliContext,
+): void {
+	for (const resource of context.commands.resources) {
+		const resourceCmd = program
+			.command(resource.resource)
+			.description(`Operations for ${resource.resource}`);
+
+		for (const action of resource.actions) {
+			const cmd = resourceCmd.command(action.action);
+			cmd.description(
+				action.summary ??
+					action.description ??
+					`${action.method} ${action.path}`,
+			);
+
+			for (const pos of action.positionals) {
+				cmd.argument(`<${pos.name}>`, pos.description);
+			}
+
+			for (const flag of action.flags) {
+				const opt = flag.flag;
+				const desc = flag.description ?? `${flag.in} parameter`;
+
+				if (flag.type === "boolean") {
+					cmd.option(opt, desc);
+					continue;
+				}
+
+				const isArray = flag.type === "array";
+				const itemType = flag.itemType ?? "string";
+				const parser = (raw: string) => coerceValue(raw, itemType);
+
+				if (isArray) {
+					const key = `${opt} <value>`;
+					cmd.option(
+						key,
+						desc,
+						(value: string, prev: unknown[] | undefined) => {
+							const next: unknown[] = [...(prev ?? [])];
+
+							// Allow `--tags a,b` and `--tags '["a","b"]'` to expand.
+							const items = coerceArrayInput(value, itemType);
+							for (const item of items) {
+								next.push(item);
+							}
+
+							return next;
+						},
+					);
+					continue;
+				}
+
+				const key = `${opt} <value>`;
+				if (flag.required) cmd.requiredOption(key, desc, parser);
+				else cmd.option(key, desc, parser);
+			}
+
+			const reservedFlags = new Set(action.flags.map((f) => f.flag));
+
+			// Common curl-replacement options.
+			// Some APIs have parameters like `accept`, `timeout`, etc. We always add
+			// namespaced variants (`--oc-*`) and only add the short versions when they
+			// do not conflict with operation flags.
+			cmd
+				.option(
+					"--oc-header <header>",
+					"Extra header (repeatable)",
+					collectRepeatable,
+				)
+				.option("--oc-accept <type>", "Override Accept header")
+				.option("--oc-status", "Include status in --json output")
+				.option("--oc-headers", "Include headers in --json output")
+				.option("--oc-dry-run", "Print request without sending")
+				.option("--oc-curl", "Print curl command without sending")
+				.option("--oc-timeout <ms>", "Request timeout in milliseconds");
+
+			if (!reservedFlags.has("--header")) {
+				cmd.option(
+					"--header <header>",
+					"Extra header (repeatable)",
+					collectRepeatable,
+				);
+			}
+			if (!reservedFlags.has("--accept")) {
+				cmd.option("--accept <type>", "Override Accept header");
+			}
+			if (!reservedFlags.has("--status")) {
+				cmd.option("--status", "Include status in --json output");
+			}
+			if (!reservedFlags.has("--headers")) {
+				cmd.option("--headers", "Include headers in --json output");
+			}
+			if (!reservedFlags.has("--dry-run")) {
+				cmd.option("--dry-run", "Print request without sending");
+			}
+			if (!reservedFlags.has("--curl")) {
+				cmd.option("--curl", "Print curl command without sending");
+			}
+			if (!reservedFlags.has("--timeout")) {
+				cmd.option("--timeout <ms>", "Request timeout in milliseconds");
+			}
+
+			if (action.requestBody) {
+				cmd
+					.option("--oc-data <data>", "Inline request body")
+					.option("--oc-file <path>", "Request body from file")
+					.option(
+						"--oc-content-type <type>",
+						"Override Content-Type (defaults from OpenAPI)",
+					);
+
+				if (!reservedFlags.has("--data")) {
+					cmd.option("--data <data>", "Inline request body");
+				}
+				if (!reservedFlags.has("--file")) {
+					cmd.option("--file <path>", "Request body from file");
+				}
+				if (!reservedFlags.has("--content-type")) {
+					cmd.option(
+						"--content-type <type>",
+						"Override Content-Type (defaults from OpenAPI)",
+					);
+				}
+
+				// Expanded JSON body flags (only for simple object bodies).
+				const schema = action.requestBodySchema;
+				if (schema && schema.type === "object" && schema.properties) {
+					for (const [name, propSchema] of Object.entries(schema.properties)) {
+						if (!name || typeof name !== "string") continue;
+						if (!propSchema || typeof propSchema !== "object") continue;
+						const t = (propSchema as { type?: unknown }).type;
+						if (
+							t !== "string" &&
+							t !== "number" &&
+							t !== "integer" &&
+							t !== "boolean"
+						) {
+							continue;
+						}
+
+						const flagName = `--body-${name}`;
+						if (t === "boolean") {
+							cmd.option(flagName, `Body field '${name}'`);
+						} else {
+							cmd.option(`${flagName} <value>`, `Body field '${name}'`);
+						}
+					}
+				}
+			}
+
+			// Commander passes positional args and then the Command instance as last arg.
+			cmd.action(async (...args) => {
+				const command = args[args.length - 1];
+				const positionalValues = args.slice(0, -1).map((v) => String(v));
+
+				if (!(command instanceof Command)) {
+					throw new Error("Unexpected commander action signature");
+				}
+
+				const globals = command.optsWithGlobals();
+				const local = command.opts();
+
+				const bodyFlags: Record<string, unknown> = {};
+				for (const key of Object.keys(local)) {
+					if (!key.startsWith("body")) continue;
+					bodyFlags[key] = local[key];
+				}
+
+				await executeAction({
+					action,
+					positionalValues,
+					flagValues: { ...local, __body: bodyFlags },
+					globals,
+					servers: context.servers,
+					authSchemes: context.authSchemes,
+					specId: context.specId,
+				});
+			});
+		}
+	}
+}

package/src/cli/runtime/headers.ts

@@ -0,0 +1,37 @@
+export function parseHeaderInput(input: string): {
+	name: string;
+	value: string;
+} {
+	const trimmed = input.trim();
+	if (!trimmed) throw new Error("Empty header");
+
+	// Support either "Name: Value" or "Name=Value".
+	const colon = trimmed.indexOf(":");
+	if (colon !== -1) {
+		const name = trimmed.slice(0, colon).trim();
+		const value = trimmed.slice(colon + 1).trim();
+		if (!name) throw new Error("Invalid header name");
+		return { name, value };
+	}
+
+	const eq = trimmed.indexOf("=");
+	if (eq !== -1) {
+		const name = trimmed.slice(0, eq).trim();
+		const value = trimmed.slice(eq + 1).trim();
+		if (!name) throw new Error("Invalid header name");
+		return { name, value };
+	}
+
+	throw new Error("Invalid header format. Use 'Name: Value' or 'Name=Value'.");
+}
+
+export function mergeHeaders(
+	base: Headers,
+	entries: Array<{ name: string; value: string }>,
+): Headers {
+	const h = new Headers(base);
+	for (const { name, value } of entries) {
+		h.set(name, value);
+	}
+	return h;
+}

package/src/cli/runtime/index.ts

@@ -0,0 +1,3 @@
+export * from "./argv.ts";
+export * from "./context.ts";
+export * from "./generated.ts";

package/src/cli/runtime/profile/secrets.ts

@@ -0,0 +1,42 @@
+import { secrets } from "bun";
+
+export type SecretKey = {
+	service: string;
+	name: string;
+};
+
+export function secretServiceForSpec(specId: string): string {
+	return `opencli:${specId}`;
+}
+
+export function tokenSecretKey(specId: string, profile: string): SecretKey {
+	return {
+		service: secretServiceForSpec(specId),
+		name: `profile:${profile}:token`,
+	};
+}
+
+export async function setToken(
+	specId: string,
+	profile: string,
+	token: string,
+): Promise<void> {
+	const key = tokenSecretKey(specId, profile);
+	await secrets.set({ service: key.service, name: key.name, value: token });
+}
+
+export async function getToken(
+	specId: string,
+	profile: string,
+): Promise<string | null> {
+	const key = tokenSecretKey(specId, profile);
+	return await secrets.get({ service: key.service, name: key.name });
+}
+
+export async function deleteToken(
+	specId: string,
+	profile: string,
+): Promise<boolean> {
+	const key = tokenSecretKey(specId, profile);
+	return await secrets.delete({ service: key.service, name: key.name });
+}

package/src/cli/runtime/profile/store.ts

@@ -0,0 +1,98 @@
+import { YAML } from "bun";
+
+export type Profile = {
+	name: string;
+	server?: string;
+	authScheme?: string;
+	// For apiKey schemes we also need the apiKey name/in from spec to inject,
+	// but that is discoverable from the spec at runtime.
+};
+
+export type ProfilesFile = {
+	profiles: Profile[];
+	defaultProfile?: string;
+};
+
+function configDir(): string {
+	// Keep it simple (v1). We can move to env-paths later.
+	const home = process.env.HOME;
+	if (!home) throw new Error("Missing HOME env var");
+	return `${home}/.config/opencli`;
+}
+
+function configPathJson(): string {
+	return `${configDir()}/profiles.json`;
+}
+
+function configPathYaml(): string {
+	return `${configDir()}/profiles.yaml`;
+}
+
+export async function readProfiles(): Promise<ProfilesFile> {
+	const jsonPath = configPathJson();
+	const yamlPath = configPathYaml();
+
+	const jsonFile = Bun.file(jsonPath);
+	const yamlFile = Bun.file(yamlPath);
+
+	const file = (await jsonFile.exists())
+		? jsonFile
+		: (await yamlFile.exists())
+			? yamlFile
+			: null;
+
+	if (!file) return { profiles: [] };
+
+	const text = await file.text();
+	let parsed: unknown;
+	try {
+		parsed = YAML.parse(text) as unknown;
+	} catch {
+		parsed = JSON.parse(text) as unknown;
+	}
+
+	const obj =
+		parsed && typeof parsed === "object"
+			? (parsed as Record<string, unknown>)
+			: {};
+	const profiles = Array.isArray(obj.profiles)
+		? (obj.profiles as Profile[])
+		: [];
+
+	return {
+		profiles: profiles.filter(Boolean),
+		defaultProfile:
+			typeof obj.defaultProfile === "string"
+				? (obj.defaultProfile as string)
+				: undefined,
+	};
+}
+
+export async function writeProfiles(data: ProfilesFile): Promise<void> {
+	const dir = configDir();
+	await Bun.$`mkdir -p ${dir}`;
+	await Bun.write(configPathJson(), JSON.stringify(data, null, 2));
+}
+
+export function getProfile(
+	data: ProfilesFile,
+	name: string | undefined,
+): Profile | undefined {
+	const wanted = name ?? data.defaultProfile;
+	if (!wanted) return undefined;
+	return data.profiles.find((p) => p?.name === wanted);
+}
+
+export function upsertProfile(
+	data: ProfilesFile,
+	profile: Profile,
+): ProfilesFile {
+	const profiles = data.profiles.filter((p) => p.name !== profile.name);
+	profiles.push(profile);
+	profiles.sort((a, b) => a.name.localeCompare(b.name));
+	return { ...data, profiles };
+}
+
+export function removeProfile(data: ProfilesFile, name: string): ProfilesFile {
+	return { ...data, profiles: data.profiles.filter((p) => p.name !== name) };
+}

package/src/cli/runtime/request.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, test } from "bun:test";
+
+import { tmpdir } from "node:os";
+
+import type { CommandAction } from "../command-model.ts";
+
+import { buildRequest } from "./request.ts";
+import { createAjv, formatAjvErrors } from "./validate/index.ts";
+
+function makeAction(partial?: Partial<CommandAction>): CommandAction {
+	return {
+		id: "test",
+		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",
+			preferredSchema: undefined,
+		},
+		requestBodySchema: {
+			type: "object",
+			properties: {
+				name: { type: "string" },
+			},
+			required: ["name"],
+		},
+		...partial,
+	};
+}
+
+describe("buildRequest (requestBody)", () => {
+	test("builds body from expanded --body-* flags", async () => {
+		const prevHome = process.env.HOME;
+		const home = `${tmpdir()}/opencli-test-${crypto.randomUUID()}`;
+		process.env.HOME = home;
+
+		try {
+			const { request, curl } = await buildRequest({
+				specId: "spec",
+				action: makeAction(),
+				positionalValues: [],
+				flagValues: { __body: { bodyName: "A" } },
+				globals: {},
+				servers: [
+					{ url: "https://api.example.com", variables: [], variableNames: [] },
+				],
+				authSchemes: [],
+			});
+
+			expect(request.headers.get("Content-Type")).toBe("application/json");
+			expect(await request.clone().text()).toBe('{"name":"A"}');
+			expect(curl).toContain("--data");
+			expect(curl).toContain('{"name":"A"}');
+		} finally {
+			process.env.HOME = prevHome;
+		}
+	});
+
+	test("throws when requestBody is required but missing", async () => {
+		const prevHome = process.env.HOME;
+		const home = `${tmpdir()}/opencli-test-${crypto.randomUUID()}`;
+		process.env.HOME = home;
+
+		try {
+			await expect(() =>
+				buildRequest({
+					specId: "spec",
+					action: makeAction(),
+					positionalValues: [],
+					flagValues: {},
+					globals: {},
+					servers: [
+						{
+							url: "https://api.example.com",
+							variables: [],
+							variableNames: [],
+						},
+					],
+					authSchemes: [],
+				}),
+			).toThrow(
+				"Missing request body. Provide --data, --file, or --body-* flags.",
+			);
+		} finally {
+			process.env.HOME = prevHome;
+		}
+	});
+
+	test("throws friendly error for missing required expanded field", async () => {
+		const prevHome = process.env.HOME;
+		const home = `${tmpdir()}/opencli-test-${crypto.randomUUID()}`;
+		process.env.HOME = home;
+
+		try {
+			await expect(() =>
+				buildRequest({
+					specId: "spec",
+					action: makeAction(),
+					positionalValues: [],
+					flagValues: { __body: { bodyFoo: "bar" } },
+					globals: {},
+					servers: [
+						{
+							url: "https://api.example.com",
+							variables: [],
+							variableNames: [],
+						},
+					],
+					authSchemes: [],
+				}),
+			).toThrow(
+				"Missing required body field 'name'. Provide --body-name or use --data/--file.",
+			);
+		} finally {
+			process.env.HOME = prevHome;
+		}
+	});
+});
+
+describe("formatAjvErrors", () => {
+	test("pretty prints required errors", () => {
+		const ajv = createAjv();
+		const validate = ajv.compile({
+			type: "object",
+			properties: { name: { type: "string" } },
+			required: ["name"],
+		});
+
+		validate({});
+		const msg = formatAjvErrors(validate.errors);
+		expect(msg).toBe("/ missing required property 'name'");
+	});
+});