specli 0.0.5 → 0.0.8

package/dist/src/cli/types.d.ts

@@ -0,0 +1,53 @@
+export type SpecSource = "embedded" | "file" | "url";
+export type SecurityRequirement = Record<string, string[]>;
+export type OpenApiDoc = {
+    openapi: string;
+    info?: {
+        title?: string;
+        version?: string;
+    };
+    servers?: Array<{
+        url: string;
+        description?: string;
+        variables?: unknown;
+    }>;
+    security?: SecurityRequirement[];
+    components?: {
+        securitySchemes?: Record<string, unknown>;
+    };
+    paths?: Record<string, unknown>;
+};
+export type NormalizedParameter = {
+    in: "path" | "query" | "header" | "cookie";
+    name: string;
+    required: boolean;
+    description?: string;
+    schema?: unknown;
+};
+export type JsonSchema = Record<string, unknown>;
+export declare function isJsonSchema(value: unknown): value is JsonSchema;
+export type NormalizedRequestBody = {
+    required: boolean;
+    contentTypes: string[];
+    schemasByContentType: Record<string, unknown | undefined>;
+};
+export type NormalizedOperation = {
+    key: string;
+    method: string;
+    path: string;
+    operationId?: string;
+    tags: string[];
+    summary?: string;
+    description?: string;
+    deprecated?: boolean;
+    security?: SecurityRequirement[];
+    parameters: NormalizedParameter[];
+    requestBody?: NormalizedRequestBody;
+};
+export type LoadedSpec = {
+    source: SpecSource;
+    id: string;
+    fingerprint: string;
+    doc: OpenApiDoc;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/src/cli/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/cli/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,MAAM,GAAG,KAAK,CAAC;AAErD,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;AAE3D,MAAM,MAAM,UAAU,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE;QACN,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC5E,QAAQ,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACjC,UAAU,CAAC,EAAE;QACZ,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC1C,CAAC;IACF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IACjC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAGF,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE;AAED,MAAM,MAAM,qBAAqB,GAAG;IACnC,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC,CAAC;CAC1D,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACjC,UAAU,EAAE,mBAAmB,EAAE,CAAC;IAClC,WAAW,CAAC,EAAE,qBAAqB,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACxB,MAAM,EAAE,UAAU,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,UAAU,CAAC;CAChB,CAAC"}

package/dist/src/cli/types.js

@@ -0,0 +1,9 @@
+// src/cli/types.ts
+function isJsonSchema(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+export {
+  isJsonSchema
+};
+
+//# debugId=D591F75F6084972664756E2164756E21

package/dist/src/cli/types.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../../../src/cli/types.ts"],
+  "sourcesContent": [
+    "export type SpecSource = \"embedded\" | \"file\" | \"url\";\n\nexport type SecurityRequirement = Record<string, string[]>;\n\nexport type OpenApiDoc = {\n\topenapi: string;\n\tinfo?: {\n\t\ttitle?: string;\n\t\tversion?: string;\n\t};\n\tservers?: Array<{ url: string; description?: string; variables?: unknown }>;\n\tsecurity?: SecurityRequirement[];\n\tcomponents?: {\n\t\tsecuritySchemes?: Record<string, unknown>;\n\t};\n\tpaths?: Record<string, unknown>;\n};\n\nexport type NormalizedParameter = {\n\tin: \"path\" | \"query\" | \"header\" | \"cookie\";\n\tname: string;\n\trequired: boolean;\n\tdescription?: string;\n\tschema?: unknown;\n};\n\n// Minimal JSON Schema-like shape for validation and flag expansion.\nexport type JsonSchema = Record<string, unknown>;\n\nexport function isJsonSchema(value: unknown): value is JsonSchema {\n\treturn Boolean(value) && typeof value === \"object\" && !Array.isArray(value);\n}\n\nexport type NormalizedRequestBody = {\n\trequired: boolean;\n\tcontentTypes: string[];\n\tschemasByContentType: Record<string, unknown | undefined>;\n};\n\nexport type NormalizedOperation = {\n\tkey: string;\n\tmethod: string;\n\tpath: string;\n\toperationId?: string;\n\ttags: string[];\n\tsummary?: string;\n\tdescription?: string;\n\tdeprecated?: boolean;\n\tsecurity?: SecurityRequirement[];\n\tparameters: NormalizedParameter[];\n\trequestBody?: NormalizedRequestBody;\n};\n\nexport type LoadedSpec = {\n\tsource: SpecSource;\n\tid: string;\n\tfingerprint: string;\n\tdoc: OpenApiDoc;\n};\n"
+  ],
+  "mappings": ";AA6BO,SAAS,YAAY,CAAC,OAAqC;AAAA,EACjE,OAAO,QAAQ,KAAK,KAAK,OAAO,UAAU,YAAY,CAAC,MAAM,QAAQ,KAAK;AAAA;",
+  "debugId": "D591F75F6084972664756E2164756E21",
+  "names": []
+}

package/package.json

@@ -1,18 +1,40 @@
 {
 	"name": "specli",
-	"module": "index.ts",
+	"version": "0.0.8",
 	"type": "module",
-	"version": "0.0.5",
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
 	"bin": {
-		"specli": "./cli.ts"
+		"specli": "./bin/specli.js"
+	},
+	"exports": {
+		".": {
+			"bun": "./index.ts",
+			"import": {
+				"types": "./dist/index.d.ts",
+				"default": "./dist/index.js"
+			}
+		},
+		"./ai/tools": {
+			"bun": "./src/ai/tools.ts",
+			"import": {
+				"types": "./dist/src/ai/tools.d.ts",
+				"default": "./dist/src/ai/tools.js"
+			}
+		}
 	},
 	"files": [
+		"dist",
+		"bin",
 		"cli.ts",
 		"index.ts",
 		"src",
 		"!**/*.test.ts"
 	],
 	"scripts": {
+		"build": "bun run scripts/build.ts",
+		"prepublishOnly": "bun run build",
 		"lint": "biome ci",
 		"lint:check": "biome check --write --unsafe",
 		"lint:format": "biome format --write",
@@ -21,6 +43,7 @@
 	"devDependencies": {
 		"@biomejs/biome": "^2.3.11",
 		"@types/bun": "^1.3.6",
+		"@types/node": "^22.19.7",
 		"@typescript/native-preview": "^7.0.0-dev.20260120.1"
 	},
 	"dependencies": {
@@ -28,6 +51,11 @@
 		"ajv": "^8.17.1",
 		"ajv-formats": "^3.0.1",
 		"commander": "^14.0.2",
-		"openapi-types": "^12.1.3"
+		"openapi-types": "^12.1.3",
+		"yaml": "^2.8.2"
+	},
+	"peerDependencies": {
+		"ai": "^6.0.42",
+		"zod": "^4.3.5"
 	}
 }

package/src/ai/tools.ts

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

@@ -2,6 +2,7 @@ import { Command } from "commander";
 
 import { getArgValue, hasAnyArg } from "./runtime/argv.ts";
 import { collectRepeatable } from "./runtime/collect.ts";
+import { readStdinText } from "./runtime/compat.ts";
 import { buildRuntimeContext } from "./runtime/context.ts";
 import { addGeneratedCommands } from "./runtime/generated.ts";
 import { deleteToken, getToken, setToken } from "./runtime/profile/secrets.ts";
@@ -86,8 +87,8 @@ export async function main(argv: string[], options: MainOptions = {}) {
 					}
 					token = Buffer.concat(chunks).toString().trim();
 				} else {
-					// Piped input - use Bun's stdin stream
-					const text = await Bun.stdin.text();
+					// Piped input - use cross-runtime stdin reading
+					const text = await readStdinText();
 					token = text.trim();
 				}
 			}

package/src/cli/runtime/body.ts

@@ -1,4 +1,4 @@
-import { YAML } from "bun";
+import { parseYamlContent, readFileText } from "./compat.ts";
 
 export type BodyInput =
 	| { kind: "none" }
@@ -11,7 +11,7 @@ export async function loadBody(
 	if (input.kind === "none") return undefined;
 	if (input.kind === "data") return { raw: input.data };
 
-	const text = await Bun.file(input.path).text();
+	const text = await readFileText(input.path);
 	return { raw: text };
 }
 
@@ -20,5 +20,5 @@ export function parseBodyAsJsonOrYaml(text: string): unknown {
 	if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
 		return JSON.parse(text);
 	}
-	return YAML.parse(text);
+	return parseYamlContent(text);
 }

package/src/cli/runtime/compat.ts

@@ -0,0 +1,89 @@
+/**
+ * Cross-runtime compatibility utilities for Bun and Node.js
+ *
+ * This module provides abstractions over Bun-specific APIs to allow
+ * the exec command to run in Node.js while compile remains Bun-only.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+
+/**
+ * Detect if we're running in Bun
+ */
+export const isBun = typeof globalThis.Bun !== "undefined";
+
+/**
+ * Read a file's text content - works in both Bun and Node.js
+ */
+export async function readFileText(path: string): Promise<string> {
+	if (isBun) {
+		return Bun.file(path).text();
+	}
+	return readFileSync(path, "utf-8");
+}
+
+/**
+ * Check if a file exists - works in both Bun and Node.js
+ */
+export async function fileExists(path: string): Promise<boolean> {
+	if (isBun) {
+		return Bun.file(path).exists();
+	}
+	return existsSync(path);
+}
+
+/**
+ * Write text to a file - works in both Bun and Node.js
+ */
+export async function writeFileText(
+	path: string,
+	content: string,
+): Promise<void> {
+	if (isBun) {
+		await Bun.write(path, content);
+		return;
+	}
+	writeFileSync(path, content, "utf-8");
+}
+
+/**
+ * Create directory recursively - works in both Bun and Node.js
+ */
+export async function mkdirp(path: string): Promise<void> {
+	if (isBun) {
+		await Bun.$`mkdir -p ${path}`;
+		return;
+	}
+	mkdirSync(path, { recursive: true });
+}
+
+/**
+ * Parse YAML content - works in both Bun and Node.js
+ */
+export function parseYamlContent(text: string): unknown {
+	if (isBun) {
+		const { YAML } = globalThis.Bun;
+		return YAML.parse(text);
+	}
+	return parseYaml(text);
+}
+
+/**
+ * Read from stdin - works in both Bun and Node.js
+ */
+export async function readStdinText(): Promise<string> {
+	if (isBun) {
+		return Bun.stdin.text();
+	}
+	// Node.js stdin reading
+	return new Promise((resolve, reject) => {
+		let data = "";
+		process.stdin.setEncoding("utf8");
+		process.stdin.on("data", (chunk) => {
+			data += chunk;
+		});
+		process.stdin.on("end", () => resolve(data));
+		process.stdin.on("error", reject);
+	});
+}

package/src/cli/runtime/execute.ts

@@ -13,51 +13,108 @@ export type ExecuteInput = {
 	specId: string;
 	embeddedDefaults?: EmbeddedDefaults;
 	bodyFlagDefs?: BodyFlagDef[];
+	/** Resource name for error messages (e.g. "plans") */
+	resourceName?: string;
 };
 
+export type ExecuteResult = {
+	ok: boolean;
+	status: number;
+	body: unknown;
+	curl: string;
+};
+
+/**
+ * Format an error message with a help hint.
+ */
+function formatError(
+	message: string,
+	resourceName: string | undefined,
+	actionName: string,
+): string {
+	const helpCmd = resourceName
+		? `${resourceName} ${actionName} --help`
+		: `${actionName} --help`;
+	return `${message}\n\nRun '${helpCmd}' to see available options.`;
+}
+
+/**
+ * Execute an action and return the result as data.
+ * This is the core execution function used by both CLI and programmatic API.
+ */
+export async function execute(
+	input: Omit<ExecuteInput, "resourceName">,
+): Promise<ExecuteResult> {
+	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: unknown = text;
+
+	if (contentType.includes("json") && text) {
+		try {
+			body = JSON.parse(text);
+		} catch {
+			// keep as text
+		}
+	}
+
+	return {
+		ok: res.ok,
+		status: res.status,
+		body,
+		curl,
+	};
+}
+
+/**
+ * Execute an action and write output to stdout/stderr.
+ * This is the CLI-facing wrapper around execute().
+ */
 export async function executeAction(input: ExecuteInput): Promise<void> {
-	try {
-		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 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 res = await fetch(request);
-		const contentType = res.headers.get("content-type") ?? "";
-		const status = res.status;
-
-		const text = await res.text();
-		let body: unknown = text;
-		let parsedJson: unknown | undefined;
+		const result = await execute(input);
 
-		if (contentType.includes("json")) {
-			try {
-				parsedJson = text ? JSON.parse(text) : null;
-				body = parsedJson;
-			} catch {
-				// keep as text
-			}
-		}
-
-		if (!res.ok) {
+		if (!result.ok) {
 			if (input.globals.json) {
-				process.stdout.write(`${JSON.stringify({ status, body })}\n`);
+				process.stdout.write(
+					`${JSON.stringify({ status: result.status, body: result.body })}\n`,
+				);
 			} else {
-				process.stderr.write(`HTTP ${status}\n`);
+				process.stderr.write(`HTTP ${result.status}\n`);
 				process.stderr.write(
-					`${typeof body === "string" ? body : JSON.stringify(body, null, 2)}\n`,
+					`${typeof result.body === "string" ? result.body : JSON.stringify(result.body, null, 2)}\n`,
 				);
 			}
 			process.exitCode = 1;
@@ -65,21 +122,23 @@ export async function executeAction(input: ExecuteInput): Promise<void> {
 		}
 
 		if (input.globals.json) {
-			process.stdout.write(`${JSON.stringify(body)}\n`);
+			process.stdout.write(`${JSON.stringify(result.body)}\n`);
 			return;
 		}
 
 		// default (human + agent readable)
-		if (typeof parsedJson !== "undefined") {
-			process.stdout.write(`${JSON.stringify(parsedJson, null, 2)}\n`);
+		if (typeof result.body === "string") {
+			process.stdout.write(result.body);
+			if (!result.body.endsWith("\n")) process.stdout.write("\n");
 		} else {
-			process.stdout.write(text);
-			if (!text.endsWith("\n")) process.stdout.write("\n");
+			process.stdout.write(`${JSON.stringify(result.body, null, 2)}\n`);
 		}
 	} catch (err) {
-		const message = err instanceof Error ? err.message : String(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: message })}\n`);
+			process.stdout.write(`${JSON.stringify({ error: rawMessage })}\n`);
 		} else {
 			process.stderr.write(`error: ${message}\n`);
 		}