specli 0.0.35 → 0.0.36

package/README.md

@@ -1,7 +1,23 @@
 # specli
 
+[![npm version](https://img.shields.io/npm/v/specli.svg)](https://www.npmjs.com/package/specli)
+
 Turn any OpenAPI spec into a CLI.
 
+## Demo
+
+Compile this weather OpenAPI spec to an executable:
+
+```sh
+npx specli compile https://raw.githubusercontent.com/open-meteo/open-meteo/refs/heads/main/openapi.yml --name weather
+```
+
+Ask an agent what the current weather is:
+
+```sh
+opencode run 'Using ./out/weather what is the current weather in new york city'
+```
+
 ## Install
 
 ```bash
@@ -330,8 +346,8 @@ const help = api.help("users", "get");
 
 // Execute an API call
 const result = await api.exec("users", "get", ["123"], { include: "profile" });
-if (result.ok) {
-  console.log(result.body);
+if (result.type === "success" && result.response.ok) {
+  console.log(result.response.body);
 }
 ```
 
@@ -355,16 +371,40 @@ if (result.ok) {
 | `help(resource, action)` | Get detailed info about an action |
 | `exec(resource, action, args?, flags?)` | Execute an API call |
 
-### ExecuteResult
+### CommandResult
 
-The `exec()` method returns:
+The `exec()` method returns a `CommandResult` which is a discriminated union:
 
 ```typescript
+// Success
 {
-  ok: boolean;     // true if status 2xx
-  status: number;  // HTTP status code
-  body: unknown;   // Parsed response body
-  curl: string;    // Equivalent curl command
+  type: "success";
+  request: PreparedRequest;
+  response: {
+    status: number;
+    ok: boolean;
+    headers: Record<string, string>;
+    body: unknown;
+    rawBody: string;
+  };
+  timing: { startedAt: string; durationMs: number };
+}
+
+// Error
+{
+  type: "error";
+  message: string;
+  response?: ResponseData;  // If HTTP error
+}
+```
+
+Type guards are available for convenience:
+
+```typescript
+import { isSuccess, isError } from "specli";
+
+if (isSuccess(result)) {
+  console.log(result.response.body);
 }
 ```
 
@@ -413,19 +453,3 @@ bun test
 bun run lint
 bun run typecheck
 ```
-
-## Demos
-
-### Weather
-
-Compile the weather spec to an executable:
-
-```sh
-npx specli compile https://raw.githubusercontent.com/open-meteo/open-meteo/refs/heads/main/openapi.yml --name weather
-```
-
-Ask an agent what the current weather is:
-
-```sh
-opencode run 'Using ./out/weather what is the current weather in new york city'
-```

package/dist/ai/tools.d.ts

@@ -30,38 +30,6 @@ export declare function specliTool(options: SpecliOptions): Promise<import("ai")
     action?: string | undefined;
     args?: string[] | undefined;
     flags?: Record<string, unknown> | undefined;
-}, import("../client/index.js").ActionDetail | {
-    resources: import("../client/index.js").ResourceInfo[];
-    error?: undefined;
-    resource?: undefined;
-    actions?: undefined;
-    status?: undefined;
-    ok?: undefined;
-    body?: undefined;
-} | {
-    error: string;
-    resources?: undefined;
-    resource?: undefined;
-    actions?: undefined;
-    status?: undefined;
-    ok?: undefined;
-    body?: undefined;
-} | {
-    resource: string;
-    actions: string[];
-    resources?: undefined;
-    error?: undefined;
-    status?: undefined;
-    ok?: undefined;
-    body?: undefined;
-} | {
-    status: number;
-    ok: boolean;
-    body: unknown;
-    resources?: undefined;
-    error?: undefined;
-    resource?: undefined;
-    actions?: undefined;
-}>>;
+}, Record<string, unknown> | import("../client/index.js").ActionDetail>>;
 export { specliTool as specli };
 export type { SpecliOptions as SpecliToolOptions } from "../client/index.js";

package/dist/ai/tools.js

@@ -19,6 +19,7 @@
  */
 import { tool } from "ai";
 import { z } from "zod";
+import { toJSON } from "../cli/runtime/render.js";
 import { createClient } from "../client/index.js";
 /**
  * Create an AI SDK tool for interacting with an OpenAPI spec.
@@ -69,13 +70,8 @@ export async function specliTool(options) {
             if (command === "exec") {
                 if (!resource || !action)
                     return { error: "Missing resource or action" };
-                try {
-                    const result = await client.exec(resource, action, args ?? [], flags ?? {});
-                    return { status: result.status, ok: result.ok, body: result.body };
-                }
-                catch (err) {
-                    return { error: err instanceof Error ? err.message : String(err) };
-                }
+                const result = await client.exec(resource, action, args ?? [], flags ?? {});
+                return toJSON(result);
             }
             return { error: `Unknown command: ${command}` };
         },

package/dist/cli/model/command-model.d.ts

@@ -9,7 +9,10 @@ export type CommandAction = {
     id: string;
     key: string;
     action: string;
+    /** CLI-friendly path arg names (kebab-case) for display */
     pathArgs: string[];
+    /** Original path template variable names (for URL substitution) */
+    rawPathArgs: string[];
     method: string;
     path: string;
     operationId?: string;

package/dist/cli/model/command-model.js

@@ -20,6 +20,7 @@ export function buildCommandModel(planned, options) {
             key: op.key,
             action: op.action,
             pathArgs: op.pathArgs,
+            rawPathArgs: op.rawPathArgs,
             method: op.method,
             path: op.path,
             operationId: op.operationId,

package/dist/cli/model/naming.d.ts

@@ -2,7 +2,10 @@ import type { NormalizedOperation } from "../core/types.js";
 export type PlannedOperation = NormalizedOperation & {
     resource: string;
     action: string;
+    /** CLI-friendly path arg names (kebab-case) */
     pathArgs: string[];
+    /** Original path template variable names (for URL substitution) */
+    rawPathArgs: string[];
     style: "rest" | "rpc";
     canonicalAction: string;
     aliasOf?: string;

package/dist/cli/model/naming.js

@@ -234,6 +234,7 @@ export function planOperation(op) {
     const style = inferStyle(op);
     const resource = inferResource(op);
     const action = style === "rpc" ? inferRpcAction(op) : inferRestAction(op);
+    const rawPathArgs = getPathArgs(op.path);
     return {
         ...op,
         key: op.key,
@@ -241,7 +242,8 @@ export function planOperation(op) {
         resource,
         action,
         canonicalAction: action,
-        pathArgs: getPathArgs(op.path).map((a) => kebabCase(a)),
+        pathArgs: rawPathArgs.map((a) => kebabCase(a)),
+        rawPathArgs,
     };
 }
 export function planOperations(ops) {

package/dist/cli/runtime/execute.d.ts

@@ -3,6 +3,7 @@ import type { AuthScheme } from "../parse/auth-schemes.js";
 import type { ServerInfo } from "../parse/servers.js";
 import type { BodyFlagDef } from "./body-flags.js";
 import { type EmbeddedDefaults, type RuntimeGlobals } from "./request.js";
+import type { CommandResult } from "./result.js";
 export type ExecuteInput = {
     action: CommandAction;
     positionalValues: string[];
@@ -16,17 +17,16 @@ export type ExecuteInput = {
     /** Resource name for error messages (e.g. "plans") */
     resourceName?: string;
 };
-export type ExecuteResult = {
-    ok: boolean;
-    status: number;
-    body: unknown;
-    curl: string;
-};
 /**
- * Execute an action and return the result as data.
+ * Build a prepared request without executing it.
+ * Returns a PreparedResult or ErrorResult (for validation failures).
+ */
+export declare function prepare(input: Omit<ExecuteInput, "resourceName">): Promise<CommandResult>;
+/**
+ * Execute an action and return the result as a CommandResult.
  * This is the core execution function used by both CLI and programmatic API.
  */
-export declare function execute(input: Omit<ExecuteInput, "resourceName">): Promise<ExecuteResult>;
+export declare function execute(input: Omit<ExecuteInput, "resourceName">): Promise<CommandResult>;
 /**
  * Execute an action and write output to stdout/stderr.
  * This is the CLI-facing wrapper around execute().

package/dist/cli/runtime/execute.js

@@ -1,47 +1,133 @@
+import { getExitCode, getOutputStream, renderToString } from "./render.js";
 import { buildRequest, } from "./request.js";
 /**
- * Format an error message with a help hint.
+ * Build a prepared request without executing it.
+ * Returns a PreparedResult or ErrorResult (for validation failures).
  */
-function formatError(message, resourceName, actionName) {
-    const helpCmd = resourceName
-        ? `${resourceName} ${actionName} --help`
-        : `${actionName} --help`;
-    return `${message}\n\nRun '${helpCmd}' to see available options.`;
+export async function prepare(input) {
+    try {
+        const { request, curl, body } = await buildRequest({
+            specId: input.specId,
+            action: input.action,
+            positionalValues: input.positionalValues,
+            flagValues: input.flagValues,
+            globals: input.globals,
+            servers: input.servers,
+            authSchemes: input.authSchemes,
+            embeddedDefaults: input.embeddedDefaults,
+            bodyFlagDefs: input.bodyFlagDefs,
+        });
+        const headers = {};
+        for (const [key, value] of request.headers.entries()) {
+            headers[key] = value;
+        }
+        const prepared = {
+            method: request.method,
+            url: request.url,
+            headers,
+            body,
+            curl,
+        };
+        return {
+            type: "prepared",
+            request: prepared,
+        };
+    }
+    catch (err) {
+        return {
+            type: "error",
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
 }
 /**
- * Execute an action and return the result as data.
+ * Execute an action and return the result as a CommandResult.
  * This is the core execution function used by both CLI and programmatic API.
  */
 export async function execute(input) {
-    const { request, curl } = await buildRequest({
-        specId: input.specId,
-        action: input.action,
-        positionalValues: input.positionalValues,
-        flagValues: input.flagValues,
-        globals: input.globals,
-        servers: input.servers,
-        authSchemes: input.authSchemes,
-        embeddedDefaults: input.embeddedDefaults,
-        bodyFlagDefs: input.bodyFlagDefs,
-    });
-    const res = await fetch(request);
-    const contentType = res.headers.get("content-type") ?? "";
-    const text = await res.text();
-    let body = text;
-    if (contentType.includes("json") && text) {
-        try {
-            body = JSON.parse(text);
+    const startTime = Date.now();
+    const startedAt = new Date().toISOString();
+    try {
+        const { request, curl, body } = await buildRequest({
+            specId: input.specId,
+            action: input.action,
+            positionalValues: input.positionalValues,
+            flagValues: input.flagValues,
+            globals: input.globals,
+            servers: input.servers,
+            authSchemes: input.authSchemes,
+            embeddedDefaults: input.embeddedDefaults,
+            bodyFlagDefs: input.bodyFlagDefs,
+        });
+        // Build PreparedRequest before fetch (since body gets consumed)
+        const headers = {};
+        for (const [key, value] of request.headers.entries()) {
+            headers[key] = value;
         }
-        catch {
-            // keep as text
+        const preparedRequest = {
+            method: request.method,
+            url: request.url,
+            headers,
+            body,
+            curl,
+        };
+        // Handle --curl mode
+        if (input.globals.curl) {
+            const result = {
+                type: "curl",
+                curl,
+                request: preparedRequest,
+            };
+            return result;
         }
+        // Execute the request
+        const res = await fetch(request);
+        const durationMs = Date.now() - startTime;
+        const contentType = res.headers.get("content-type") ?? "";
+        const rawBody = await res.text();
+        let parsedBody = rawBody;
+        if (contentType.includes("json") && rawBody) {
+            try {
+                parsedBody = JSON.parse(rawBody);
+            }
+            catch {
+                // keep as text
+            }
+        }
+        // Build response headers
+        const responseHeaders = {};
+        for (const [key, value] of res.headers.entries()) {
+            responseHeaders[key] = value;
+        }
+        const result = {
+            type: "success",
+            request: preparedRequest,
+            response: {
+                status: res.status,
+                ok: res.ok,
+                headers: responseHeaders,
+                body: parsedBody,
+                rawBody,
+            },
+            timing: {
+                startedAt,
+                durationMs,
+            },
+        };
+        return result;
+    }
+    catch (err) {
+        const durationMs = Date.now() - startTime;
+        const result = {
+            type: "error",
+            message: err instanceof Error ? err.message : String(err),
+            timing: {
+                startedAt,
+                durationMs,
+            },
+        };
+        return result;
     }
-    return {
-        ok: res.ok,
-        status: res.status,
-        body,
-        curl,
-    };
 }
 /**
  * Execute an action and write output to stdout/stderr.
@@ -50,57 +136,24 @@ export async function execute(input) {
 export async function executeAction(input) {
     const actionName = input.action.action;
     const resourceName = input.resourceName;
-    try {
-        if (input.globals.curl) {
-            const { curl } = await buildRequest({
-                specId: input.specId,
-                action: input.action,
-                positionalValues: input.positionalValues,
-                flagValues: input.flagValues,
-                globals: input.globals,
-                servers: input.servers,
-                authSchemes: input.authSchemes,
-                embeddedDefaults: input.embeddedDefaults,
-                bodyFlagDefs: input.bodyFlagDefs,
-            });
-            process.stdout.write(`${curl}\n`);
-            return;
-        }
-        const result = await execute(input);
-        if (!result.ok) {
-            if (input.globals.json) {
-                process.stdout.write(`${JSON.stringify({ status: result.status, body: result.body })}\n`);
-            }
-            else {
-                process.stderr.write(`HTTP ${result.status}\n`);
-                process.stderr.write(`${typeof result.body === "string" ? result.body : JSON.stringify(result.body, null, 2)}\n`);
-            }
-            process.exitCode = 1;
-            return;
-        }
-        if (input.globals.json) {
-            process.stdout.write(`${JSON.stringify(result.body)}\n`);
-            return;
-        }
-        // default (human + agent readable)
-        if (typeof result.body === "string") {
-            process.stdout.write(result.body);
-            if (!result.body.endsWith("\n"))
-                process.stdout.write("\n");
-        }
-        else {
-            process.stdout.write(`${JSON.stringify(result.body, null, 2)}\n`);
-        }
+    // Execute and get the result
+    const result = await execute(input);
+    // Add context for error messages
+    if (result.type === "error" || result.type === "validation") {
+        result.resource = resourceName;
+        result.action = actionName;
     }
-    catch (err) {
-        const rawMessage = err instanceof Error ? err.message : String(err);
-        const message = formatError(rawMessage, resourceName, actionName);
-        if (input.globals.json) {
-            process.stdout.write(`${JSON.stringify({ error: rawMessage })}\n`);
-        }
-        else {
-            process.stderr.write(`error: ${message}\n`);
-        }
-        process.exitCode = 1;
+    // Render the result
+    const format = input.globals.json ? "json" : "text";
+    const output = renderToString(result, { format });
+    // Write to appropriate stream
+    const stream = getOutputStream(result);
+    if (stream === "stderr") {
+        process.stderr.write(output);
+    }
+    else {
+        process.stdout.write(output);
     }
+    // Set exit code
+    process.exitCode = getExitCode(result);
 }

package/dist/cli/runtime/render.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Render functions for CommandResult.
+ *
+ * These functions convert the IR to output formats suitable for
+ * CLI display or programmatic consumption.
+ */
+import type { CommandResult } from "./result.js";
+export type RenderOptions = {
+    /** Output format: "text" (human readable) or "json" (machine readable) */
+    format?: "text" | "json";
+    /** Include timing information in output */
+    showTiming?: boolean;
+    /** Pretty-print JSON output (default: true for text, false for json format) */
+    prettyPrint?: boolean;
+};
+/**
+ * Render a CommandResult to a string for CLI output.
+ *
+ * @param result - The command result to render
+ * @param options - Rendering options
+ * @returns A string ready to be output (includes trailing newline)
+ */
+export declare function renderToString(result: CommandResult, options?: RenderOptions): string;
+/**
+ * Render a CommandResult to JSON string.
+ */
+export declare function renderToJSON(result: CommandResult, options?: RenderOptions): string;
+/**
+ * Convert a CommandResult to a plain JSON-serializable object.
+ */
+export declare function toJSON(result: CommandResult): Record<string, unknown>;
+/**
+ * Render a CommandResult to human-readable text.
+ */
+export declare function renderToText(result: CommandResult, options?: RenderOptions): string;
+/**
+ * Determine the exit code for a CommandResult.
+ * Returns 0 for success, 1 for errors.
+ */
+export declare function getExitCode(result: CommandResult): number;
+/**
+ * Determine which output stream to use for a CommandResult.
+ * Returns "stdout" for success, "stderr" for errors.
+ */
+export declare function getOutputStream(result: CommandResult): "stdout" | "stderr";

package/dist/cli/runtime/render.js

@@ -0,0 +1,212 @@
+/**
+ * Render functions for CommandResult.
+ *
+ * These functions convert the IR to output formats suitable for
+ * CLI display or programmatic consumption.
+ */
+// ----------------------------------------------------------------------------
+// Main Render Function
+// ----------------------------------------------------------------------------
+/**
+ * Render a CommandResult to a string for CLI output.
+ *
+ * @param result - The command result to render
+ * @param options - Rendering options
+ * @returns A string ready to be output (includes trailing newline)
+ */
+export function renderToString(result, options = {}) {
+    const { format = "text" } = options;
+    if (format === "json") {
+        return renderToJSON(result, options);
+    }
+    return renderToText(result, options);
+}
+// ----------------------------------------------------------------------------
+// JSON Rendering
+// ----------------------------------------------------------------------------
+/**
+ * Render a CommandResult to JSON string.
+ */
+export function renderToJSON(result, options = {}) {
+    const { prettyPrint = false } = options;
+    const indent = prettyPrint ? 2 : undefined;
+    const json = toJSON(result);
+    return `${JSON.stringify(json, null, indent)}\n`;
+}
+/**
+ * Convert a CommandResult to a plain JSON-serializable object.
+ */
+export function toJSON(result) {
+    switch (result.type) {
+        case "success":
+            return {
+                ok: true,
+                status: result.response.status,
+                body: result.response.body,
+            };
+        case "error":
+            return {
+                ok: false,
+                error: result.message,
+                ...(result.response && {
+                    status: result.response.status,
+                    body: result.response.body,
+                }),
+            };
+        case "validation":
+            return {
+                ok: false,
+                error: "Validation failed",
+                errors: result.errors,
+            };
+        case "prepared":
+            return {
+                ok: true,
+                request: result.request,
+            };
+        case "curl":
+            return {
+                ok: true,
+                curl: result.curl,
+            };
+        case "data":
+            return {
+                ok: true,
+                data: result.data,
+            };
+    }
+}
+// ----------------------------------------------------------------------------
+// Text Rendering
+// ----------------------------------------------------------------------------
+/**
+ * Render a CommandResult to human-readable text.
+ */
+export function renderToText(result, options = {}) {
+    switch (result.type) {
+        case "success":
+            return renderSuccessText(result, options);
+        case "error":
+            return renderErrorText(result, options);
+        case "validation":
+            return renderValidationText(result, options);
+        case "prepared":
+            return renderPreparedText(result, options);
+        case "curl":
+            return renderCurlText(result, options);
+        case "data":
+            return renderDataText(result, options);
+    }
+}
+function renderSuccessText(result, _options) {
+    const body = result.response.body;
+    if (typeof body === "string") {
+        return body.endsWith("\n") ? body : `${body}\n`;
+    }
+    return `${JSON.stringify(body, null, 2)}\n`;
+}
+function renderErrorText(result, _options) {
+    const lines = [];
+    // If we have an HTTP response, show status first
+    if (result.response) {
+        lines.push(`HTTP ${result.response.status}`);
+        const body = result.response.body;
+        if (typeof body === "string") {
+            lines.push(body);
+        }
+        else if (body !== undefined && body !== null) {
+            lines.push(JSON.stringify(body, null, 2));
+        }
+    }
+    else {
+        // No HTTP response - just an error message
+        lines.push(`error: ${result.message}`);
+        // Add help hint if we have resource/action context
+        if (result.action) {
+            const helpCmd = result.resource
+                ? `${result.resource} ${result.action} --help`
+                : `${result.action} --help`;
+            lines.push("");
+            lines.push(`Run '${helpCmd}' to see available options.`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+function renderValidationText(result, _options) {
+    const lines = ["Validation errors:"];
+    for (const error of result.errors) {
+        lines.push(`  ${error.path}: ${error.message}`);
+    }
+    // Add help hint if we have resource/action context
+    if (result.action) {
+        const helpCmd = result.resource
+            ? `${result.resource} ${result.action} --help`
+            : `${result.action} --help`;
+        lines.push("");
+        lines.push(`Run '${helpCmd}' to see available options.`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+function renderPreparedText(result, _options) {
+    const { request } = result;
+    const lines = [`${request.method} ${request.url}`, "", "Headers:"];
+    for (const [key, value] of Object.entries(request.headers)) {
+        lines.push(`  ${key}: ${value}`);
+    }
+    if (request.body) {
+        lines.push("");
+        lines.push("Body:");
+        lines.push(request.body);
+    }
+    return `${lines.join("\n")}\n`;
+}
+function renderCurlText(result, _options) {
+    return `${result.curl}\n`;
+}
+function renderDataText(result, _options) {
+    const { data } = result;
+    if (typeof data === "string") {
+        return data.endsWith("\n") ? data : `${data}\n`;
+    }
+    return `${JSON.stringify(data, null, 2)}\n`;
+}
+// ----------------------------------------------------------------------------
+// Exit Code Helper
+// ----------------------------------------------------------------------------
+/**
+ * Determine the exit code for a CommandResult.
+ * Returns 0 for success, 1 for errors.
+ */
+export function getExitCode(result) {
+    switch (result.type) {
+        case "success":
+            return result.response.ok ? 0 : 1;
+        case "error":
+        case "validation":
+            return 1;
+        case "prepared":
+        case "curl":
+        case "data":
+            return 0;
+    }
+}
+// ----------------------------------------------------------------------------
+// Output Stream Helper
+// ----------------------------------------------------------------------------
+/**
+ * Determine which output stream to use for a CommandResult.
+ * Returns "stdout" for success, "stderr" for errors.
+ */
+export function getOutputStream(result) {
+    switch (result.type) {
+        case "success":
+            return result.response.ok ? "stdout" : "stderr";
+        case "error":
+        case "validation":
+            return "stderr";
+        case "prepared":
+        case "curl":
+        case "data":
+            return "stdout";
+    }
+}

package/dist/cli/runtime/request.d.ts

@@ -33,4 +33,5 @@ export type BuildRequestInput = {
 export declare function buildRequest(input: BuildRequestInput): Promise<{
     request: Request;
     curl: string;
+    body?: string;
 }>;

package/dist/cli/runtime/request.js

@@ -103,18 +103,14 @@ export async function buildRequest(input) {
         servers: input.servers,
         serverVars,
     });
-    // Path params: action.positionals order matches templated params order.
+    // Path params: positionals order matches templated params order.
+    // Use rawPathArgs (original template variable names) for URL substitution.
     const pathVars = {};
     for (let i = 0; i < input.action.positionals.length; i++) {
-        const pos = input.action.positionals[i];
-        const raw = input.action.pathArgs[i];
+        const rawName = input.action.rawPathArgs[i];
         const value = input.positionalValues[i];
-        if (typeof raw === "string" && typeof value === "string") {
-            pathVars[raw] = value;
-        }
-        // Use cli name too as fallback
-        if (pos?.name && typeof value === "string") {
-            pathVars[pos.name] = value;
+        if (typeof rawName === "string" && typeof value === "string") {
+            pathVars[rawName] = value;
         }
     }
     const path = applyTemplate(input.action.path, pathVars, { encode: true });
@@ -259,7 +255,7 @@ export async function buildRequest(input) {
         body,
     });
     const curl = buildCurl(req, body);
-    return { request: req, curl };
+    return { request: req, curl, body };
 }
 function buildCurl(req, body) {
     const parts = ["curl", "-sS", "-X", req.method];

package/dist/cli/runtime/result.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Intermediate Representation (IR) for command results.
+ *
+ * All specli operations return a CommandResult which can be:
+ * - Rendered to string for CLI output
+ * - Serialized to JSON for programmatic use
+ * - Inspected/modified before execution (PreparedRequest)
+ */
+/**
+ * A request that has been built but not yet executed.
+ * Can be inspected, modified, or converted to curl.
+ */
+export type PreparedRequest = {
+    /** HTTP method */
+    method: string;
+    /** Full URL including query params */
+    url: string;
+    /** Request headers */
+    headers: Record<string, string>;
+    /** Request body (if any) */
+    body?: string;
+    /** Curl command equivalent */
+    curl: string;
+};
+/**
+ * HTTP response data.
+ */
+export type ResponseData = {
+    /** HTTP status code */
+    status: number;
+    /** Whether status is 2xx */
+    ok: boolean;
+    /** Response headers */
+    headers: Record<string, string>;
+    /** Parsed response body */
+    body: unknown;
+    /** Raw response body as string */
+    rawBody: string;
+};
+/**
+ * A single validation error.
+ */
+export type ValidationError = {
+    /** Path to the invalid field (e.g., "body.name", "query.limit") */
+    path: string;
+    /** Error message */
+    message: string;
+    /** The invalid value (if available) */
+    value?: unknown;
+};
+/**
+ * Request timing information.
+ */
+export type Timing = {
+    /** When the request started (ISO string) */
+    startedAt: string;
+    /** Total duration in milliseconds */
+    durationMs: number;
+};
+/**
+ * Base fields shared by all result types.
+ */
+type ResultBase = {
+    /** Resource name (e.g., "users") */
+    resource?: string;
+    /** Action name (e.g., "list", "get") */
+    action?: string;
+};
+/**
+ * Successful execution result.
+ */
+export type SuccessResult = ResultBase & {
+    type: "success";
+    /** The prepared request that was sent */
+    request: PreparedRequest;
+    /** The response received */
+    response: ResponseData;
+    /** Request timing */
+    timing: Timing;
+};
+/**
+ * Error result (HTTP error or execution error).
+ */
+export type ErrorResult = ResultBase & {
+    type: "error";
+    /** Error message */
+    message: string;
+    /** The prepared request (if available) */
+    request?: PreparedRequest;
+    /** The response (if HTTP error) */
+    response?: ResponseData;
+    /** Request timing (if request was made) */
+    timing?: Timing;
+};
+/**
+ * Validation failure result.
+ */
+export type ValidationResult = ResultBase & {
+    type: "validation";
+    /** Validation errors */
+    errors: ValidationError[];
+    /** The request that failed validation (partial) */
+    request?: Partial<PreparedRequest>;
+};
+/**
+ * Prepared request result (dry-run mode).
+ */
+export type PreparedResult = ResultBase & {
+    type: "prepared";
+    /** The prepared request ready to execute */
+    request: PreparedRequest;
+};
+/**
+ * Curl output result (--curl mode).
+ */
+export type CurlResult = ResultBase & {
+    type: "curl";
+    /** The curl command */
+    curl: string;
+    /** The full prepared request */
+    request: PreparedRequest;
+};
+/**
+ * Data result (for list, help, schema commands).
+ */
+export type DataResult = ResultBase & {
+    type: "data";
+    /** The data payload */
+    data: unknown;
+};
+/**
+ * All possible command result types.
+ */
+export type CommandResult = SuccessResult | ErrorResult | ValidationResult | PreparedResult | CurlResult | DataResult;
+export declare function isSuccess(result: CommandResult): result is SuccessResult;
+export declare function isError(result: CommandResult): result is ErrorResult;
+export declare function isValidation(result: CommandResult): result is ValidationResult;
+export declare function isPrepared(result: CommandResult): result is PreparedResult;
+export declare function isCurl(result: CommandResult): result is CurlResult;
+export declare function isData(result: CommandResult): result is DataResult;
+/**
+ * Returns true if the result represents a successful operation.
+ * For HTTP requests, this means a 2xx status code.
+ */
+export declare function isOk(result: CommandResult): boolean;
+/**
+ * Extract the response body from a result (if available).
+ */
+export declare function getBody(result: CommandResult): unknown;
+/**
+ * Extract the HTTP status code from a result (if available).
+ */
+export declare function getStatus(result: CommandResult): number | undefined;
+export {};

package/dist/cli/runtime/result.js

@@ -0,0 +1,83 @@
+/**
+ * Intermediate Representation (IR) for command results.
+ *
+ * All specli operations return a CommandResult which can be:
+ * - Rendered to string for CLI output
+ * - Serialized to JSON for programmatic use
+ * - Inspected/modified before execution (PreparedRequest)
+ */
+// ----------------------------------------------------------------------------
+// Type guards
+// ----------------------------------------------------------------------------
+export function isSuccess(result) {
+    return result.type === "success";
+}
+export function isError(result) {
+    return result.type === "error";
+}
+export function isValidation(result) {
+    return result.type === "validation";
+}
+export function isPrepared(result) {
+    return result.type === "prepared";
+}
+export function isCurl(result) {
+    return result.type === "curl";
+}
+export function isData(result) {
+    return result.type === "data";
+}
+// ----------------------------------------------------------------------------
+// Helper to check if result represents a successful operation
+// ----------------------------------------------------------------------------
+/**
+ * Returns true if the result represents a successful operation.
+ * For HTTP requests, this means a 2xx status code.
+ */
+export function isOk(result) {
+    switch (result.type) {
+        case "success":
+            return result.response.ok;
+        case "error":
+        case "validation":
+            return false;
+        case "prepared":
+        case "curl":
+        case "data":
+            return true;
+    }
+}
+// ----------------------------------------------------------------------------
+// Helper to extract body from result
+// ----------------------------------------------------------------------------
+/**
+ * Extract the response body from a result (if available).
+ */
+export function getBody(result) {
+    switch (result.type) {
+        case "success":
+            return result.response.body;
+        case "error":
+            return result.response?.body;
+        case "data":
+            return result.data;
+        default:
+            return undefined;
+    }
+}
+// ----------------------------------------------------------------------------
+// Helper to extract status from result
+// ----------------------------------------------------------------------------
+/**
+ * Extract the HTTP status code from a result (if available).
+ */
+export function getStatus(result) {
+    switch (result.type) {
+        case "success":
+            return result.response.status;
+        case "error":
+            return result.response?.status;
+        default:
+            return undefined;
+    }
+}

package/dist/client/index.d.ts

@@ -3,7 +3,7 @@
  */
 import type { AuthScheme } from "../cli/parse/auth-schemes.js";
 import type { ServerInfo } from "../cli/parse/servers.js";
-import { type ExecuteResult } from "../cli/runtime/execute.js";
+import type { CommandResult } from "../cli/runtime/result.js";
 export type SpecliOptions = {
     /** The OpenAPI spec URL or file path */
     spec: string;
@@ -57,8 +57,15 @@ export type SpecliClient = {
     list(): ResourceInfo[];
     /** Get detailed help for a specific action */
     help(resource: string, action: string): ActionDetail | undefined;
-    /** Execute an API action */
-    exec(resource: string, action: string, args?: string[], flags?: Record<string, unknown>): Promise<ExecuteResult>;
+    /**
+     * Execute an API action and return the full CommandResult.
+     */
+    exec(resource: string, action: string, args?: string[], flags?: Record<string, unknown>): Promise<CommandResult>;
+    /**
+     * Prepare a request without executing it.
+     * Returns a PreparedResult or ErrorResult.
+     */
+    prepare(resource: string, action: string, args?: string[], flags?: Record<string, unknown>): Promise<CommandResult>;
     /** Get server information */
     servers: ServerInfo[];
     /** Get authentication schemes */
@@ -70,4 +77,4 @@ export type SpecliClient = {
 export declare function createClient(options: SpecliOptions): Promise<SpecliClient>;
 export type { AuthScheme } from "../cli/parse/auth-schemes.js";
 export type { ServerInfo } from "../cli/parse/servers.js";
-export type { ExecuteResult } from "../cli/runtime/execute.js";
+export type { CommandResult, CurlResult, DataResult, ErrorResult, PreparedRequest, PreparedResult, ResponseData, SuccessResult, Timing, ValidationError, ValidationResult, } from "../cli/runtime/result.js";

package/dist/client/index.js

@@ -2,7 +2,7 @@
  * Specli Client - Core programmatic API for OpenAPI specs
  */
 import { buildRuntimeContext } from "../cli/runtime/context.js";
-import { execute } from "../cli/runtime/execute.js";
+import { execute, prepare } from "../cli/runtime/execute.js";
 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());
@@ -63,9 +63,14 @@ export async function createClient(options) {
         async exec(resource, action, args = [], flags = {}) {
             const actionDef = findAction(ctx, resource, action);
             if (!actionDef) {
-                throw new Error(`Unknown action: ${resource} ${action}`);
+                return {
+                    type: "error",
+                    message: `Unknown action: ${resource} ${action}`,
+                    resource,
+                    action,
+                };
             }
-            return execute({
+            const result = await execute({
                 specId: ctx.loaded.id,
                 action: actionDef,
                 positionalValues: args,
@@ -74,6 +79,34 @@ export async function createClient(options) {
                 servers: ctx.servers,
                 authSchemes: ctx.authSchemes,
             });
+            // Add context to the result
+            result.resource = resource;
+            result.action = action;
+            return result;
+        },
+        async prepare(resource, action, args = [], flags = {}) {
+            const actionDef = findAction(ctx, resource, action);
+            if (!actionDef) {
+                return {
+                    type: "error",
+                    message: `Unknown action: ${resource} ${action}`,
+                    resource,
+                    action,
+                };
+            }
+            const result = await prepare({
+                specId: ctx.loaded.id,
+                action: actionDef,
+                positionalValues: args,
+                flagValues: flags,
+                globals,
+                servers: ctx.servers,
+                authSchemes: ctx.authSchemes,
+            });
+            // Add context to the result
+            result.resource = resource;
+            result.action = action;
+            return result;
         },
         servers: ctx.servers,
         authSchemes: ctx.authSchemes,

package/dist/index.d.ts

@@ -10,9 +10,11 @@
  * // List available resources and actions
  * const resources = api.list();
  *
- * // Execute an API call
+ * // Execute an API call and get the full result
  * const result = await api.exec("users", "get", ["123"]);
- * console.log(result.body);
+ * if (result.type === "success") {
+ *   console.log(result.response.body);
+ * }
  * ```
  */
 import { type SpecliClient, type SpecliOptions } from "./client/index.js";
@@ -33,10 +35,12 @@ import { type SpecliClient, type SpecliOptions } from "./client/index.js";
  *
  * // Execute a call
  * const result = await api.exec("users", "list");
- * if (result.ok) {
- *   console.log(result.body);
+ * if (result.type === "success" && result.response.ok) {
+ *   console.log(result.response.body);
  * }
  * ```
  */
 export declare function specli(options: SpecliOptions): Promise<SpecliClient>;
-export type { ActionDetail, ActionInfo, AuthScheme, ExecuteResult, ResourceInfo, ServerInfo, SpecliClient, SpecliOptions, } from "./client/index.js";
+export { getExitCode, getOutputStream, type RenderOptions, renderToJSON, renderToString, toJSON, } from "./cli/runtime/render.js";
+export { getBody, getStatus, isCurl, isData, isError, isOk, isPrepared, isSuccess, isValidation, } from "./cli/runtime/result.js";
+export type { ActionDetail, ActionInfo, AuthScheme, CommandResult, CurlResult, DataResult, ErrorResult, PreparedRequest, PreparedResult, ResourceInfo, ResponseData, ServerInfo, SpecliClient, SpecliOptions, SuccessResult, Timing, ValidationError, ValidationResult, } from "./client/index.js";

package/dist/index.js

@@ -10,9 +10,11 @@
  * // List available resources and actions
  * const resources = api.list();
  *
- * // Execute an API call
+ * // Execute an API call and get the full result
  * const result = await api.exec("users", "get", ["123"]);
- * console.log(result.body);
+ * if (result.type === "success") {
+ *   console.log(result.response.body);
+ * }
  * ```
  */
 import { createClient, } from "./client/index.js";
@@ -33,11 +35,15 @@ import { createClient, } from "./client/index.js";
  *
  * // Execute a call
  * const result = await api.exec("users", "list");
- * if (result.ok) {
- *   console.log(result.body);
+ * if (result.type === "success" && result.response.ok) {
+ *   console.log(result.response.body);
  * }
  * ```
  */
 export async function specli(options) {
     return createClient(options);
 }
+// Re-export render utilities for advanced usage
+export { getExitCode, getOutputStream, renderToJSON, renderToString, toJSON, } from "./cli/runtime/render.js";
+// Re-export type guards for convenience
+export { getBody, getStatus, isCurl, isData, isError, isOk, isPrepared, isSuccess, isValidation, } from "./cli/runtime/result.js";

package/package.json

@@ -1,10 +1,10 @@
 {
 	"name": "specli",
-	"version": "0.0.35",
-	"description": "Run any OpenAPI spec as a CLI. Built for Agents.",
+	"version": "0.0.36",
+	"description": "Run any OpenAPI spec as an Agent optimized executable",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/AndrewBarba/specli.git"
+		"url": "https://github.com/vercel-labs/specli.git"
 	},
 	"type": "module",
 	"module": "./dist/index.js",