specli 0.0.17 → 0.0.18

package/dist/cli/compile.js

@@ -1,4 +1,11 @@
+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");
 function parseKeyValue(input) {
     const idx = input.indexOf("=");
     if (idx === -1)
@@ -42,7 +49,7 @@ export async function compileCommand(spec, options) {
         buildArgs.push("--no-compile-autoload-dotenv");
     if (options.bunfig === false)
         buildArgs.push("--no-compile-autoload-bunfig");
-    buildArgs.push("./src/compiled.ts");
+    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 = {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "specli",
-	"version": "0.0.17",
+	"version": "0.0.18",
 	"type": "module",
 	"module": "./dist/index.js",
 	"types": "./dist/index.d.ts",
@@ -16,6 +16,7 @@
 	"files": [
 		"bin",
 		"dist",
+		"src",
 		"README.md",
 		"package.json"
 	],

package/src/ai/tools.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test } from "bun:test";
+import { clearSpecliCache, specli } from "./tools.js";
+
+const mockOptions = {
+	toolCallId: "test-call-id",
+	abortSignal: new AbortController().signal,
+	messages: [],
+};
+
+describe("specli tool", () => {
+	test("creates a tool with correct structure", () => {
+		const tool = specli({
+			spec: "https://petstore3.swagger.io/api/v3/openapi.json",
+		});
+
+		expect(tool).toHaveProperty("description");
+		expect(tool).toHaveProperty("inputSchema");
+		expect(tool).toHaveProperty("execute");
+		expect(typeof tool.execute).toBe("function");
+	});
+
+	test("list command returns resources", async () => {
+		const tool = specli({
+			spec: "https://petstore3.swagger.io/api/v3/openapi.json",
+		});
+
+		const result = (await tool.execute?.({ command: "list" }, mockOptions)) as {
+			resources: unknown[];
+		};
+
+		expect(result).toHaveProperty("resources");
+		expect(Array.isArray(result.resources)).toBe(true);
+	});
+
+	test("help command returns action details", async () => {
+		const tool = specli({
+			spec: "https://petstore3.swagger.io/api/v3/openapi.json",
+		});
+
+		const result = (await tool.execute?.(
+			{ command: "help", resource: "pets", action: "get" },
+			mockOptions,
+		)) as { action: string };
+
+		expect(result).toHaveProperty("action");
+		expect(result.action).toBe("get");
+	});
+
+	test("help command with missing resource returns error", async () => {
+		const tool = specli({
+			spec: "https://petstore3.swagger.io/api/v3/openapi.json",
+		});
+
+		const result = (await tool.execute?.({ command: "help" }, mockOptions)) as {
+			error: string;
+		};
+
+		expect(result).toHaveProperty("error");
+	});
+
+	test("exec command with missing args returns error", async () => {
+		const tool = specli({
+			spec: "https://petstore3.swagger.io/api/v3/openapi.json",
+		});
+
+		const result = (await tool.execute?.(
+			{ command: "exec", resource: "pets", action: "get" },
+			mockOptions,
+		)) as { error: string };
+
+		expect(result).toHaveProperty("error");
+		expect(result.error).toContain("Missing args");
+	});
+
+	test("clearCache works", async () => {
+		const spec = "https://petstore3.swagger.io/api/v3/openapi.json";
+		const tool = specli({ spec });
+
+		await tool.execute?.({ command: "list" }, mockOptions);
+		clearSpecliCache(spec);
+		clearSpecliCache();
+	});
+});

package/src/ai/tools.ts

@@ -0,0 +1,211 @@
+/**
+ * AI SDK tools for specli
+ *
+ * Provides tools for AI agents to explore and execute OpenAPI specs.
+ *
+ * @example
+ * ```ts
+ * import { specli } from "specli/ai";
+ * import { generateText } from "ai";
+ *
+ * const result = await generateText({
+ *   model: yourModel,
+ *   tools: {
+ *     api: specli({ spec: "https://api.example.com/openapi.json" }),
+ *   },
+ *   prompt: "List all users",
+ * });
+ * ```
+ */
+
+import { tool } from "ai";
+import { z } from "zod";
+
+import type { CommandAction } from "../cli/command-model.js";
+import { buildRuntimeContext } from "../cli/runtime/context.js";
+import { execute } from "../cli/runtime/execute.js";
+import type { RuntimeGlobals } from "../cli/runtime/request.js";
+
+export type SpecliToolOptions = {
+	/** The OpenAPI spec URL or file path */
+	spec: string;
+	/** Override the server/base URL */
+	server?: string;
+	/** Server URL template variables */
+	serverVars?: Record<string, string>;
+	/** Bearer token for authentication */
+	bearerToken?: string;
+	/** API key for authentication */
+	apiKey?: string;
+	/** Basic auth credentials */
+	basicAuth?: { username: string; password: string };
+	/** Auth scheme to use (if multiple are available) */
+	authScheme?: string;
+};
+
+// Cache contexts to avoid reloading spec on every call
+const contextCache = new Map<
+	string,
+	Awaited<ReturnType<typeof buildRuntimeContext>>
+>();
+
+async function getContext(spec: string) {
+	let ctx = contextCache.get(spec);
+	if (!ctx) {
+		ctx = await buildRuntimeContext({ spec });
+		contextCache.set(spec, ctx);
+	}
+	return ctx;
+}
+
+function findAction(
+	ctx: Awaited<ReturnType<typeof buildRuntimeContext>>,
+	resource: string,
+	action: string,
+): CommandAction | undefined {
+	const r = ctx.commands.resources.find(
+		(r) => r.resource.toLowerCase() === resource.toLowerCase(),
+	);
+	return r?.actions.find(
+		(a) => a.action.toLowerCase() === action.toLowerCase(),
+	);
+}
+
+/**
+ * Create an AI SDK tool for interacting with an OpenAPI spec.
+ */
+export function specli(options: SpecliToolOptions) {
+	const {
+		spec,
+		server,
+		serverVars,
+		bearerToken,
+		apiKey,
+		basicAuth,
+		authScheme,
+	} = options;
+
+	return tool({
+		description: `Execute API operations. Commands: "list" (show resources/actions), "help" (action details), "exec" (call API).`,
+		inputSchema: z.object({
+			command: z.enum(["list", "help", "exec"]).describe("Command to run"),
+			resource: z.string().optional().describe("Resource name (e.g. users)"),
+			action: z
+				.string()
+				.optional()
+				.describe("Action name (e.g. list, get, create)"),
+			args: z.array(z.string()).optional().describe("Positional arguments"),
+			flags: z
+				.record(z.string(), z.unknown())
+				.optional()
+				.describe("Named flags"),
+		}),
+		execute: async ({ command, resource, action, args, flags }) => {
+			const ctx = await getContext(spec);
+
+			if (command === "list") {
+				return {
+					resources: ctx.commands.resources.map((r) => ({
+						name: r.resource,
+						actions: r.actions.map((a) => ({
+							name: a.action,
+							summary: a.summary,
+							method: a.method,
+							path: a.path,
+							args: a.positionals.map((p) => p.name),
+							requiredFlags: a.flags
+								.filter((f) => f.required)
+								.map((f) => f.flag),
+						})),
+					})),
+				};
+			}
+
+			if (command === "help") {
+				if (!resource) return { error: "Missing resource" };
+				const r = ctx.commands.resources.find(
+					(r) => r.resource.toLowerCase() === resource.toLowerCase(),
+				);
+				if (!r) return { error: `Unknown resource: ${resource}` };
+				if (!action) {
+					return {
+						resource: r.resource,
+						actions: r.actions.map((a) => a.action),
+					};
+				}
+				const a = r.actions.find(
+					(a) => a.action.toLowerCase() === action.toLowerCase(),
+				);
+				if (!a) return { error: `Unknown action: ${action}` };
+				return {
+					action: a.action,
+					method: a.method,
+					path: a.path,
+					summary: a.summary,
+					args: a.positionals.map((p) => ({
+						name: p.name,
+						description: p.description,
+					})),
+					flags: a.flags.map((f) => ({
+						name: f.flag,
+						type: f.type,
+						required: f.required,
+						description: f.description,
+					})),
+				};
+			}
+
+			if (command === "exec") {
+				if (!resource || !action)
+					return { error: "Missing resource or action" };
+				const actionDef = findAction(ctx, resource, action);
+				if (!actionDef) return { error: `Unknown: ${resource} ${action}` };
+
+				const positionalValues = args ?? [];
+				if (positionalValues.length < actionDef.positionals.length) {
+					return {
+						error: `Missing args: ${actionDef.positionals
+							.slice(positionalValues.length)
+							.map((p) => p.name)
+							.join(", ")}`,
+					};
+				}
+
+				const globals: RuntimeGlobals = {
+					server,
+					serverVar: serverVars
+						? Object.entries(serverVars).map(([k, v]) => `${k}=${v}`)
+						: undefined,
+					auth: authScheme,
+					bearerToken,
+					apiKey,
+					username: basicAuth?.username,
+					password: basicAuth?.password,
+				};
+
+				try {
+					const result = await execute({
+						specId: ctx.loaded.id,
+						action: actionDef,
+						positionalValues,
+						flagValues: flags ?? {},
+						globals,
+						servers: ctx.servers,
+						authSchemes: ctx.authSchemes,
+					});
+					return { status: result.status, ok: result.ok, body: result.body };
+				} catch (err) {
+					return { error: err instanceof Error ? err.message : String(err) };
+				}
+			}
+
+			return { error: `Unknown command: ${command}` };
+		},
+	});
+}
+
+/** Clear cached spec context */
+export function clearSpecliCache(spec?: string): void {
+	if (spec) contextCache.delete(spec);
+	else contextCache.clear();
+}

package/src/cli/auth-requirements.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, test } from "bun:test";
+
+import { summarizeAuth } from "./auth-requirements.js";
+import type { AuthScheme } from "./auth-schemes.js";
+
+describe("summarizeAuth", () => {
+	test("uses operation-level security when present", () => {
+		const schemes: AuthScheme[] = [{ key: "oauth", kind: "oauth2" }];
+
+		const summary = summarizeAuth(
+			[{ oauth: ["read:ping"] }],
+			[{ oauth: ["read:other"] }],
+			schemes,
+		);
+
+		expect(summary.alternatives).toEqual([
+			[{ key: "oauth", scopes: ["read:ping"] }],
+		]);
+	});
+
+	test("empty operation security disables auth", () => {
+		const schemes: AuthScheme[] = [{ key: "oauth", kind: "oauth2" }];
+
+		const summary = summarizeAuth([], [{ oauth: ["read:other"] }], schemes);
+		expect(summary.alternatives).toEqual([]);
+	});
+});

package/src/cli/auth-requirements.ts

@@ -0,0 +1,91 @@
+import type { AuthScheme } from "./auth-schemes.js";
+import type { SecurityRequirement } from "./types.js";
+
+export type AuthRequirement = {
+	key: string;
+	scopes: string[];
+};
+
+export type AuthSummary = {
+	// Alternatives: any one of these sets is sufficient.
+	alternatives: AuthRequirement[][];
+};
+
+function isSecurityRequirement(value: unknown): value is SecurityRequirement {
+	if (!value || typeof value !== "object") return false;
+	if (Array.isArray(value)) return false;
+
+	for (const [k, v] of Object.entries(value)) {
+		if (typeof k !== "string") return false;
+		if (!Array.isArray(v)) return false;
+		if (!v.every((s) => typeof s === "string")) return false;
+	}
+
+	return true;
+}
+
+function normalizeSecurity(value: unknown): {
+	requirements: SecurityRequirement[];
+	source: "none" | "empty" | "non-empty";
+} {
+	if (value == null) return { requirements: [], source: "none" };
+	if (!Array.isArray(value)) return { requirements: [], source: "none" };
+
+	const reqs = value.filter(isSecurityRequirement);
+	if (reqs.length === 0) return { requirements: [], source: "empty" };
+	return { requirements: reqs, source: "non-empty" };
+}
+
+export function summarizeAuth(
+	operationSecurity: unknown,
+	globalSecurity: unknown,
+	knownSchemes: AuthScheme[],
+): AuthSummary {
+	// Per spec:
+	// - operation security overrides root
+	// - empty array [] means "no auth"
+	const op = normalizeSecurity(operationSecurity);
+	if (op.source === "non-empty") {
+		return { alternatives: toAlternatives(op.requirements, knownSchemes) };
+	}
+	if (op.source === "empty") {
+		return { alternatives: [] };
+	}
+
+	const global = normalizeSecurity(globalSecurity);
+	if (global.source === "non-empty") {
+		return { alternatives: toAlternatives(global.requirements, knownSchemes) };
+	}
+
+	return { alternatives: [] };
+}
+
+function toAlternatives(
+	requirements: SecurityRequirement[],
+	knownSchemes: AuthScheme[],
+): AuthRequirement[][] {
+	const known = new Set(knownSchemes.map((s) => s.key));
+
+	return requirements.map((req) => {
+		const out: AuthRequirement[] = [];
+		for (const [key, scopes] of Object.entries(req)) {
+			out.push({
+				key,
+				scopes: Array.isArray(scopes) ? scopes : [],
+			});
+		}
+
+		// Stable order.
+		out.sort((a, b) => a.key.localeCompare(b.key));
+
+		// Prefer known schemes first.
+		out.sort((a, b) => {
+			const ak = known.has(a.key) ? 0 : 1;
+			const bk = known.has(b.key) ? 0 : 1;
+			if (ak !== bk) return ak - bk;
+			return a.key.localeCompare(b.key);
+		});
+
+		return out;
+	});
+}

package/src/cli/auth-schemes.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test } from "bun:test";
+
+import { listAuthSchemes } from "./auth-schemes.js";
+import type { OpenApiDoc } from "./types.js";
+
+describe("listAuthSchemes", () => {
+	test("parses bearer + apiKey", () => {
+		const doc: OpenApiDoc = {
+			openapi: "3.0.3",
+			components: {
+				securitySchemes: {
+					bearerAuth: {
+						type: "http",
+						scheme: "bearer",
+						bearerFormat: "JWT",
+					},
+					apiKeyAuth: {
+						type: "apiKey",
+						in: "header",
+						name: "X-API-Key",
+					},
+				},
+			},
+		};
+
+		const schemes = listAuthSchemes(doc);
+		expect(schemes).toHaveLength(2);
+
+		const bearer = schemes.find((s) => s.key === "bearerAuth");
+		expect(bearer?.kind).toBe("http-bearer");
+
+		const apiKey = schemes.find((s) => s.key === "apiKeyAuth");
+		expect(apiKey?.kind).toBe("api-key");
+		expect(apiKey?.in).toBe("header");
+		expect(apiKey?.name).toBe("X-API-Key");
+	});
+
+	test("parses oauth2 flows", () => {
+		const doc = {
+			openapi: "3.0.3",
+			components: {
+				securitySchemes: {
+					oauth: {
+						type: "oauth2",
+						flows: {
+							clientCredentials: {
+								tokenUrl: "https://example.com/oauth/token",
+								scopes: {
+									"read:ping": "read ping",
+								},
+							},
+						},
+					},
+				},
+			},
+		} as const;
+
+		const schemes = listAuthSchemes(doc);
+		const oauth = schemes.find((s) => s.key === "oauth");
+		expect(oauth?.kind).toBe("oauth2");
+		expect(oauth?.oauthFlows?.clientCredentials?.tokenUrl).toBe(
+			"https://example.com/oauth/token",
+		);
+		expect(oauth?.oauthFlows?.clientCredentials?.scopes).toEqual(["read:ping"]);
+	});
+});

package/src/cli/auth-schemes.ts

@@ -0,0 +1,187 @@
+import { kebabCase } from "./strings.js";
+import type { OpenApiDoc } from "./types.js";
+
+export type AuthSchemeKind =
+	| "http-bearer"
+	| "http-basic"
+	| "api-key"
+	| "oauth2"
+	| "openIdConnect"
+	| "unknown";
+
+export type AuthScheme = {
+	key: string;
+	kind: AuthSchemeKind;
+	name?: string;
+	in?: "header" | "query" | "cookie";
+	scheme?: string;
+	bearerFormat?: string;
+	description?: string;
+
+	// oauth2/openid only (subset of spec, enough to derive flags + docs)
+	oauthFlows?: OAuthFlows;
+	openIdConnectUrl?: string;
+};
+
+export type OAuthFlow = {
+	authorizationUrl?: string;
+	tokenUrl?: string;
+	refreshUrl?: string;
+	scopes: string[];
+};
+
+export type OAuthFlows = Partial<
+	Record<
+		"implicit" | "password" | "clientCredentials" | "authorizationCode",
+		OAuthFlow
+	>
+>;
+
+type RawOAuthFlow = {
+	authorizationUrl?: unknown;
+	tokenUrl?: unknown;
+	refreshUrl?: unknown;
+	scopes?: unknown;
+};
+
+type RawOAuthFlows = {
+	implicit?: RawOAuthFlow;
+	password?: RawOAuthFlow;
+	clientCredentials?: RawOAuthFlow;
+	authorizationCode?: RawOAuthFlow;
+};
+
+type RawSecurityScheme = {
+	type?: string;
+	description?: string;
+	name?: string;
+	in?: string;
+	scheme?: string;
+	bearerFormat?: string;
+	flows?: RawOAuthFlows;
+	openIdConnectUrl?: string;
+};
+
+function parseOAuthFlow(flow: RawOAuthFlow | undefined): OAuthFlow | undefined {
+	if (!flow) return undefined;
+	const scopesObj = flow.scopes;
+	const scopes =
+		scopesObj && typeof scopesObj === "object" && !Array.isArray(scopesObj)
+			? Object.keys(scopesObj as Record<string, unknown>)
+			: [];
+
+	return {
+		authorizationUrl:
+			typeof flow.authorizationUrl === "string"
+				? flow.authorizationUrl
+				: undefined,
+		tokenUrl: typeof flow.tokenUrl === "string" ? flow.tokenUrl : undefined,
+		refreshUrl:
+			typeof flow.refreshUrl === "string" ? flow.refreshUrl : undefined,
+		scopes: scopes.sort(),
+	};
+}
+
+function parseOAuthFlows(
+	flows: RawOAuthFlows | undefined,
+): OAuthFlows | undefined {
+	if (!flows) return undefined;
+	const out: OAuthFlows = {};
+
+	const implicit = parseOAuthFlow(flows.implicit);
+	if (implicit) out.implicit = implicit;
+
+	const password = parseOAuthFlow(flows.password);
+	if (password) out.password = password;
+
+	const clientCredentials = parseOAuthFlow(flows.clientCredentials);
+	if (clientCredentials) out.clientCredentials = clientCredentials;
+
+	const authorizationCode = parseOAuthFlow(flows.authorizationCode);
+	if (authorizationCode) out.authorizationCode = authorizationCode;
+
+	return Object.keys(out).length ? out : undefined;
+}
+
+export function listAuthSchemes(doc: OpenApiDoc): AuthScheme[] {
+	const schemes = doc.components?.securitySchemes;
+	if (!schemes || typeof schemes !== "object") return [];
+
+	const out: AuthScheme[] = [];
+
+	for (const [key, raw] of Object.entries(schemes)) {
+		if (!raw || typeof raw !== "object") continue;
+		const s = raw as RawSecurityScheme;
+
+		const type = s.type;
+		if (type === "http") {
+			const scheme = (s.scheme ?? "").toLowerCase();
+			if (scheme === "bearer") {
+				out.push({
+					key,
+					kind: "http-bearer",
+					scheme: scheme,
+					bearerFormat: s.bearerFormat,
+					description: s.description,
+				});
+			} else if (scheme === "basic") {
+				out.push({
+					key,
+					kind: "http-basic",
+					scheme: scheme,
+					description: s.description,
+				});
+			} else {
+				out.push({
+					key,
+					kind: "unknown",
+					scheme: s.scheme,
+					description: s.description,
+				});
+			}
+			continue;
+		}
+
+		if (type === "apiKey") {
+			const where = s.in;
+			const loc =
+				where === "header" || where === "query" || where === "cookie"
+					? where
+					: undefined;
+			out.push({
+				key,
+				kind: "api-key",
+				name: s.name,
+				in: loc,
+				description: s.description,
+			});
+			continue;
+		}
+
+		if (type === "oauth2") {
+			out.push({
+				key,
+				kind: "oauth2",
+				description: s.description,
+				oauthFlows: parseOAuthFlows(s.flows),
+			});
+			continue;
+		}
+
+		if (type === "openIdConnect") {
+			out.push({
+				key,
+				kind: "openIdConnect",
+				description: s.description,
+				openIdConnectUrl: s.openIdConnectUrl,
+			});
+			continue;
+		}
+
+		out.push({ key, kind: "unknown", description: s.description });
+	}
+
+	// Stable order.
+	out.sort((a, b) => kebabCase(a.key).localeCompare(kebabCase(b.key)));
+	return out;
+}