specli 0.0.10 → 0.0.12

package/bin/cli.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env sh
+set -eu
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+CLI_JS="$SCRIPT_DIR/../dist/cli.js"
+
+is_compile=0
+for arg in "$@"; do
+	if [ "$arg" = "compile" ]; then
+		is_compile=1
+		break
+	fi
+done
+
+# 1. Prefer Bun if installed
+if command -v bun >/dev/null 2>&1; then
+	exec bun "$CLI_JS" "$@"
+fi
+
+# 2. Bun is required for compile
+if [ "$is_compile" -eq 1 ]; then
+	printf '%s\n' "Error: The 'compile' command requires Bun." "Install Bun: https://bun.sh" >&2
+	exit 1
+fi
+
+# 3. Fallback to Node.js
+exec node "$CLI_JS" "$@"

package/dist/{src/ai → ai}/tools.d.ts

@@ -136,4 +136,3 @@ export declare function specli(options: SpecliToolOptions): import("ai").Tool<{
 }>;
 /** Clear cached spec context */
 export declare function clearSpecliCache(spec?: string): void;
-//# sourceMappingURL=tools.d.ts.map

package/dist/ai/tools.js

@@ -0,0 +1,161 @@
+/**
+ * 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 { buildRuntimeContext } from "../cli/runtime/context.js";
+import { execute } from "../cli/runtime/execute.js";
+// Cache contexts to avoid reloading spec on every call
+const contextCache = new Map();
+async function getContext(spec) {
+    let ctx = contextCache.get(spec);
+    if (!ctx) {
+        ctx = await buildRuntimeContext({ spec });
+        contextCache.set(spec, ctx);
+    }
+    return ctx;
+}
+function findAction(ctx, resource, action) {
+    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) {
+    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 = {
+                    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) {
+    if (spec)
+        contextCache.delete(spec);
+    else
+        contextCache.clear();
+}

package/dist/ai/tools.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ai/tools.test.js

@@ -0,0 +1,56 @@
+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));
+        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));
+        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));
+        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));
+        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/dist/{src/cli → cli}/auth-requirements.d.ts

@@ -7,4 +7,3 @@ export type AuthSummary = {
     alternatives: AuthRequirement[][];
 };
 export declare function summarizeAuth(operationSecurity: unknown, globalSecurity: unknown, knownSchemes: AuthScheme[]): AuthSummary;
-//# sourceMappingURL=auth-requirements.d.ts.map

package/dist/cli/auth-requirements.js

@@ -0,0 +1,65 @@
+function isSecurityRequirement(value) {
+    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) {
+    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, globalSecurity, knownSchemes) {
+    // 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, knownSchemes) {
+    const known = new Set(knownSchemes.map((s) => s.key));
+    return requirements.map((req) => {
+        const out = [];
+        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/dist/cli/auth-requirements.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/auth-requirements.test.js

@@ -0,0 +1,16 @@
+import { describe, expect, test } from "bun:test";
+import { summarizeAuth } from "./auth-requirements.js";
+describe("summarizeAuth", () => {
+    test("uses operation-level security when present", () => {
+        const schemes = [{ 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 = [{ key: "oauth", kind: "oauth2" }];
+        const summary = summarizeAuth([], [{ oauth: ["read:other"] }], schemes);
+        expect(summary.alternatives).toEqual([]);
+    });
+});

package/dist/{src/cli → cli}/auth-schemes.d.ts

@@ -19,4 +19,3 @@ export type OAuthFlow = {
 };
 export type OAuthFlows = Partial<Record<"implicit" | "password" | "clientCredentials" | "authorizationCode", OAuthFlow>>;
 export declare function listAuthSchemes(doc: OpenApiDoc): AuthScheme[];
-//# sourceMappingURL=auth-schemes.d.ts.map

package/dist/cli/auth-schemes.js

@@ -0,0 +1,112 @@
+import { kebabCase } from "./strings.js";
+function parseOAuthFlow(flow) {
+    if (!flow)
+        return undefined;
+    const scopesObj = flow.scopes;
+    const scopes = scopesObj && typeof scopesObj === "object" && !Array.isArray(scopesObj)
+        ? Object.keys(scopesObj)
+        : [];
+    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) {
+    if (!flows)
+        return undefined;
+    const out = {};
+    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) {
+    const schemes = doc.components?.securitySchemes;
+    if (!schemes || typeof schemes !== "object")
+        return [];
+    const out = [];
+    for (const [key, raw] of Object.entries(schemes)) {
+        if (!raw || typeof raw !== "object")
+            continue;
+        const s = raw;
+        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/dist/cli/auth-schemes.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/auth-schemes.test.js

@@ -0,0 +1,56 @@
+import { describe, expect, test } from "bun:test";
+import { listAuthSchemes } from "./auth-schemes.js";
+describe("listAuthSchemes", () => {
+    test("parses bearer + apiKey", () => {
+        const doc = {
+            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",
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        };
+        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/dist/{src/cli → cli}/capabilities.d.ts

@@ -29,4 +29,3 @@ export declare function deriveCapabilities(input: {
     operations: NormalizedOperation[];
     commands?: CommandModel;
 }): Capabilities;
-//# sourceMappingURL=capabilities.d.ts.map

package/dist/cli/capabilities.js

@@ -0,0 +1,41 @@
+function uniqueSorted(items, compare) {
+    const out = [...items];
+    out.sort(compare);
+    return out.filter((v, i) => i === 0 || compare(out[i - 1], v) !== 0);
+}
+function hasSecurity(requirements) {
+    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) {
+    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/dist/cli/capabilities.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/capabilities.test.js

@@ -0,0 +1,84 @@
+import { describe, expect, test } from "bun:test";
+import { deriveCapabilities } from "./capabilities.js";
+describe("deriveCapabilities", () => {
+    test("reports requestBody + server vars", () => {
+        const doc = {
+            openapi: "3.0.3",
+            security: [{ bearerAuth: [] }],
+        };
+        const servers = [
+            {
+                url: "https://{region}.api.example.com",
+                variables: [],
+                variableNames: ["region"],
+            },
+        ];
+        const authSchemes = [
+            { key: "bearerAuth", kind: "http-bearer" },
+        ];
+        const operations = [
+            {
+                key: "POST /contacts",
+                method: "POST",
+                path: "/contacts",
+                tags: [],
+                parameters: [],
+                requestBody: {
+                    required: true,
+                    contentTypes: ["application/json"],
+                    schemasByContentType: { "application/json": { type: "object" } },
+                },
+            },
+        ];
+        const commands = {
+            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/dist/{src/cli → cli}/command-id.d.ts

@@ -5,4 +5,3 @@ export type CommandIdParts = {
     operationKey: string;
 };
 export declare function buildCommandId(parts: CommandIdParts): string;
-//# sourceMappingURL=command-id.d.ts.map

package/dist/cli/command-id.js

@@ -0,0 +1,8 @@
+import { kebabCase } from "./strings.js";
+export function buildCommandId(parts) {
+    // 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}`;
+}