specli 0.0.18 → 0.0.20

package/README.md

@@ -321,7 +321,7 @@ import { generateText } from "ai";
 const result = await generateText({
   model: yourModel,
   tools: {
-    api: specli({
+    api: await specli({
       spec: "https://api.example.com/openapi.json",
       bearerToken: process.env.API_TOKEN,
     }),
@@ -330,6 +330,8 @@ const result = await generateText({
 });
 ```
 
+The `specli()` function is async and fetches the OpenAPI spec upfront, so the returned tool is ready to use immediately without any additional network requests.
+
 The tool supports three commands:
 - `list` - Show available resources and actions
 - `help` - Get details about a specific action

package/dist/ai/tools.d.ts

@@ -11,7 +11,7 @@
  * const result = await generateText({
  *   model: yourModel,
  *   tools: {
- *     api: specli({ spec: "https://api.example.com/openapi.json" }),
+ *     api: await specli({ spec: "https://api.example.com/openapi.json" }),
  *   },
  *   prompt: "List all users",
  * });
@@ -38,8 +38,11 @@ export type SpecliToolOptions = {
 };
 /**
  * Create an AI SDK tool for interacting with an OpenAPI spec.
+ *
+ * The spec is fetched once when this function is called, so the returned
+ * tool already has the spec loaded and ready to use.
  */
-export declare function specli(options: SpecliToolOptions): import("ai").Tool<{
+export declare function specli(options: SpecliToolOptions): Promise<import("ai").Tool<{
     command: "list" | "exec" | "help";
     resource?: string | undefined;
     action?: string | undefined;
@@ -133,6 +136,4 @@ export declare function specli(options: SpecliToolOptions): import("ai").Tool<{
     summary?: undefined;
     args?: undefined;
     flags?: undefined;
-}>;
-/** Clear cached spec context */
-export declare function clearSpecliCache(spec?: string): void;
+}>>;

package/dist/ai/tools.js

@@ -11,7 +11,7 @@
  * const result = await generateText({
  *   model: yourModel,
  *   tools: {
- *     api: specli({ spec: "https://api.example.com/openapi.json" }),
+ *     api: await specli({ spec: "https://api.example.com/openapi.json" }),
  *   },
  *   prompt: "List all users",
  * });
@@ -21,25 +21,20 @@ 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.
+ *
+ * The spec is fetched once when this function is called, so the returned
+ * tool already has the spec loaded and ready to use.
  */
-export function specli(options) {
+export async function specli(options) {
     const { spec, server, serverVars, bearerToken, apiKey, basicAuth, authScheme, } = options;
+    // Fetch and parse the spec upfront
+    const ctx = await buildRuntimeContext({ spec });
     return tool({
         description: `Execute API operations. Commands: "list" (show resources/actions), "help" (action details), "exec" (call API).`,
         inputSchema: z.object({
@@ -56,7 +51,6 @@ export function specli(options) {
                 .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) => ({
@@ -152,10 +146,3 @@ export function specli(options) {
         },
     });
 }
-/** Clear cached spec context */
-export function clearSpecliCache(spec) {
-    if (spec)
-        contextCache.delete(spec);
-    else
-        contextCache.clear();
-}

package/dist/ai/tools.test.js

@@ -1,13 +1,13 @@
 import { describe, expect, test } from "bun:test";
-import { clearSpecliCache, specli } from "./tools.js";
+import { 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({
+    test("creates a tool with correct structure", async () => {
+        const tool = await specli({
             spec: "https://petstore3.swagger.io/api/v3/openapi.json",
         });
         expect(tool).toHaveProperty("description");
@@ -16,7 +16,7 @@ describe("specli tool", () => {
         expect(typeof tool.execute).toBe("function");
     });
     test("list command returns resources", async () => {
-        const tool = specli({
+        const tool = await specli({
             spec: "https://petstore3.swagger.io/api/v3/openapi.json",
         });
         const result = (await tool.execute?.({ command: "list" }, mockOptions));
@@ -24,7 +24,7 @@ describe("specli tool", () => {
         expect(Array.isArray(result.resources)).toBe(true);
     });
     test("help command returns action details", async () => {
-        const tool = specli({
+        const tool = await specli({
             spec: "https://petstore3.swagger.io/api/v3/openapi.json",
         });
         const result = (await tool.execute?.({ command: "help", resource: "pets", action: "get" }, mockOptions));
@@ -32,25 +32,18 @@ describe("specli tool", () => {
         expect(result.action).toBe("get");
     });
     test("help command with missing resource returns error", async () => {
-        const tool = specli({
+        const tool = await 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({
+        const tool = await 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/cli/compile.js

@@ -1,11 +1,11 @@
+import fs from "node:fs";
+import os from "node:os";
 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)
+// Resolve the package root directory (at runtime this file is at dist/cli/compile.js)
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const compiledEntrypoint = path.resolve(__dirname, "../../src/compiled.ts");
+const packageRoot = path.resolve(__dirname, "../..");
 function parseKeyValue(input) {
     const idx = input.indexOf("=");
     if (idx === -1)
@@ -16,6 +16,72 @@ function parseKeyValue(input) {
         throw new Error(`Invalid --define '${input}', missing key`);
     return { key, value };
 }
+/**
+ * Loads the OpenAPI spec from a URL or file path.
+ */
+async function loadSpec(spec) {
+    if (!spec)
+        throw new Error("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 fs.promises.readFile(spec, "utf-8");
+}
+/**
+ * Reads the package version from package.json.
+ */
+function getPackageVersion() {
+    const packageJsonPath = path.join(packageRoot, "package.json");
+    const content = fs.readFileSync(packageJsonPath, "utf-8");
+    const packageJson = JSON.parse(content);
+    return packageJson.version;
+}
+/**
+ * Generates a temporary entrypoint file with all values hardcoded.
+ * This avoids the Bun macro security restriction in node_modules.
+ */
+function generateEntrypoint(options) {
+    const mainImportPath = path.join(packageRoot, "dist/cli/main.js");
+    // Escape the spec text for embedding as a string literal
+    const escapedSpec = JSON.stringify(options.specText);
+    const escapedName = options.cliName
+        ? JSON.stringify(options.cliName)
+        : "undefined";
+    const escapedServer = options.server
+        ? JSON.stringify(options.server)
+        : "undefined";
+    const escapedServerVars = options.serverVars
+        ? JSON.stringify(options.serverVars)
+        : "undefined";
+    const escapedAuth = options.auth ? JSON.stringify(options.auth) : "undefined";
+    const escapedVersion = JSON.stringify(options.version);
+    return `#!/usr/bin/env bun
+// Auto-generated entrypoint for specli compile
+// This file embeds all configuration at build time
+
+import { main } from ${JSON.stringify(mainImportPath)};
+
+const embeddedSpecText = ${escapedSpec};
+const cliName = ${escapedName};
+const server = ${escapedServer};
+const serverVars = ${escapedServerVars};
+const auth = ${escapedAuth};
+const embeddedVersion = ${escapedVersion};
+
+await main(process.argv, {
+	embeddedSpecText,
+	cliName,
+	server,
+	serverVars: serverVars ? serverVars.split(",") : undefined,
+	auth,
+	version: embeddedVersion,
+});
+`;
+}
 export async function compileCommand(spec, options) {
     // Derive name from spec if not provided
     const name = options.name ?? (await deriveBinaryName(spec));
@@ -23,64 +89,74 @@ export async function compileCommand(spec, options) {
     const target = options.target
         ? options.target
         : `bun-${process.platform}-${process.arch}`;
-    // Parse --define pairs
-    const define = {};
-    if (options.define) {
-        for (const pair of options.define) {
-            const { key, value } = parseKeyValue(pair);
-            define[key] = JSON.stringify(value);
+    // Load the spec content
+    process.stdout.write(`Loading spec: ${spec}\n`);
+    const specText = await loadSpec(spec);
+    // Get package version
+    const version = getPackageVersion();
+    // Generate temporary entrypoint file
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "specli-"));
+    const tempEntrypoint = path.join(tempDir, "entrypoint.ts");
+    const entrypointCode = generateEntrypoint({
+        specText,
+        cliName: name,
+        server: options.server,
+        serverVars: options.serverVar?.join(","),
+        auth: options.auth,
+        version,
+    });
+    fs.writeFileSync(tempEntrypoint, entrypointCode);
+    try {
+        // Parse --define pairs
+        const define = {};
+        if (options.define) {
+            for (const pair of options.define) {
+                const { key, value } = parseKeyValue(pair);
+                define[key] = JSON.stringify(value);
+            }
         }
+        // Build command args
+        const buildArgs = [
+            "build",
+            "--compile",
+            `--outfile=${outfile}`,
+            `--target=${target}`,
+        ];
+        if (options.minify)
+            buildArgs.push("--minify");
+        if (options.bytecode)
+            buildArgs.push("--bytecode");
+        for (const [k, v] of Object.entries(define)) {
+            buildArgs.push("--define", `${k}=${v}`);
+        }
+        if (options.dotenv === false)
+            buildArgs.push("--no-compile-autoload-dotenv");
+        if (options.bunfig === false)
+            buildArgs.push("--no-compile-autoload-bunfig");
+        buildArgs.push(tempEntrypoint);
+        const proc = Bun.spawn({
+            cmd: ["bun", ...buildArgs],
+            stdout: "pipe",
+            stderr: "pipe",
+            env: process.env,
+        });
+        const output = await new Response(proc.stdout).text();
+        const error = await new Response(proc.stderr).text();
+        const code = await proc.exited;
+        if (output)
+            process.stdout.write(output);
+        if (error)
+            process.stderr.write(error);
+        if (code !== 0) {
+            process.exitCode = code;
+            return;
+        }
+        process.stdout.write(`ok: built ${outfile}\n`);
+        process.stdout.write(`target: ${target}\n`);
+        process.stdout.write(`name: ${name}\n`);
     }
-    // Build command args
-    const buildArgs = [
-        "build",
-        "--compile",
-        `--outfile=${outfile}`,
-        `--target=${target}`,
-    ];
-    if (options.minify)
-        buildArgs.push("--minify");
-    if (options.bytecode)
-        buildArgs.push("--bytecode");
-    for (const [k, v] of Object.entries(define)) {
-        buildArgs.push("--define", `${k}=${v}`);
-    }
-    if (options.dotenv === false)
-        buildArgs.push("--no-compile-autoload-dotenv");
-    if (options.bunfig === false)
-        buildArgs.push("--no-compile-autoload-bunfig");
-    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 = {
-        ...process.env,
-        SPECLI_SPEC: spec,
-        SPECLI_NAME: name,
-    };
-    if (options.server)
-        buildEnv.SPECLI_SERVER = options.server;
-    if (options.serverVar?.length)
-        buildEnv.SPECLI_SERVER_VARS = options.serverVar.join(",");
-    if (options.auth)
-        buildEnv.SPECLI_AUTH = options.auth;
-    const proc = Bun.spawn({
-        cmd: ["bun", ...buildArgs],
-        stdout: "pipe",
-        stderr: "pipe",
-        env: buildEnv,
-    });
-    const output = await new Response(proc.stdout).text();
-    const error = await new Response(proc.stderr).text();
-    const code = await proc.exited;
-    if (output)
-        process.stdout.write(output);
-    if (error)
-        process.stderr.write(error);
-    if (code !== 0) {
-        process.exitCode = code;
-        return;
+    finally {
+        // Clean up temporary files
+        fs.rmSync(tempDir, { recursive: true, force: true });
     }
-    process.stdout.write(`ok: built ${outfile}\n`);
-    process.stdout.write(`target: ${target}\n`);
-    process.stdout.write(`name: ${name}\n`);
 }

package/dist/cli.d.ts

@@ -1,2 +1 @@
-#!/usr/bin/env node
 export {};

package/dist/cli.js

@@ -1,4 +1,3 @@
-#!/usr/bin/env node
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";

package/package.json

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

package/src/ai/tools.test.ts

@@ -1,83 +0,0 @@
-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();
-	});
-});