specli 0.0.17 → 0.0.18

package/src/cli/exec.ts

@@ -0,0 +1,72 @@
+import { main } from "./main.js";
+
+export type ExecOptions = {
+	server?: string;
+	serverVar?: string[];
+	auth?: string;
+	bearerToken?: string;
+	oauthToken?: string;
+	username?: string;
+	password?: string;
+	apiKey?: string;
+	profile?: string;
+	json?: boolean;
+};
+
+export async function execCommand(
+	spec: string,
+	options: ExecOptions,
+	commandArgs: string[],
+): Promise<void> {
+	// commandArgs includes the spec as first element, filter it out
+	// to get the remaining args (resource, action, etc.)
+	const remainingArgs = commandArgs.slice(1);
+
+	// Reconstruct argv for main():
+	// [node, script, --spec, <spec>, ...options, ...remainingArgs]
+	const argv = [
+		process.argv[0] ?? "bun",
+		process.argv[1] ?? "specli",
+		"--spec",
+		spec,
+	];
+
+	// Add common options back as flags
+	if (options.server) {
+		argv.push("--server", options.server);
+	}
+	if (options.serverVar) {
+		for (const v of options.serverVar) {
+			argv.push("--server-var", v);
+		}
+	}
+	if (options.auth) {
+		argv.push("--auth", options.auth);
+	}
+	if (options.bearerToken) {
+		argv.push("--bearer-token", options.bearerToken);
+	}
+	if (options.oauthToken) {
+		argv.push("--oauth-token", options.oauthToken);
+	}
+	if (options.username) {
+		argv.push("--username", options.username);
+	}
+	if (options.password) {
+		argv.push("--password", options.password);
+	}
+	if (options.apiKey) {
+		argv.push("--api-key", options.apiKey);
+	}
+	if (options.profile) {
+		argv.push("--profile", options.profile);
+	}
+	if (options.json) {
+		argv.push("--json");
+	}
+
+	// Append remaining args (subcommand + its args)
+	argv.push(...remainingArgs);
+
+	await main(argv);
+}

package/src/cli/main.ts

@@ -0,0 +1,255 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+
+import { getArgValue, hasAnyArg } from "./runtime/argv.js";
+import { collectRepeatable } from "./runtime/collect.js";
+
+/**
+ * Reads the version from package.json at runtime.
+ * Used when running in non-compiled mode.
+ */
+function getPackageVersion(): string {
+	try {
+		const currentDir = dirname(fileURLToPath(import.meta.url));
+		const packageJsonPath = join(currentDir, "../../package.json");
+		const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+		return packageJson.version ?? "0.0.0";
+	} catch {
+		return "0.0.0";
+	}
+}
+
+import { readStdinText } from "./runtime/compat.js";
+import { buildRuntimeContext } from "./runtime/context.js";
+import { addGeneratedCommands } from "./runtime/generated.js";
+import { deleteToken, getToken, setToken } from "./runtime/profile/secrets.js";
+import {
+	readProfiles,
+	upsertProfile,
+	writeProfiles,
+} from "./runtime/profile/store.js";
+import { toMinimalSchemaOutput } from "./schema.js";
+import { stableStringify } from "./stable-json.js";
+
+type MainOptions = {
+	embeddedSpecText?: string;
+	cliName?: string;
+	server?: string;
+	serverVars?: string[];
+	auth?: string;
+	version?: string;
+};
+
+export async function main(argv: string[], options: MainOptions = {}) {
+	const program = new Command();
+
+	// Get version - use embedded version if available, otherwise read from package.json
+	const cliVersion = options.version ?? getPackageVersion();
+
+	program
+		.name(options.cliName ?? "specli")
+		.description("Generate a CLI from an OpenAPI spec")
+		.version(cliVersion, "-v, --version", "Output the version number")
+		.option("--spec <urlOrPath>", "OpenAPI URL or file path")
+		.option("--server <url>", "Override server/base URL")
+		.option(
+			"--server-var <name=value>",
+			"Server URL template variable (repeatable)",
+			collectRepeatable,
+		)
+		.option("--auth <scheme>", "Select auth scheme by key")
+		.option("--bearer-token <token>", "Bearer token (Authorization: Bearer)")
+		.option("--oauth-token <token>", "OAuth token (alias of bearer)")
+		.option("--username <username>", "Basic auth username")
+		.option("--password <password>", "Basic auth password")
+		.option("--api-key <key>", "API key value")
+		.option("--json", "Machine-readable output")
+		.showHelpAfterError();
+
+	// If user asks for help and we have no embedded spec and no --spec, show minimal help.
+	const spec = getArgValue(argv, "--spec");
+	const wantsHelp = hasAnyArg(argv, ["-h", "--help"]);
+	if (!spec && !options.embeddedSpecText && wantsHelp) {
+		program.addHelpText(
+			"after",
+			"\nTo see generated commands, run with --spec <url|path>.\n",
+		);
+		program.parse(argv);
+		return;
+	}
+
+	const ctx = await buildRuntimeContext({
+		spec,
+		embeddedSpecText: options.embeddedSpecText,
+	});
+
+	// Simple auth commands
+	const defaultProfileName = "default";
+
+	program
+		.command("login [token]")
+		.description("Store a bearer token for authentication")
+		.action(async (tokenArg: string | undefined, _opts, command) => {
+			const globals = command.optsWithGlobals() as { json?: boolean };
+
+			let token = tokenArg;
+
+			// If no token argument, try to read from stdin (for piping)
+			if (!token) {
+				const isTTY = process.stdin.isTTY;
+				if (isTTY) {
+					// Interactive mode - prompt user
+					process.stdout.write("Enter token: ");
+					const reader = process.stdin;
+					const chunks: Buffer[] = [];
+					for await (const chunk of reader) {
+						chunks.push(chunk);
+						// Read one line only
+						if (chunk.includes(10)) break; // newline
+					}
+					token = Buffer.concat(chunks).toString().trim();
+				} else {
+					// Piped input - use cross-runtime stdin reading
+					const text = await readStdinText();
+					token = text.trim();
+				}
+			}
+
+			if (!token) {
+				throw new Error(
+					"No token provided. Usage: login <token> or echo $TOKEN | login",
+				);
+			}
+
+			// Ensure default profile exists
+			const file = await readProfiles();
+			if (!file.profiles.find((p) => p.name === defaultProfileName)) {
+				const updated = upsertProfile(file, { name: defaultProfileName });
+				await writeProfiles({ ...updated, defaultProfile: defaultProfileName });
+			} else if (!file.defaultProfile) {
+				await writeProfiles({ ...file, defaultProfile: defaultProfileName });
+			}
+
+			await setToken(ctx.loaded.id, defaultProfileName, token);
+
+			if (globals.json) {
+				process.stdout.write(`${JSON.stringify({ ok: true })}\n`);
+				return;
+			}
+			process.stdout.write("ok: logged in\n");
+		});
+
+	program
+		.command("logout")
+		.description("Clear stored authentication token")
+		.action(async (_opts, command) => {
+			const globals = command.optsWithGlobals() as { json?: boolean };
+
+			const deleted = await deleteToken(ctx.loaded.id, defaultProfileName);
+
+			if (globals.json) {
+				process.stdout.write(`${JSON.stringify({ ok: deleted })}\n`);
+				return;
+			}
+			process.stdout.write(
+				deleted ? "ok: logged out\n" : "ok: not logged in\n",
+			);
+		});
+
+	program
+		.command("whoami")
+		.description("Show current authentication status")
+		.action(async (_opts, command) => {
+			const globals = command.optsWithGlobals() as { json?: boolean };
+
+			const token = await getToken(ctx.loaded.id, defaultProfileName);
+			const hasToken = Boolean(token);
+
+			// Mask the token for display (show first 8 and last 4 chars)
+			let maskedToken: string | null = null;
+			if (token && token.length > 16) {
+				maskedToken = `${token.slice(0, 8)}...${token.slice(-4)}`;
+			} else if (token) {
+				maskedToken = `${token.slice(0, 4)}...`;
+			}
+
+			if (globals.json) {
+				process.stdout.write(
+					`${JSON.stringify({ authenticated: hasToken, token: maskedToken })}\n`,
+				);
+				return;
+			}
+
+			if (hasToken) {
+				process.stdout.write(`authenticated: yes\n`);
+				process.stdout.write(`token: ${maskedToken}\n`);
+			} else {
+				process.stdout.write(`authenticated: no\n`);
+				process.stdout.write(`Run 'login <token>' to authenticate.\n`);
+			}
+		});
+
+	program
+		.command("__schema")
+		.description("Print indexed operations (machine-readable when --json)")
+		.option("--pretty", "Pretty-print JSON when used with --json")
+		.option("--min", "Minimal JSON output (commands + metadata only)")
+		.action(async (_opts, command) => {
+			const flags = command.optsWithGlobals() as {
+				json?: boolean;
+				pretty?: boolean;
+				min?: boolean;
+			};
+
+			if (flags.json) {
+				const pretty = Boolean(flags.pretty);
+				const payload = flags.min
+					? toMinimalSchemaOutput(ctx.schema)
+					: ctx.schema;
+				const text = stableStringify(payload, { space: pretty ? 2 : 0 });
+				process.stdout.write(`${text}\n`);
+				return;
+			}
+
+			process.stdout.write(`${ctx.schema.openapi.title ?? "(untitled)"}\n`);
+			process.stdout.write(`OpenAPI: ${ctx.schema.openapi.version}\n`);
+			process.stdout.write(
+				`Spec: ${ctx.schema.spec.id} (${ctx.schema.spec.source})\n`,
+			);
+			process.stdout.write(`Fingerprint: ${ctx.schema.spec.fingerprint}\n`);
+			process.stdout.write(`Servers: ${ctx.schema.servers.length}\n`);
+			process.stdout.write(`Auth Schemes: ${ctx.schema.authSchemes.length}\n`);
+			process.stdout.write(`Operations: ${ctx.schema.operations.length}\n`);
+
+			for (const op of ctx.schema.operations) {
+				const id = op.operationId ? ` (${op.operationId})` : "";
+				process.stdout.write(`- ${op.method} ${op.path}${id}\n`);
+			}
+
+			if (ctx.schema.planned?.length) {
+				process.stdout.write("\nPlanned commands:\n");
+				for (const op of ctx.schema.planned) {
+					const args = op.pathArgs.length
+						? ` ${op.pathArgs.map((a) => `<${a}>`).join(" ")}`
+						: "";
+					process.stdout.write(`- specli ${op.resource} ${op.action}${args}\n`);
+				}
+			}
+		});
+
+	addGeneratedCommands(program, {
+		servers: ctx.servers,
+		authSchemes: ctx.authSchemes,
+		commands: ctx.commands,
+		specId: ctx.loaded.id,
+		embeddedDefaults: {
+			server: options.server,
+			serverVars: options.serverVars,
+			auth: options.auth,
+		},
+	});
+
+	await program.parseAsync(argv);
+}

package/src/cli/naming.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, test } from "bun:test";
+import { planOperation } from "./naming.js";
+import type { NormalizedOperation } from "./types.js";
+
+describe("planOperation", () => {
+	test("REST: GET /contacts -> contacts list", () => {
+		const op: NormalizedOperation = {
+			key: "GET /contacts",
+			method: "GET",
+			path: "/contacts",
+			operationId: "Contacts.List",
+			tags: ["Contacts"],
+			parameters: [],
+		};
+
+		const planned = planOperation(op);
+		expect(planned.style).toBe("rest");
+		expect(planned.resource).toBe("contacts");
+		expect(planned.action).toBe("list");
+		expect(planned.pathArgs).toEqual([]);
+	});
+
+	test("REST: singleton /ping stays ping and prefers operationId action", () => {
+		const op: NormalizedOperation = {
+			key: "GET /ping",
+			method: "GET",
+			path: "/ping",
+			operationId: "Ping.Get",
+			tags: [],
+			parameters: [],
+		};
+
+		const planned = planOperation(op);
+		expect(planned.style).toBe("rest");
+		expect(planned.resource).toBe("ping");
+		expect(planned.action).toBe("get");
+	});
+
+	test("REST: singular path pluralizes to contacts", () => {
+		const op: NormalizedOperation = {
+			key: "GET /contact/{id}",
+			method: "GET",
+			path: "/contact/{id}",
+			tags: [],
+			parameters: [],
+		};
+
+		const planned = planOperation(op);
+		expect(planned.style).toBe("rest");
+		expect(planned.resource).toBe("contacts");
+		expect(planned.action).toBe("get");
+		expect(planned.pathArgs).toEqual(["id"]);
+	});
+
+	test("RPC: POST /Contacts.List -> contacts list", () => {
+		const op: NormalizedOperation = {
+			key: "POST /Contacts.List",
+			method: "POST",
+			path: "/Contacts.List",
+			operationId: "Contacts.List",
+			tags: [],
+			parameters: [],
+		};
+
+		const planned = planOperation(op);
+		expect(planned.style).toBe("rpc");
+		expect(planned.resource).toBe("contacts");
+		expect(planned.action).toBe("list");
+	});
+
+	test("RPC: Retrieve canonicalizes to get", () => {
+		const op: NormalizedOperation = {
+			key: "POST /Contacts.Retrieve",
+			method: "POST",
+			path: "/Contacts.Retrieve",
+			operationId: "Contacts.Retrieve",
+			tags: [],
+			parameters: [],
+		};
+
+		const planned = planOperation(op);
+		expect(planned.style).toBe("rpc");
+		expect(planned.resource).toBe("contacts");
+		expect(planned.action).toBe("get");
+	});
+});

package/src/cli/naming.ts

@@ -0,0 +1,224 @@
+import { pluralize } from "./pluralize.js";
+import { kebabCase } from "./strings.js";
+import type { NormalizedOperation } from "./types.js";
+
+export type PlannedOperation = NormalizedOperation & {
+	resource: string;
+	action: string;
+	pathArgs: string[];
+	style: "rest" | "rpc";
+	canonicalAction: string;
+	aliasOf?: string;
+};
+
+const GENERIC_TAGS = new Set(["default", "defaults", "api"]);
+
+function getPathSegments(path: string): string[] {
+	return path
+		.split("/")
+		.map((s) => s.trim())
+		.filter(Boolean);
+}
+
+function getPathArgs(path: string): string[] {
+	const args: string[] = [];
+	const re = /\{([^}]+)\}/g;
+
+	while (true) {
+		const match = re.exec(path);
+		if (!match) break;
+		// biome-ignore lint/style/noNonNullAssertion: unknown
+		args.push(match[1]!);
+	}
+
+	return args;
+}
+
+function pickResourceFromTags(tags: string[]): string | undefined {
+	if (!tags.length) return undefined;
+	const first = tags[0]?.trim();
+	if (!first) return undefined;
+	if (GENERIC_TAGS.has(first.toLowerCase())) return undefined;
+	return first;
+}
+
+function splitOperationId(operationId: string): {
+	prefix?: string;
+	suffix?: string;
+} {
+	const trimmed = operationId.trim();
+	if (!trimmed) return {};
+
+	// Prefer dot-notation when present: Contacts.List
+	if (trimmed.includes(".")) {
+		const [prefix, ...rest] = trimmed.split(".");
+		return { prefix, suffix: rest.join(".") };
+	}
+
+	// Try separators: Contacts_List, Contacts__List
+	if (trimmed.includes("__")) {
+		const [prefix, ...rest] = trimmed.split("__");
+		return { prefix, suffix: rest.join("__") };
+	}
+
+	if (trimmed.includes("_")) {
+		const [prefix, ...rest] = trimmed.split("_");
+		return { prefix, suffix: rest.join("_") };
+	}
+
+	return { suffix: trimmed };
+}
+
+function inferStyle(op: NormalizedOperation): "rest" | "rpc" {
+	// Path-based RPC convention (common in gRPC-ish HTTP gateways)
+	// - POST /Contacts.List
+	// - POST /Contacts/Service.List
+	if (op.path.includes(".")) return "rpc";
+
+	// operationId dot-notation alone is not enough to call it RPC; many REST APIs
+	// have dotted ids. We treat dotted operationId as a weak signal.
+	if (op.operationId?.includes(".") && op.method === "POST") return "rpc";
+
+	return "rest";
+}
+
+function inferResource(op: NormalizedOperation): string {
+	const tag = pickResourceFromTags(op.tags);
+	if (tag) return pluralize(kebabCase(tag));
+
+	if (op.operationId) {
+		const { prefix } = splitOperationId(op.operationId);
+		if (prefix) {
+			const fromId = kebabCase(prefix);
+			if (fromId === "ping") return "ping";
+			return pluralize(fromId);
+		}
+	}
+
+	const segments = getPathSegments(op.path);
+	let first = segments[0] ?? "api";
+
+	// If first segment is rpc-ish, like Contacts.List, split it.
+	// biome-ignore lint/style/noNonNullAssertion: split always returns at least one element
+	first = first.includes(".") ? first.split(".")[0]! : first;
+
+	// Singletons like /ping generally shouldn't become `pings`.
+	if (first.toLowerCase() === "ping") return "ping";
+
+	// Strip path params if they appear in first segment (rare)
+	const cleaned = first.replace(/^\{.+\}$/, "");
+	return pluralize(kebabCase(cleaned || "api"));
+}
+
+function canonicalizeAction(action: string): string {
+	const a = kebabCase(action);
+
+	// Common RPC verbs -> REST canonical verbs
+	if (a === "retrieve" || a === "read") return "get";
+	if (a === "list" || a === "search") return "list";
+	if (a === "create") return "create";
+	if (a === "update" || a === "patch") return "update";
+	if (a === "delete" || a === "remove") return "delete";
+
+	return a;
+}
+
+function inferRestAction(op: NormalizedOperation): string {
+	// If operationId is present and looks intentional, prefer it.
+	// This helps with singleton endpoints like GET /ping (Ping.Get) vs collections.
+	if (op.operationId) {
+		const { suffix } = splitOperationId(op.operationId);
+		if (suffix) {
+			const fromId = canonicalizeAction(suffix);
+			if (
+				fromId === "get" ||
+				fromId === "list" ||
+				fromId === "create" ||
+				fromId === "update" ||
+				fromId === "delete"
+			) {
+				return fromId;
+			}
+		}
+	}
+
+	const method = op.method.toUpperCase();
+	const args = getPathArgs(op.path);
+	const hasId = args.length > 0;
+
+	if (method === "GET" && !hasId) return "list";
+	if (method === "POST" && !hasId) return "create";
+
+	if (method === "GET" && hasId) return "get";
+	if ((method === "PUT" || method === "PATCH") && hasId) return "update";
+	if (method === "DELETE" && hasId) return "delete";
+
+	return kebabCase(method);
+}
+
+function inferRpcAction(op: NormalizedOperation): string {
+	// Prefer operationId suffix: Contacts.List -> list
+	if (op.operationId) {
+		const { suffix } = splitOperationId(op.operationId);
+		if (suffix) return canonicalizeAction(suffix);
+	}
+
+	// Else take last segment and split by '.'
+	const segments = getPathSegments(op.path);
+	const last = segments[segments.length - 1] ?? "";
+	if (last.includes(".")) {
+		const part = last.split(".").pop() ?? last;
+		return canonicalizeAction(part);
+	}
+
+	return kebabCase(op.method);
+}
+
+export function planOperation(op: NormalizedOperation): PlannedOperation {
+	const style = inferStyle(op);
+	const resource = inferResource(op);
+	const action = style === "rpc" ? inferRpcAction(op) : inferRestAction(op);
+
+	return {
+		...op,
+		key: op.key,
+		style,
+		resource,
+		action,
+		canonicalAction: action,
+		pathArgs: getPathArgs(op.path).map((a) => kebabCase(a)),
+	};
+}
+
+export function planOperations(ops: NormalizedOperation[]): PlannedOperation[] {
+	const planned = ops.map(planOperation);
+
+	// Stable collision handling: if resource+action repeats, add a suffix.
+	const counts = new Map<string, number>();
+	for (const op of planned) {
+		const key = `${op.resource}:${op.action}`;
+		counts.set(key, (counts.get(key) ?? 0) + 1);
+	}
+
+	const seen = new Map<string, number>();
+	return planned.map((op) => {
+		const key = `${op.resource}:${op.action}`;
+		const total = counts.get(key) ?? 0;
+		if (total <= 1) return op;
+
+		const idx = (seen.get(key) ?? 0) + 1;
+		seen.set(key, idx);
+
+		const suffix = op.operationId
+			? kebabCase(op.operationId)
+			: kebabCase(`${op.method}-${op.path}`);
+
+		const disambiguatedAction = `${op.action}-${suffix}-${idx}`;
+
+		return {
+			...op,
+			action: disambiguatedAction,
+			aliasOf: `${op.resource} ${op.canonicalAction}`,
+		};
+	});
+}

package/src/cli/operations.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from "bun:test";
+
+import { indexOperations } from "./operations.js";
+import type { OpenApiDoc } from "./types.js";
+
+describe("indexOperations", () => {
+	test("indexes basic operations", () => {
+		const doc: OpenApiDoc = {
+			openapi: "3.0.3",
+			paths: {
+				"/contacts": {
+					get: {
+						operationId: "Contacts.List",
+						tags: ["Contacts"],
+						parameters: [
+							{
+								in: "query",
+								name: "limit",
+								schema: { type: "integer" },
+							},
+						],
+					},
+				},
+				"/contacts/{id}": {
+					get: {
+						operationId: "Contacts.Get",
+						tags: ["Contacts"],
+						parameters: [
+							{
+								in: "path",
+								name: "id",
+								required: true,
+								schema: { type: "string" },
+							},
+						],
+					},
+				},
+			},
+		};
+
+		const ops = indexOperations(doc);
+		expect(ops).toHaveLength(2);
+
+		expect(ops[0]?.key).toBe("GET /contacts");
+		expect(ops[0]?.path).toBe("/contacts");
+		expect(ops[0]?.method).toBe("GET");
+		expect(ops[0]?.parameters).toHaveLength(1);
+		expect(ops[0]?.parameters[0]?.in).toBe("query");
+
+		expect(ops[1]?.key).toBe("GET /contacts/{id}");
+		expect(ops[1]?.path).toBe("/contacts/{id}");
+		expect(ops[1]?.method).toBe("GET");
+		expect(ops[1]?.parameters).toHaveLength(1);
+		expect(ops[1]?.parameters[0]?.in).toBe("path");
+		expect(ops[1]?.parameters[0]?.required).toBe(true);
+	});
+});