specli 0.0.5 → 0.0.8

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

@@ -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

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> {