specli 0.0.16 → 0.0.18

package/src/cli/capabilities.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from "bun:test";
+import type { AuthScheme } from "./auth-schemes.js";
+import { deriveCapabilities } from "./capabilities.js";
+import type { CommandModel } from "./command-model.js";
+import type { ServerInfo } from "./server.js";
+import type { NormalizedOperation, OpenApiDoc } from "./types.js";
+
+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.js";
+import type { CommandModel } from "./command-model.js";
+import type { ServerInfo } from "./server.js";
+import type {
+	NormalizedOperation,
+	OpenApiDoc,
+	SecurityRequirement,
+} from "./types.js";
+
+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.js";
+
+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.js";
+
+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.js";
+
+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.js";
+import type { PlannedOperation } from "./naming.js";
+
+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.js";
+import { summarizeAuth } from "./auth-requirements.js";
+import type { AuthScheme } from "./auth-schemes.js";
+import { buildCommandId } from "./command-id.js";
+import type { PlannedOperation } from "./naming.js";
+import type { ParamSpec } from "./params.js";
+import { deriveParamSpecs } from "./params.js";
+import { deriveFlags, derivePositionals } from "./positional.js";
+import type { RequestBodyInfo } from "./request-body.js";
+import { deriveRequestBodyInfo } from "./request-body.js";
+import type { SecurityRequirement } from "./types.js";
+
+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.js").PositionalArg>;
+	flags: Array<
+		Pick<
+			import("./params.js").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.js").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 };
+}

package/src/cli/compile.ts

@@ -0,0 +1,109 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { deriveBinaryName } from "./derive-name.js";
+
+// Resolve the path to compiled.ts relative to this file's location
+// At runtime this file is at dist/cli/compile.js, so we go up two levels to package root
+// then into src/compiled.ts (which must be included in the published package)
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const compiledEntrypoint = path.resolve(__dirname, "../../src/compiled.ts");
+
+export type CompileOptions = {
+	name?: string;
+	outfile?: string;
+	target?: string;
+	minify?: boolean;
+	bytecode?: boolean;
+	dotenv?: boolean; // --no-dotenv sets this to false
+	bunfig?: boolean; // --no-bunfig sets this to false
+	define?: string[];
+	server?: string;
+	serverVar?: string[];
+	auth?: string;
+};
+
+function parseKeyValue(input: string): { key: string; value: string } {
+	const idx = input.indexOf("=");
+	if (idx === -1)
+		throw new Error(`Invalid --define '${input}', expected key=value`);
+	const key = input.slice(0, idx).trim();
+	const value = input.slice(idx + 1).trim();
+	if (!key) throw new Error(`Invalid --define '${input}', missing key`);
+	return { key, value };
+}
+
+export async function compileCommand(
+	spec: string,
+	options: CompileOptions,
+): Promise<void> {
+	// Derive name from spec if not provided
+	const name = options.name ?? (await deriveBinaryName(spec));
+	const outfile = options.outfile ?? `./out/${name}`;
+
+	const target = options.target
+		? (options.target as Bun.Build.Target)
+		: (`bun-${process.platform}-${process.arch}` as Bun.Build.Target);
+
+	// Parse --define pairs
+	const define: Record<string, string> = {};
+	if (options.define) {
+		for (const pair of options.define) {
+			const { key, value } = parseKeyValue(pair);
+			define[key] = JSON.stringify(value);
+		}
+	}
+
+	// Build command args
+	const buildArgs = [
+		"build",
+		"--compile",
+		`--outfile=${outfile}`,
+		`--target=${target}`,
+	];
+
+	if (options.minify) buildArgs.push("--minify");
+	if (options.bytecode) buildArgs.push("--bytecode");
+
+	for (const [k, v] of Object.entries(define)) {
+		buildArgs.push("--define", `${k}=${v}`);
+	}
+
+	if (options.dotenv === false) buildArgs.push("--no-compile-autoload-dotenv");
+	if (options.bunfig === false) buildArgs.push("--no-compile-autoload-bunfig");
+
+	buildArgs.push(compiledEntrypoint);
+
+	// Only set env vars that have actual values - avoid empty strings
+	// because the macros will embed them and they will override defaults.
+	const buildEnv: Record<string, string> = {
+		...process.env,
+		SPECLI_SPEC: spec,
+		SPECLI_NAME: name,
+	};
+	if (options.server) buildEnv.SPECLI_SERVER = options.server;
+	if (options.serverVar?.length)
+		buildEnv.SPECLI_SERVER_VARS = options.serverVar.join(",");
+	if (options.auth) buildEnv.SPECLI_AUTH = options.auth;
+
+	const proc = Bun.spawn({
+		cmd: ["bun", ...buildArgs],
+		stdout: "pipe",
+		stderr: "pipe",
+		env: buildEnv,
+	});
+
+	const output = await new Response(proc.stdout).text();
+	const error = await new Response(proc.stderr).text();
+	const code = await proc.exited;
+
+	if (output) process.stdout.write(output);
+	if (error) process.stderr.write(error);
+	if (code !== 0) {
+		process.exitCode = code;
+		return;
+	}
+
+	process.stdout.write(`ok: built ${outfile}\n`);
+	process.stdout.write(`target: ${target}\n`);
+	process.stdout.write(`name: ${name}\n`);
+}

package/src/cli/crypto.ts

@@ -0,0 +1,9 @@
+export async function sha256Hex(text: string): Promise<string> {
+	const data = new TextEncoder().encode(text);
+	const hash = await crypto.subtle.digest("SHA-256", data);
+	const bytes = new Uint8Array(hash);
+
+	let out = "";
+	for (const b of bytes) out += b.toString(16).padStart(2, "0");
+	return out;
+}

package/src/cli/derive-name.ts

@@ -0,0 +1,101 @@
+const RESERVED_NAMES = [
+	"exec",
+	"compile",
+	"profile",
+	"auth",
+	"help",
+	"version",
+];
+
+/**
+ * Derives a clean binary name from an OpenAPI spec.
+ * Priority:
+ *   1. info.title (kebab-cased, sanitized)
+ *   2. Host from spec URL (if URL provided)
+ *   3. Fallback to "specli"
+ */
+export async function deriveBinaryName(spec: string): Promise<string> {
+	try {
+		// Load spec to extract title
+		const text = await loadSpecText(spec);
+		const doc = parseSpec(text);
+
+		const title = doc?.info?.title;
+		if (title && typeof title === "string") {
+			const name = sanitizeName(title);
+			if (name) return name;
+		}
+	} catch {
+		// Fall through to URL-based derivation
+	}
+
+	// Try to derive from URL host
+	if (/^https?:\/\//i.test(spec)) {
+		try {
+			const url = new URL(spec);
+			const hostParts = url.hostname.split(".");
+			// Use first meaningful segment (skip www, api prefixes)
+			const meaningful = hostParts.find(
+				(p) => p !== "www" && p !== "api" && p.length > 2,
+			);
+			if (meaningful) {
+				const name = sanitizeName(meaningful);
+				if (name) return name;
+			}
+		} catch {
+			// Invalid URL, fall through
+		}
+	}
+
+	// Fallback
+	return "specli";
+}
+
+async function loadSpecText(spec: string): Promise<string> {
+	if (/^https?:\/\//i.test(spec)) {
+		const res = await fetch(spec);
+		if (!res.ok) throw new Error(`Failed to fetch: ${res.status}`);
+		return res.text();
+	}
+	return Bun.file(spec).text();
+}
+
+function parseSpec(text: string): { info?: { title?: string } } | null {
+	try {
+		const trimmed = text.trimStart();
+		if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+			return JSON.parse(text);
+		}
+		// Use Bun's YAML parser
+		const { YAML } = globalThis.Bun ?? {};
+		if (YAML?.parse) {
+			return YAML.parse(text) as { info?: { title?: string } };
+		}
+		// Fallback: only JSON supported
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Convert title to valid binary name:
+ * - kebab-case
+ * - lowercase
+ * - remove invalid chars
+ * - max 32 chars
+ * - avoid reserved names
+ */
+function sanitizeName(input: string): string {
+	let name = input
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-") // Replace non-alphanumeric with dash
+		.replace(/^-+|-+$/g, "") // Trim leading/trailing dashes
+		.slice(0, 32); // Limit length
+
+	if (RESERVED_NAMES.includes(name)) {
+		name = `${name}-cli`;
+	}
+
+	return name;
+}