@ollie-shop/cli 0.3.0 → 0.3.3

package/src/utils/deploy-helpers.ts

@@ -0,0 +1,357 @@
+import {
+  type BuildResponse,
+  type BuildResult,
+  formatBuildError,
+  setBuilderUrl,
+  waitForBuildCompletion,
+} from "@ollie-shop/core";
+import { validateBuilderApiUrl } from "../schemas/command.schema";
+import type { CliConsole } from "./console";
+import { DEPLOYMENT_SETTINGS, ERROR_MESSAGES } from "./constants";
+import { RichProgressReporter } from "./rich-progress.js";
+
+/**
+ * Resource types that can be deployed through the CLI
+ * @typedef {"component" | "function"} ResourceType
+ */
+export type ResourceType = "component" | "function";
+
+/**
+ * Error types that can occur during deployment operations
+ * @typedef {"BuildTimeoutError" | "BuildFailedError" | "BuildValidationError" | "UnknownError"} DeploymentErrorType
+ */
+export type DeploymentErrorType =
+  | "BuildTimeoutError"
+  | "BuildFailedError"
+  | "BuildValidationError"
+  | "UnknownError";
+
+/**
+ * Deployment progress information returned after successful deployment
+ * @interface DeploymentProgress
+ * @property {BuildResponse} completedBuild - The completed build response from the builder service
+ * @property {number} duration - Total deployment duration in seconds
+ */
+export interface DeploymentProgress {
+  completedBuild: BuildResponse;
+  duration: number;
+}
+
+/**
+ * Configure the builder URL from environment variable with validation
+ * Uses BUILDER_API_URL environment variable if set, validates it's a proper URL
+ *
+ * @throws {Error} If BUILDER_API_URL is set but invalid
+ * @example
+ * ```typescript
+ * // Set environment variable first
+ * process.env.BUILDER_API_URL = "https://builder.ollie.shop";
+ *
+ * // Configure the builder
+ * configureBuilderUrl();
+ * ```
+ */
+export function configureBuilderUrl(): void {
+  const builderUrl = process.env.BUILDER_API_URL;
+  if (builderUrl) {
+    if (!validateBuilderApiUrl(builderUrl)) {
+      throw new Error(
+        "Invalid BUILDER_API_URL environment variable. Must be a valid HTTP or HTTPS URL.",
+      );
+    }
+    setBuilderUrl(builderUrl);
+  }
+}
+
+/**
+ * Handle deployment errors with proper type safety and user-friendly messages
+ * Provides specific error messages and recovery suggestions based on error type
+ *
+ * @param {unknown} error - The error that occurred during deployment
+ * @param {string} _buildId - The build ID (currently unused but kept for future use)
+ * @param {ResourceType} resourceType - Type of resource being deployed (component/function)
+ * @param {CliConsole} cliConsole - Console instance for output
+ * @example
+ * ```typescript
+ * try {
+ *   await deployComponent(options);
+ * } catch (error) {
+ *   handleDeploymentError(error, buildId, "component", console);
+ * }
+ * ```
+ */
+export function handleDeploymentError(
+  error: unknown,
+  _buildId: string,
+  resourceType: ResourceType,
+  cliConsole: CliConsole,
+): void {
+  const errorType = getErrorType(error);
+  const errorMessage = getErrorMessage(error);
+
+  switch (errorType) {
+    case "BuildTimeoutError":
+      cliConsole.error(ERROR_MESSAGES.DEPLOYMENT_TIMEOUT);
+      cliConsole.suggestions([
+        `Retry deployment: ollieshop ${resourceType} deploy --id <${resourceType}-id>`,
+        "Check your network connection and try again",
+        "Contact support if timeouts persist - this may indicate infrastructure issues",
+      ]);
+      break;
+    case "BuildFailedError":
+      cliConsole.error(ERROR_MESSAGES.BUILD_FAILED);
+      cliConsole.info("Review the build logs above for specific error details");
+      if (errorMessage) {
+        cliConsole.info(`Error details: ${errorMessage}`);
+      }
+      cliConsole.suggestions([
+        `Validate your ${resourceType} code: ollieshop ${resourceType} validate`,
+        "Check your code for syntax errors and missing dependencies",
+        "Ensure all imports and exports are correctly defined",
+      ]);
+      break;
+    case "BuildValidationError":
+      cliConsole.error(ERROR_MESSAGES.BUILD_VALIDATION_FAILED);
+      handleBuildValidationError(error, resourceType, cliConsole);
+      break;
+    default:
+      cliConsole.error(`${ERROR_MESSAGES.UNKNOWN_ERROR}: ${errorMessage}`);
+      break;
+  }
+}
+
+/**
+ * Get the error type from an unknown error with proper type safety
+ */
+function getErrorType(error: unknown): DeploymentErrorType {
+  if (error && typeof error === "object" && "name" in error) {
+    const errorName = (error as { name: string }).name;
+    if (isValidErrorType(errorName)) {
+      return errorName;
+    }
+  }
+  return "UnknownError";
+}
+
+/**
+ * Get the error message from an unknown error with proper type safety
+ */
+function getErrorMessage(error: unknown): string {
+  if (error && typeof error === "object" && "message" in error) {
+    return String((error as { message: unknown }).message);
+  }
+  return "An unknown error occurred";
+}
+
+/**
+ * Type guard to check if a string is a valid error type
+ */
+function isValidErrorType(errorName: string): errorName is DeploymentErrorType {
+  return [
+    "BuildTimeoutError",
+    "BuildFailedError",
+    "BuildValidationError",
+  ].includes(errorName);
+}
+
+/**
+ * Show deployment success message with build details
+ * Displays build ID, duration, and infrastructure deployment confirmation
+ *
+ * @param {BuildResponse} completedBuild - The completed build response
+ * @param {number} duration - Deployment duration in seconds
+ * @param {string} _resourceId - Resource ID (currently unused but kept for future use)
+ * @param {ResourceType} _resourceType - Resource type (currently unused but kept for future use)
+ * @param {CliConsole} cliConsole - Console instance for output
+ * @example
+ * ```typescript
+ * const { completedBuild, duration } = await waitForDeploymentWithProgress(
+ *   buildId,
+ *   "component",
+ *   console
+ * );
+ * showDeploymentSuccess(completedBuild, duration, componentId, "component", console);
+ * ```
+ */
+export function showDeploymentSuccess(
+  completedBuild: BuildResponse,
+  duration: number,
+  _resourceId: string,
+  _resourceType: ResourceType,
+  cliConsole: CliConsole,
+): void {
+  cliConsole.success("\n✅ Deployment completed successfully!");
+  cliConsole.info(`Build ID: ${completedBuild.id}`);
+  cliConsole.info(`Duration: ${duration.toFixed(1)}s`);
+
+  // Note: Deployment URLs are dynamically generated by the infrastructure
+  // For components: CloudFront URL (managed by SST router)
+  // For functions: Lambda ARN (managed by AWS)
+  cliConsole.info("✨ Resources deployed to cloud infrastructure");
+}
+
+// Removed showAsyncModeNextSteps as deployments now always wait for completion
+
+/**
+ * Wait for deployment completion with real-time progress reporting
+ * Shows animated progress bar with ETA while polling the builder service
+ *
+ * @async
+ * @param {string} buildId - The build ID to monitor
+ * @param {ResourceType} resourceType - Type of resource being deployed
+ * @param {CliConsole} cliConsole - Console instance for progress display
+ * @returns {Promise<DeploymentProgress>} Deployment details including completed build and duration
+ * @throws {Error} If deployment times out or fails
+ * @example
+ * ```typescript
+ * const result = await buildAndDeployComponent(componentId, path);
+ * const { completedBuild, duration } = await waitForDeploymentWithProgress(
+ *   result.buildId,
+ *   "component",
+ *   console
+ * );
+ * console.log(`Deployment completed in ${duration}s`);
+ * ```
+ */
+export async function waitForDeploymentWithProgress(
+  buildId: string,
+  resourceType: ResourceType,
+  cliConsole: CliConsole,
+): Promise<DeploymentProgress> {
+  const progressReporter = new RichProgressReporter(cliConsole);
+  progressReporter.start();
+
+  const startTime = Date.now();
+  const estimatedDuration = DEPLOYMENT_SETTINGS.ESTIMATED_BUILD_DURATION_MS;
+
+  // Update progress based on elapsed time
+  const progressTimer = setInterval(() => {
+    const elapsed = Date.now() - startTime;
+    const progress = Math.min(
+      elapsed / estimatedDuration,
+      DEPLOYMENT_SETTINGS.MAX_PROGRESS_BEFORE_COMPLETION,
+    );
+    const remainingSeconds = Math.max(
+      0,
+      Math.ceil((estimatedDuration - elapsed) / 1000),
+    );
+
+    progressReporter.updateProgress({
+      phase: "building",
+      message: `Building ${resourceType}... ETA: ${remainingSeconds}s`,
+      progress,
+    });
+  }, DEPLOYMENT_SETTINGS.PROGRESS_UPDATE_INTERVAL_MS);
+
+  try {
+    const completedBuild = await waitForBuildCompletion(buildId, {
+      pollIntervalMs: DEPLOYMENT_SETTINGS.DEFAULT_POLL_INTERVAL_MS,
+      maxWaitMs: DEPLOYMENT_SETTINGS.DEFAULT_MAX_WAIT_MS,
+    });
+
+    clearInterval(progressTimer);
+    const duration = (Date.now() - startTime) / 1000;
+    progressReporter.stop(true);
+
+    return { completedBuild, duration };
+  } catch (error) {
+    clearInterval(progressTimer);
+    progressReporter.stop(false);
+    throw error;
+  }
+}
+
+/**
+ * Handle build validation errors with specific suggestions
+ * Provides targeted help for common validation issues
+ *
+ * @param {unknown} error - The validation error
+ * @param {ResourceType} resourceType - Type of resource that failed validation
+ * @param {CliConsole} cliConsole - Console instance for output
+ * @example
+ * ```typescript
+ * if (error.code === "BUILD_VALIDATION_ERROR") {
+ *   handleBuildValidationError(error, "component", console);
+ * }
+ * ```
+ */
+export function handleBuildValidationError(
+  error: unknown,
+  resourceType: ResourceType,
+  cliConsole: CliConsole,
+): void {
+  const errorCode = getErrorCode(error);
+
+  if (errorCode === "BUILD_VALIDATION_ERROR") {
+    cliConsole.suggestions([
+      `Ensure the ${resourceType} ID is a valid UUID format (e.g., 123e4567-e89b-12d3-a456-426614174000)`,
+      `Verify the ${resourceType} directory exists and contains the required files`,
+      `Check that your ${resourceType} has a valid package.json with correct entry point`,
+      `Run: ollieshop ${resourceType} validate --path <path> to identify specific issues`,
+    ]);
+  }
+}
+
+/**
+ * Get error code from unknown error with proper type safety
+ */
+function getErrorCode(error: unknown): string | undefined {
+  if (error && typeof error === "object" && "code" in error) {
+    const code = (error as { code: unknown }).code;
+    return typeof code === "string" ? code : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Handle deployment result with proper error handling and type safety
+ * Updates spinner state and throws error if deployment failed
+ *
+ * @param {BuildResult} result - The build result from the deployment attempt
+ * @param {ResourceType} resourceType - Type of resource being deployed
+ * @param {CliConsole} cliConsole - Console instance for output
+ * @param {ReturnType<CliConsole["spinner"]>} spinner - Active spinner to update
+ * @throws {Error} If the deployment failed
+ * @example
+ * ```typescript
+ * const result = await buildAndDeployComponent(componentId, path);
+ * handleDeploymentResult(result, "component", console, spinner);
+ * // If we get here, deployment was initiated successfully
+ * ```
+ */
+export function handleDeploymentResult(
+  result: BuildResult,
+  resourceType: ResourceType,
+  cliConsole: CliConsole,
+  spinner: ReturnType<CliConsole["spinner"]>,
+): void {
+  if (!result.success) {
+    const capitalizedType = capitalizeResourceType(resourceType);
+    spinner.fail(`${capitalizedType} deployment failed`);
+
+    const errorMessage = result.error
+      ? formatBuildError(result.error)
+      : "Unknown error occurred";
+
+    cliConsole.error(errorMessage);
+    handleBuildValidationError(result.error, resourceType, cliConsole);
+
+    const error = new Error(
+      getErrorMessage(result.error) || "Deployment failed",
+    );
+    error.name = "DeploymentError";
+    throw error;
+  }
+
+  const capitalizedType = capitalizeResourceType(resourceType);
+  spinner.succeed(`${capitalizedType} deployment initiated!`);
+  cliConsole.success(`Build ID: ${result.buildId}`);
+  cliConsole.info(`Status: ${result.status}`);
+}
+
+/**
+ * Capitalize resource type for display purposes
+ */
+function capitalizeResourceType(resourceType: ResourceType): string {
+  return resourceType.charAt(0).toUpperCase() + resourceType.slice(1);
+}

package/src/utils/errors.ts

@@ -1,15 +1,45 @@
 import type { ZodError } from "zod";
 import type { ErrorContext } from "../types";
 
+/**
+ * Recovery action that can be suggested to users when an error occurs
+ * @interface RecoveryAction
+ * @property {string} description - Human-readable description of the recovery action
+ * @property {string} [command] - Optional CLI command that can help resolve the issue
+ */
 export interface RecoveryAction {
   description: string;
   command?: string;
 }
 
+/**
+ * Base error class for all Ollie Shop CLI errors
+ * Provides context and recovery suggestions to help users resolve issues
+ *
+ * @class OllieShopCLIError
+ * @extends {Error}
+ * @example
+ * ```typescript
+ * throw new OllieShopCLIError(
+ *   "Component build failed",
+ *   { componentId: "123", path: "./src" },
+ *   [
+ *     { description: "Check your TypeScript configuration" },
+ *     { description: "Run validation", command: "ollieshop component validate" }
+ *   ]
+ * );
+ * ```
+ */
 export class OllieShopCLIError extends Error {
   public readonly context: ErrorContext;
   public readonly recoveryActions: RecoveryAction[];
 
+  /**
+   * Creates a new OllieShopCLIError instance
+   * @param {string} message - The error message
+   * @param {ErrorContext} [context={}] - Additional context about the error
+   * @param {RecoveryAction[]} [recoveryActions=[]] - Suggested actions to resolve the error
+   */
   constructor(
     message: string,
     context: ErrorContext = {},
@@ -21,14 +51,41 @@ export class OllieShopCLIError extends Error {
     this.recoveryActions = recoveryActions;
   }
 
+  /**
+   * Get the error context details
+   * @returns {ErrorContext} The error context object
+   */
   get details(): ErrorContext {
     return this.context;
   }
 
+  /**
+   * Get suggested recovery actions
+   * @returns {RecoveryAction[]} Array of recovery actions
+   */
   get suggestions(): RecoveryAction[] {
     return this.recoveryActions;
   }
 
+  /**
+   * Create an OllieShopCLIError from a Zod validation error
+   * Extracts the most relevant error message and provides validation-specific suggestions
+   *
+   * @static
+   * @param {ZodError} error - The Zod validation error
+   * @param {ErrorContext} [context={}] - Additional context to include
+   * @returns {OllieShopCLIError} A new OllieShopCLIError instance
+   * @example
+   * ```typescript
+   * try {
+   *   ComponentNameSchema.parse("Invalid Name!");
+   * } catch (error) {
+   *   if (error instanceof ZodError) {
+   *     throw OllieShopCLIError.fromZodError(error, { field: "name" });
+   *   }
+   * }
+   * ```
+   */
   static fromZodError(
     error: ZodError,
     context: ErrorContext = {},
@@ -48,6 +105,23 @@ export class OllieShopCLIError extends Error {
     ]);
   }
 
+  /**
+   * Create an OllieShopCLIError from an unknown error type
+   * Safely handles any error type and converts it to OllieShopCLIError
+   *
+   * @static
+   * @param {unknown} error - Any error or value
+   * @param {ErrorContext} [context={}] - Additional context to include
+   * @returns {OllieShopCLIError} A new OllieShopCLIError instance
+   * @example
+   * ```typescript
+   * try {
+   *   // some operation
+   * } catch (error) {
+   *   throw OllieShopCLIError.fromUnknown(error, { operation: "deploy" });
+   * }
+   * ```
+   */
   static fromUnknown(
     error: unknown,
     context: ErrorContext = {},
@@ -68,6 +142,20 @@ export class OllieShopCLIError extends Error {
     );
   }
 
+  /**
+   * Create a file not found error with helpful suggestions
+   *
+   * @static
+   * @param {string} path - The file path that was not found
+   * @param {ErrorContext} [context={}] - Additional context to include
+   * @returns {OllieShopCLIError} A new OllieShopCLIError instance with file-specific suggestions
+   * @example
+   * ```typescript
+   * if (!fs.existsSync(configPath)) {
+   *   throw OllieShopCLIError.fileNotFound(configPath, { operation: "load-config" });
+   * }
+   * ```
+   */
   static fileNotFound(
     path: string,
     context: ErrorContext = {},
@@ -86,11 +174,29 @@ export class OllieShopCLIError extends Error {
 export const CLIError = OllieShopCLIError;
 
 /**
- * Command execution error
+ * Error thrown when a CLI command execution fails
+ * Includes an error code for programmatic error handling
+ *
+ * @class CommandError
+ * @extends {OllieShopCLIError}
+ * @example
+ * ```typescript
+ * throw new CommandError(
+ *   "Failed to connect to builder service",
+ *   "BUILDER_CONNECTION_ERROR",
+ *   { url: builderUrl, timeout: 5000 }
+ * );
+ * ```
  */
 export class CommandError extends OllieShopCLIError {
   public readonly code: string;
 
+  /**
+   * Creates a new CommandError instance
+   * @param {string} message - The error message
+   * @param {string} code - A unique error code for this type of error
+   * @param {ErrorContext} [context={}] - Additional context about the error
+   */
   constructor(message: string, code: string, context: ErrorContext = {}) {
     super(message, context);
     this.name = "CommandError";
@@ -99,11 +205,32 @@ export class CommandError extends OllieShopCLIError {
 }
 
 /**
- * Validation error with detailed field information
+ * Error thrown when validation fails with detailed field-level information
+ * Useful for form validation and input checking scenarios
+ *
+ * @class ValidationError
+ * @extends {OllieShopCLIError}
+ * @example
+ * ```typescript
+ * throw new ValidationError(
+ *   "Component configuration is invalid",
+ *   [
+ *     { field: "name", message: "Must be lowercase with hyphens" },
+ *     { field: "slot", message: "Invalid slot type" }
+ *   ],
+ *   { componentPath: "./src/components/header" }
+ * );
+ * ```
  */
 export class ValidationError extends OllieShopCLIError {
   public readonly fields: Array<{ field: string; message: string }>;
 
+  /**
+   * Creates a new ValidationError instance
+   * @param {string} message - The overall error message
+   * @param {Array<{field: string; message: string}>} [fields=[]] - Field-specific validation errors
+   * @param {ErrorContext} [context={}] - Additional context about the error
+   */
   constructor(
     message: string,
     fields: Array<{ field: string; message: string }> = [],
@@ -114,6 +241,10 @@ export class ValidationError extends OllieShopCLIError {
     this.fields = fields;
   }
 
+  /**
+   * Get error details including field-level errors
+   * @returns {ErrorContext & {fields: Array<{field: string; message: string}>}} Combined context and field errors
+   */
   get details(): ErrorContext & {
     fields: Array<{ field: string; message: string }>;
   } {

package/src/utils/interactive-builder.ts

@@ -5,11 +5,40 @@ import type { ComponentDeployOptions } from "../schemas/command.schema";
 import type { InteractiveChoice, MockComponent } from "../types";
 import type { CliConsole } from "./console.js";
 
+/**
+ * Interactive command builder for creating CLI commands through prompts
+ * Provides a wizard-like interface for complex commands
+ *
+ * @class InteractiveCommandBuilder
+ * @example
+ * ```typescript
+ * const builder = new InteractiveCommandBuilder(console);
+ * await builder.buildDeployComponentCommand();
+ * // User is guided through deployment options
+ * ```
+ */
 export class InteractiveCommandBuilder {
+  /**
+   * Creates a new InteractiveCommandBuilder instance
+   * @param {CliConsole} console - Console instance for I/O operations
+   */
   constructor(private console: CliConsole) {}
 
   /**
    * Build component deploy command interactively
+   * Guides user through selecting a component and deployment options
+   *
+   * @async
+   * @throws {Error} If user cancels the wizard
+   * @example
+   * ```typescript
+   * await builder.buildDeployComponentCommand();
+   * // Shows:
+   * // - List of available components
+   * // - Deployment options checkboxes
+   * // - Command preview
+   * // - Execution confirmation
+   * ```
    */
   async buildDeployComponentCommand(): Promise<void> {
     this.console.log(chalk.blue.bold("\n🚀 Component Deployment Wizard\n"));
@@ -37,7 +66,6 @@ export class InteractiveCommandBuilder {
           name: "options",
           message: "Deployment options:",
           choices: [
-            { name: "Wait for completion", value: "wait", checked: true },
             { name: "Run tests before deploy", value: "test", checked: true },
             {
               name: "Enable verbose logging",
@@ -51,10 +79,6 @@ export class InteractiveCommandBuilder {
       // Build the command
       let command = `ollieshop component deploy --id ${answers.component}`;
 
-      if (answers.options.includes("wait")) {
-        command += " --wait";
-      }
-
       if (answers.options.includes("verbose")) {
         command += " --verbose";
       }
@@ -82,7 +106,6 @@ export class InteractiveCommandBuilder {
         const deployOptions: ComponentDeployOptions = {
           componentId: answers.component,
           path: process.cwd(),
-          wait: answers.options.includes("wait"),
         };
         await deployComponent(deployOptions, this.console);
       } else {
@@ -99,6 +122,19 @@ export class InteractiveCommandBuilder {
 
   /**
    * Build component create command interactively
+   * Guides user through component creation options with live validation
+   *
+   * @async
+   * @throws {Error} If user cancels the wizard
+   * @example
+   * ```typescript
+   * await builder.buildCreateComponentCommand();
+   * // Prompts for:
+   * // - Component name (with live validation)
+   * // - Component slot selection
+   * // - Language preference (TypeScript/JavaScript)
+   * // - Test file inclusion
+   * ```
    */
   async buildCreateComponentCommand(): Promise<void> {
     this.console.log(chalk.blue.bold("\n🎨 Component Creation Wizard\n"));
@@ -209,6 +245,11 @@ export class InteractiveCommandBuilder {
 
   /**
    * Get available components (mock for now)
+   * TODO: Replace with actual API call to list components
+   *
+   * @private
+   * @async
+   * @returns {Promise<MockComponent[]>} Array of mock component data
    */
   private async getAvailableComponents(): Promise<MockComponent[]> {
     // TODO: Replace with actual API call
@@ -248,7 +289,20 @@ export class InteractiveCommandBuilder {
 }
 
 /**
- * Create an interactive command builder
+ * Run an interactive command builder for the specified command
+ * Creates a wizard-like interface based on the command type
+ *
+ * @async
+ * @param {string} command - The command type to run interactively
+ * @param {CliConsole} console - Console instance for I/O
+ * @example
+ * ```typescript
+ * // Run deployment wizard
+ * await runInteractiveCommand("deploy", console);
+ *
+ * // Run component creation wizard
+ * await runInteractiveCommand("create", console);
+ * ```
  */
 export async function runInteractiveCommand(
   command: string,