specli 0.0.1

package/src/cli/runtime/validate/schema.ts

@@ -0,0 +1,54 @@
+import type { CommandAction } from "../../command-model.ts";
+import type { JsonSchema } from "../../types.ts";
+
+export type ValidationSchemas = {
+	querySchema?: JsonSchema;
+	headerSchema?: JsonSchema;
+	cookieSchema?: JsonSchema;
+};
+
+type ObjectSchema = {
+	type: "object";
+	properties: Record<string, JsonSchema>;
+	required?: string[];
+};
+
+export function deriveValidationSchemas(
+	action: CommandAction,
+): ValidationSchemas {
+	// We validate only simple containers for now.
+	// Deep style/encoding differences for OpenAPI params are out of scope for v1.
+	const query: ObjectSchema = { type: "object", properties: {}, required: [] };
+	const header: ObjectSchema = { type: "object", properties: {}, required: [] };
+	const cookie: ObjectSchema = { type: "object", properties: {}, required: [] };
+
+	for (const p of action.params) {
+		if (p.kind !== "flag") continue;
+		const target =
+			p.in === "query"
+				? query
+				: p.in === "header"
+					? header
+					: p.in === "cookie"
+						? cookie
+						: undefined;
+		if (!target) continue;
+
+		const schema = p.schema ?? (p.type === "unknown" ? {} : { type: p.type });
+		target.properties[p.name] = schema;
+		if (p.required) {
+			if (!target.required) target.required = [];
+			target.required.push(p.name);
+		}
+	}
+
+	if (!query.required?.length) delete query.required;
+	if (!header.required?.length) delete header.required;
+	if (!cookie.required?.length) delete cookie.required;
+
+	return {
+		querySchema: Object.keys(query.properties).length ? query : undefined,
+		headerSchema: Object.keys(header.properties).length ? header : undefined,
+		cookieSchema: Object.keys(cookie.properties).length ? cookie : undefined,
+	};
+}

package/src/cli/schema-shape.ts

@@ -0,0 +1,36 @@
+export type ParamType =
+	| "string"
+	| "number"
+	| "integer"
+	| "boolean"
+	| "array"
+	| "object"
+	| "unknown";
+
+export function getSchemaType(schema: unknown): ParamType {
+	if (!schema || typeof schema !== "object") return "unknown";
+	const t = (schema as { type?: unknown }).type;
+	if (t === "string") return "string";
+	if (t === "number") return "number";
+	if (t === "integer") return "integer";
+	if (t === "boolean") return "boolean";
+	if (t === "array") return "array";
+	if (t === "object") return "object";
+	return "unknown";
+}
+
+export function getSchemaFormat(schema: unknown): string | undefined {
+	if (!schema || typeof schema !== "object") return undefined;
+	const f = (schema as { format?: unknown }).format;
+	return typeof f === "string" ? f : undefined;
+}
+
+export function getSchemaEnumStrings(schema: unknown): string[] | undefined {
+	if (!schema || typeof schema !== "object") return undefined;
+	const e = (schema as { enum?: unknown }).enum;
+	if (!Array.isArray(e)) return undefined;
+
+	// We only surface string enums for now (enough for flag docs + completion).
+	const values = e.filter((v) => typeof v === "string") as string[];
+	return values.length ? values : undefined;
+}

package/src/cli/schema.ts

@@ -0,0 +1,76 @@
+import type { AuthScheme } from "./auth-schemes.ts";
+import type { Capabilities } from "./capabilities.ts";
+import type { CommandModel } from "./command-model.ts";
+import type { PlannedOperation } from "./naming.ts";
+import type { ServerInfo } from "./server.ts";
+import type { LoadedSpec, NormalizedOperation } from "./types.ts";
+
+export type SchemaOutput = {
+	schemaVersion: 1;
+	openapi: {
+		version: string;
+		title?: string;
+		infoVersion?: string;
+	};
+	spec: {
+		id: string;
+		fingerprint: string;
+		source: LoadedSpec["source"];
+	};
+	capabilities: Capabilities;
+	servers: ServerInfo[];
+	authSchemes: AuthScheme[];
+	operations: NormalizedOperation[];
+	planned?: PlannedOperation[];
+	commands?: CommandModel;
+	commandsIndex?: import("./command-index.ts").CommandsIndex;
+};
+
+export type MinimalSchemaOutput = Pick<
+	SchemaOutput,
+	"schemaVersion" | "openapi" | "spec" | "capabilities" | "commands"
+>;
+
+export function buildSchemaOutput(
+	loaded: LoadedSpec,
+	operations: NormalizedOperation[],
+	planned: PlannedOperation[] | undefined,
+	servers: ServerInfo[],
+	authSchemes: AuthScheme[],
+	commands: CommandModel | undefined,
+	commandsIndex: import("./command-index.ts").CommandsIndex | undefined,
+	capabilities: Capabilities,
+): SchemaOutput {
+	return {
+		schemaVersion: 1,
+		openapi: {
+			version: loaded.doc.openapi,
+			title: loaded.doc.info?.title,
+			infoVersion: loaded.doc.info?.version,
+		},
+		spec: {
+			id: loaded.id,
+			fingerprint: loaded.fingerprint,
+			source: loaded.source,
+		},
+		capabilities,
+		servers,
+		authSchemes,
+		operations,
+		planned,
+		commands,
+		commandsIndex,
+	};
+}
+
+export function toMinimalSchemaOutput(
+	output: SchemaOutput,
+): MinimalSchemaOutput {
+	return {
+		schemaVersion: output.schemaVersion,
+		openapi: output.openapi,
+		spec: output.spec,
+		capabilities: output.capabilities,
+		commands: output.commands,
+	};
+}

package/src/cli/server.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "bun:test";
+
+import { listServers } from "./server.ts";
+import type { OpenApiDoc } from "./types.ts";
+
+describe("listServers", () => {
+	test("extracts server variables from template", () => {
+		const doc: OpenApiDoc = {
+			openapi: "3.0.3",
+			servers: [
+				{
+					url: "https://{region}.api.example.com/{basePath}",
+					variables: {
+						region: {
+							default: "us",
+							enum: ["us", "eu"],
+						},
+						basePath: {
+							default: "v1",
+						},
+					},
+				} as const,
+			],
+		};
+
+		const servers = listServers(doc);
+		expect(servers).toHaveLength(1);
+		expect(servers[0]?.variableNames).toEqual(["region", "basePath"]);
+		expect(servers[0]?.variables.map((v) => v.name)).toEqual([
+			"region",
+			"basePath",
+		]);
+		expect(servers[0]?.variables[0]?.enum).toEqual(["us", "eu"]);
+	});
+});

package/src/cli/server.ts

@@ -0,0 +1,88 @@
+import { getSchemaEnumStrings } from "./schema-shape.ts";
+import type { OpenApiDoc } from "./types.ts";
+
+export type ServerVariable = {
+	name: string;
+	default?: string;
+	enum?: string[];
+	description?: string;
+};
+
+export type ServerInfo = {
+	url: string;
+	description?: string;
+	variables: ServerVariable[];
+	variableNames: string[];
+};
+
+type RawServerVariable = {
+	default?: unknown;
+	enum?: unknown;
+	description?: unknown;
+};
+
+type RawServer = {
+	url?: unknown;
+	description?: unknown;
+	variables?: unknown;
+};
+
+function extractVariableNames(url: string): string[] {
+	const names: string[] = [];
+	const re = /\{([^}]+)\}/g;
+
+	while (true) {
+		const match = re.exec(url);
+		if (!match) break;
+		names.push(match[1] ?? "");
+	}
+
+	return names.map((n) => n.trim()).filter(Boolean);
+}
+
+export function listServers(doc: OpenApiDoc): ServerInfo[] {
+	const servers = doc.servers ?? [];
+	const out: ServerInfo[] = [];
+
+	for (const raw of servers) {
+		const s = raw as RawServer;
+		if (!s || typeof s !== "object") continue;
+		if (typeof s.url !== "string") continue;
+
+		const variableNames = extractVariableNames(s.url);
+		const variables: ServerVariable[] = [];
+
+		const rawVars =
+			s.variables &&
+			typeof s.variables === "object" &&
+			!Array.isArray(s.variables)
+				? (s.variables as Record<string, RawServerVariable>)
+				: {};
+
+		for (const name of variableNames) {
+			const v = rawVars[name];
+			const def = v?.default;
+			const desc = v?.description;
+			variables.push({
+				name,
+				default: typeof def === "string" ? def : undefined,
+				enum: getSchemaEnumStrings(v),
+				description: typeof desc === "string" ? desc : undefined,
+			});
+		}
+
+		out.push({
+			url: s.url,
+			description:
+				typeof s.description === "string" ? s.description : undefined,
+			variables,
+			variableNames,
+		});
+	}
+
+	return out;
+}
+
+export function getDefaultServerUrl(doc: OpenApiDoc): string | undefined {
+	return listServers(doc)[0]?.url;
+}

package/src/cli/spec-id.ts

@@ -0,0 +1,12 @@
+import { kebabCase } from "./strings.ts";
+import type { LoadedSpec } from "./types.ts";
+
+export function getSpecId(
+	loaded: Pick<LoadedSpec, "doc" | "fingerprint">,
+): string {
+	const title = loaded.doc.info?.title;
+	const fromTitle = title ? kebabCase(title) : "";
+	if (fromTitle) return fromTitle;
+
+	return loaded.fingerprint.slice(0, 12);
+}

package/src/cli/spec-loader.ts

@@ -0,0 +1,58 @@
+import SwaggerParser from "@apidevtools/swagger-parser";
+import { YAML } from "bun";
+
+import { sha256Hex } from "./crypto.ts";
+import { getSpecId } from "./spec-id.ts";
+import { stableStringify } from "./stable-json.ts";
+import type { LoadedSpec, OpenApiDoc, SpecSource } from "./types.ts";
+
+export type LoadSpecOptions = {
+	spec?: string;
+	embeddedSpecText?: string;
+};
+
+function isProbablyUrl(input: string): boolean {
+	return /^https?:\/\//i.test(input);
+}
+
+function parseSpecText(text: string): unknown {
+	const trimmed = text.trimStart();
+	if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+		return JSON.parse(text);
+	}
+
+	return YAML.parse(text);
+}
+
+export async function loadSpec(options: LoadSpecOptions): Promise<LoadedSpec> {
+	const { spec, embeddedSpecText } = options;
+
+	let source: SpecSource;
+	let inputForParser: unknown;
+
+	if (typeof embeddedSpecText === "string") {
+		source = "embedded";
+		inputForParser = parseSpecText(embeddedSpecText);
+	} else if (spec) {
+		source = isProbablyUrl(spec) ? "url" : "file";
+		inputForParser = spec;
+	} else {
+		throw new Error(
+			"Missing spec. Provide --spec <url|path> or build with an embedded spec.",
+		);
+	}
+
+	const doc = (await SwaggerParser.dereference(
+		// biome-ignore lint/suspicious/noExplicitAny: unknown
+		inputForParser as any,
+	)) as OpenApiDoc;
+
+	if (!doc || typeof doc !== "object" || typeof doc.openapi !== "string") {
+		throw new Error("Loaded spec is not a valid OpenAPI document");
+	}
+
+	const fingerprint = await sha256Hex(stableStringify(doc));
+	const id = getSpecId({ doc, fingerprint });
+
+	return { source, id, fingerprint, doc };
+}

package/src/cli/stable-json.ts

@@ -0,0 +1,35 @@
+export function stableStringify(
+	value: unknown,
+	options?: { space?: number },
+): string {
+	const visiting = new WeakSet<object>();
+	return JSON.stringify(sort(value, visiting), null, options?.space);
+}
+
+function sort(value: unknown, visiting: WeakSet<object>): unknown {
+	if (value === null) return null;
+
+	if (Array.isArray(value)) {
+		if (visiting.has(value)) return { __opencli_circular: true };
+		visiting.add(value);
+		const out = value.map((v) => sort(v, visiting));
+		visiting.delete(value);
+		return out;
+	}
+
+	if (typeof value === "object") {
+		if (visiting.has(value)) return { __opencli_circular: true };
+		visiting.add(value);
+
+		const obj = value as Record<string, unknown>;
+		const out: Record<string, unknown> = {};
+		for (const key of Object.keys(obj).sort()) {
+			out[key] = sort(obj[key], visiting);
+		}
+
+		visiting.delete(value);
+		return out;
+	}
+
+	return value;
+}

package/src/cli/strings.ts

@@ -0,0 +1,21 @@
+export function kebabCase(input: string): string {
+	const trimmed = input.trim();
+	if (!trimmed) return "";
+
+	// Convert spaces/underscores/dots to dashes, split camelCase.
+	return trimmed
+		.replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+		.replace(/[\s_.:/]+/g, "-")
+		.replace(/[^a-zA-Z0-9-]/g, "-")
+		.replace(/-+/g, "-")
+		.replace(/^-|-$/g, "")
+		.toLowerCase();
+}
+
+export function titleCase(input: string): string {
+	return input
+		.split(/\s+/g)
+		.filter(Boolean)
+		.map((w) => w[0]?.toUpperCase() + w.slice(1))
+		.join(" ");
+}

package/src/cli/types.ts

@@ -0,0 +1,59 @@
+export type SpecSource = "embedded" | "file" | "url";
+
+export type SecurityRequirement = Record<string, string[]>;
+
+export type OpenApiDoc = {
+	openapi: string;
+	info?: {
+		title?: string;
+		version?: string;
+	};
+	servers?: Array<{ url: string; description?: string; variables?: unknown }>;
+	security?: SecurityRequirement[];
+	components?: {
+		securitySchemes?: Record<string, unknown>;
+	};
+	paths?: Record<string, unknown>;
+};
+
+export type NormalizedParameter = {
+	in: "path" | "query" | "header" | "cookie";
+	name: string;
+	required: boolean;
+	description?: string;
+	schema?: unknown;
+};
+
+// Minimal JSON Schema-like shape for validation and flag expansion.
+export type JsonSchema = Record<string, unknown>;
+
+export function isJsonSchema(value: unknown): value is JsonSchema {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+export type NormalizedRequestBody = {
+	required: boolean;
+	contentTypes: string[];
+	schemasByContentType: Record<string, unknown | undefined>;
+};
+
+export type NormalizedOperation = {
+	key: string;
+	method: string;
+	path: string;
+	operationId?: string;
+	tags: string[];
+	summary?: string;
+	description?: string;
+	deprecated?: boolean;
+	security?: SecurityRequirement[];
+	parameters: NormalizedParameter[];
+	requestBody?: NormalizedRequestBody;
+};
+
+export type LoadedSpec = {
+	source: SpecSource;
+	id: string;
+	fingerprint: string;
+	doc: OpenApiDoc;
+};

package/src/compiled.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env bun
+
+import { main } from "./cli/main.ts";
+import { env, envRequired } from "./macros/env.ts" with { type: "macro" };
+import { loadSpec } from "./macros/spec.ts" with { type: "macro" };
+
+// This entrypoint is intended to be compiled.
+// The spec is embedded via Bun macro at bundle-time.
+const embeddedSpecText = await loadSpec(envRequired("OPENCLI_EMBED_SPEC"));
+
+// CLI name is also embedded at bundle-time.
+const cliName = env("OPENCLI_CLI_NAME");
+
+// Use embedded `execArgv` as default CLI args.
+// We insert them before user-provided args so user flags win.
+const argv = [
+	process.argv[0] ?? cliName ?? "opencli",
+	process.argv[1] ?? cliName ?? "opencli",
+	...(process.execArgv ?? []),
+	...process.argv.slice(2),
+];
+
+await main(argv, { embeddedSpecText, cliName });

package/src/macros/env.ts

@@ -0,0 +1,25 @@
+/**
+ * Bun macro: reads an environment variable at bundle-time.
+ * Returns undefined if the env var is not set.
+ *
+ * Usage:
+ *   import { env } from "./macros/env.ts" with { type: "macro" };
+ *   const value = env("MY_VAR");
+ */
+export function env(name: string): string | undefined {
+	if (!name) throw new Error("env macro: missing variable name");
+	return process.env[name];
+}
+
+/**
+ * Bun macro: reads a required environment variable at bundle-time.
+ * Throws if the env var is not set.
+ */
+export function envRequired(name: string): string {
+	if (!name) throw new Error("envRequired macro: missing variable name");
+	const value = process.env[name];
+	if (value === undefined) {
+		throw new Error(`Missing required env var: ${name}`);
+	}
+	return value;
+}

package/src/macros/spec.ts

@@ -0,0 +1,17 @@
+/**
+ * Bun macro: loads an OpenAPI spec from a URL or file path at bundle-time.
+ * The spec text is inlined into the bundle.
+ */
+export async function loadSpec(spec: string): Promise<string> {
+	if (!spec) throw new Error("loadSpec macro: missing spec path/URL");
+
+	if (/^https?:\/\//i.test(spec)) {
+		const res = await fetch(spec);
+		if (!res.ok) {
+			throw new Error(`Failed to fetch spec: ${res.status} ${res.statusText}`);
+		}
+		return await res.text();
+	}
+
+	return await Bun.file(spec).text();
+}

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+	"compilerOptions": {
+		// Environment setup & latest features
+		"lib": ["ESNext"],
+		"target": "ESNext",
+		"module": "Preserve",
+		"moduleDetection": "force",
+		"jsx": "react-jsx",
+		"allowJs": true,
+
+		// Bundler mode
+		"moduleResolution": "bundler",
+		"allowImportingTsExtensions": true,
+		"verbatimModuleSyntax": true,
+		"noEmit": true,
+
+		// Best practices
+		"strict": true,
+		"skipLibCheck": true,
+		"noFallthroughCasesInSwitch": true,
+		"noUncheckedIndexedAccess": true,
+		"noImplicitOverride": true,
+
+		// Some stricter flags (disabled by default)
+		"noUnusedLocals": false,
+		"noUnusedParameters": false,
+		"noPropertyAccessFromIndexSignature": false
+	}
+}