specli 0.0.4 → 0.0.7

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`);
 		}

package/src/cli/runtime/generated.ts

@@ -1,7 +1,7 @@
 import { Command } from "commander";
 
 import type { AuthScheme } from "../auth-schemes.ts";
-import type { CommandModel } from "../command-model.ts";
+import type { CommandAction, CommandModel } from "../command-model.ts";
 import type { ServerInfo } from "../server.ts";
 
 import { type BodyFlagDef, generateBodyFlags } from "./body-flags.ts";
@@ -9,6 +9,106 @@ import { executeAction } from "./execute.ts";
 import type { EmbeddedDefaults } from "./request.ts";
 import { coerceArrayInput, coerceValue } from "./validate/index.ts";
 
+// Flag type from CommandAction
+type CommandFlag = CommandAction["flags"][number];
+
+/**
+ * Format help output that is clear for both humans and AI agents.
+ * Groups options into Required, Optional, and Global sections.
+ */
+function formatCustomHelp(
+	cmd: Command,
+	action: CommandAction,
+	operationFlags: CommandFlag[],
+	bodyFlagDefs: BodyFlagDef[],
+): string {
+	const lines: string[] = [];
+	const cmdName = cmd.name();
+	const parentName = cmd.parent?.name() ?? "";
+	const fullCmd = parentName ? `${parentName} ${cmdName}` : cmdName;
+
+	// Usage line
+	const positionals = action.positionals.map((p) => `<${p.name}>`).join(" ");
+	const usageSuffix = positionals ? ` ${positionals}` : "";
+	lines.push(`Usage: ${fullCmd}${usageSuffix} [options]`);
+	lines.push("");
+
+	// Description
+	const desc =
+		action.summary ?? action.description ?? `${action.method} ${action.path}`;
+	lines.push(desc);
+	lines.push("");
+
+	// Collect all options into categories
+	const requiredOpts: string[] = [];
+	const optionalOpts: string[] = [];
+
+	// Format a single option line
+	const formatOpt = (
+		flag: string,
+		type: string,
+		desc: string,
+		required: boolean,
+	): string => {
+		const typeStr = type === "boolean" ? "" : ` <${type}>`;
+		const reqMarker = required ? " (required)" : "";
+		return `  ${flag}${typeStr}${reqMarker}\n      ${desc}`;
+	};
+
+	// Operation flags (query/header/path params)
+	for (const f of operationFlags) {
+		const type = f.type === "array" ? `${f.itemType ?? "string"}[]` : f.type;
+		const line = formatOpt(
+			f.flag,
+			type,
+			f.description ?? `${f.in} parameter`,
+			f.required,
+		);
+		if (f.required) {
+			requiredOpts.push(line);
+		} else {
+			optionalOpts.push(line);
+		}
+	}
+
+	// Body flags
+	for (const def of bodyFlagDefs) {
+		const line = formatOpt(def.flag, def.type, def.description, def.required);
+		if (def.required) {
+			requiredOpts.push(line);
+		} else {
+			optionalOpts.push(line);
+		}
+	}
+
+	// Required options section
+	if (requiredOpts.length > 0) {
+		lines.push("Required:");
+		lines.push(...requiredOpts);
+		lines.push("");
+	}
+
+	// Optional options section
+	if (optionalOpts.length > 0) {
+		lines.push("Options:");
+		lines.push(...optionalOpts);
+		lines.push("");
+	}
+
+	// Global options (always available)
+	lines.push("Global:");
+	lines.push("  --curl\n      Print curl command instead of executing");
+	lines.push("  --json\n      Output response as JSON");
+	lines.push("  --server <url>\n      Override the API server URL");
+	lines.push(
+		"  --bearer-token <token>\n      Provide auth token (or use 'login' command)",
+	);
+	lines.push("  -h, --help\n      Show this help message");
+	lines.push("");
+
+	return lines.join("\n");
+}
+
 export type GeneratedCliContext = {
 	servers: ServerInfo[];
 	authSchemes: AuthScheme[];
@@ -78,11 +178,11 @@ export function addGeneratedCommands(
 			}
 
 			// Collect reserved flags: operation params + --curl
-			const operationFlags = new Set(action.flags.map((f) => f.flag));
-			const reservedFlags = new Set([...operationFlags, "--curl"]);
+			const operationFlagSet = new Set(action.flags.map((f) => f.flag));
+			const reservedFlags = new Set([...operationFlagSet, "--curl"]);
 
 			// Only --curl is a built-in flag (for debugging)
-			if (!operationFlags.has("--curl")) {
+			if (!operationFlagSet.has("--curl")) {
 				cmd.option("--curl", "Print curl command without sending");
 			}
 
@@ -106,6 +206,12 @@ export function addGeneratedCommands(
 				}
 			}
 
+			// Custom help output for better agent/human readability
+			cmd.configureHelp({
+				formatHelp: () =>
+					formatCustomHelp(cmd, action, action.flags, bodyFlagDefs),
+			});
+
 			// Commander passes positional args and then the Command instance as last arg.
 			cmd.action(async (...args) => {
 				const command = args[args.length - 1];
@@ -128,6 +234,7 @@ export function addGeneratedCommands(
 					specId: context.specId,
 					embeddedDefaults: context.embeddedDefaults,
 					bodyFlagDefs,
+					resourceName: resource.resource,
 				});
 			});
 		}

package/src/cli/runtime/profile/secrets.ts

@@ -1,4 +1,6 @@
-import { secrets } from "bun";
+import { isBun } from "../compat.ts";
+
+const bunLiteral = "bun" as const;
 
 export type SecretKey = {
 	service: string;
@@ -16,27 +18,66 @@ export function tokenSecretKey(specId: string, profile: string): SecretKey {
 	};
 }
 
+/**
+ * Store a token securely.
+ * In Bun: uses the native secrets store (system keychain)
+ * In Node.js: secrets are not supported, warns user
+ */
 export async function setToken(
 	specId: string,
 	profile: string,
 	token: string,
 ): Promise<void> {
+	if (!isBun) {
+		console.warn(
+			"Warning: Secure token storage requires Bun. Token will not be persisted.",
+		);
+		console.warn(
+			"Use --bearer-token <token> flag instead when running with Node.js.",
+		);
+		return;
+	}
+
+	const { secrets } = await import(bunLiteral);
 	const key = tokenSecretKey(specId, profile);
 	await secrets.set({ service: key.service, name: key.name, value: token });
 }
 
+/**
+ * Retrieve a stored token.
+ * In Bun: retrieves from the native secrets store
+ * In Node.js: returns null (secrets not supported)
+ */
 export async function getToken(
 	specId: string,
 	profile: string,
 ): Promise<string | null> {
+	if (!isBun) {
+		return null;
+	}
+
+	const { secrets } = await import(bunLiteral);
 	const key = tokenSecretKey(specId, profile);
 	return await secrets.get({ service: key.service, name: key.name });
 }
 
+/**
+ * Delete a stored token.
+ * In Bun: removes from the native secrets store
+ * In Node.js: returns false (secrets not supported)
+ */
 export async function deleteToken(
 	specId: string,
 	profile: string,
 ): Promise<boolean> {
+	if (!isBun) {
+		console.warn(
+			"Warning: Secure token storage requires Bun. No token to delete.",
+		);
+		return false;
+	}
+
+	const { secrets } = await import(bunLiteral);
 	const key = tokenSecretKey(specId, profile);
 	return await secrets.delete({ service: key.service, name: key.name });
 }

package/src/cli/runtime/profile/store.ts

@@ -1,4 +1,10 @@
-import { YAML } from "bun";
+import {
+	fileExists,
+	mkdirp,
+	parseYamlContent,
+	readFileText,
+	writeFileText,
+} from "../compat.ts";
 
 export type Profile = {
 	name: string;
@@ -32,21 +38,17 @@ export async function readProfiles(): Promise<ProfilesFile> {
 	const jsonPath = configPathJson();
 	const yamlPath = configPathYaml();
 
-	const jsonFile = Bun.file(jsonPath);
-	const yamlFile = Bun.file(yamlPath);
+	const jsonExists = await fileExists(jsonPath);
+	const yamlExists = await fileExists(yamlPath);
 
-	const file = (await jsonFile.exists())
-		? jsonFile
-		: (await yamlFile.exists())
-			? yamlFile
-			: null;
+	const filePath = jsonExists ? jsonPath : yamlExists ? yamlPath : null;
 
-	if (!file) return { profiles: [] };
+	if (!filePath) return { profiles: [] };
 
-	const text = await file.text();
+	const text = await readFileText(filePath);
 	let parsed: unknown;
 	try {
-		parsed = YAML.parse(text) as unknown;
+		parsed = parseYamlContent(text) as unknown;
 	} catch {
 		parsed = JSON.parse(text) as unknown;
 	}
@@ -70,8 +72,8 @@ export async function readProfiles(): Promise<ProfilesFile> {
 
 export async function writeProfiles(data: ProfilesFile): Promise<void> {
 	const dir = configDir();
-	await Bun.$`mkdir -p ${dir}`;
-	await Bun.write(configPathJson(), JSON.stringify(data, null, 2));
+	await mkdirp(dir);
+	await writeFileText(configPathJson(), JSON.stringify(data, null, 2));
 }
 
 export function getProfile(

package/src/cli/runtime/request.ts

@@ -26,8 +26,6 @@ export type RuntimeGlobals = {
 	username?: string;
 	password?: string;
 	apiKey?: string;
-
-	profile?: string;
 };
 
 function parseKeyValuePairs(
@@ -155,8 +153,10 @@ export type BuildRequestInput = {
 export async function buildRequest(
 	input: BuildRequestInput,
 ): Promise<{ request: Request; curl: string }> {
+	// Always use the "default" profile for simplicity
+	const defaultProfileName = "default";
 	const profilesFile = await readProfiles();
-	const profile = getProfile(profilesFile, input.globals.profile);
+	const profile = getProfile(profilesFile, defaultProfileName);
 	const embedded = input.embeddedDefaults;
 
 	// Merge server vars: CLI flags override embedded defaults
@@ -275,9 +275,18 @@ export async function buildRequest(
 
 		const schema = input.action.requestBodySchema;
 
+		// Check if there are any required fields in the body
+		const requiredFields = bodyFlagDefs.filter((d) => d.required);
+
 		if (!hasBodyFlags) {
+			if (requiredFields.length > 0) {
+				// Error: user must provide required fields
+				const flagList = requiredFields.map((d) => `--${d.path.join(".")}`);
+				throw new Error(`Required: ${flagList.join(", ")}`);
+			}
+			// No required fields - send empty body if body is required, otherwise skip
 			if (input.action.requestBody.required) {
-				throw new Error("Missing required request body fields.");
+				body = "{}";
 			}
 		} else {
 			if (!contentType?.includes("json")) {
@@ -292,9 +301,8 @@ export async function buildRequest(
 			);
 			const missing = findMissingRequired(input.flagValues, bodyFlagDefs);
 			if (missing.length > 0) {
-				throw new Error(
-					`Missing required body field '${missing[0]}'. Provide --${missing[0]}.`,
-				);
+				const missingFlags = missing.map((m) => `--${m}`).join(", ");
+				throw new Error(`Missing required fields: ${missingFlags}`);
 			}
 
 			// Build nested object from dot-notation flags
@@ -311,6 +319,11 @@ export async function buildRequest(
 		}
 	}
 
+	// Check if user has a stored token (needed for auth scheme auto-selection)
+	const storedToken = profile?.name
+		? await getToken(input.specId, profile.name)
+		: null;
+
 	// Auth resolution priority: CLI flag > profile > embedded default
 	const resolvedAuthScheme = resolveAuthScheme(
 		input.authSchemes,
@@ -319,13 +332,11 @@ export async function buildRequest(
 			flagAuthScheme: input.globals.auth,
 			profileAuthScheme: profile?.authScheme,
 			embeddedAuthScheme: embedded?.auth,
+			hasStoredToken: Boolean(storedToken),
 		},
 	);
 
-	const tokenFromProfile =
-		profile?.name && resolvedAuthScheme
-			? await getToken(input.specId, profile.name)
-			: null;
+	const tokenFromProfile = resolvedAuthScheme ? storedToken : null;
 
 	const globalsWithProfileAuth: RuntimeGlobals = {
 		...input.globals,

package/src/cli/spec-loader.ts

@@ -1,7 +1,7 @@
 import SwaggerParser from "@apidevtools/swagger-parser";
-import { YAML } from "bun";
 
 import { sha256Hex } from "./crypto.ts";
+import { parseYamlContent } from "./runtime/compat.ts";
 import { getSpecId } from "./spec-id.ts";
 import { stableStringify } from "./stable-json.ts";
 import type { LoadedSpec, OpenApiDoc, SpecSource } from "./types.ts";
@@ -21,7 +21,7 @@ function parseSpecText(text: string): unknown {
 		return JSON.parse(text);
 	}
 
-	return YAML.parse(text);
+	return parseYamlContent(text);
 }
 
 export async function loadSpec(options: LoadSpecOptions): Promise<LoadedSpec> {