specli 0.0.11 → 0.0.13

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.ts";
-import { buildRuntimeContext } from "../cli/runtime/context.ts";
-import { execute } from "../cli/runtime/execute.ts";
-import type { RuntimeGlobals } from "../cli/runtime/request.ts";
-
-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.ts

@@ -1,91 +0,0 @@
-import type { AuthScheme } from "./auth-schemes.ts";
-import type { SecurityRequirement } from "./types.ts";
-
-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.ts

@@ -1,187 +0,0 @@
-import { kebabCase } from "./strings.ts";
-import type { OpenApiDoc } from "./types.ts";
-
-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.ts

@@ -1,88 +0,0 @@
-import type { AuthScheme, AuthSchemeKind } from "./auth-schemes.ts";
-import type { CommandModel } from "./command-model.ts";
-import type { ServerInfo } from "./server.ts";
-import type {
-	NormalizedOperation,
-	OpenApiDoc,
-	SecurityRequirement,
-} from "./types.ts";
-
-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.ts

@@ -1,16 +0,0 @@
-import { kebabCase } from "./strings.ts";
-
-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

@@ -1,19 +0,0 @@
-import type { CommandAction, CommandModel } from "./command-model.ts";
-
-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 };
-}