shakapacker 8.4.0 → 9.0.0

data/package/types/README.md

@@ -0,0 +1,87 @@
+# Shakapacker TypeScript Types
+
+This directory exports all TypeScript types used in Shakapacker for easier consumer imports.
+
+## Usage
+
+Instead of importing types from deep paths:
+
+```typescript
+// ❌ Old way - importing from multiple deep paths
+import type { Config } from 'shakapacker/package/types'
+import type { WebpackConfigWithDevServer } from 'shakapacker/package/environments/types'
+```
+
+You can now import all types from a single location:
+
+```typescript
+// ✅ New way - single import path
+import type {
+  Config,
+  WebpackConfigWithDevServer,
+  RspackConfigWithDevServer
+} from 'shakapacker/types'
+```
+
+## Available Types
+
+### Core Configuration Types
+- `Config` - Main Shakapacker configuration interface
+- `YamlConfig` - YAML configuration structure
+- `LegacyConfig` - Legacy configuration with deprecated options
+- `Env` - Environment variables interface
+- `DevServerConfig` - Development server configuration
+
+### Loader Types
+- `ShakapackerLoader` - Loader interface
+- `ShakapackerLoaderOptions` - Loader options interface
+- `LoaderResolver` - Function type for resolving loaders
+- `LoaderConfig` - Loader configuration interface
+
+### Webpack/Rspack Types
+- `WebpackConfigWithDevServer` - Webpack config with dev server
+- `RspackConfigWithDevServer` - Rspack config with dev server
+- `RspackPlugin` - Rspack plugin interface
+- `RspackDevServerConfig` - Rspack dev server configuration
+- `CompressionPluginOptions` - Options for compression plugin
+- `CompressionPluginConstructor` - Constructor type for compression plugin
+- `ReactRefreshWebpackPlugin` - React refresh plugin for Webpack
+- `ReactRefreshRspackPlugin` - React refresh plugin for Rspack
+
+### Webpack-Specific Types
+- `ShakapackerWebpackConfig` - Extended Webpack configuration
+- `ShakapackerRule` - Extended Webpack rule
+- `LoaderType` - String or loader object type
+- `LoaderUtils` - Loader utility functions
+
+### Re-exported Types
+- `WebpackConfiguration` - From 'webpack'
+- `WebpackPluginInstance` - From 'webpack'
+- `RuleSetRule` - From 'webpack'
+- `NodeJSError` - Node.js error exception type
+
+## Example Usage
+
+```typescript
+import type {
+  Config,
+  WebpackConfigWithDevServer
+} from 'shakapacker/types'
+
+const config: Config = {
+  source_path: 'app/javascript',
+  source_entry_path: 'packs',
+  public_root_path: 'public',
+  public_output_path: 'packs',
+  // ... other config
+}
+
+const webpackConfig: WebpackConfigWithDevServer = {
+  mode: 'development',
+  devServer: {
+    hot: true,
+    port: 3035
+  }
+  // ... other webpack config
+}
+```

data/package/types/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Central type exports for Shakapacker
+ * This file re-exports all public TypeScript types for easier consumer imports
+ *
+ * @example
+ * ```typescript
+ * import type { Config, WebpackConfigWithDevServer } from 'shakapacker/types'
+ * ```
+ *
+ * @module shakapacker/types
+ */
+
+// Core configuration types
+export type {
+  Config,
+  YamlConfig,
+  LegacyConfig,
+  Env,
+  DevServerConfig
+} from '../types'
+
+// Loader types
+export type {
+  ShakapackerLoader,
+  ShakapackerLoaderOptions,
+  LoaderResolver,
+  LoaderConfig
+} from '../loaders'
+
+// Webpack-specific types
+export type {
+  ShakapackerWebpackConfig,
+  ShakapackerRule,
+  ShakapackerLoaderOptions as WebpackLoaderOptions,
+  ShakapackerLoader as WebpackLoader,
+  LoaderType,
+  LoaderUtils
+} from '../webpack-types'
+
+// Environment configuration types
+export type {
+  WebpackConfigWithDevServer,
+  RspackPlugin,
+  RspackDevServerConfig,
+  RspackConfigWithDevServer,
+  CompressionPluginOptions,
+  CompressionPluginConstructor,
+  ReactRefreshWebpackPlugin,
+  ReactRefreshRspackPlugin
+} from '../environments/types'
+
+// Node.js error type (re-exported for convenience)
+export type NodeJSError = NodeJS.ErrnoException
+
+// Re-export commonly used webpack types for convenience
+export type {
+  Configuration as WebpackConfiguration,
+  WebpackPluginInstance,
+  RuleSetRule
+} from 'webpack'

data/package/types.ts

@@ -0,0 +1,108 @@
+import * as https from "node:https"
+
+// Type for the raw YAML config file
+export interface YamlConfig {
+  [environment: string]: Partial<Config>
+}
+
+// Type for backward compatibility
+export interface LegacyConfig extends Config {
+  webpack_loader?: string
+}
+
+export interface Config {
+  source_path: string
+  source_entry_path: string
+  nested_entries: boolean
+  css_extract_ignore_order_warnings: boolean
+  public_root_path: string
+  public_output_path: string
+  private_output_path?: string
+  cache_path: string
+  webpack_compile_output: boolean
+  shakapacker_precompile: boolean
+  additional_paths: string[]
+  cache_manifest: boolean
+  javascript_transpiler: string
+  ensure_consistent_versioning: boolean
+  compiler_strategy: string
+  useContentHash: boolean
+  compile: boolean
+  outputPath: string
+  publicPath: string
+  publicPathWithoutCDN: string
+  manifestPath: string
+  manifest_path?: string
+  assets_bundler?: string
+  dev_server?: DevServerConfig
+  integrity?: {
+    enabled: boolean
+    cross_origin: string
+    hash_functions?: string[]
+  }
+}
+
+export interface Env {
+  railsEnv: string
+  nodeEnv: string
+  isProduction: boolean
+  isDevelopment: boolean
+  runningWebpackDevServer: boolean
+}
+
+type Header =
+  | Array<{ key: string; value: string }>
+  | Record<string, string | string[]>
+type ServerType = "http" | "https" | "spdy"
+type WebSocketType = "sockjs" | "ws"
+
+/**
+ * This has the same keys and behavior as https://webpack.js.org/configuration/dev-server/ except:
+ * 1. `hot` is replaced by `hmr`;
+ * 2. Camel-cased properties are replaced by snake-cased ones.
+ * @see {import('webpack-dev-server').Configuration}
+ */
+export interface DevServerConfig {
+  allowed_hosts?: "all" | "auto" | string | string[]
+  bonjour?: boolean | Record<string, unknown> // bonjour.BonjourOptions
+  client?: Record<string, unknown> // Client
+  compress?: boolean
+  dev_middleware?: Record<string, unknown> // webpackDevMiddleware.Options
+  headers?: Header | (() => Header)
+  history_api_fallback?: boolean | Record<string, unknown> // HistoryApiFallbackOptions
+  hmr?: "only" | boolean
+  host?: "local-ip" | "local-ipv4" | "local-ipv6" | string
+  http2?: boolean
+  https?: boolean | https.ServerOptions
+  ipc?: boolean | string
+  magic_html?: boolean
+  live_reload?: boolean
+  inline_css?: boolean
+  env_prefix?: string
+  open?:
+    | boolean
+    | string
+    | string[]
+    | Record<string, unknown>
+    | Record<string, unknown>[]
+  port?: "auto" | string | number
+  proxy?: unknown // ProxyConfigMap | ProxyConfigArray
+  setup_exit_signals?: boolean
+  static?: boolean | string | unknown // Static | Array<string | Static>
+  watch_files?: string | string[] | unknown // WatchFiles | Array<WatchFiles | string>
+  web_socket_server?:
+    | string
+    | boolean
+    | WebSocketType
+    | {
+        type?: string | boolean | WebSocketType
+        options?: Record<string, unknown>
+      }
+  server?:
+    | string
+    | boolean
+    | ServerType
+    | { type?: string | boolean | ServerType; options?: https.ServerOptions }
+  [otherWebpackDevServerConfigKey: string]: unknown
+}
+

data/package/utils/configPath.ts

@@ -0,0 +1,6 @@
+import { resolve } from "path"
+
+const configPath: string =
+  process.env.SHAKAPACKER_CONFIG || resolve("config", "shakapacker.yml")
+
+export = configPath

data/package/utils/debug.ts

@@ -0,0 +1,49 @@
+/**
+ * Debug utility for Shakapacker
+ * Provides conditional logging based on environment variables
+ */
+
+const isDebugMode = (): boolean => {
+  // Explicitly check for debug mode being disabled
+  if (process.env.SHAKAPACKER_DEBUG === "false") {
+    return false
+  }
+
+  // Support both SHAKAPACKER_DEBUG (new) and DEBUG_SHAKAPACKER (legacy) for backwards compatibility
+  return (
+    process.env.SHAKAPACKER_DEBUG === "true" ||
+    process.env.DEBUG_SHAKAPACKER === "true"
+  )
+}
+
+const debug = (message: string, ...args: any[]): void => {
+  if (isDebugMode()) {
+    // eslint-disable-next-line no-console
+    console.log(`[Shakapacker] ${message}`, ...args)
+  }
+}
+
+const warn = (message: string, ...args: any[]): void => {
+  // eslint-disable-next-line no-console
+  console.warn(`[Shakapacker] WARNING: ${message}`, ...args)
+}
+
+const error = (message: string, ...args: any[]): void => {
+  // eslint-disable-next-line no-console
+  console.error(`[Shakapacker] ERROR: ${message}`, ...args)
+}
+
+const info = (message: string, ...args: any[]): void => {
+  if (isDebugMode()) {
+    // eslint-disable-next-line no-console
+    console.info(`[Shakapacker] INFO: ${message}`, ...args)
+  }
+}
+
+export = {
+  debug,
+  warn,
+  error,
+  info,
+  isDebugMode
+}

data/package/utils/defaultConfigPath.ts

@@ -0,0 +1,4 @@
+import { resolve } from "path"
+
+const path: string = resolve(__dirname, "../../lib/install/config/shakapacker.yml")
+export = path

data/package/utils/errorCodes.ts

@@ -0,0 +1,219 @@
+/**
+ * Error codes for programmatic error handling in Shakapacker
+ * These codes allow consumers to handle specific errors programmatically
+ * @module shakapacker/utils/errorCodes
+ */
+
+/**
+ * Error code enumeration for Shakapacker errors
+ */
+export enum ErrorCode {
+  // Configuration errors (1xxx)
+  CONFIG_NOT_FOUND = 'SHAKAPACKER_1001',
+  CONFIG_INVALID_YAML = 'SHAKAPACKER_1002',
+  CONFIG_MISSING_REQUIRED = 'SHAKAPACKER_1003',
+  CONFIG_VALIDATION_FAILED = 'SHAKAPACKER_1004',
+  CONFIG_MERGE_FAILED = 'SHAKAPACKER_1005',
+  CONFIG_TYPE_MISMATCH = 'SHAKAPACKER_1006',
+
+  // File system errors (2xxx)
+  FILE_NOT_FOUND = 'SHAKAPACKER_2001',
+  FILE_READ_ERROR = 'SHAKAPACKER_2002',
+  FILE_WRITE_ERROR = 'SHAKAPACKER_2003',
+  FILE_PERMISSION_DENIED = 'SHAKAPACKER_2004',
+  PATH_TRAVERSAL_DETECTED = 'SHAKAPACKER_2005',
+  INVALID_PATH = 'SHAKAPACKER_2006',
+
+  // Module errors (3xxx)
+  MODULE_NOT_FOUND = 'SHAKAPACKER_3001',
+  MODULE_LOAD_FAILED = 'SHAKAPACKER_3002',
+  MODULE_INVALID_EXPORT = 'SHAKAPACKER_3003',
+  LOADER_NOT_FOUND = 'SHAKAPACKER_3004',
+  PLUGIN_NOT_FOUND = 'SHAKAPACKER_3005',
+  PLUGIN_INVALID = 'SHAKAPACKER_3006',
+
+  // Environment errors (4xxx)
+  ENV_INVALID_NODE_ENV = 'SHAKAPACKER_4001',
+  ENV_MISSING_REQUIRED = 'SHAKAPACKER_4002',
+  ENV_INVALID_VALUE = 'SHAKAPACKER_4003',
+  ENV_SANITIZATION_REQUIRED = 'SHAKAPACKER_4004',
+
+  // Bundler errors (5xxx)
+  BUNDLER_UNSUPPORTED = 'SHAKAPACKER_5001',
+  BUNDLER_CONFIG_INVALID = 'SHAKAPACKER_5002',
+  WEBPACK_CONFIG_INVALID = 'SHAKAPACKER_5003',
+  RSPACK_CONFIG_INVALID = 'SHAKAPACKER_5004',
+  TRANSPILER_NOT_FOUND = 'SHAKAPACKER_5005',
+  TRANSPILER_CONFIG_INVALID = 'SHAKAPACKER_5006',
+
+  // Dev server errors (6xxx)
+  DEVSERVER_CONFIG_INVALID = 'SHAKAPACKER_6001',
+  DEVSERVER_PORT_INVALID = 'SHAKAPACKER_6002',
+  DEVSERVER_PORT_IN_USE = 'SHAKAPACKER_6003',
+  DEVSERVER_START_FAILED = 'SHAKAPACKER_6004',
+
+  // Security errors (7xxx)
+  SECURITY_PATH_TRAVERSAL = 'SHAKAPACKER_7001',
+  SECURITY_INVALID_INPUT = 'SHAKAPACKER_7002',
+  SECURITY_CONTROL_CHARS = 'SHAKAPACKER_7003',
+  SECURITY_INJECTION_ATTEMPT = 'SHAKAPACKER_7004',
+
+  // Validation errors (8xxx)
+  VALIDATION_FAILED = 'SHAKAPACKER_8001',
+  VALIDATION_TYPE_ERROR = 'SHAKAPACKER_8002',
+  VALIDATION_RANGE_ERROR = 'SHAKAPACKER_8003',
+  VALIDATION_FORMAT_ERROR = 'SHAKAPACKER_8004',
+  VALIDATION_CONSTRAINT_ERROR = 'SHAKAPACKER_8005',
+
+  // Generic errors (9xxx)
+  UNKNOWN_ERROR = 'SHAKAPACKER_9000',
+  INTERNAL_ERROR = 'SHAKAPACKER_9001',
+  DEPRECATED_FEATURE = 'SHAKAPACKER_9002',
+  NOT_IMPLEMENTED = 'SHAKAPACKER_9003',
+  OPERATION_FAILED = 'SHAKAPACKER_9004'
+}
+
+/**
+ * Error message templates for each error code
+ */
+export const ErrorMessages: Record<ErrorCode, string> = {
+  // Configuration errors
+  [ErrorCode.CONFIG_NOT_FOUND]: 'Configuration file not found: {path}',
+  [ErrorCode.CONFIG_INVALID_YAML]: 'Invalid YAML in configuration file: {path}',
+  [ErrorCode.CONFIG_MISSING_REQUIRED]: 'Missing required configuration field: {field}',
+  [ErrorCode.CONFIG_VALIDATION_FAILED]: 'Configuration validation failed: {reason}',
+  [ErrorCode.CONFIG_MERGE_FAILED]: 'Failed to merge configurations: {reason}',
+  [ErrorCode.CONFIG_TYPE_MISMATCH]: 'Configuration type mismatch for {field}: expected {expected}, got {actual}',
+
+  // File system errors
+  [ErrorCode.FILE_NOT_FOUND]: 'File not found: {path}',
+  [ErrorCode.FILE_READ_ERROR]: 'Error reading file: {path}',
+  [ErrorCode.FILE_WRITE_ERROR]: 'Error writing file: {path}',
+  [ErrorCode.FILE_PERMISSION_DENIED]: 'Permission denied accessing: {path}',
+  [ErrorCode.PATH_TRAVERSAL_DETECTED]: 'Path traversal attempt detected: {path}',
+  [ErrorCode.INVALID_PATH]: 'Invalid path: {path}',
+
+  // Module errors
+  [ErrorCode.MODULE_NOT_FOUND]: 'Module not found: {module}',
+  [ErrorCode.MODULE_LOAD_FAILED]: 'Failed to load module: {module}',
+  [ErrorCode.MODULE_INVALID_EXPORT]: 'Invalid export from module: {module}',
+  [ErrorCode.LOADER_NOT_FOUND]: 'Loader not found: {loader}',
+  [ErrorCode.PLUGIN_NOT_FOUND]: 'Plugin not found: {plugin}',
+  [ErrorCode.PLUGIN_INVALID]: 'Invalid plugin: {plugin}',
+
+  // Environment errors
+  [ErrorCode.ENV_INVALID_NODE_ENV]: 'Invalid NODE_ENV value: {value}. Valid values are: {valid}',
+  [ErrorCode.ENV_MISSING_REQUIRED]: 'Missing required environment variable: {variable}',
+  [ErrorCode.ENV_INVALID_VALUE]: 'Invalid value for environment variable {variable}: {value}',
+  [ErrorCode.ENV_SANITIZATION_REQUIRED]: 'Environment variable {variable} contained unsafe characters and was sanitized',
+
+  // Bundler errors
+  [ErrorCode.BUNDLER_UNSUPPORTED]: 'Unsupported bundler: {bundler}',
+  [ErrorCode.BUNDLER_CONFIG_INVALID]: 'Invalid bundler configuration: {reason}',
+  [ErrorCode.WEBPACK_CONFIG_INVALID]: 'Invalid webpack configuration: {reason}',
+  [ErrorCode.RSPACK_CONFIG_INVALID]: 'Invalid rspack configuration: {reason}',
+  [ErrorCode.TRANSPILER_NOT_FOUND]: 'Transpiler not found: {transpiler}',
+  [ErrorCode.TRANSPILER_CONFIG_INVALID]: 'Invalid transpiler configuration: {reason}',
+
+  // Dev server errors
+  [ErrorCode.DEVSERVER_CONFIG_INVALID]: 'Invalid dev server configuration: {reason}',
+  [ErrorCode.DEVSERVER_PORT_INVALID]: 'Invalid port: {port}',
+  [ErrorCode.DEVSERVER_PORT_IN_USE]: 'Port {port} is already in use',
+  [ErrorCode.DEVSERVER_START_FAILED]: 'Failed to start dev server: {reason}',
+
+  // Security errors
+  [ErrorCode.SECURITY_PATH_TRAVERSAL]: 'Security: Path traversal attempt blocked: {path}',
+  [ErrorCode.SECURITY_INVALID_INPUT]: 'Security: Invalid input detected: {input}',
+  [ErrorCode.SECURITY_CONTROL_CHARS]: 'Security: Control characters detected and removed from: {field}',
+  [ErrorCode.SECURITY_INJECTION_ATTEMPT]: 'Security: Potential injection attempt blocked: {details}',
+
+  // Validation errors
+  [ErrorCode.VALIDATION_FAILED]: 'Validation failed: {reason}',
+  [ErrorCode.VALIDATION_TYPE_ERROR]: 'Type validation error: {field} should be {type}',
+  [ErrorCode.VALIDATION_RANGE_ERROR]: 'Value out of range: {field} must be between {min} and {max}',
+  [ErrorCode.VALIDATION_FORMAT_ERROR]: 'Format error: {field} does not match expected format',
+  [ErrorCode.VALIDATION_CONSTRAINT_ERROR]: 'Constraint violation: {constraint}',
+
+  // Generic errors
+  [ErrorCode.UNKNOWN_ERROR]: 'An unknown error occurred',
+  [ErrorCode.INTERNAL_ERROR]: 'Internal error: {details}',
+  [ErrorCode.DEPRECATED_FEATURE]: 'Deprecated feature: {feature}. Use {alternative} instead',
+  [ErrorCode.NOT_IMPLEMENTED]: 'Feature not yet implemented: {feature}',
+  [ErrorCode.OPERATION_FAILED]: 'Operation failed: {operation}'
+}
+
+/**
+ * Shakapacker error class with error code support
+ */
+export class ShakapackerError extends Error {
+  public readonly code: ErrorCode
+  public readonly details?: Record<string, any>
+
+  constructor(code: ErrorCode, details?: Record<string, any>, customMessage?: string) {
+    const template = ErrorMessages[code] || 'An error occurred'
+    const message = customMessage || ShakapackerError.formatMessage(template, details)
+
+    super(message)
+    this.name = 'ShakapackerError'
+    this.code = code
+    this.details = details
+
+    // Maintain proper stack trace for where error was thrown
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ShakapackerError)
+    }
+  }
+
+  /**
+   * Format error message with template values
+   */
+  private static formatMessage(template: string, details?: Record<string, any>): string {
+    if (!details) return template
+
+    return template.replace(/{(\w+)}/g, (match, key) => {
+      const value = details[key]
+      if (value === undefined) return match
+      if (typeof value === 'object') {
+        return JSON.stringify(value)
+      }
+      return String(value)
+    })
+  }
+
+  /**
+   * Convert error to JSON for logging or API responses
+   */
+  toJSON(): Record<string, any> {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      details: this.details,
+      stack: this.stack
+    }
+  }
+}
+
+/**
+ * Helper function to create a Shakapacker error
+ */
+export function createError(code: ErrorCode, details?: Record<string, any>): ShakapackerError {
+  return new ShakapackerError(code, details)
+}
+
+/**
+ * Helper function to check if an error is a Shakapacker error
+ */
+export function isShakapackerError(error: unknown): error is ShakapackerError {
+  return error instanceof ShakapackerError
+}
+
+/**
+ * Helper function to get error code from any error
+ */
+export function getErrorCode(error: unknown): ErrorCode | null {
+  if (isShakapackerError(error)) {
+    return error.code
+  }
+  return null
+}

data/package/utils/errorHelpers.ts

@@ -0,0 +1,143 @@
+/**
+ * Error handling utilities for consistent error management
+ */
+
+import { ErrorCode, ShakapackerError } from './errorCodes'
+
+/**
+ * Checks if an error is a file not found error (ENOENT)
+ */
+export function isFileNotFoundError(error: unknown): boolean {
+  return (
+    error !== null &&
+    typeof error === 'object' &&
+    'code' in error &&
+    (error as NodeJS.ErrnoException).code === 'ENOENT'
+  )
+}
+
+/**
+ * Checks if an error is a module not found error
+ */
+export function isModuleNotFoundError(error: unknown): boolean {
+  return (
+    error !== null &&
+    typeof error === 'object' &&
+    'code' in error &&
+    (error as NodeJS.ErrnoException).code === 'MODULE_NOT_FOUND'
+  )
+}
+
+/**
+ * Creates a consistent error message for file operations
+ */
+export function createFileOperationError(
+  operation: 'read' | 'write' | 'delete',
+  filePath: string,
+  details?: string
+): ShakapackerError {
+  const errorCode = operation === 'read'
+    ? ErrorCode.FILE_READ_ERROR
+    : operation === 'write'
+    ? ErrorCode.FILE_WRITE_ERROR
+    : ErrorCode.FILE_NOT_FOUND
+
+  return new ShakapackerError(errorCode, {
+    path: filePath,
+    operation,
+    details
+  })
+}
+
+/**
+ * Creates a consistent error message for file operations (backward compatibility)
+ */
+export function createFileOperationErrorLegacy(
+  operation: 'read' | 'write' | 'delete',
+  filePath: string,
+  details?: string
+): Error {
+  const baseMessage = `Failed to ${operation} file at path '${filePath}'`
+  const errorDetails = details ? ` - ${details}` : ''
+  const suggestion = operation === 'read'
+    ? ' (check if file exists and permissions are correct)'
+    : operation === 'write'
+    ? ' (check write permissions and disk space)'
+    : ' (check permissions)'
+  return new Error(`${baseMessage}${errorDetails}${suggestion}`)
+}
+
+/**
+ * Safely gets error message from unknown error type
+ */
+export function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    // Include stack trace for better debugging in development
+    const isDev = process.env.NODE_ENV === 'development'
+    return isDev && error.stack ? `${error.message}\n${error.stack}` : error.message
+  }
+  if (typeof error === 'string') {
+    return error
+  }
+  if (error && typeof error === 'object' && 'message' in error) {
+    return String((error as { message: unknown }).message)
+  }
+  // Provide more context for truly unknown errors
+  return `Unknown error occurred (type: ${typeof error}, value: ${JSON.stringify(error)})`
+}
+
+/**
+ * Type guard for NodeJS errors with errno
+ */
+export function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+  return (
+    error instanceof Error &&
+    'code' in error &&
+    typeof (error as NodeJS.ErrnoException).code === 'string'
+  )
+}
+
+/**
+ * Creates a configuration validation error
+ */
+export function createConfigValidationErrorWithCode(
+  configPath: string,
+  environment: string,
+  reason: string
+): ShakapackerError {
+  return new ShakapackerError(ErrorCode.CONFIG_VALIDATION_FAILED, {
+    path: configPath,
+    environment,
+    reason
+  })
+}
+
+/**
+ * Creates a module not found error
+ */
+export function createModuleNotFoundError(moduleName: string, details?: string): ShakapackerError {
+  return new ShakapackerError(ErrorCode.MODULE_NOT_FOUND, {
+    module: moduleName,
+    details
+  })
+}
+
+/**
+ * Creates a path traversal security error
+ */
+export function createPathTraversalError(path: string): ShakapackerError {
+  return new ShakapackerError(ErrorCode.SECURITY_PATH_TRAVERSAL, {
+    path
+  })
+}
+
+/**
+ * Creates a port validation error
+ */
+export function createPortValidationError(port: unknown): ShakapackerError {
+  return new ShakapackerError(ErrorCode.DEVSERVER_PORT_INVALID, {
+    port: String(port)
+  })
+}
+
+