specli 0.0.18 → 0.0.20

package/src/ai/tools.ts

@@ -1,211 +0,0 @@
-/**
- * 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

@@ -1,27 +0,0 @@
-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

@@ -1,91 +0,0 @@
-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

@@ -1,66 +0,0 @@
-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

@@ -1,187 +0,0 @@
-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;
-}

package/src/cli/capabilities.test.ts

@@ -1,94 +0,0 @@
-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"]);
-	});
-});