@zapier/zapier-sdk-cli 0.16.1 → 0.16.4

package/src/utils/cli-generator.ts

@@ -1,807 +0,0 @@
-import type { Command } from "commander";
-import { z } from "zod";
-import type { ZapierSdk } from "@zapier/zapier-sdk";
-import {
-  isPositional,
-  formatErrorMessage,
-  ZapierError,
-  type FunctionRegistryEntry,
-} from "@zapier/zapier-sdk";
-import { SchemaParameterResolver } from "./parameter-resolver";
-import { formatItemsFromSchema, formatJsonOutput } from "./schema-formatter";
-import chalk from "chalk";
-import inquirer from "inquirer";
-import { ZapierCliError, ZapierCliExitError } from "./errors";
-
-// ============================================================================
-// Types
-// ============================================================================
-
-interface CliCommandConfig {
-  description: string;
-  parameters: CliParameter[];
-  handler: (...args: unknown[]) => Promise<void>;
-}
-
-interface CliParameter {
-  name: string;
-  type: "string" | "number" | "boolean" | "array";
-  required: boolean;
-  description?: string;
-  default?: unknown;
-  choices?: string[];
-  hasResolver?: boolean;
-  isPositional?: boolean;
-}
-
-// ============================================================================
-// Schema Analysis
-// ============================================================================
-
-function analyzeZodSchema(
-  schema: z.ZodSchema,
-  functionInfo?: FunctionRegistryEntry,
-): CliParameter[] {
-  const parameters: CliParameter[] = [];
-
-  // Handle ZodEffects (schemas with .refine(), .transform(), etc.)
-  // In Zod, effects have type "effect" and inner schema is accessed via innerType
-  const schemaDef = (
-    schema as unknown as {
-      _zod?: { def?: { type?: string; innerType?: z.ZodSchema } };
-    }
-  )._zod?.def;
-  if (schemaDef?.type === "effect" && schemaDef.innerType) {
-    return analyzeZodSchema(schemaDef.innerType, functionInfo);
-  }
-
-  if (schema instanceof z.ZodObject) {
-    const shape = schema.shape;
-
-    for (const [key, fieldSchema] of Object.entries(shape)) {
-      const param = analyzeZodField(
-        key,
-        fieldSchema as z.ZodSchema,
-        functionInfo,
-      );
-      if (param) {
-        parameters.push(param);
-      }
-    }
-  }
-
-  return parameters;
-}
-
-function analyzeZodField(
-  name: string,
-  schema: z.ZodSchema,
-  functionInfo?: FunctionRegistryEntry,
-): CliParameter | null {
-  let baseSchema = schema;
-  let required = true;
-  let defaultValue: unknown = undefined;
-
-  // Unwrap optional, default, and nullable wrappers - keep unwrapping until we get to the base type
-  while (true) {
-    if (baseSchema instanceof z.ZodOptional) {
-      required = false;
-      baseSchema = baseSchema._zod.def.innerType as z.ZodSchema;
-    } else if (baseSchema instanceof z.ZodDefault) {
-      required = false;
-      defaultValue = (baseSchema._zod.def.defaultValue as () => unknown)();
-      baseSchema = baseSchema._zod.def.innerType as z.ZodSchema;
-    } else {
-      // Check for ZodNullable - nullable doesn't affect CLI required status, but we need to unwrap it to get the base type
-      const zodDef = (
-        baseSchema as unknown as {
-          _zod?: { def?: { typeName?: string; innerType?: z.ZodSchema } };
-        }
-      )._zod?.def;
-
-      if (zodDef?.typeName === "ZodNullable" && zodDef.innerType) {
-        baseSchema = zodDef.innerType;
-        continue;
-      }
-
-      // No more wrappers to unwrap
-      break;
-    }
-  }
-
-  // Determine parameter type
-  let paramType: CliParameter["type"] = "string";
-  let choices: string[] | undefined;
-
-  if (baseSchema instanceof z.ZodString) {
-    paramType = "string";
-  } else if (baseSchema instanceof z.ZodNumber) {
-    paramType = "number";
-  } else if (baseSchema instanceof z.ZodBoolean) {
-    paramType = "boolean";
-  } else if (baseSchema instanceof z.ZodArray) {
-    paramType = "array";
-  } else if (baseSchema instanceof z.ZodEnum) {
-    paramType = "string";
-    choices = baseSchema.options as string[];
-  } else if (baseSchema instanceof z.ZodRecord) {
-    // Handle Record<string, any> as JSON string input
-    paramType = "string";
-  }
-
-  // Check if this parameter has a resolver
-  let paramHasResolver = false;
-
-  // Check function-specific resolvers first
-  if (functionInfo?.resolvers?.[name]) {
-    paramHasResolver = true;
-  }
-
-  // Extract resolver metadata
-  return {
-    name,
-    type: paramType,
-    required,
-    description: schema.description,
-    default: defaultValue,
-    choices,
-    hasResolver: paramHasResolver,
-    isPositional: isPositional(schema),
-  };
-}
-
-// ============================================================================
-// CLI Structure Derivation - Purely Generic
-// ============================================================================
-
-/**
- * Convert camelCase to kebab-case
- * e.g., listApps -> list-apps, generateTypes -> generate-types
- */
-function toKebabCase(str: string): string {
-  return str.replace(/([A-Z])/g, "-$1").toLowerCase();
-}
-
-/**
- * Convert SDK method name directly to CLI command
- * e.g., listApps -> list-apps, getApp -> get-app, generateTypes -> generate-types
- */
-function methodNameToCliCommand(methodName: string): string {
-  return toKebabCase(methodName);
-}
-
-// ============================================================================
-// CLI Command Generation - Completely Generic
-// ============================================================================
-
-export function generateCliCommands(program: Command, sdk: ZapierSdk): void {
-  // Check if SDK has registry
-  if (typeof sdk.getRegistry !== "function") {
-    console.error("SDK registry not available");
-    return;
-  }
-
-  const registry = sdk.getRegistry({ package: "cli" });
-
-  // Create all commands first
-  registry.functions.forEach((fnInfo) => {
-    if (!fnInfo.inputSchema) {
-      console.warn(`Schema not found for ${fnInfo.name}`);
-      return;
-    }
-
-    // Convert methodName to kebab-case CLI command
-    const cliCommandName = methodNameToCliCommand(fnInfo.name);
-
-    const config = createCommandConfig(cliCommandName, fnInfo, sdk);
-
-    addCommand(program, cliCommandName, config);
-  });
-
-  // Override the help display to show commands grouped by category
-  program.configureHelp({
-    formatHelp: (cmd, helper) => {
-      const helpWidth = helper.helpWidth || 80;
-
-      let output = helper.commandUsage(cmd) + "\n";
-
-      if (cmd.description()) {
-        output += helper.wrap(cmd.description(), helpWidth, 0) + "\n";
-      }
-
-      // Add options section
-      const options = helper.visibleOptions(cmd);
-      if (options.length > 0) {
-        output += "\nOptions:\n";
-        const longestOptionLength = Math.max(
-          ...options.map((opt) => helper.optionTerm(opt).length),
-        );
-        options.forEach((option) => {
-          const term = helper.optionTerm(option);
-          const padding = " ".repeat(
-            Math.max(2, longestOptionLength - term.length + 4),
-          );
-          output += `  ${term}${padding}${helper.optionDescription(option)}\n`;
-        });
-      }
-
-      // Add categorized commands section
-      const commands = helper.visibleCommands(cmd);
-      if (commands.length > 0) {
-        output += "\nCommands:\n";
-
-        // Collect all SDK commands that belong to categories
-        const categorizedCommands = new Set<string>();
-
-        // Group SDK commands by categories
-        registry.categories.forEach((category) => {
-          const categoryCommands = commands.filter((command) =>
-            category.functions.some((functionName) => {
-              const cliCommandName = methodNameToCliCommand(functionName);
-              return command.name() === cliCommandName;
-            }),
-          );
-
-          if (categoryCommands.length > 0) {
-            output += `\n  ${category.titlePlural}:\n`;
-            categoryCommands.forEach((command) => {
-              output += `    ${helper.subcommandTerm(command)}\n`;
-              categorizedCommands.add(command.name());
-            });
-          }
-        });
-
-        // Add any remaining commands that aren't part of SDK categories
-        const otherCommands = commands.filter(
-          (command) => !categorizedCommands.has(command.name()),
-        );
-        if (otherCommands.length > 0) {
-          output += `\n  Other:\n`;
-          otherCommands.forEach((command) => {
-            output += `    ${helper.subcommandTerm(command)}\n`;
-          });
-        }
-      }
-
-      return output;
-    },
-  });
-}
-
-function createCommandConfig(
-  cliCommandName: string,
-  functionInfo: FunctionRegistryEntry,
-  sdk: ZapierSdk,
-): CliCommandConfig {
-  const schema = functionInfo.inputSchema as z.ZodSchema;
-  const parameters = analyzeZodSchema(schema, functionInfo);
-  const description = schema.description || `${cliCommandName} command`;
-
-  const handler = async (...args: unknown[]) => {
-    try {
-      // The last argument is always the command object with parsed options
-      const commandObj = args[args.length - 1] as {
-        opts(): Record<string, unknown>;
-      };
-      const options = commandObj.opts();
-
-      // Check if this is a list command for pagination
-      const isListCommand = functionInfo.type === "list";
-      const hasPaginationParams = parameters.some(
-        (p) => p.name === "maxItems" || p.name === "pageSize",
-      );
-      const hasUserSpecifiedMaxItems: boolean =
-        "maxItems" in options && options.maxItems !== undefined;
-      const shouldUseJson = options.json;
-
-      // Convert CLI args to SDK method parameters
-      const rawParams = convertCliArgsToSdkParams(
-        parameters,
-        args.slice(0, -1),
-        options,
-      );
-
-      // Resolve missing parameters interactively using schema metadata
-      const resolver = new SchemaParameterResolver();
-      const resolvedParams = await resolver.resolveParameters(
-        schema,
-        rawParams,
-        sdk,
-        functionInfo.name,
-      );
-
-      // Handle paginated list commands with async iteration
-      if (
-        isListCommand &&
-        hasPaginationParams &&
-        !shouldUseJson &&
-        !hasUserSpecifiedMaxItems
-      ) {
-        // Get the async iterable directly from the SDK method call (don't await it! that breaks the next page behavior)
-        const sdkObj = sdk as unknown as Record<
-          string,
-          (params: unknown) => Promise<unknown> & AsyncIterable<unknown>
-        >;
-        const sdkIterator = sdkObj[functionInfo.name](resolvedParams);
-        await handlePaginatedListWithAsyncIteration(
-          functionInfo.name,
-          sdkIterator,
-          functionInfo,
-        );
-      } else {
-        // Special handling for commands that write to files
-        const hasOutputFile = (resolvedParams as { output?: unknown }).output;
-        if (hasOutputFile) {
-          // Call the SDK method for file output commands
-          const sdkObj = sdk as unknown as Record<
-            string,
-            (params: unknown) => Promise<unknown>
-          >;
-          await sdkObj[functionInfo.name](resolvedParams);
-          console.log(
-            chalk.green(`✅ ${cliCommandName} completed successfully!`),
-          );
-          console.log(chalk.gray(`Output written to: ${hasOutputFile}`));
-          return;
-        }
-
-        // Call the SDK method and handle non-paginated results
-        const sdkObj = sdk as unknown as Record<
-          string,
-          (params: unknown) => Promise<unknown>
-        >;
-        let result: unknown = await sdkObj[functionInfo.name](resolvedParams);
-
-        // Handle Response objects by wrapping in a structured envelope
-        if (result instanceof Response) {
-          const response = result;
-          let body: unknown;
-          try {
-            body = await response.json();
-          } catch {
-            // If JSON parsing fails, try to get text for error context
-            const text = response.bodyUsed
-              ? "[body already consumed]"
-              : await response.text().catch(() => "[unable to read body]");
-            throw new Error(
-              `Failed to parse response as JSON (status: ${response.status}). Body: ${text.slice(0, 200)}`,
-            );
-          }
-          result = {
-            statusCode: response.status,
-            headers: Object.fromEntries(response.headers.entries()),
-            body,
-          };
-        }
-
-        const items = (result as { data?: unknown })?.data
-          ? (result as { data: unknown }).data
-          : result;
-
-        if (shouldUseJson) {
-          console.log(JSON.stringify(items, null, 2));
-        } else if (isListCommand) {
-          formatNonPaginatedResults(
-            items as unknown[],
-            (resolvedParams as { maxItems?: number }).maxItems,
-            hasUserSpecifiedMaxItems,
-            shouldUseJson as boolean,
-            functionInfo,
-          );
-        } else {
-          formatJsonOutput(items);
-        }
-      }
-    } catch (error) {
-      // Handle Zod validation errors more gracefully
-      if (error instanceof Error && error.message.includes('"code"')) {
-        try {
-          const validationErrors = JSON.parse(error.message);
-          console.error(chalk.red("❌ Validation Error:"));
-          validationErrors.forEach((err: unknown) => {
-            const errorObj = err as { path?: string[]; message?: string };
-            const field = errorObj?.path?.join(".") || "unknown";
-            console.error(
-              chalk.yellow(
-                `  • ${field}: ${errorObj?.message || "Unknown error"}`,
-              ),
-            );
-          });
-          console.error(
-            "\n" + chalk.dim(`Use --help to see available options`),
-          );
-          throw new ZapierCliExitError("Validation failed", 1);
-        } catch {
-          console.error(
-            chalk.red("Error:"),
-            error instanceof Error ? error.message : String(error),
-          );
-          throw new ZapierCliExitError(
-            error instanceof Error ? error.message : String(error),
-            1,
-          );
-        }
-      } else if (error instanceof ZapierCliError) {
-        // Re-throw all CLI errors as-is
-        throw error;
-      } else if (error instanceof ZapierError) {
-        // Handle SDK errors with clean, user-friendly messages using our formatter
-        const formattedMessage = formatErrorMessage(error);
-        console.error(chalk.red("❌ Error:"), formattedMessage);
-        throw new ZapierCliExitError(formattedMessage, 1);
-      } else {
-        // Handle other errors
-        const errorMessage =
-          error instanceof Error ? error.message : "Unknown error";
-        console.error(chalk.red("❌ Error:"), errorMessage);
-        throw new ZapierCliExitError(errorMessage, 1);
-      }
-    }
-  };
-
-  return {
-    description,
-    parameters,
-    handler,
-  };
-}
-
-function addCommand(
-  program: Command,
-  commandName: string,
-  config: CliCommandConfig,
-): void {
-  const command = program.command(commandName).description(config.description);
-
-  // Track whether we've already used a positional array parameter
-  let hasPositionalArray = false;
-
-  // Add parameters to command
-  config.parameters.forEach((param) => {
-    // Convert camelCase to kebab-case for CLI display
-    const kebabName = param.name.replace(/([A-Z])/g, "-$1").toLowerCase();
-
-    if (param.hasResolver && param.required) {
-      // Required parameters with resolvers become optional positional arguments (resolver handles prompting)
-      command.argument(
-        `[${kebabName}]`,
-        param.description || `${kebabName} parameter`,
-      );
-    } else if (
-      param.required &&
-      param.type === "array" &&
-      !hasPositionalArray
-    ) {
-      // First required array parameter becomes a variadic positional argument
-      hasPositionalArray = true;
-      command.argument(
-        `<${kebabName}...>`,
-        param.description || `${kebabName} parameter`,
-      );
-    } else if (param.required && param.type === "array") {
-      // Subsequent required array parameters become required flags
-      const flags = [`--${kebabName}`];
-      const flagSignature = flags.join(", ") + ` <values...>`;
-      command.requiredOption(
-        flagSignature,
-        param.description || `${kebabName} parameter (required)`,
-      );
-    } else if (param.required) {
-      // Required parameters without resolvers become required positional arguments
-      command.argument(
-        `<${kebabName}>`,
-        param.description || `${kebabName} parameter`,
-      );
-    } else if (param.isPositional) {
-      // Optional parameters marked as positional become optional positional arguments
-      command.argument(
-        `[${kebabName}]`,
-        param.description || `${kebabName} parameter`,
-      );
-    } else {
-      // Optional parameters become flags (whether they have resolvers or not)
-      const flags = [`--${kebabName}`];
-
-      if (param.type === "boolean") {
-        command.option(flags.join(", "), param.description);
-      } else if (param.type === "array") {
-        // For arrays, use variadic syntax to collect multiple values
-        const flagSignature = flags.join(", ") + ` <values...>`;
-        command.option(
-          flagSignature,
-          param.description,
-          param.default as string[] | undefined,
-        );
-      } else {
-        const flagSignature = flags.join(", ") + ` <${param.type}>`;
-        command.option(
-          flagSignature,
-          param.description || "",
-          param.default as string | boolean | string[] | undefined,
-        );
-      }
-    }
-  });
-
-  // Add formatting options for all commands
-  command.option("--json", "Output raw JSON instead of formatted results");
-
-  command.action(config.handler);
-}
-
-// ============================================================================
-// Parameter Conversion
-// ============================================================================
-
-function convertCliArgsToSdkParams(
-  parameters: CliParameter[],
-  positionalArgs: unknown[],
-  options: Record<string, unknown>,
-): Record<string, unknown> {
-  const sdkParams: Record<string, unknown> = {};
-
-  // Handle positional arguments (required parameters or optional positional parameters)
-  let argIndex = 0;
-  parameters.forEach((param) => {
-    if (
-      (param.required || param.isPositional) &&
-      argIndex < positionalArgs.length
-    ) {
-      // Use the original camelCase parameter name for the SDK
-      sdkParams[param.name] = convertValue(
-        positionalArgs[argIndex],
-        param.type,
-      );
-      argIndex++;
-    }
-  });
-
-  // Handle option flags
-  Object.entries(options).forEach(([key, value]) => {
-    // Convert kebab-case back to camelCase
-    const camelKey = key.replace(/-([a-z])/g, (g) => g[1].toUpperCase());
-    const param = parameters.find((p) => p.name === camelKey);
-
-    if (param && value !== undefined) {
-      sdkParams[camelKey] = convertValue(value, param.type);
-    }
-  });
-
-  return sdkParams;
-}
-
-function convertValue(value: unknown, type: CliParameter["type"]): unknown {
-  // Don't convert undefined values - let the resolver system handle them
-  if (value === undefined) {
-    return undefined;
-  }
-
-  switch (type) {
-    case "number":
-      return Number(value);
-    case "boolean":
-      return Boolean(value);
-    case "array":
-      return Array.isArray(value) ? value : [value];
-    case "string":
-    default:
-      // Handle JSON string for objects
-      if (
-        typeof value === "string" &&
-        (value.startsWith("{") || value.startsWith("["))
-      ) {
-        try {
-          return JSON.parse(value);
-        } catch {
-          return value;
-        }
-      }
-      return value;
-  }
-}
-
-// ============================================================================
-// Pagination Handlers
-// ============================================================================
-
-async function handlePaginatedListWithAsyncIteration(
-  sdkMethodName: string,
-  sdkResult: unknown,
-  functionInfo: FunctionRegistryEntry,
-): Promise<void> {
-  const itemName = getItemNameFromMethod(functionInfo);
-  let totalShown = 0;
-  let pageCount = 0;
-
-  console.log(
-    chalk.blue(`📋 ${getListTitleFromMethod(sdkMethodName, functionInfo)}\n`),
-  );
-
-  try {
-    // Use async iteration to go through pages
-    for await (const page of sdkResult as AsyncIterable<{
-      data?: unknown[];
-      nextCursor?: string;
-    }>) {
-      const items = page.data || page;
-      pageCount++;
-
-      if (!Array.isArray(items)) {
-        console.log(chalk.yellow(`No ${itemName} found.`));
-        return;
-      }
-
-      if (items.length === 0 && pageCount === 1) {
-        console.log(chalk.yellow(`No ${itemName} found.`));
-        return;
-      }
-
-      if (items.length === 0) {
-        break; // No more items
-      }
-
-      // Clear screen for subsequent pages (not the first)
-      if (pageCount > 1) {
-        console.clear();
-        console.log(
-          chalk.blue(
-            `📋 ${getListTitleFromMethod(sdkMethodName, functionInfo)}\n`,
-          ),
-        );
-      }
-
-      // Format and display items using function info
-      if (functionInfo && functionInfo.inputSchema) {
-        formatItemsFromSchema(
-          functionInfo as { inputSchema: z.ZodType; outputSchema?: z.ZodType },
-          items,
-          totalShown,
-        );
-      } else {
-        formatItemsGeneric(items, totalShown);
-      }
-
-      totalShown += items.length;
-      console.log(
-        chalk.green(
-          `\n✅ Showing ${totalShown} ${itemName} (page ${pageCount})`,
-        ),
-      );
-
-      // Only prompt if there's a nextCursor (more pages available)
-      if (page.nextCursor) {
-        const { continueReading } = await inquirer.prompt([
-          {
-            type: "confirm",
-            name: "continueReading",
-            message: `Load next page?`,
-            default: true,
-          },
-        ]);
-
-        if (!continueReading) {
-          break;
-        }
-      } else {
-        // No more pages available, exit gracefully
-        break;
-      }
-    }
-
-    console.log(chalk.gray(`\n📄 Finished browsing ${itemName}`));
-  } catch (error) {
-    // If the result is not async iterable, fall back to showing the first page
-    const items = (sdkResult as { data?: unknown[] })?.data || sdkResult;
-    if (Array.isArray(items)) {
-      if (items.length === 0) {
-        console.log(chalk.yellow(`No ${itemName} found.`));
-        return;
-      }
-
-      if (functionInfo && functionInfo.inputSchema) {
-        formatItemsFromSchema(
-          functionInfo as { inputSchema: z.ZodType; outputSchema?: z.ZodType },
-          items,
-          0,
-        );
-      } else {
-        formatItemsGeneric(items, 0);
-      }
-
-      console.log(chalk.green(`\n✅ Showing ${items.length} ${itemName}`));
-    } else {
-      throw error;
-    }
-  }
-}
-
-function formatNonPaginatedResults(
-  result: unknown[],
-  requestedMaxItems?: number,
-  userSpecifiedMaxItems?: boolean,
-  useRawJson?: boolean,
-  functionInfo?: FunctionRegistryEntry,
-): void {
-  if (!Array.isArray(result)) {
-    if (useRawJson) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      formatJsonOutput(result);
-    }
-    return;
-  }
-
-  if (useRawJson) {
-    console.log(JSON.stringify(result, null, 2));
-    return;
-  }
-
-  const itemName = functionInfo ? getItemNameFromMethod(functionInfo) : "items";
-
-  if (result.length === 0) {
-    console.log(chalk.yellow(`No ${itemName} found.`));
-    return;
-  }
-
-  console.log(chalk.green(`\n✅ Found ${result.length} ${itemName}:\n`));
-
-  // Use function info for formatting
-  if (functionInfo && functionInfo.inputSchema) {
-    formatItemsFromSchema(
-      functionInfo as { inputSchema: z.ZodType; outputSchema?: z.ZodType },
-      result,
-    );
-  } else {
-    // Fallback to generic formatting
-    formatItemsGeneric(result);
-  }
-
-  // Show appropriate status message
-  if (userSpecifiedMaxItems && requestedMaxItems) {
-    console.log(
-      chalk.gray(
-        `\n📄 Showing up to ${requestedMaxItems} ${itemName} (--max-items ${requestedMaxItems})`,
-      ),
-    );
-  } else {
-    console.log(chalk.gray(`\n📄 All available ${itemName} shown`));
-  }
-}
-
-function formatItemsGeneric(
-  items: unknown[],
-  startingNumber: number = 0,
-): void {
-  // Fallback formatting for items without schema metadata
-  items.forEach((item, index) => {
-    const itemObj = item as Record<string, unknown>;
-    const name = itemObj?.name || itemObj?.key || itemObj?.id || "Item";
-    console.log(
-      `${chalk.gray(`${startingNumber + index + 1}.`)} ${chalk.cyan(String(name))}`,
-    );
-    if (itemObj?.description) {
-      console.log(`   ${chalk.dim(String(itemObj.description))}`);
-    }
-    console.log();
-  });
-}
-
-// Generic helper functions that infer from schema description or method name
-function getItemNameFromMethod(functionInfo: FunctionRegistryEntry): string {
-  if (functionInfo.itemType) {
-    return `${functionInfo.itemType} items`;
-  }
-
-  return "items";
-}
-
-function getListTitleFromMethod(
-  methodName: string,
-  functionInfo: FunctionRegistryEntry,
-): string {
-  if (functionInfo.itemType) {
-    return `Available ${functionInfo.itemType} items`;
-  }
-
-  return `${methodName} items`;
-}