@zapier/zapier-sdk-cli 0.0.1

package/src/utils/cli-generator.ts

@@ -0,0 +1,578 @@
+import { Command } from "commander";
+import { z } from "zod";
+import { ActionsSDK } from "@zapier/actions-sdk";
+import { SDKSchemas } from "../../../actions-sdk/dist/schemas";
+import { SchemaParameterResolver } from "./parameter-resolver";
+import { createPager } from "./pager";
+import { formatItemsFromSchema } from "./schema-formatter";
+import chalk from "chalk";
+import util from "util";
+
+// ============================================================================
+// JSON Formatting
+// ============================================================================
+
+function formatJSONOutput(data: any): void {
+  // Show success message for action results
+  if (
+    data &&
+    typeof data === "object" &&
+    !Array.isArray(data) &&
+    (data.success !== undefined || data.id || data.status)
+  ) {
+    console.log(chalk.green("✅ Action completed successfully!\n"));
+  }
+
+  // Use util.inspect for colored output
+  console.log(
+    util.inspect(data, { colors: true, depth: null, breakLength: 80 }),
+  );
+}
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface CLICommandConfig {
+  description: string;
+  parameters: CLIParameter[];
+  handler: (...args: any[]) => Promise<void>;
+}
+
+interface CLIParameter {
+  name: string;
+  type: "string" | "number" | "boolean" | "array";
+  required: boolean;
+  description?: string;
+  default?: any;
+  choices?: string[];
+  resolverMeta?: any;
+}
+
+// ============================================================================
+// Schema Analysis
+// ============================================================================
+
+function analyzeZodSchema(schema: z.ZodSchema): CLIParameter[] {
+  const parameters: CLIParameter[] = [];
+
+  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);
+      if (param) {
+        parameters.push(param);
+      }
+    }
+  }
+
+  return parameters;
+}
+
+function analyzeZodField(
+  name: string,
+  schema: z.ZodSchema,
+): CLIParameter | null {
+  let baseSchema = schema;
+  let required = true;
+  let defaultValue: any = undefined;
+
+  // Unwrap optional and default wrappers
+  if (baseSchema instanceof z.ZodOptional) {
+    required = false;
+    baseSchema = baseSchema._def.innerType;
+  }
+
+  if (baseSchema instanceof z.ZodDefault) {
+    required = false;
+    defaultValue = baseSchema._def.defaultValue();
+    baseSchema = baseSchema._def.innerType;
+  }
+
+  // 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._def.values;
+  } else if (baseSchema instanceof z.ZodRecord) {
+    // Handle Record<string, any> as JSON string input
+    paramType = "string";
+  }
+
+  // Extract resolver metadata
+  const resolverMeta = (schema._def as any).resolverMeta;
+
+  return {
+    name,
+    type: paramType,
+    required,
+    description: schema.description,
+    default: defaultValue,
+    choices,
+    resolverMeta,
+  };
+}
+
+// ============================================================================
+// CLI Command Generation
+// ============================================================================
+
+export function generateCLICommands(program: Command, sdk: ActionsSDK): void {
+  // Check if SDKSchemas is available
+  if (!SDKSchemas) {
+    console.error("SDKSchemas not available");
+    return;
+  }
+
+  // Generate namespace commands (apps, actions, auths, fields)
+  Object.entries(SDKSchemas).forEach(([namespace, methods]) => {
+    if (namespace === "generate" || namespace === "bundle") {
+      // Handle root tools separately
+      return;
+    }
+
+    const namespaceCommand = program
+      .command(namespace)
+      .description(`${namespace} management commands`);
+
+    if (typeof methods === "object" && methods !== null) {
+      Object.entries(methods).forEach(([method, schema]) => {
+        const config = createCommandConfig(
+          namespace,
+          method,
+          schema as z.ZodSchema,
+          sdk,
+        );
+        addSubCommand(namespaceCommand, method, config);
+      });
+    }
+  });
+
+  // Generate root tool commands
+  if (SDKSchemas.generate) {
+    const generateConfig = createCommandConfig(
+      "",
+      "generate",
+      SDKSchemas.generate,
+      sdk,
+    );
+    addSubCommand(program, "generate", generateConfig);
+  }
+
+  if (SDKSchemas.bundle) {
+    const bundleConfig = createCommandConfig(
+      "",
+      "bundle",
+      SDKSchemas.bundle,
+      sdk,
+    );
+    addSubCommand(program, "bundle", bundleConfig);
+  }
+}
+
+function createCommandConfig(
+  namespace: string,
+  method: string,
+  schema: z.ZodSchema,
+  sdk: ActionsSDK,
+): CLICommandConfig {
+  const parameters = analyzeZodSchema(schema);
+  const description = schema.description || `${namespace} ${method} command`;
+
+  const handler = async (...args: any[]) => {
+    try {
+      // The last argument is always the command object with parsed options
+      const command = args[args.length - 1];
+      const options = command.opts();
+
+      // Check if this is a list command with pagination support
+      const isListCommand = method === "list";
+      const hasPaginationParams = parameters.some(
+        (p) => p.name === "limit" || p.name === "offset",
+      );
+      const hasUserSpecifiedLimit =
+        "limit" in options && options.limit !== undefined;
+      const shouldUsePaging =
+        isListCommand && hasPaginationParams && !hasUserSpecifiedLimit;
+      const shouldUseJSON = options.json;
+
+      // Convert CLI args to SDK method parameters
+      const rawParams = convertCLIArgsToSDKParams(
+        parameters,
+        args.slice(0, -1),
+        options,
+      );
+
+      // NEW: Resolve missing parameters interactively using schema metadata
+      const resolver = new SchemaParameterResolver();
+      const resolvedParams = await resolver.resolveParameters(
+        schema,
+        rawParams,
+        sdk,
+      );
+
+      if (shouldUsePaging && !shouldUseJSON) {
+        // Use interactive paging for list commands
+        await handlePaginatedList(namespace, method, resolvedParams, sdk);
+      } else {
+        // Call the appropriate SDK method with complete, validated parameters
+        let result: any;
+        if (namespace === "") {
+          // Root tool (generate, bundle)
+          result = await (sdk as any)[method](resolvedParams);
+        } else {
+          // Regular namespace method
+          result = await (sdk as any)[namespace][method](resolvedParams);
+        }
+
+        // Special handling for generate and bundle commands - don't output to console if writing to file
+        const isRootCommandWithOutput =
+          namespace === "" && (method === "generate" || method === "bundle");
+        const hasOutputFile = isRootCommandWithOutput && resolvedParams.output;
+
+        // Output result (JSON or formatted)
+        if (!hasOutputFile && (shouldUseJSON || !isListCommand)) {
+          // Use raw JSON if --json flag is specified, otherwise use pretty formatting
+          if (shouldUseJSON) {
+            console.log(JSON.stringify(result, null, 2));
+          } else {
+            formatJSONOutput(result);
+          }
+        } else if (!hasOutputFile) {
+          // Format list results nicely (non-paginated)
+          formatNonPaginatedResults(
+            namespace,
+            result,
+            resolvedParams.limit,
+            hasUserSpecifiedLimit,
+            shouldUseJSON,
+          );
+        } else if (hasOutputFile) {
+          // Show success message for file output instead of printing generated content
+          console.log(chalk.green(`✅ ${method} completed successfully!`));
+          console.log(
+            chalk.gray(`Output written to: ${resolvedParams.output}`),
+          );
+        }
+      }
+    } catch (error) {
+      console.error(
+        "Error:",
+        error instanceof Error ? error.message : "Unknown error",
+      );
+      process.exit(1);
+    }
+  };
+
+  return {
+    description,
+    parameters,
+    handler,
+  };
+}
+
+function addSubCommand(
+  parentCommand: Command,
+  name: string,
+  config: CLICommandConfig,
+): void {
+  const command = parentCommand.command(name).description(config.description);
+
+  // Add parameters to command
+  config.parameters.forEach((param) => {
+    if (param.resolverMeta?.resolver && param.required) {
+      // Required parameters with resolvers become optional positional arguments (resolver handles prompting)
+      command.argument(
+        `[${param.name}]`,
+        param.description || `${param.name} parameter`,
+      );
+    } else if (param.required) {
+      // Required parameters without resolvers become required positional arguments
+      command.argument(
+        `<${param.name}>`,
+        param.description || `${param.name} parameter`,
+      );
+    } else {
+      // Optional parameters become flags (whether they have resolvers or not)
+      const flags = [
+        `--${param.name.replace(/([A-Z])/g, "-$1").toLowerCase()}`,
+      ];
+
+      if (param.type === "boolean") {
+        command.option(flags.join(", "), param.description);
+      } else {
+        const flagSignature = flags.join(", ") + ` <${param.type}>`;
+        command.option(flagSignature, param.description, param.default);
+      }
+    }
+  });
+
+  // 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: any[],
+  options: Record<string, any>,
+): Record<string, any> {
+  const sdkParams: Record<string, any> = {};
+
+  // Handle positional arguments (required parameters only, whether they have resolvers or not)
+  let argIndex = 0;
+  parameters.forEach((param) => {
+    if (param.required && argIndex < positionalArgs.length) {
+      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: any, type: CLIParameter["type"]): any {
+  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 handlePaginatedList(
+  namespace: string,
+  method: string,
+  baseParams: any,
+  sdk: ActionsSDK,
+): Promise<void> {
+  const limit = baseParams.limit || 20;
+  const itemName = getItemName(namespace);
+
+  console.log(chalk.blue(`📋 Fetching ${itemName}...`));
+
+  const pager = createPager({
+    pageSize: Math.min(limit, 20),
+    itemName,
+  });
+
+  const displayFunction = (
+    items: any[],
+    totalShown: number,
+    totalAvailable?: number,
+  ) => {
+    // Only clear screen if we have items to show
+    if (items.length > 0) {
+      console.clear();
+    }
+    console.log(chalk.blue(`📋 ${getListTitle(namespace)}\n`));
+
+    if (items.length === 0) {
+      console.log(chalk.yellow(`No ${itemName} found.`));
+      return;
+    }
+
+    // Get the schema for this namespace/method to extract formatting info
+    const schema = SDKSchemas[namespace as keyof typeof SDKSchemas];
+    const listSchema =
+      schema && typeof schema === "object" && "list" in schema
+        ? schema.list
+        : null;
+
+    if (listSchema) {
+      formatItemsFromSchema(listSchema as z.ZodType, items);
+    } else {
+      // Fallback to generic formatting
+      formatItemsGeneric(items);
+    }
+
+    const totalInfo = totalAvailable
+      ? ` of ${totalAvailable.toLocaleString()} total`
+      : "";
+    console.log(
+      chalk.green(`\n✅ Showing ${totalShown}${totalInfo} ${itemName}`),
+    );
+  };
+
+  await pager.paginate(
+    (params) =>
+      (sdk as any)[namespace][method]({
+        ...baseParams,
+        ...params,
+      }),
+    {},
+    displayFunction,
+  );
+}
+
+function formatNonPaginatedResults(
+  namespace: string,
+  result: any[],
+  requestedLimit?: number,
+  userSpecifiedLimit?: boolean,
+  useRawJSON?: boolean,
+): 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 = getItemName(namespace);
+
+  if (result.length === 0) {
+    console.log(chalk.yellow(`No ${itemName} found.`));
+    return;
+  }
+
+  console.log(chalk.green(`\n✅ Found ${result.length} ${itemName}:\n`));
+
+  // Get the schema for this namespace/method to extract formatting info
+  const schema = SDKSchemas[namespace as keyof typeof SDKSchemas];
+  const listSchema =
+    schema && typeof schema === "object" && "list" in schema
+      ? schema.list
+      : null;
+
+  if (listSchema) {
+    formatItemsFromSchema(listSchema as z.ZodType, result);
+  } else {
+    // Fallback to generic formatting
+    formatItemsGeneric(result);
+  }
+
+  // Show appropriate status message
+  if (userSpecifiedLimit && requestedLimit) {
+    console.log(
+      chalk.gray(
+        `\n📄 Showing up to ${requestedLimit} ${itemName} (--limit ${requestedLimit})`,
+      ),
+    );
+  } else {
+    console.log(chalk.gray(`\n📄 All available ${itemName} shown`));
+  }
+}
+
+function formatItemsGeneric(items: any[]): void {
+  // Fallback formatting for items without schema metadata
+  items.forEach((item, index) => {
+    const name = item.name || item.key || item.id || "Item";
+    console.log(`${chalk.gray(`${index + 1}.`)} ${chalk.cyan(name)}`);
+    if (item.description) {
+      console.log(`   ${chalk.dim(item.description)}`);
+    }
+    console.log();
+  });
+}
+
+function getItemName(namespace: string): string {
+  switch (namespace) {
+    case "apps":
+      return "apps";
+    case "actions":
+      return "actions";
+    case "auths":
+      return "authentications";
+    case "fields":
+      return "fields";
+    default:
+      return "items";
+  }
+}
+
+function getListTitle(namespace: string): string {
+  switch (namespace) {
+    case "apps":
+      return "Available Apps";
+    case "actions":
+      return "Available Actions";
+    case "auths":
+      return "Available Authentications";
+    case "fields":
+      return "Available Fields";
+    default:
+      return "Available Items";
+  }
+}
+
+// ============================================================================
+// Help Text Enhancement
+// ============================================================================
+
+export function enhanceCommandHelp(program: Command): void {
+  // Add custom help that shows schema-driven nature
+  program.on("--help", () => {
+    console.log("");
+    console.log("Commands are automatically generated from SDK schemas.");
+    console.log(
+      "Each command maps directly to an SDK method with the same parameters.",
+    );
+    console.log("");
+    console.log("Examples:");
+    console.log("  zapier-sdk apps list --category=productivity --limit=10");
+    console.log(
+      '  zapier-sdk actions run slack search user_by_email --inputs=\'{"email":"user@example.com"}\'',
+    );
+    console.log("  zapier-sdk generate my-app --output=./generated/");
+    console.log("  zsdk apps list --limit=5  # Using the shorter alias");
+    console.log("");
+  });
+}