shakapacker 9.2.0 → 9.3.0.beta.1

data/package/configExporter/cli.ts

@@ -1,22 +1,98 @@
 // This will be a substantial file - the main CLI entry point
 // Migrating from bin/export-bundler-config but streamlined for TypeScript
 
-import { existsSync, readFileSync } from "fs"
+import { existsSync, readFileSync, writeFileSync } from "fs"
 import { resolve, dirname, sep, delimiter, basename } from "path"
 import { inspect } from "util"
 import { load as loadYaml } from "js-yaml"
+import yargs from "yargs"
 import { ExportOptions, ConfigMetadata, FileOutput } from "./types"
 import { YamlSerializer } from "./yamlSerializer"
 import { FileWriter } from "./fileWriter"
+import { ConfigFileLoader, generateSampleConfigFile } from "./configFile"
+import { BuildValidator } from "./buildValidator"
+
+// Read version from package.json
+const packageJson = JSON.parse(
+  readFileSync(resolve(__dirname, "../../package.json"), "utf8")
+)
+const VERSION = packageJson.version
+
+/**
+ * Environment variable names that can be set by build configurations
+ */
+const BUILD_ENV_VARS = [
+  "NODE_ENV",
+  "RAILS_ENV",
+  "NODE_OPTIONS",
+  "BABEL_ENV",
+  "WEBPACK_SERVE",
+  "CLIENT_BUNDLE_ONLY",
+  "SERVER_BUNDLE_ONLY"
+] as const
+
+/**
+ * Saves current values of build environment variables for later restoration
+ * @returns Object mapping variable names to their current values (or undefined)
+ */
+function saveBuildEnvironmentVariables(): Record<string, string | undefined> {
+  const saved: Record<string, string | undefined> = {}
+  BUILD_ENV_VARS.forEach((varName) => {
+    saved[varName] = process.env[varName]
+  })
+  return saved
+}
+
+/**
+ * Restores previously saved environment variable values
+ * @param saved - Object mapping variable names to their original values
+ */
+function restoreBuildEnvironmentVariables(
+  saved: Record<string, string | undefined>
+): void {
+  BUILD_ENV_VARS.forEach((varName) => {
+    const originalValue = saved[varName]
+    if (originalValue === undefined) {
+      delete process.env[varName]
+    } else {
+      process.env[varName] = originalValue
+    }
+  })
+}
+
+/**
+ * Clears all whitelisted build environment variables from process.env
+ * to prevent environment variable leakage between builds
+ */
+function clearBuildEnvironmentVariables(): void {
+  BUILD_ENV_VARS.forEach((varName) => {
+    delete process.env[varName]
+  })
+}
 
 // Main CLI entry point
 export async function run(args: string[]): Promise<number> {
   try {
     const options = parseArguments(args)
 
-    if (options.help) {
-      showHelp()
-      return 0
+    // Handle --init command
+    if (options.init) {
+      return runInitCommand(options)
+    }
+
+    // Handle --list-builds command
+    if (options.listBuilds) {
+      return runListBuildsCommand(options)
+    }
+
+    // Handle --validate or --validate-build command
+    if (options.validate || options.validateBuild) {
+      return await runValidateCommand(options)
+    }
+
+    // Handle --all-builds command
+    if (options.allBuilds) {
+      return runAllBuildsCommand(options)
     }
 
     // Set up environment
@@ -27,137 +103,547 @@ export async function run(args: string[]): Promise<number> {
     // Apply defaults
     applyDefaults(options)
 
-    // Validate options
-    validateOptions(options)
+    // Validate after defaults are applied
+    if (options.annotate && options.format !== "yaml") {
+      throw new Error(
+        "Annotation requires YAML format. Use --no-annotate or --format=yaml."
+      )
+    }
+
+    // Validate --build requires config file
+    if (options.build) {
+      const loader = new ConfigFileLoader(options.configFile)
+      if (!loader.exists()) {
+        const configPath = options.configFile || ".bundler-config.yml"
+        throw new Error(
+          `--build requires a config file but ${configPath} not found. Run --init to create it.`
+        )
+      }
+    }
 
     // Execute based on mode
     if (options.doctor) {
       await runDoctorMode(options, appRoot)
-    } else if (options.save) {
-      await runSaveMode(options, appRoot)
-    } else {
+    } else if (options.stdout) {
+      // Explicit stdout mode
       await runStdoutMode(options, appRoot)
+    } else if (options.output) {
+      // Save to single file
+      await runSingleFileMode(options, appRoot)
+    } else {
+      // Default: save to directory
+      await runSaveMode(options, appRoot)
     }
 
     return 0
-  } catch (error: any) {
-    console.error(`[Config Exporter] Error: ${error.message}`)
+  } catch (error: unknown) {
+    const errorMessage = error instanceof Error ? error.message : String(error)
+    console.error(`[Config Exporter] Error: ${errorMessage}`)
     return 1
   }
 }
 
 function parseArguments(args: string[]): ExportOptions {
-  const options: ExportOptions = {
-    bundler: undefined,
-    env: "development",
-    clientOnly: false,
-    serverOnly: false,
-    output: undefined,
-    depth: 20,
-    format: undefined,
-    help: false,
-    verbose: false,
-    doctor: false,
-    save: false,
-    saveDir: undefined,
-    annotate: undefined
-  }
+  const argv = yargs(args)
+    .version(VERSION)
+    .usage(
+      `Shakapacker Config Exporter
 
-  const parseValue = (arg: string, prefix: string): string => {
-    const value = arg.substring(prefix.length)
-    if (value.length === 0) {
-      throw new Error(`${prefix} requires a value`)
-    }
-    return value
-  }
+Exports webpack or rspack configuration in a verbose, human-readable format
+for comparison and analysis.
 
-  for (const arg of args) {
-    if (arg === "--help" || arg === "-h") {
-      options.help = true
-    } else if (arg === "--doctor") {
-      options.doctor = true
-    } else if (arg === "--save") {
-      options.save = true
-    } else if (arg.startsWith("--save-dir=")) {
-      options.saveDir = parseValue(arg, "--save-dir=")
-    } else if (arg.startsWith("--bundler=")) {
-      const bundler = parseValue(arg, "--bundler=")
-      if (bundler !== "webpack" && bundler !== "rspack") {
+QUICK START (for troubleshooting):
+  bin/export-bundler-config --doctor
+
+  Exports annotated YAML configs for both development and production.
+  Creates separate files for client and server bundles.
+  Best for debugging, AI analysis, and comparing configurations.`
+    )
+    .option("doctor", {
+      type: "boolean",
+      default: false,
+      description:
+        "Export all configs for troubleshooting (dev + prod, annotated YAML)"
+    })
+    .option("save-dir", {
+      type: "string",
+      description:
+        "Directory for output files (default: shakapacker-config-exports)"
+    })
+    .option("stdout", {
+      type: "boolean",
+      default: false,
+      description: "Output to stdout instead of saving to files"
+    })
+    .option("bundler", {
+      type: "string",
+      choices: ["webpack", "rspack"] as const,
+      description: "Specify bundler (auto-detected if not provided)"
+    })
+    .option("env", {
+      type: "string",
+      choices: ["development", "production", "test"] as const,
+      description:
+        "Node environment (default: development, ignored with --doctor or --build)"
+    })
+    .option("client-only", {
+      type: "boolean",
+      default: false,
+      description: "Generate only client config (sets CLIENT_BUNDLE_ONLY=yes)"
+    })
+    .option("server-only", {
+      type: "boolean",
+      default: false,
+      description: "Generate only server config (sets SERVER_BUNDLE_ONLY=yes)"
+    })
+    .option("output", {
+      type: "string",
+      description: "Output to specific file instead of directory"
+    })
+    .option("depth", {
+      type: "number",
+      default: 20,
+      coerce: (value: number | string) => {
+        if (value === "null" || value === null) return null
+        return typeof value === "number" ? value : parseInt(String(value), 10)
+      },
+      description: "Inspection depth (use 'null' for unlimited)"
+    })
+    .option("format", {
+      type: "string",
+      choices: ["yaml", "json", "inspect"] as const,
+      description: "Output format (default: yaml for files, inspect for stdout)"
+    })
+    .option("annotate", {
+      type: "boolean",
+      description:
+        "Enable inline documentation (YAML only, default with --doctor or file output)"
+    })
+    .option("verbose", {
+      type: "boolean",
+      default: false,
+      description: "Show full output without compact mode"
+    })
+    .option("init", {
+      type: "boolean",
+      default: false,
+      description: "Generate sample .bundler-config.yml with examples"
+    })
+    .option("config-file", {
+      type: "string",
+      description: "Path to config file (default: .bundler-config.yml)"
+    })
+    .option("build", {
+      type: "string",
+      description: "Export config for specific build from config file"
+    })
+    .option("list-builds", {
+      type: "boolean",
+      default: false,
+      description: "List all available builds from config file"
+    })
+    .option("all-builds", {
+      type: "boolean",
+      default: false,
+      description: "Export all builds from config file"
+    })
+    .option("validate", {
+      type: "boolean",
+      default: false,
+      description:
+        "Validate all builds by running webpack/rspack (requires config file)"
+    })
+    .option("validate-build", {
+      type: "string",
+      description: "Validate specific build from config file"
+    })
+    .option("webpack", {
+      type: "boolean",
+      default: false,
+      description: "Use webpack (overrides config file)"
+    })
+    .option("rspack", {
+      type: "boolean",
+      default: false,
+      description: "Use rspack (overrides config file)"
+    })
+    .check((argv) => {
+      if (argv.webpack && argv.rspack) {
         throw new Error(
-          `Invalid bundler '${bundler}'. Must be 'webpack' or 'rspack'.`
+          "--webpack and --rspack are mutually exclusive. Please specify only one."
         )
       }
-      options.bundler = bundler
-    } else if (arg.startsWith("--env=")) {
-      const env = parseValue(arg, "--env=")
-      if (env !== "development" && env !== "production" && env !== "test") {
+      if (argv["client-only"] && argv["server-only"]) {
         throw new Error(
-          `Invalid environment '${env}'. Must be 'development', 'production', or 'test'.`
+          "--client-only and --server-only are mutually exclusive. Please specify only one."
         )
       }
-      options.env = env
-    } else if (arg === "--client-only") {
-      options.clientOnly = true
-    } else if (arg === "--server-only") {
-      options.serverOnly = true
-    } else if (arg.startsWith("--output=")) {
-      options.output = parseValue(arg, "--output=")
-    } else if (arg.startsWith("--depth=")) {
-      const depth = parseValue(arg, "--depth=")
-      options.depth = depth === "null" ? null : parseInt(depth, 10)
-    } else if (arg.startsWith("--format=")) {
-      const format = parseValue(arg, "--format=")
-      if (format !== "yaml" && format !== "json" && format !== "inspect") {
+      if (argv.output && argv["save-dir"]) {
         throw new Error(
-          `Invalid format '${format}'. Must be 'yaml', 'json', or 'inspect'.`
+          "--output and --save-dir are mutually exclusive. Use one or the other."
         )
       }
-      options.format = format
-    } else if (arg === "--no-annotate") {
-      options.annotate = false
-    } else if (arg === "--verbose") {
-      options.verbose = true
-    }
-  }
+      if (argv.stdout && argv["save-dir"]) {
+        throw new Error(
+          "--stdout and --save-dir are mutually exclusive. Use one or the other."
+        )
+      }
+      if (argv.build && argv["all-builds"]) {
+        throw new Error(
+          "--build and --all-builds are mutually exclusive. Use one or the other."
+        )
+      }
+      if (argv.validate && argv["validate-build"]) {
+        throw new Error(
+          "--validate and --validate-build are mutually exclusive. Use one or the other."
+        )
+      }
+      if (argv.validate && (argv.build || argv["all-builds"])) {
+        throw new Error(
+          "--validate cannot be used with --build or --all-builds."
+        )
+      }
+      return true
+    })
+    .help("help")
+    .alias("help", "h")
+    .epilogue(
+      `Examples:
+
+  # Config File Workflow
+  bin/export-bundler-config --init
+  bin/export-bundler-config --list-builds
+  bin/export-bundler-config --build=dev
+  bin/export-bundler-config --all-builds --save-dir=./configs
+  bin/export-bundler-config --build=dev --rspack
+
+  # Traditional Workflow (without config file)
+  bin/export-bundler-config --doctor
+  # Creates: webpack-development-client-hmr.yaml, webpack-development-client.yaml,
+  #          webpack-development-server.yaml, webpack-production-client.yaml,
+  #          webpack-production-server.yaml
+
+  bin/export-bundler-config --env=production --client-only
+  bin/export-bundler-config --save-dir=./debug
+  bin/export-bundler-config                               # Saves to shakapacker-config-exports/
+
+  # Validate builds
+  bin/export-bundler-config --validate                    # Validate all builds
+  bin/export-bundler-config --validate-build=dev          # Validate specific build
+  bin/export-bundler-config --validate --verbose          # Validate with full logs
 
-  return options
+  # View config in terminal (stdout)
+  bin/export-bundler-config --stdout
+  bin/export-bundler-config --output=config.yaml          # Save to specific file`
+    )
+    .strict()
+    .parseSync()
+
+  // Type assertions are safe here because yargs validates choices at runtime
+  // Handle --webpack and --rspack flags
+  let bundler: "webpack" | "rspack" | undefined = argv.bundler as
+    | "webpack"
+    | "rspack"
+    | undefined
+  if (argv.webpack) bundler = "webpack"
+  if (argv.rspack) bundler = "rspack"
+
+  return {
+    bundler,
+    env: argv.env as "development" | "production" | "test" | undefined,
+    clientOnly: argv["client-only"],
+    serverOnly: argv["server-only"],
+    output: argv.output,
+    depth: argv.depth as number | null,
+    format: argv.format as "yaml" | "json" | "inspect" | undefined,
+    help: false, // yargs handles help internally
+    verbose: argv.verbose,
+    doctor: argv.doctor,
+    saveDir: argv["save-dir"],
+    stdout: argv.stdout,
+    annotate: argv.annotate,
+    init: argv.init,
+    configFile: argv["config-file"],
+    build: argv.build,
+    listBuilds: argv["list-builds"],
+    allBuilds: argv["all-builds"],
+    validate: argv.validate,
+    validateBuild: argv["validate-build"]
+  }
 }
 
 function applyDefaults(options: ExportOptions): void {
   if (options.doctor) {
-    options.save = true
     if (options.format === undefined) options.format = "yaml"
     if (options.annotate === undefined) options.annotate = true
-  } else if (options.save) {
+  } else if (!options.stdout && !options.output) {
+    // Default mode: save to directory
     if (options.format === undefined) options.format = "yaml"
     if (options.annotate === undefined) options.annotate = true
   } else {
     if (options.format === undefined) options.format = "inspect"
     if (options.annotate === undefined) options.annotate = false
   }
+
+  // Set default save directory for file output modes
+  if (!options.stdout && !options.output && !options.saveDir) {
+    options.saveDir = resolve(process.cwd(), "shakapacker-config-exports")
+  }
 }
 
-function validateOptions(options: ExportOptions): void {
-  if (options.clientOnly && options.serverOnly) {
-    throw new Error(
-      "--client-only and --server-only are mutually exclusive. Please specify only one."
+function runInitCommand(options: ExportOptions): number {
+  const configPath = options.configFile || ".bundler-config.yml"
+  const fullPath = resolve(process.cwd(), configPath)
+
+  if (existsSync(fullPath)) {
+    console.error(
+      `[Config Exporter] Error: Config file already exists: ${fullPath}`
+    )
+    console.error(
+      `Remove it first or use --config-file=<path> for a different location.`
     )
+    return 1
   }
 
-  if (options.saveDir && !options.save && !options.doctor) {
-    throw new Error("--save-dir requires --save or --doctor flag.")
+  const sampleConfig = generateSampleConfigFile()
+  writeFileSync(fullPath, sampleConfig, "utf8")
+
+  console.log(`[Config Exporter] ✅ Created config file: ${fullPath}`)
+  console.log(`\nNext steps:`)
+  console.log(`  1. Edit the config file to match your build setup`)
+  console.log(
+    `  2. List available builds: bin/export-bundler-config --list-builds`
+  )
+  console.log(
+    `  3. Export a build: bin/export-bundler-config --build=<name> --save\n`
+  )
+
+  return 0
+}
+
+function runListBuildsCommand(options: ExportOptions): number {
+  try {
+    const loader = new ConfigFileLoader(options.configFile)
+    loader.listBuilds()
+    return 0
+  } catch (error: unknown) {
+    const errorMessage = error instanceof Error ? error.message : String(error)
+    console.error(`[Config Exporter] Error: ${errorMessage}`)
+    return 1
   }
+}
 
-  if (options.output && options.saveDir) {
-    throw new Error(
-      "--output and --save-dir are mutually exclusive. Use one or the other."
-    )
+async function runValidateCommand(options: ExportOptions): Promise<number> {
+  const savedEnv = saveBuildEnvironmentVariables()
+
+  try {
+    // Validate that config file exists
+    const loader = new ConfigFileLoader(options.configFile)
+    if (!loader.exists()) {
+      const configPath = options.configFile || ".bundler-config.yml"
+      throw new Error(
+        `Config file ${configPath} not found. Run --init to create it.`
+      )
+    }
+
+    // Set up environment
+    const appRoot = findAppRoot()
+    process.chdir(appRoot)
+    setupNodePath(appRoot)
+
+    const config = loader.load()
+    const validator = new BuildValidator({ verbose: options.verbose || false })
+
+    // Determine which builds to validate
+    let buildsToValidate: string[]
+    if (options.validateBuild) {
+      // Validate specific build
+      if (!config.builds[options.validateBuild]) {
+        const available = Object.keys(config.builds).join(", ")
+        throw new Error(
+          `Build '${options.validateBuild}' not found in config file.\n` +
+            `Available builds: ${available}`
+        )
+      }
+      buildsToValidate = [options.validateBuild]
+    } else {
+      // Validate all builds
+      buildsToValidate = Object.keys(config.builds)
+
+      // Handle empty builds edge case
+      if (buildsToValidate.length === 0) {
+        throw new Error(
+          `No builds found in config file. Add at least one build to .bundler-config.yml or run --init to see examples.`
+        )
+      }
+    }
+
+    console.log("\n" + "=".repeat(80))
+    console.log("🔍 Validating Builds")
+    console.log("=".repeat(80))
+    console.log(`\nValidating ${buildsToValidate.length} build(s)...\n`)
+
+    if (options.verbose) {
+      console.log("⚡ VERBOSE MODE ENABLED - Full build output will be shown")
+      console.log(
+        "   This includes all webpack/rspack compilation logs, warnings, and progress messages"
+      )
+      console.log("   Use without --verbose to see only errors and summaries\n")
+      console.log("=".repeat(80) + "\n")
+    }
+
+    const results = []
+
+    // Validate each build
+    for (const buildName of buildsToValidate) {
+      if (options.verbose) {
+        console.log("\n" + "=".repeat(80))
+        console.log(`📦 VALIDATING BUILD: ${buildName}`)
+        console.log("=".repeat(80))
+      } else {
+        console.log(`\n📦 Validating build: ${buildName}`)
+      }
+
+      // Clear and restore environment to prevent leakage between builds
+      clearBuildEnvironmentVariables()
+      restoreBuildEnvironmentVariables(savedEnv)
+
+      // Get the build's environment to use for auto-detection
+      const buildConfig = config.builds[buildName]
+      const buildEnv =
+        buildConfig.environment?.NODE_ENV ||
+        (buildConfig.environment?.RAILS_ENV as
+          | "development"
+          | "production"
+          | "test"
+          | undefined) ||
+        "development"
+
+      // Auto-detect bundler using the build's environment
+      const defaultBundler = await autoDetectBundler(buildEnv, appRoot)
+
+      // Resolve build config with the correct default bundler
+      const resolvedBuild = loader.resolveBuild(
+        buildName,
+        options,
+        defaultBundler
+      )
+
+      // Validate the build
+      const result = await validator.validateBuild(resolvedBuild, appRoot)
+      results.push(result)
+
+      // Show immediate feedback
+      if (options.verbose) {
+        console.log("=".repeat(80))
+      }
+      if (result.success) {
+        console.log(`   ✅ Build passed`)
+      } else {
+        console.log(`   ❌ Build failed with ${result.errors.length} error(s)`)
+      }
+      if (options.verbose) {
+        console.log("")
+      }
+    }
+
+    // Print formatted results
+    const formattedResults = validator.formatResults(results)
+    console.log(formattedResults)
+
+    // Return exit code based on results
+    const hasFailures = results.some((r) => !r.success)
+    return hasFailures ? 1 : 0
+  } catch (error: unknown) {
+    const errorMessage = error instanceof Error ? error.message : String(error)
+    console.error(`[Config Exporter] Error: ${errorMessage}`)
+    return 1
+  } finally {
+    // Restore original environment
+    restoreBuildEnvironmentVariables(savedEnv)
   }
+}
+
+async function runAllBuildsCommand(options: ExportOptions): Promise<number> {
+  // Save original environment to restore after all builds
+  const savedEnv = saveBuildEnvironmentVariables()
 
-  if (options.annotate && options.format !== "yaml") {
-    throw new Error(
-      "--annotate (or default with --save/--doctor) requires --format=yaml. Use --no-annotate or --format=inspect/json."
+  try {
+    // Set up environment
+    const appRoot = findAppRoot()
+    process.chdir(appRoot)
+    setupNodePath(appRoot)
+
+    // Apply defaults
+    applyDefaults(options)
+
+    const loader = new ConfigFileLoader(options.configFile)
+    if (!loader.exists()) {
+      const configPath = options.configFile || ".bundler-config.yml"
+      throw new Error(
+        `Config file ${configPath} not found. Run --init to create it.`
+      )
+    }
+
+    const config = loader.load()
+    const buildNames = Object.keys(config.builds)
+
+    console.log(
+      `\n📦 Exporting ${buildNames.length} builds from config file...\n`
     )
+
+    const fileWriter = new FileWriter()
+    const targetDir = options.saveDir! // Set by applyDefaults
+    const createdFiles: string[] = []
+
+    // Export each build
+    for (const buildName of buildNames) {
+      console.log(`\n📦 Exporting build: ${buildName}`)
+
+      // Clear and restore environment to prevent leakage between builds
+      clearBuildEnvironmentVariables()
+      restoreBuildEnvironmentVariables(savedEnv)
+
+      // Create a modified options object for this build
+      const buildOptions = { ...options, build: buildName }
+      const configs = await loadConfigsForEnv(undefined, buildOptions, appRoot)
+
+      for (const { config: cfg, metadata } of configs) {
+        const output = formatConfig(cfg, metadata, options, appRoot)
+        const filename = fileWriter.generateFilename(
+          metadata.bundler,
+          metadata.environment,
+          metadata.configType,
+          options.format!,
+          metadata.buildName
+        )
+
+        const fullPath = resolve(targetDir, filename)
+        fileWriter.writeSingleFile(fullPath, output)
+        createdFiles.push(fullPath)
+      }
+    }
+
+    // Print summary
+    console.log("\n" + "=".repeat(80))
+    console.log("✅ All Builds Exported!")
+    console.log("=".repeat(80))
+    console.log(`\nCreated ${createdFiles.length} configuration file(s) in:`)
+    console.log(`  ${targetDir}\n`)
+    console.log("Files:")
+    createdFiles.forEach((file) => {
+      console.log(`  ✓ ${basename(file)}`)
+    })
+    console.log("\n" + "=".repeat(80) + "\n")
+
+    return 0
+  } catch (error: unknown) {
+    const errorMessage = error instanceof Error ? error.message : String(error)
+    console.error(`[Config Exporter] Error: ${errorMessage}`)
+    return 1
+  } finally {
+    // Restore original environment
+    restoreBuildEnvironmentVariables(savedEnv)
   }
 }
 
@@ -165,42 +651,148 @@ async function runDoctorMode(
   options: ExportOptions,
   appRoot: string
 ): Promise<void> {
-  console.log("\n" + "=".repeat(80))
-  console.log("🔍 Config Exporter - Doctor Mode")
-  console.log("=".repeat(80))
-  console.log("\nExporting development AND production configs...")
-  console.log("")
+  // Save original environment to restore after all builds
+  const savedEnv = saveBuildEnvironmentVariables()
 
-  const environments: Array<"development" | "production"> = [
-    "development",
-    "production"
-  ]
-  const fileWriter = new FileWriter()
-  const defaultDir = resolve(process.cwd(), "shakapacker-config-exports")
-  const targetDir = options.saveDir || defaultDir
+  try {
+    console.log("\n" + "=".repeat(80))
+    console.log("🔍 Config Exporter - Doctor Mode")
+    console.log("=".repeat(80))
+
+    const fileWriter = new FileWriter()
+    const targetDir = options.saveDir! // Set by applyDefaults
+
+    const createdFiles: string[] = []
+
+    // Check if config file exists with shakapacker_doctor_default_builds_here flag
+    const configFilePath = options.configFile || ".bundler-config.yml"
+    const loader = new ConfigFileLoader(configFilePath)
+
+    if (loader.exists()) {
+      try {
+        const configData = loader.load()
+        if (configData.shakapacker_doctor_default_builds_here) {
+          console.log(
+            "\nUsing builds from config file (shakapacker_doctor_default_builds_here: true)...\n"
+          )
+          // Use config file builds
+          const buildNames = Object.keys(configData.builds)
+
+          for (const buildName of buildNames) {
+            console.log(`\n📦 Loading build: ${buildName}`)
+
+            // Clear and restore environment to prevent leakage between builds
+            clearBuildEnvironmentVariables()
+            restoreBuildEnvironmentVariables(savedEnv)
+
+            const configs = await loadConfigsForEnv(
+              undefined,
+              { ...options, build: buildName },
+              appRoot
+            )
+
+            for (const { config, metadata } of configs) {
+              const output = formatConfig(config, metadata, options, appRoot)
+              const filename = fileWriter.generateFilename(
+                metadata.bundler,
+                metadata.environment,
+                metadata.configType,
+                options.format!,
+                metadata.buildName
+              )
+              const fullPath = resolve(targetDir, filename)
+              fileWriter.writeSingleFile(fullPath, output)
+              createdFiles.push(fullPath)
+            }
+          }
 
-  const createdFiles: string[] = []
+          // Print summary and exit early
+          printDoctorSummary(createdFiles, targetDir)
+          return
+        }
+      } catch (error: unknown) {
+        // If config file exists but is invalid, warn and fall through to default behavior
+        const errorMessage =
+          error instanceof Error ? error.message : String(error)
+        console.log(`\n⚠️  Config file found but invalid: ${errorMessage}`)
+        console.log("Falling back to default doctor mode...\n")
+      }
+    }
 
-  for (const env of environments) {
-    console.log(`\n📦 Loading ${env} configuration...`)
-    const configs = await loadConfigsForEnv(env, options, appRoot)
+    // Default behavior: hardcoded configs
+    console.log("\nExporting all development and production configs...")
+    console.log("")
 
-    for (const { config, metadata } of configs) {
-      const output = formatConfig(config, metadata, options, appRoot)
-      const filename = fileWriter.generateFilename(
-        metadata.bundler,
-        metadata.environment,
-        metadata.configType,
-        options.format!
-      )
+    const configsToExport = [
+      { label: "development (HMR)", env: "development" as const, hmr: true },
+      { label: "development", env: "development" as const, hmr: false },
+      { label: "production", env: "production" as const, hmr: false }
+    ]
 
-      const fullPath = resolve(targetDir, filename)
-      const fileOutput: FileOutput = { filename, content: output, metadata }
-      fileWriter.writeSingleFile(fullPath, output, true) // quiet mode
-      createdFiles.push(fullPath)
+    for (const { label, env, hmr } of configsToExport) {
+      console.log(`\n📦 Loading ${label} configuration...`)
+
+      // Clear and restore environment to prevent leakage between builds
+      clearBuildEnvironmentVariables()
+      restoreBuildEnvironmentVariables(savedEnv)
+
+      // Set WEBPACK_SERVE for HMR config
+      if (hmr) {
+        process.env.WEBPACK_SERVE = "true"
+      }
+
+      const configs = await loadConfigsForEnv(env, options, appRoot)
+
+      for (const { config, metadata } of configs) {
+        const output = formatConfig(config, metadata, options, appRoot)
+
+        // Adjust filename for HMR config
+        let filename: string
+        if (
+          hmr &&
+          (metadata.configType === "client" || metadata.configType === "all")
+        ) {
+          /**
+           * HMR Mode Filename Logic:
+           * - When WEBPACK_SERVE=true, webpack-dev-server runs and HMR is enabled
+           * - HMR only applies to client bundles (server bundles don't use HMR)
+           * - If configType is "all", we still only generate client file for HMR
+           *   because the server bundle is identical to non-HMR development
+           * - Filename uses "client" type and "development-hmr" build name to
+           *   distinguish it from regular development client bundle
+           */
+          filename = fileWriter.generateFilename(
+            metadata.bundler,
+            metadata.environment,
+            "client",
+            options.format!,
+            "development-hmr"
+          )
+        } else {
+          filename = fileWriter.generateFilename(
+            metadata.bundler,
+            metadata.environment,
+            metadata.configType,
+            options.format!,
+            metadata.buildName
+          )
+        }
+
+        const fullPath = resolve(targetDir, filename)
+        const fileOutput: FileOutput = { filename, content: output, metadata }
+        fileWriter.writeSingleFile(fullPath, output)
+        createdFiles.push(fullPath)
+      }
     }
+
+    printDoctorSummary(createdFiles, targetDir)
+  } finally {
+    // Restore original environment
+    restoreBuildEnvironmentVariables(savedEnv)
   }
+}
 
+function printDoctorSummary(createdFiles: string[], targetDir: string): void {
   // Print summary
   console.log("\n" + "=".repeat(80))
   console.log("✅ Export Complete!")
@@ -239,11 +831,13 @@ async function runSaveMode(
   options: ExportOptions,
   appRoot: string
 ): Promise<void> {
-  console.log(`[Config Exporter] Save mode: Exporting ${options.env} configs`)
+  const env = options.env || "development"
+  console.log(`[Config Exporter] Exporting ${env} configs`)
 
   const fileWriter = new FileWriter()
-  const targetDir = options.saveDir || process.cwd()
-  const configs = await loadConfigsForEnv(options.env!, options, appRoot)
+  const targetDir = options.saveDir! // Set by applyDefaults
+  const configs = await loadConfigsForEnv(options.env, options, appRoot)
+  const createdFiles: string[] = []
 
   if (options.output) {
     // Single file output
@@ -257,7 +851,9 @@ async function runSaveMode(
       options,
       appRoot
     )
-    fileWriter.writeSingleFile(resolve(options.output), output)
+    const fullPath = resolve(options.output)
+    fileWriter.writeSingleFile(fullPath, output)
+    createdFiles.push(fullPath)
   } else {
     // Multi-file output (one per config)
     for (const { config, metadata } of configs) {
@@ -266,11 +862,20 @@ async function runSaveMode(
         metadata.bundler,
         metadata.environment,
         metadata.configType,
-        options.format!
+        options.format!,
+        metadata.buildName
       )
-      fileWriter.writeSingleFile(resolve(targetDir, filename), output)
+      const fullPath = resolve(targetDir, filename)
+      fileWriter.writeSingleFile(fullPath, output)
+      createdFiles.push(fullPath)
     }
   }
+
+  // Log all created files
+  console.log(`\n[Config Exporter] Created ${createdFiles.length} file(s):`)
+  createdFiles.forEach((file) => {
+    console.log(`  ✓ ${file}`)
+  })
 }
 
 async function runStdoutMode(
@@ -289,17 +894,116 @@ async function runStdoutMode(
   console.log(output)
 }
 
+async function runSingleFileMode(
+  options: ExportOptions,
+  appRoot: string
+): Promise<void> {
+  const configs = await loadConfigsForEnv(options.env!, options, appRoot)
+  const combined = configs.map((c) => c.config)
+  const metadata = configs[0].metadata
+  metadata.configCount = combined.length
+
+  const config = combined.length === 1 ? combined[0] : combined
+  const output = formatConfig(config, metadata, options, appRoot)
+
+  const fileWriter = new FileWriter()
+  const filePath = resolve(process.cwd(), options.output!)
+  fileWriter.writeSingleFile(filePath, output)
+}
+
 async function loadConfigsForEnv(
-  env: "development" | "production" | "test",
+  env: "development" | "production" | "test" | undefined,
   options: ExportOptions,
   appRoot: string
 ): Promise<Array<{ config: any; metadata: ConfigMetadata }>> {
-  // Auto-detect bundler if not specified
-  const bundler = options.bundler || (await autoDetectBundler(env, appRoot))
+  let bundler: "webpack" | "rspack"
+  let buildName: string | undefined
+  let buildOutputs: string[] = []
+  let customConfigFile: string | undefined
+  let bundlerEnvArgs: string[] = []
+  let finalEnv: "development" | "production" | "test"
+
+  // If using config file build
+  if (options.build) {
+    // Use a temporary env for auto-detection, will be overridden by build config
+    const tempEnv = env || "development"
+    const loader = new ConfigFileLoader(options.configFile)
+    const defaultBundler = await autoDetectBundler(tempEnv, appRoot)
+    const resolvedBuild = loader.resolveBuild(
+      options.build,
+      options,
+      defaultBundler
+    )
+
+    bundler = resolvedBuild.bundler
+    buildName = resolvedBuild.name
+    buildOutputs = resolvedBuild.outputs
+    customConfigFile = resolvedBuild.configFile
+    bundlerEnvArgs = resolvedBuild.bundlerEnvArgs
+
+    // Set environment variables from config
+    // Security: Only allow specific environment variables to prevent malicious configs
+    const DANGEROUS_ENV_VARS = [
+      "PATH",
+      "HOME",
+      "LD_PRELOAD",
+      "LD_LIBRARY_PATH",
+      "DYLD_LIBRARY_PATH",
+      "DYLD_INSERT_LIBRARIES"
+    ]
+
+    for (const [key, value] of Object.entries(resolvedBuild.environment)) {
+      if (DANGEROUS_ENV_VARS.includes(key)) {
+        console.warn(
+          `[Config Exporter] Warning: Skipping dangerous environment variable: ${key}`
+        )
+        continue
+      }
+      if (!(BUILD_ENV_VARS as readonly string[]).includes(key)) {
+        console.warn(
+          `[Config Exporter] Warning: Skipping non-whitelisted environment variable: ${key}. ` +
+            `Allowed variables are: ${BUILD_ENV_VARS.join(", ")}`
+        )
+        continue
+      }
+      process.env[key] = value
+    }
+
+    // Determine final env: CLI flag > build config NODE_ENV > default
+    if (options.env) {
+      finalEnv = options.env
+    } else if (resolvedBuild.environment.NODE_ENV) {
+      const nodeEnv = resolvedBuild.environment.NODE_ENV
+      const allowedEnvs = ["development", "production", "test"]
+      if (allowedEnvs.includes(nodeEnv)) {
+        finalEnv = nodeEnv as "development" | "production" | "test"
+      } else {
+        throw new Error(
+          `Invalid NODE_ENV value in config: "${nodeEnv}". ` +
+            `Allowed values are: ${allowedEnvs.join(", ")}.`
+        )
+      }
+    } else {
+      finalEnv = "development"
+    }
+
+    // Sync process.env to reflect resolved environment
+    process.env.NODE_ENV = finalEnv
+    // Determine RAILS_ENV: CLI env option > build config RAILS_ENV > finalEnv
+    const railsEnv =
+      options.env || resolvedBuild.environment.RAILS_ENV || finalEnv
+    process.env.RAILS_ENV = railsEnv
+  } else {
+    // No build config - use CLI env or default
+    finalEnv = env || "development"
 
-  // Set environment variables
-  process.env.NODE_ENV = env
-  process.env.RAILS_ENV = env
+    // Auto-detect bundler if not specified
+    bundler = options.bundler || (await autoDetectBundler(finalEnv, appRoot))
+
+    // Set environment variables
+    process.env.NODE_ENV = finalEnv
+    process.env.RAILS_ENV = finalEnv
+  }
 
   if (options.clientOnly) {
     process.env.CLIENT_BUNDLE_ONLY = "yes"
@@ -308,12 +1012,16 @@ async function loadConfigsForEnv(
   }
 
   // Find and load config file
-  const configFile = findConfigFile(bundler, appRoot)
+  const configFile =
+    customConfigFile || findConfigFile(bundler, appRoot, finalEnv)
   // Quiet mode for cleaner output - only show if verbose or errors
   if (process.env.VERBOSE) {
     console.log(`[Config Exporter] Loading config: ${configFile}`)
-    console.log(`[Config Exporter] Environment: ${env}`)
+    console.log(`[Config Exporter] Environment: ${finalEnv}`)
     console.log(`[Config Exporter] Bundler: ${bundler}`)
+    if (buildName) {
+      console.log(`[Config Exporter] Build: ${buildName}`)
+    }
   }
 
   // Load the config
@@ -331,8 +1039,26 @@ async function loadConfigsForEnv(
   }
 
   // Clear require cache for config file and all related modules
-  // This is critical for loading different environments in the same process
-  // MUST clear shakapacker env module cache so env.nodeEnv is re-read!
+  /**
+   * AGGRESSIVE REQUIRE CACHE CLEARING
+   *
+   * Why: This tool can load multiple environments (dev/prod) and builds in a
+   * single process. Node's require cache prevents modules from re-evaluating,
+   * which causes stale environment values (NODE_ENV, etc.) to persist.
+   *
+   * What: Clears cache for:
+   * - Webpack/rspack config files (they read process.env)
+   * - Shakapacker modules (env detection, config loading)
+   * - Config directory files (custom helpers that may read env)
+   *
+   * Trade-offs:
+   * - More reliable: Ensures each build gets fresh environment
+   * - Potentially brittle: String matching on paths (but comprehensive)
+   * - Performance: Minimal impact since this runs per-build, not per-file
+   *
+   * Maintenance: If adding new shakapacker modules that read env vars,
+   * ensure their paths are covered by the patterns below.
+   */
   const configDir = dirname(configFile)
   Object.keys(require.cache).forEach((key) => {
     if (
@@ -359,6 +1085,40 @@ async function loadConfigsForEnv(
     loadedConfig = loadedConfig.default
   }
 
+  // Handle function exports (webpack config functions)
+  if (typeof loadedConfig === "function") {
+    // Webpack config functions receive (env, argv) parameters
+    // Build env object from bundler_env args if available
+    const envObject: Record<string, any> = {}
+    if (bundlerEnvArgs && bundlerEnvArgs.length > 0) {
+      // Parse --env key=value or --env key into object
+      for (let i = 0; i < bundlerEnvArgs.length; i += 2) {
+        if (bundlerEnvArgs[i] === "--env") {
+          const envArg = bundlerEnvArgs[i + 1]
+          if (envArg.includes("=")) {
+            const [key, value] = envArg.split("=")
+            envObject[key] = value
+          } else {
+            envObject[envArg] = true
+          }
+        }
+      }
+    }
+
+    const argv = { mode: finalEnv }
+    try {
+      loadedConfig = loadedConfig(envObject, argv)
+    } catch (error: unknown) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error)
+      throw new Error(
+        `Failed to execute config function: ${errorMessage}\n` +
+          `Config file: ${configFile}\n` +
+          `Environment: ${JSON.stringify(envObject)}`
+      )
+    }
+  }
+
   // Determine config type and split if array
   const configs: any[] = Array.isArray(loadedConfig)
     ? loadedConfig
@@ -368,8 +1128,27 @@ async function loadConfigsForEnv(
   configs.forEach((cfg, index) => {
     let configType: "client" | "server" | "all" = "all"
 
-    // Try to infer config type from the config itself
-    if (configs.length === 2) {
+    // Use outputs from build config if available
+    if (
+      buildOutputs.length > 0 &&
+      index < buildOutputs.length &&
+      buildOutputs[index]
+    ) {
+      const outputValue = buildOutputs[index]
+      // Validate the output value is a valid config type
+      if (
+        outputValue === "client" ||
+        outputValue === "server" ||
+        outputValue === "all"
+      ) {
+        configType = outputValue
+      } else {
+        throw new Error(
+          `Invalid output type '${outputValue}' at index ${index} in build '${buildName}'. ` +
+            `Allowed values are: client, server, all`
+        )
+      }
+    } else if (configs.length === 2) {
       // Likely client and server configs
       configType = index === 0 ? "client" : "server"
     } else if (options.clientOnly) {
@@ -381,15 +1160,17 @@ async function loadConfigsForEnv(
     const metadata: ConfigMetadata = {
       exportedAt: new Date().toISOString(),
       bundler,
-      environment: env,
+      environment: finalEnv,
       configFile,
       configType,
       configCount: configs.length,
+      buildName,
       environmentVariables: {
         NODE_ENV: process.env.NODE_ENV,
         RAILS_ENV: process.env.RAILS_ENV,
         CLIENT_BUNDLE_ONLY: process.env.CLIENT_BUNDLE_ONLY,
-        SERVER_BUNDLE_ONLY: process.env.SERVER_BUNDLE_ONLY
+        SERVER_BUNDLE_ONLY: process.env.SERVER_BUNDLE_ONLY,
+        WEBPACK_SERVE: process.env.WEBPACK_SERVE
       }
     }
 
@@ -526,46 +1307,86 @@ function cleanConfig(obj: any, rootPath: string): any {
   return clean(obj)
 }
 
-async function autoDetectBundler(
+/**
+ * Loads and returns shakapacker.yml configuration
+ */
+function loadShakapackerConfig(
   env: string,
   appRoot: string
-): Promise<"webpack" | "rspack"> {
+): { bundler: "webpack" | "rspack"; configPath: string } {
   try {
-    const configPath =
+    const configFilePath =
       process.env.SHAKAPACKER_CONFIG ||
       resolve(appRoot, "config/shakapacker.yml")
 
-    if (existsSync(configPath)) {
-      const config: any = loadYaml(readFileSync(configPath, "utf8"))
+    if (existsSync(configFilePath)) {
+      const config: any = loadYaml(readFileSync(configFilePath, "utf8"))
       const envConfig = config[env] || config.default || {}
+
+      // Get bundler
       const bundler = envConfig.assets_bundler || "webpack"
       if (bundler !== "webpack" && bundler !== "rspack") {
         console.warn(
           `[Config Exporter] Invalid bundler '${bundler}' in shakapacker.yml, defaulting to webpack`
         )
-        return "webpack"
+        return {
+          bundler: "webpack",
+          configPath: bundler === "rspack" ? "config/rspack" : "config/webpack"
+        }
       }
-      console.log(`[Config Exporter] Auto-detected bundler: ${bundler}`)
-      return bundler
+
+      // Get config path
+      const customConfigPath = envConfig.assets_bundler_config_path
+      const configPath =
+        customConfigPath ||
+        (bundler === "rspack" ? "config/rspack" : "config/webpack")
+
+      console.log(
+        `[Config Exporter] Auto-detected bundler: ${bundler}, config path: ${configPath}`
+      )
+      return { bundler, configPath }
     }
-  } catch (error: any) {
+  } catch (error: unknown) {
     console.warn(
-      `[Config Exporter] Error detecting bundler, defaulting to webpack`
+      `[Config Exporter] Error loading shakapacker config, defaulting to webpack`
     )
   }
 
-  return "webpack"
+  return { bundler: "webpack", configPath: "config/webpack" }
+}
+
+/**
+ * Auto-detects bundler from shakapacker.yml
+ *
+ * Error Handling Strategy:
+ * - Invalid bundler → warns and defaults to webpack (graceful fallback)
+ * - Config read errors → warns and defaults to webpack (graceful fallback)
+ *
+ * Rationale for warnings vs errors:
+ * - This reads shakapacker.yml (infrastructure config), not user build config
+ * - Failures here should not block the tool; defaulting to webpack is safe
+ * - Contrast with NODE_ENV validation in build configs, which throws errors
+ *   because invalid NODE_ENV would produce incorrect builds
+ */
+async function autoDetectBundler(
+  env: string,
+  appRoot: string
+): Promise<"webpack" | "rspack"> {
+  const { bundler } = loadShakapackerConfig(env, appRoot)
+  return bundler
 }
 
 function findConfigFile(
   bundler: "webpack" | "rspack",
-  appRoot: string
+  appRoot: string,
+  env: string
 ): string {
+  const { configPath } = loadShakapackerConfig(env, appRoot)
   const extensions = ["ts", "js"]
 
   if (bundler === "rspack") {
     for (const ext of extensions) {
-      const rspackPath = resolve(appRoot, `config/rspack/rspack.config.${ext}`)
+      const rspackPath = resolve(appRoot, configPath, `rspack.config.${ext}`)
       if (existsSync(rspackPath)) {
         return rspackPath
       }
@@ -574,14 +1395,14 @@ function findConfigFile(
 
   // Fall back to webpack config
   for (const ext of extensions) {
-    const webpackPath = resolve(appRoot, `config/webpack/webpack.config.${ext}`)
+    const webpackPath = resolve(appRoot, configPath, `webpack.config.${ext}`)
     if (existsSync(webpackPath)) {
       return webpackPath
     }
   }
 
   throw new Error(
-    `Could not find ${bundler} config file. Expected: config/${bundler}/${bundler}.config.{js,ts}`
+    `Could not find ${bundler} config file. Expected: ${configPath}/${bundler}.config.{js,ts}`
   )
 }
 
@@ -622,62 +1443,3 @@ function setupNodePath(appRoot: string): void {
     require("module").Module._initPaths()
   }
 }
-
-function showHelp(): void {
-  console.log(`
-Shakapacker Config Exporter
-
-Exports webpack or rspack configuration in a verbose, human-readable format
-for comparison and analysis.
-
-QUICK START (for troubleshooting):
-  bin/export-bundler-config --doctor
-
-  Exports annotated YAML configs for both development and production.
-  Creates separate files for client and server bundles.
-  Best for debugging, AI analysis, and comparing configurations.
-
-Usage:
-  bin/export-bundler-config [options]
-
-Options:
-  --doctor                   Export all configs for troubleshooting (dev + prod, annotated YAML)
-  --save                     Save to auto-generated file(s) (default: YAML format)
-  --save-dir=<directory>     Directory for output files (requires --save)
-  --bundler=webpack|rspack   Specify bundler (auto-detected if not provided)
-  --env=development|production|test    Node environment (default: development, ignored with --doctor)
-  --client-only              Generate only client config (sets CLIENT_BUNDLE_ONLY=yes)
-  --server-only              Generate only server config (sets SERVER_BUNDLE_ONLY=yes)
-  --output=<filename>        Output to specific file (default: stdout)
-  --depth=<number>           Inspection depth (default: 20, use 'null' for unlimited)
-  --format=yaml|json|inspect Output format (default: inspect for stdout, yaml for --save/--doctor)
-  --no-annotate              Disable inline documentation (YAML only)
-  --verbose                  Show full output without compact mode
-  --help, -h                 Show this help message
-
-Note: --client-only and --server-only are mutually exclusive.
-      --save-dir requires --save.
-      --output and --save-dir are mutually exclusive.
-      If neither --client-only nor --server-only specified, both configs are generated.
-
-Examples:
-  # RECOMMENDED: Export everything for troubleshooting
-  bin/export-bundler-config --doctor
-  # Creates: webpack-development-client.yaml, webpack-development-server.yaml,
-  #          webpack-production-client.yaml, webpack-production-server.yaml
-
-  # Save current environment configs
-  bin/export-bundler-config --save
-  # Creates: webpack-development-client.yaml, webpack-development-server.yaml
-
-  # Save to specific directory
-  bin/export-bundler-config --save --save-dir=./debug
-
-  # Export only client config for production
-  bin/export-bundler-config --save --env=production --client-only
-  # Creates: webpack-production-client.yaml
-
-  # View config in terminal (stdout)
-  bin/export-bundler-config
-`)
-}