@ollie-shop/cli 0.3.0 → 0.3.3

package/src/schemas/command.schema.ts

@@ -16,21 +16,55 @@ export { ComponentNameSchema, FunctionNameSchema };
 /**
  * CLI-specific schemas (only for CLI-specific concerns)
  */
+
+/**
+ * Schema for file system paths
+ * @example "./src/components/header"
+ * @example "/absolute/path/to/component"
+ */
 export const PathSchema = z.string().min(1, "Path cannot be empty");
 
+/**
+ * Schema for store identifiers
+ * Must be a valid UUID v4 format
+ * @example "123e4567-e89b-12d3-a456-426614174000"
+ */
 export const StoreIdSchema = z.string().uuid("Invalid store ID format");
 
+/**
+ * Schema for version names
+ * @example "Production v2.0"
+ * @example "Holiday Sale Version"
+ * @minLength 1
+ * @maxLength 100
+ */
 export const VersionNameSchema = z
   .string()
   .min(1, "Version name is required")
   .max(100, "Version name is too long (max 100 characters)");
 
+/**
+ * Schema for function execution priority
+ * Higher numbers execute first
+ * @minimum 0
+ * @maximum 100
+ * @example 50 - Default priority
+ * @example 90 - High priority (executes early)
+ * @example 10 - Low priority (executes late)
+ */
 export const PrioritySchema = z
   .number()
   .int("Priority must be a whole number")
   .min(0, "Priority must be between 0 and 100")
   .max(100, "Priority must be between 0 and 100");
 
+/**
+ * Schema for URLs and URL patterns
+ * Supports both full URLs and path patterns
+ * @example "https://api.example.com/webhook"
+ * @example "/api/cart/*"
+ * @example "/*" - Matches all paths
+ */
 export const UrlSchema = z
   .string()
   .min(1, "URL is required")
@@ -48,6 +82,13 @@ export const UrlSchema = z
     }
   }, "URL must be a valid URL or path pattern");
 
+/**
+ * Schema for semantic version numbers
+ * @pattern ^\d+\.\d+\.\d+$
+ * @example "1.0.0"
+ * @example "2.4.6"
+ * @see https://semver.org/
+ */
 export const SemverSchema = z
   .string()
   .regex(
@@ -58,6 +99,19 @@ export const SemverSchema = z
 /**
  * Component command schemas
  */
+
+/**
+ * Options for creating a new component
+ * @property {string} [name] - Component name in kebab-case (e.g., "header-banner")
+ * @property {"header"|"main"|"footer"|"sidebar"} [slot="main"] - Where the component renders in the checkout
+ * @property {boolean} [tests=true] - Whether to generate test files
+ * @property {string} [template] - Custom template to use for generation
+ * @property {boolean} [interactive] - Use interactive mode with prompts
+ * @example
+ * // CLI usage:
+ * ollieshop component create --name header-banner --slot header
+ * ollieshop component create --interactive
+ */
 export const ComponentCreateOptionsSchema = z
   .object({
     name: ComponentNameSchema.optional(), // Optional for interactive mode
@@ -71,6 +125,18 @@ export const ComponentCreateOptionsSchema = z
     path: ["name"],
   });
 
+/**
+ * Options for building a component
+ * @property {string} [path] - Path to component directory (defaults to current directory)
+ * @property {boolean} [watch=false] - Watch for file changes and rebuild automatically
+ * @property {boolean} [minify=true] - Minify the output bundle
+ * @property {boolean} [sourcemap=true] - Generate source maps for debugging
+ * @example
+ * // CLI usage:
+ * ollieshop component build
+ * ollieshop component build --watch
+ * ollieshop component build --path ./components/header --no-minify
+ */
 export const ComponentBuildOptionsSchema = z.object({
   path: PathSchema.optional(),
   watch: z.boolean().optional(),
@@ -78,22 +144,57 @@ export const ComponentBuildOptionsSchema = z.object({
   sourcemap: z.boolean().optional(),
 });
 
+/**
+ * Options for validating a component
+ * @property {string} [path] - Path to component directory (defaults to current directory)
+ * @property {boolean} [strict=false] - Enable strict validation mode with additional checks
+ * @property {boolean} [fix=false] - Automatically fix fixable validation issues
+ * @example
+ * // CLI usage:
+ * ollieshop component validate
+ * ollieshop component validate --strict
+ * ollieshop component validate --fix
+ */
 export const ComponentValidateOptionsSchema = z.object({
   path: PathSchema.optional(),
   strict: z.boolean().optional(),
   fix: z.boolean().optional(),
 });
 
+/**
+ * Options for deploying a component
+ * @property {string} [path] - Path to component directory (defaults to current directory)
+ * @property {string} [componentId] - UUID of the component to deploy (internal use)
+ * @property {string} [id] - UUID of the component to deploy (CLI flag)
+ * @example
+ * // CLI usage:
+ * ollieshop component deploy --id 123e4567-e89b-12d3-a456-426614174000
+ * ollieshop component deploy --id 123e4567-e89b-12d3-a456-426614174000 --path ./dist
+ */
 export const ComponentDeployOptionsSchema = z.object({
   path: PathSchema.optional(),
-  componentId: z.string().optional(),
-  id: z.string().optional(), // CLI uses --id flag
-  wait: z.boolean().optional(),
+  componentId: z.string().uuid("Invalid component ID format").optional(),
+  id: z.string().uuid("Invalid component ID format").optional(), // CLI uses --id flag
 });
 
 /**
  * Function command schemas
  */
+
+/**
+ * Options for creating a new function
+ * @property {string} name - Function name in kebab-case (e.g., "validate-cart")
+ * @property {"request"|"response"} [invocation="request"] - When the function executes in the request lifecycle
+ * @property {number} [priority=0] - Execution priority (0-100, higher executes first)
+ * @property {"throw"|"skip"} [onError="throw"] - Error handling behavior
+ * @property {boolean} [tests=true] - Whether to generate test files
+ * @property {string} [template] - Custom template to use for generation
+ * @property {string} [description] - Human-readable description of function purpose
+ * @example
+ * // CLI usage:
+ * ollieshop function create --name validate-cart --invocation request --priority 90
+ * ollieshop function create --name apply-discount --on-error skip
+ */
 export const FunctionCreateOptionsSchema = z.object({
   name: FunctionNameSchema,
   invocation: FunctionInvocationType.optional().default("request"),
@@ -104,6 +205,18 @@ export const FunctionCreateOptionsSchema = z.object({
   description: z.string().optional(),
 });
 
+/**
+ * Options for building a function
+ * @property {string} [path] - Path to function directory (defaults to current directory)
+ * @property {boolean} [watch=false] - Watch for file changes and rebuild automatically
+ * @property {boolean} [minify=true] - Minify the output bundle
+ * @property {"node16"|"node18"|"node20"} [target="node18"] - Target Node.js runtime version
+ * @example
+ * // CLI usage:
+ * ollieshop function build
+ * ollieshop function build --watch --target node20
+ * ollieshop function build --no-minify
+ */
 export const FunctionBuildOptionsSchema = z.object({
   path: PathSchema.optional(),
   watch: z.boolean().optional(),
@@ -117,6 +230,19 @@ export const FunctionValidateOptionsSchema = z.object({
   fix: z.boolean().optional(),
 });
 
+/**
+ * Options for testing a function
+ * @property {string} [path] - Path to function directory (defaults to current directory)
+ * @property {string} [payload] - JSON payload to send to the function
+ * @property {number} [timeout=30000] - Test timeout in milliseconds
+ * @property {boolean} [coverage=false] - Generate code coverage report
+ * @property {boolean} [watch=false] - Run tests in watch mode
+ * @example
+ * // CLI usage:
+ * ollieshop function test
+ * ollieshop function test --payload '{"cart": {"total": 100}}'
+ * ollieshop function test --watch --coverage
+ */
 export const FunctionTestOptionsSchema = z.object({
   path: PathSchema.optional(),
   payload: z.string().optional(),
@@ -125,16 +251,42 @@ export const FunctionTestOptionsSchema = z.object({
   watch: z.boolean().optional(),
 });
 
+/**
+ * Options for deploying a function
+ * @property {string} [path] - Path to function directory (defaults to current directory)
+ * @property {string} [functionId] - UUID of the function to deploy (internal use)
+ * @property {string} [id] - UUID of the function to deploy (CLI flag)
+ * @example
+ * // CLI usage:
+ * ollieshop function deploy --id 123e4567-e89b-12d3-a456-426614174000
+ * ollieshop function deploy --id 123e4567-e89b-12d3-a456-426614174000 --path ./dist
+ */
 export const FunctionDeployOptionsSchema = z.object({
   path: PathSchema.optional(),
-  functionId: z.string().optional(),
-  id: z.string().optional(), // CLI uses --id flag
-  wait: z.boolean().optional(),
+  functionId: z.string().uuid("Invalid function ID format").optional(),
+  id: z.string().uuid("Invalid function ID format").optional(), // CLI uses --id flag
 });
 
 /**
  * Development server schemas
  */
+
+/**
+ * Options for running a development server
+ * @property {number} [port=3000] - Port number to run the server on (1000-65535)
+ * @property {string} [host="localhost"] - Host to bind the server to
+ * @property {boolean} [open=true] - Open browser automatically when server starts
+ * @property {string} [component] - Path to specific component to develop
+ * @property {string} [function] - Path to specific function to develop
+ * @property {string} [mockData] - Path to mock data file for testing
+ * @property {boolean} [hot=true] - Enable hot module replacement
+ * @property {boolean} [https=false] - Enable HTTPS with self-signed certificate
+ * @example
+ * // CLI usage:
+ * ollieshop dev
+ * ollieshop dev --port 8080 --no-open
+ * ollieshop dev --component ./components/header --hot
+ */
 export const DevServerOptionsSchema = z.object({
   port: z.number().min(1000).max(65535).default(3000),
   host: z.string().default("localhost"),
@@ -149,6 +301,20 @@ export const DevServerOptionsSchema = z.object({
 /**
  * Global CLI options schemas
  */
+
+/**
+ * Global options available for all CLI commands
+ * @property {boolean} [verbose=false] - Show detailed output and debug information
+ * @property {boolean} [quiet=false] - Suppress all output except errors
+ * @property {boolean} [color=true] - Enable colored output (use --no-color to disable)
+ * @property {string} [config] - Path to custom configuration file
+ * @property {"error"|"warn"|"info"|"debug"} [logLevel="info"] - Minimum log level to display
+ * @example
+ * // CLI usage:
+ * ollieshop --verbose component create --name header
+ * ollieshop --quiet function deploy --id abc-123
+ * ollieshop --no-color --log-level debug component build
+ */
 export const GlobalOptionsSchema = z.object({
   verbose: z.boolean().default(false),
   quiet: z.boolean().default(false),
@@ -160,6 +326,21 @@ export const GlobalOptionsSchema = z.object({
 /**
  * Build command schemas
  */
+
+/**
+ * Options for building projects, components, or functions
+ * @property {string} [path] - Path to build (defaults to current directory)
+ * @property {string} [output] - Output directory for build artifacts
+ * @property {boolean} [minify=true] - Minify the output
+ * @property {boolean} [sourcemap=true] - Generate source maps
+ * @property {boolean} [watch=false] - Watch mode for continuous builds
+ * @property {boolean} [clean=true] - Clean output directory before building
+ * @example
+ * // CLI usage:
+ * ollieshop build
+ * ollieshop build --output ./dist --no-minify
+ * ollieshop build --watch --no-clean
+ */
 export const BuildOptionsSchema = z.object({
   path: PathSchema.optional(),
   output: PathSchema.optional(),
@@ -172,6 +353,18 @@ export const BuildOptionsSchema = z.object({
 /**
  * Login/Auth schemas
  */
+
+/**
+ * Options for CLI authentication
+ * @property {string} [token] - Authentication token (if not using interactive login)
+ * @property {boolean} [interactive=true] - Use interactive browser-based login
+ * @property {boolean} [save=true] - Save credentials for future use
+ * @example
+ * // CLI usage:
+ * ollieshop login
+ * ollieshop login --token abc123
+ * ollieshop login --no-save
+ */
 export const LoginOptionsSchema = z.object({
   token: z.string().optional(),
   interactive: z.boolean().default(true),
@@ -181,6 +374,20 @@ export const LoginOptionsSchema = z.object({
 /**
  * Init project schemas
  */
+
+/**
+ * Options for initializing a new Ollie Shop project
+ * @property {string} [name="my-ollie-shop"] - Project name
+ * @property {"default"|"grocery"|"sales"} [template="default"] - Checkout template to use
+ * @property {boolean} [git=true] - Initialize git repository
+ * @property {boolean} [install=true] - Install dependencies automatically
+ * @property {string} [path] - Where to create the project (defaults to project name)
+ * @example
+ * // CLI usage:
+ * ollieshop init --name my-checkout
+ * ollieshop init --template grocery --no-install
+ * ollieshop init --name holiday-sale --path ./projects/holiday
+ */
 export const InitOptionsSchema = z.object({
   name: z.string().optional(),
   template: Template.optional().default("default"),
@@ -192,6 +399,18 @@ export const InitOptionsSchema = z.object({
 /**
  * Store version command schemas
  */
+
+/**
+ * Options for creating a store version
+ * @property {string} store - UUID of the store
+ * @property {string} name - Version name (1-100 characters)
+ * @property {"default"|"grocery"|"sales"} [template] - Checkout template
+ * @property {boolean} [active=true] - Whether version is active immediately
+ * @example
+ * // CLI usage:
+ * ollieshop version create --store 123e4567-e89b-12d3-a456-426614174000 --name "Black Friday"
+ * ollieshop version create --store abc-123 --name "Test" --template grocery --no-active
+ */
 export const StoreVersionCreateOptionsSchema = z.object({
   store: StoreIdSchema,
   name: VersionNameSchema,
@@ -291,6 +510,77 @@ export function validateSemver(version: string): boolean {
   return SemverSchema.safeParse(version).success;
 }
 
+export function validateUUID(id: string): boolean {
+  const uuidSchema = z.string().uuid();
+  return uuidSchema.safeParse(id).success;
+}
+
+/**
+ * Environment variable validation schemas and helpers
+ */
+export const BuilderApiUrlSchema = z
+  .string()
+  .url("BUILDER_API_URL must be a valid URL")
+  .refine(
+    (url) => {
+      try {
+        const parsed = new URL(url);
+        return ["http:", "https:"].includes(parsed.protocol);
+      } catch {
+        return false;
+      }
+    },
+    {
+      message: "BUILDER_API_URL must use http or https protocol",
+    },
+  );
+
+export const EnvironmentVariablesSchema = z.object({
+  BUILDER_API_URL: BuilderApiUrlSchema.optional(),
+  DEBUG: z.string().optional(),
+  NODE_ENV: z.enum(["development", "test", "production"]).optional(),
+});
+
+/**
+ * Validates all CLI environment variables
+ * @returns {Object} Validation result with success flag and optional errors
+ * @returns {boolean} result.success - True if all env vars are valid
+ * @returns {string[]} [result.errors] - Array of validation error messages
+ * @example
+ * const result = validateEnvironmentVariables();
+ * if (!result.success) {
+ *   console.error("Invalid environment:", result.errors);
+ * }
+ */
+export function validateEnvironmentVariables(): {
+  success: boolean;
+  errors?: string[];
+} {
+  const envVars = {
+    BUILDER_API_URL: process.env.BUILDER_API_URL,
+    DEBUG: process.env.DEBUG,
+    NODE_ENV: process.env.NODE_ENV,
+  };
+
+  const result = EnvironmentVariablesSchema.safeParse(envVars);
+
+  if (!result.success) {
+    return {
+      success: false,
+      errors: result.error.issues.map(
+        (issue) => `${issue.path.join(".")}: ${issue.message}`,
+      ),
+    };
+  }
+
+  return { success: true };
+}
+
+export function validateBuilderApiUrl(url?: string): boolean {
+  if (!url) return true; // Optional
+  return BuilderApiUrlSchema.safeParse(url).success;
+}
+
 /**
  * CLI Data Display Schemas
  * These schemas define the structure for data displayed in CLI commands

package/src/utils/__tests__/rich-progress.test.ts

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { CliConsole } from "../console";
 import { RichProgressReporter, SimpleProgressReporter } from "../rich-progress";
 
 // Mock cli-progress
@@ -34,10 +35,20 @@ vi.mock("ora", () => ({
 
 describe("RichProgressReporter", () => {
   let reporter: RichProgressReporter;
+  let mockConsole: CliConsole;
   let consoleLogSpy: ReturnType<typeof vi.spyOn>;
 
   beforeEach(() => {
-    // Skip creating the actual reporter to avoid mocking issues
+    // Create a mock console with all required methods
+    mockConsole = {
+      info: vi.fn(),
+      success: vi.fn(),
+      error: vi.fn(),
+      warn: vi.fn(),
+      debug: vi.fn(),
+      log: vi.fn(),
+    } as unknown as CliConsole;
+
     consoleLogSpy = vi.spyOn(console, "log").mockImplementation(() => {
       // Intentionally empty for test isolation
     });
@@ -49,16 +60,16 @@ describe("RichProgressReporter", () => {
   });
 
   it("should start progress tracking", () => {
-    reporter = new RichProgressReporter();
+    reporter = new RichProgressReporter(mockConsole);
     reporter.start();
 
-    expect(consoleLogSpy).toHaveBeenCalledWith(
+    expect(mockConsole.info).toHaveBeenCalledWith(
       expect.stringContaining("🚀 Starting deployment..."),
     );
   });
 
   it("should update progress with build status", () => {
-    reporter = new RichProgressReporter();
+    reporter = new RichProgressReporter(mockConsole);
 
     const progress = {
       phase: "build",
@@ -72,21 +83,21 @@ describe("RichProgressReporter", () => {
 
   it("should show success summary", () => {
     // Test just the summary method
-    const reporter = new RichProgressReporter();
+    const reporter = new RichProgressReporter(mockConsole);
     // Access private method for testing
     const reporterWithPrivate = reporter as unknown as {
       showSuccessSummary(): void;
     };
     reporterWithPrivate.showSuccessSummary();
 
-    expect(consoleLogSpy).toHaveBeenCalledWith(
+    expect(mockConsole.success).toHaveBeenCalledWith(
       expect.stringContaining("✅ Deployment completed successfully!"),
     );
   });
 
   it("should show failure message", () => {
     // Create a minimal test that doesn't rely on bars
-    const reporter = new RichProgressReporter();
+    const reporter = new RichProgressReporter(mockConsole);
     // Access private properties for testing
     const reporterWithPrivate = reporter as unknown as {
       multibar: { stop: () => void };
@@ -97,13 +108,13 @@ describe("RichProgressReporter", () => {
 
     reporter.stop(false);
 
-    expect(consoleLogSpy).toHaveBeenCalledWith(
+    expect(mockConsole.error).toHaveBeenCalledWith(
       expect.stringContaining("❌ Deployment failed"),
     );
   });
 
   it("should display build stats when available", () => {
-    const reporter = new RichProgressReporter();
+    const reporter = new RichProgressReporter(mockConsole);
 
     // Set stats directly for testing
     const reporterWithPrivate = reporter as unknown as {
@@ -120,10 +131,10 @@ describe("RichProgressReporter", () => {
     };
     reporterWithSummary.showSuccessSummary();
 
-    expect(consoleLogSpy).toHaveBeenCalledWith(
+    expect(mockConsole.info).toHaveBeenCalledWith(
       expect.stringContaining("📊 Build Stats:"),
     );
-    expect(consoleLogSpy).toHaveBeenCalledWith(
+    expect(mockConsole.info).toHaveBeenCalledWith(
       expect.stringContaining("Bundle size: 146.5KB"),
     );
   });

package/src/utils/cli-progress-reporter.ts

@@ -37,8 +37,8 @@ export class CLIProgressReporter {
   }
 
   updateProgress(progress: BuildProgress): void {
-    const phaseDisplay = this.formatPhase(progress.currentPhase);
-    const etaFormatted = this.formatETA(progress.estimatedRemainingSeconds);
+    const phaseDisplay = this.formatPhase(progress.status);
+    const etaFormatted = this.formatETA(0); // ETA not available in BuildProgress
 
     this.bar.update(progress.percentComplete, {
       phase: phaseDisplay,

package/src/utils/command-parser.ts

@@ -200,11 +200,6 @@ export const COMMON_OPTIONS = {
     description: "Path to component or function directory",
     parser: parsePath,
   },
-  wait: {
-    flags: "-w, --wait",
-    description: "Wait for operation to complete",
-    defaultValue: false,
-  },
   storeId: {
     flags: "-s, --store <id>",
     description: "Store ID (UUID format)",

package/src/utils/console.ts

@@ -1,4 +1,5 @@
 import chalk from "chalk";
+import inquirer from "inquirer";
 import ora, { type Ora } from "ora";
 import type { OllieShopCLIError } from "./errors";
 
@@ -234,10 +235,38 @@ export class Console {
   }
 
   async confirm(message: string): Promise<boolean> {
-    // For now, return false in non-interactive mode
-    // TODO: Implement interactive confirmation
-    this.warn(`${message} (y/N)`);
-    return false;
+    // In quiet mode, default to false for non-interactive usage
+    if (this.options.quiet) {
+      return false;
+    }
+
+    // Check if we're in a TTY environment (interactive terminal)
+    if (!process.stdin.isTTY) {
+      this.warn(`${message} (y/N) - Non-interactive mode, defaulting to 'No'`);
+      return false;
+    }
+
+    try {
+      const answer = await inquirer.prompt([
+        {
+          type: "confirm",
+          name: "confirmed",
+          message,
+          default: false,
+        },
+      ]);
+
+      return answer.confirmed;
+    } catch (error) {
+      // Handle Ctrl+C or other interruptions gracefully
+      if (error && typeof error === "object" && "isTtyError" in error) {
+        this.warn("Interactive prompt not supported in this environment");
+        return false;
+      }
+
+      // For other errors, re-throw
+      throw error;
+    }
   }
 
   listResults<T>(items: T[], formatter: (item: T) => string) {

package/src/utils/constants.ts

@@ -5,3 +5,35 @@ export const META_FILE = "meta.json";
 export const CONFIG_FILE = "ollie.json";
 export const OLLIE_SHOP_ASSETS_DIR = "node_modules/.ollie-shop";
 export const TEMPLATES_DIR = "templates";
+
+// Note: Deployment URLs are dynamically generated by the infrastructure
+// Components are deployed to CloudFront (router.url from SST)
+// Functions are deployed to Lambda (managed by AWS)
+
+// Error messages with actionable guidance
+export const ERROR_MESSAGES = {
+  DEPLOYMENT_TIMEOUT:
+    "⏱️  Deployment timed out after 5 minutes. This may indicate a network issue or resource constraints.",
+  BUILD_FAILED:
+    "❌ Build failed. Check the build logs above for specific error details.",
+  BUILD_VALIDATION_FAILED:
+    "❌ Build validation failed. Ensure your code meets the required standards.",
+  UNKNOWN_ERROR:
+    "❌ An unexpected error occurred. Please try again or contact support if the issue persists.",
+  COMPONENT_ID_REQUIRED:
+    "Component ID is required for deployment. Use: ollieshop component deploy --id <component-id>",
+  FUNCTION_ID_REQUIRED:
+    "Function ID is required for deployment. Use: ollieshop function deploy --id <function-id>",
+} as const;
+
+// Note: Build status messages are available from @ollie-shop/core
+// Use getBuildProgressMessage() from core instead of duplicating
+
+// Deployment settings
+export const DEPLOYMENT_SETTINGS = {
+  DEFAULT_POLL_INTERVAL_MS: 2000,
+  DEFAULT_MAX_WAIT_MS: 300000, // 5 minutes
+  PROGRESS_UPDATE_INTERVAL_MS: 1000,
+  ESTIMATED_BUILD_DURATION_MS: 30000, // 30 seconds
+  MAX_PROGRESS_BEFORE_COMPLETION: 0.95,
+} as const;