prodex 1.1.0 → 1.2.0

package/README.md

@@ -1,140 +1,228 @@
-# 🧩 Prodex — Unified Project Indexer & Dependency Extractor
 
-> **Prodex** *(short for “Project Index”)* — a cross-language dependency combiner for modern full-stack applications.  
-> Traverses **Laravel + React + TypeScript** projects to generate a single, organized view of your project’s true dependency scope.
+# 🧩 Prodex v1.2.0
+
+> **Because every project deserves a clear map, not a maze.**
 
 ---
 
-## 🧠 Recent Fixes & Updates — v1.0.8
-- ⭐ **Priority Files Support**  — priority files will now appear **first** on the entry selection list.
+## 🧠 What’s New — v1.2.0
 
-- 🪟 **Windows path resolution fixed** — now uses proper `file://` URLs for full ESM compatibility.  
-- 🧾 **Improved output naming** — automatic, context-aware filenames (e.g. `prodex-[entries]-combined.txt`).  
-- ⚙️ **“Yes to all” confirmation added** — skip repetitive prompts during CLI runs.
+- 🆕 **Full CLI support with integrated [Sade](https://github.com/lukeed/sade).**  
+  Prodex now runs entirely from the terminal — no `prodex.json` required.  
+  Supports short flags and native glob patterns for flexible targeting.  
+  ```bash
+  prodex -f "**/web.php,**/app.tsx" -i "**/*.d.ts" -x "node_modules/**"
+  prodex --files **/web.php **/app.tsx --include **/*.interface.ts --exclude @shadcn/**
+  ```
 
----
+- 🧾 **Markdown mode added and now default.**  
+  Output is fully fenced and linkable — jump between the index and any code block.  
+  Text mode remains available using `--txt` or `-t`.  
+
+- 🗂 **Output naming improved.**  
+  Output files are now versioned by default.  
+  Custom names are supported using `--name` or `-n`.  
+  Naming conventions have been updated for cleaner, consistent results.  
 
 ---
 
-## 📦 Installation
+## ⚙️ Usage
+
+Prodex v1.2.0 runs entirely from the command line.  
+Interactive mode is currently unstable — use CLI flags instead.
+
+### Installation
 
-### Global install (recommended)
 ```bash
 npm install -g prodex
 ```
 
+Or run without installing:
 
-## 🚀 Features
-
-| Feature | Description |
-|----------|-------------|
-| ⚙️ **Cross-language resolver** | Parses JS/TS (`import`, `export`) and PHP (`use`, `require`, `include`) dependency trees. |
-| 🧭 **Alias detection** | Reads `tsconfig.json` and `vite.config.*` for alias paths (`@/components/...`). |
-| 🧩 **Laravel-aware** | Maps PSR-4 namespaces and detects providers under `app/Providers`. |
-| 🔄 **Recursive chain following** | Resolves dependency graphs up to a configurable depth and file limit. |
-| 🪶 **Clean unified output** | Merges all resolved files into a single `.txt` file with region markers for readability. |
-| 🧠 **Static & safe** | Fully static parsing — no runtime execution or file modification. |
-| 💬 **Interactive CLI** | Select files, confirm settings, or use “Yes to all” for streamlined automation. |
+```bash
+npx prodex
+```
 
 ---
 
-## ⚙️ Configuration
-
-Optional `.prodex.json` (in project root):
+### Basic Run
 
-```json
-{
-  "$schema": "https://raw.githubusercontent.com/emxhive/prodex/main/schema/prodex.schema.json",
-  "output": "prodex",
-  "scanDepth": 2,
-  "limit": 200,
-  "baseDirs": ["app", "routes", "resources/js"],
-  "aliasOverrides": {
-    "@hooks": "resources/js/hooks",
-    "@data": "resources/js/data"
-  },
-  "entryExcludes": [
-    "resources/js/components/ui/",
-    "app/DTOs/"
-  ],
-  "importExcludes": [
-    "node_modules",
-    "@shadcn/"
-  ], 
-  "priorityFiles": [
-  "routes/web.php",
-  "routes/api.php",
-  "index.",
-  "main.",
-  "app."
-]
-}
+```bash
+prodex -f "**/web.php,**/app.tsx"
 ```
 
+### With Includes, exclude, and Custom Name
+
+```bash
+prodex -f "**/web.php,**/app.tsx" -i "**/*.d.ts" -x "node_modules/**" -n "combined-output"
 ```
 
+### Flag Reference
 
+| Flag | Short | Description |
+|------|--------|-------------|
+| `--files` | `-f` | Entry files — starting points for dependency resolution. Accepts multiple names or globs. |
+| `--include` | `-i` | Adds extra files or patterns to include (e.g. `.d.ts`, interface, or type files). These files are **not dependency-resolved** — they’re appended as-is. |
+| `--exclude` | `-x` | Patterns or folders to skip during the scan. |
+| `--name` | `-n` | Custom output filename (without extension). Versioning still applies automatically. |
 
-```
+> Globs are powered by [Fast-Glob](https://github.com/mrmlnc/fast-glob).  
+> Use **comma-separated values** for multiple entries.  
+> Wrap globs in quotes when they include special characters like `|` or `&`.  
 
+---
 
+## 🧭 Plans
 
-Files are matched using `.includes()` (case-insensitive), so `"index."` will match `src/index.js`, `app/index.tsx`, etc.  
-Popular entries appear at the top of the picker.
+- **Alias Resolution Improvements**  
+  Planned overhaul of alias handling to support deeper nested paths, wildcard matching, and auto-mapped imports across mixed stacks.
 
+- **Language Support**  
+  Currently supports **JavaScript**, **React**, and **Laravel + React** stacks.  
+  May work with other frameworks but remains untested.  
+  Broader multi-language support is planned for future versions.
 
+- **Combined Output**  
+  All code from multiple entries is merged into a single output file.  
+  There’s currently **no limit** on output size, but it’s advised to avoid combining *too many large entries* in a single run.  
+  Future versions will include **smart naming** and **automatic splitting** for oversized outputs.
 
+- **Performance Optimizations**  
+  Planned improvements to resolver speed and dependency traversal for faster processing on large projects.  
 
+---
+
+## 🧩 Features
+
+| Status | Feature | Description |
+|:--:|----------|--------------|
+| ✅ | **Cross-language indexing** | Resolves imports across JS, TS, React, and PHP (Laravel) projects. |
+| ✅ | **Markdown output** | Generates clean `.md` files with anchors, back-to-top links, and fenced code blocks. |
+| ✅ | **Text output** | Optional `.txt` mode using `--txt` or `-t`. |
+| ✅ | **Glob support** | Works with flexible glob patterns powered by [Fast-Glob](https://github.com/mrmlnc/fast-glob). |
+| ✅ | **Custom output names** | Define your own output prefix using `--name` or `-n`. |
+| ⚠️ | **Interactive picker (UI)** | Still unstable — not recommended for production use. |
+| ⚠️ | **Alias resolution** | Basic alias mapping supported; advanced cases in progress. |
+| 🚧 | **Smart file splitting** | Planned for large combined outputs. |
+| 🚧 | **PSR-4 deep scan** | Planned to improve PHP dependency resolution. |
+| 🚧 | **Speed optimization** | Further resolver and I/O improvements under development. |
 
 ---
 
-## 🧱 Example: Laravel + React
+## 🧱 Use Cases
 
-```bash
-prodex
-```
+Prodex can technically combine your entire codebase into one file —  
+but it’s **best used in parts**, focusing on specific sections or features.  
+Each run produces a clean, self-contained map showing all related files and dependencies.
 
-```
-🧩 Following dependency chain...
-✅ prodex-app-routes-combined.txt written (24 file(s)).
-```
+### 🧩 Common Scenarios
 
-Included files:
-```
-resources/js/pages/accounts.tsx
-app/Http/Controllers/Shots/AccountsController.php
-app/Repositories/Shots/FireflyApiRepository.php
-app/Enums/Shots/Granularity.php
-app/Support/Shots/CacheKeys.php
-...
-```
+- **🤖 Project Awareness for AI Assistants**  
+  Generate compact `.md` summaries of key parts of your project.  
+  These can be shared with AI tools (like ChatGPT, Claude, or Copilot) to give them structured context about your codebase — without exposing unnecessary files.
+
+- **📦 Feature or Module Mapping**  
+  Combine everything connected to a specific feature (e.g., `Checkout`, `Dashboard`, or `Payments`).  
+  Prodex gathers all linked imports, helpers, and files into one readable document.
+
+- **🔍 Dependency Insight**  
+  Trace how a particular entry file connects through your stack — whether it’s `app.tsx` on the frontend or `routes/web.php` on the backend.  
+  Great for debugging, refactoring, or understanding cross-stack dependencies.
+
+- **📖 Documentation Bundles**  
+  Create readable Markdown maps per module or domain instead of one large export.  
+  Each output acts as a focused, navigable view of your code relationships.
+
+- **🧠 Team Handoffs**  
+  Share isolated code scopes (like `Auth`, `Payments`, or `User Management`) with full dependency context.  
+  Makes onboarding and code reviews significantly faster.
 
 ---
 
-## 🧠 Ideal Use Cases
+## 🧩 Recommended Workflow
+
+Prodex works best when used to **map and export projects in logical parts** rather than all at once.  
+Each run focuses on one or more entry points, and Prodex automatically **loads all imports recursively** for those files —  
+then appends any files matched by the `--include` flag.
+
+### 🧠 Suggested Pattern
+
+1. **Pick a meaningful entry file**  
+   Example:  
+   - Frontend: `resources/js/**/dashboard.tsx`  
+   - Backend: `routes/**/(web|api).php`  
+   - Shared logic: `app/Services/**/PaymentService.php`
+
+2. **Run Prodex with includes for type or interface files**  
+   ```bash
+   prodex -f "**/dashboard.tsx" -i "**/*.d.ts,**/*.interface.ts"
+   ```
+
+3. **Export separate maps for each major area**  
+   ```bash
+   prodex -f "**/dashboard.tsx" -n "dashboard-map"
+   prodex -f "**/web|api.php" -n "backend-map"
+   ```
 
-- 📦 Generate single-file **project snapshots**  
-- 🤖 Provide structured context for **AI assistants**  
-- 🧩 Perform **dependency audits** or code reviews  
-- 📄 Simplify documentation and onboarding  
+4. **Use them together**  
+   Store each output in `/prodex/` or `/docs/maps/`.  
+   These maps can be shared with teammates or loaded into AI tools for structured, code-aware assistance.
+
+> ⚡ Each run recursively resolves every import, applies includes, and outputs one complete dependency map for that section.
 
 ---
 
-## 🔮 Upcoming Features
+## ⚙️ Optional — `prodex.json`
+
+`prodex.json` is **fully optional** in v1.2.0.  
+You can run Prodex entirely from the command line, but the config file can be useful for saved defaults.
+
+### 🪄 Quick Setup
+
+You can generate a ready-to-use config file with:
+
+```bash
+prodex init
+```
+
+This creates a `prodex.json` file in your project root with sensible defaults — including base directories, globs, and priority files.
+
+### 🧩 Running with a Config File
+
+If you’ve defined your entry files in the config under `entry.files`,  
+you can run Prodex directly without specifying `--files`:
+
+```bash
+prodex -c
+```
 
-- 📝 **Markdown export** (`.md`) with automatic code fences  
-- 📦 **Configurable output formats** (txt / md)  
-- ⚡ **Alias auto-discovery for Laravel Mix and Next.js**  
+The `-c` (or `--ci`) flag skips interactive mode and uses the config values automatically.  
+Specifying `-f` ( or `--files`) from the CLI also disables the picker by default.  
+
+You can permanently disable the picker in the config by setting:
+
+```json
+"entry": {
+  "ui": {
+    "enablePicker": false
+  }
+}
+```
 
 ---
 
-## 🧾 License
+## 📜 License
 
-**MIT © 2025 [emxhive](https://github.com/emxhive)**  
-Issues and contributions welcome:  
-👉 [github.com/emxhive/prodex/issues](https://github.com/emxhive/prodex/issues)
+**MIT License**  
+© 2025 [emxhive](https://github.com/emxhive)
 
 ---
 
-**Prodex** — *Codebase, decoded*
+## ⚠️ Note from the Author
+
+Prodex is still a **work in progress**.  
+Some parts of the experience may be rough, especially around interactive mode and advanced resolvers.  
+Updates are released **multiple times per week — sometimes daily** — to keep improving stability and support.  
 
+Please stay up to date for the best experience.  
+Thank you for testing Prodex early. ❤️  

package/bin/prodex.js

@@ -1,18 +1,2 @@
 #!/usr/bin/env node
-import fs from "fs";
-import path from "path";
-import { pathToFileURL, fileURLToPath } from "url";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-const devPath = path.resolve(__dirname, "../src/index.js");
-const distPath = path.resolve(__dirname, "../dist/src/index.js");
-
-// prefer dist in published package
-const entry = fs.existsSync(distPath) ? distPath : devPath;
-
-// convert to file:// URL for cross-platform ESM loading
-const entryUrl = pathToFileURL(entry).href;
-
-import(entryUrl).then(({ default: startProdex }) => startProdex());
+require("../dist/index.js").default();

package/dist/cli/cli-input.js

@@ -0,0 +1,86 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCliInput = parseCliInput;
+const sade_1 = __importDefault(require("sade"));
+const flags_1 = require("./flags");
+const logger_1 = require("../lib/logger");
+const path_1 = __importDefault(require("path"));
+const package_json_1 = __importDefault(require("../../package.json"));
+/**
+ * Unified CLI parser powered by Sade.
+ * Returns { root, entries (from --files), flags, warnings, errors }.
+ */
+function parseCliInput(argv = process.argv) {
+    if (argv.includes("-v") || argv.includes("--version")) {
+        logger_1.logger.log(`prodex v${package_json_1.default.version}`);
+        process.exit(0);
+    }
+    const program = (0, sade_1.default)("prodex [root]");
+    // Register flags dynamically
+    for (const [key, meta] of Object.entries(flags_1.PRODEX_FLAGS)) {
+        const short = meta.short ? `-${meta.short}, ` : "";
+        const long = `--${key}`;
+        const desc = meta.description;
+        let defaultVal;
+        switch (meta.type) {
+            case "boolean":
+                defaultVal = false;
+                break;
+            default:
+                defaultVal = undefined; // defer strings/numbers/lists
+        }
+        if (defaultVal !== undefined) {
+            program.option(`${short}${long}`, desc, defaultVal);
+        }
+        else {
+            program.option(`${short}${long}`, desc);
+        }
+    }
+    let parsed = { root: undefined, flags: {} };
+    // Define default command (root optional)
+    program.action((root, opts) => {
+        const cwd = process.cwd();
+        parsed = {
+            root: root ? path_1.default.resolve(cwd, root) : cwd,
+            flags: { ...opts },
+        };
+    });
+    program.parse(argv);
+    const warnings = [];
+    const errors = [];
+    // Post-parse casting + normalization
+    for (const [key, meta] of Object.entries(flags_1.PRODEX_FLAGS)) {
+        const raw = parsed.flags[key];
+        if (raw === undefined)
+            continue;
+        const obj = {};
+        switch (meta.type) {
+            case "number": {
+                const num = Number(raw);
+                if (Number.isNaN(num)) {
+                    errors.push(`Flag --${key} expected a number but got "${raw}"`);
+                }
+                else {
+                    parsed.flags[key] = num;
+                }
+                break;
+            }
+            case "list": {
+                const arr = String(raw)
+                    .split(",")
+                    .map((v) => v.trim())
+                    .filter(Boolean);
+                parsed.flags[key] = arr;
+                break;
+            }
+        }
+    }
+    return {
+        ...parsed,
+        warnings,
+        errors,
+    };
+}

package/dist/cli/flags.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLI_USAGE = exports.FLAG_SHORT_MAP = exports.PRODEX_FLAGS = exports.FlagKey = void 0;
+var FlagKey;
+(function (FlagKey) {
+    FlagKey["Txt"] = "txt";
+    FlagKey["Ci"] = "ci";
+    FlagKey["Debug"] = "debug";
+    FlagKey["Name"] = "name";
+    FlagKey["Limit"] = "limit";
+    FlagKey["Inc"] = "include";
+    FlagKey["Exc"] = "exclude";
+    FlagKey["Help"] = "help";
+    FlagKey["Files"] = "files";
+})(FlagKey || (exports.FlagKey = FlagKey = {}));
+exports.PRODEX_FLAGS = {
+    [FlagKey.Files]: { short: "f", type: "list", description: "Comma-separated entry files." },
+    [FlagKey.Txt]: { short: "t", type: "boolean", description: "Output as .txt instead of .md." },
+    [FlagKey.Ci]: { short: "c", type: "boolean", description: "Headless/no-UI mode." },
+    [FlagKey.Debug]: { short: "d", type: "boolean", description: "Enable debug logs." },
+    [FlagKey.Name]: { short: "n", type: "string", description: "Custom output filename." },
+    [FlagKey.Limit]: { short: "l", type: "number", description: "Override traversal limit." },
+    [FlagKey.Inc]: { type: "list", short: "i", description: "Comma-separated include globs." },
+    [FlagKey.Exc]: { type: "list", short: "x", description: "Comma-separated exclude globs." },
+    [FlagKey.Help]: { short: "h", type: "boolean", description: "Show CLI help and exit." },
+};
+/** Reverse lookup for short aliases. */
+exports.FLAG_SHORT_MAP = Object.entries(exports.PRODEX_FLAGS).reduce((acc, [key, meta]) => {
+    if (meta.short)
+        acc[meta.short] = key;
+    return acc;
+}, {});
+exports.CLI_USAGE = `
+Usage: prodex [-fcdv]
+       [--files=<globs>|-f=<globs>]
+       [--include=<globs>|-i=<globs>]
+       [--exclude=<globs>|-x=<globs>]
+       [--txt|-t] [--ci|-c] [--debug|-d] [--version|-v]
+       [--name=<string>|-n=<string>]
+       [--limit=<int>|-l=<int>]
+       [--help|-h]
+`;

package/dist/cli/init.js

@@ -0,0 +1,21 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initProdex = initProdex;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const default_config_1 = require("../constants/default-config");
+const logger_1 = require("../lib/logger");
+async function initProdex() {
+    logger_1.logger.log("🪄 Prodex Init — Configuration Wizard (v2)");
+    const dest = path_1.default.join(process.cwd(), "prodex.json");
+    if (fs_1.default.existsSync(dest)) {
+        logger_1.logger.error("prodex.json already exists. Delete or modify it manually.\n");
+        return;
+    }
+    fs_1.default.writeFileSync(dest, JSON.stringify(default_config_1.DEFAULT_PRODEX_CONFIG, null, 2) + "\n", "utf8");
+    logger_1.logger.log(`✅ Created ${dest}`);
+    logger_1.logger.log("💡 Globs supported everywhere (include, exclude, priority).");
+}

package/dist/cli/picker.js

@@ -0,0 +1,82 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pickEntries = pickEntries;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const inquirer_1 = __importDefault(require("inquirer"));
+const config_1 = require("../constants/config");
+const helpers_1 = require("../core/helpers");
+const file_utils_1 = require("../core/file-utils");
+const utils_1 = require("../lib/utils");
+const logger_1 = require("../lib/logger");
+async function pickEntries(baseDirs, depth = 2, cfg) {
+    const entryPatterns = cfg.entry?.files || [];
+    const priorities = [...entryPatterns, ...(cfg.entry?.priority || [])];
+    const verbose = !!cfg.verbose;
+    // 1) Resolve patterns to absolute files and preselect them
+    const resolvedEntries = (await (0, file_utils_1.globScan)(entryPatterns, { cwd: config_1.ROOT })).files;
+    let selected = [...resolvedEntries];
+    // cache: depth -> files[]
+    const scanCache = new Map();
+    for (;;) {
+        const files = await getFilesAtDepth({
+            baseDirs,
+            depth,
+            cfg,
+            scanCache,
+            verbose,
+        });
+        // Merge resolved entries with current scan results
+        const combined = (0, utils_1.unique)([...resolvedEntries, ...files]);
+        // Priority-aware ordering: entries first, then other priorities
+        const sorted = (0, helpers_1.orderByPriority)(combined, priorities);
+        // Build UI selection list
+        const choices = sorted.map(f => ({
+            name: path_1.default.relative(config_1.ROOT, f).norm(),
+            value: f,
+            checked: selected.includes(f),
+        }));
+        choices.push(new inquirer_1.default.Separator());
+        choices.push({ name: "🔽 Load more (go deeper)", value: "__loadmore" });
+        const { picks } = await inquirer_1.default.prompt([
+            {
+                type: "checkbox",
+                name: "picks",
+                message: `Select entry files (depth ${depth})`,
+                choices,
+                loop: false,
+                pageSize: 20,
+            }
+        ]);
+        if (picks.includes("__loadmore")) {
+            depth++;
+            selected = picks.filter(p => p !== "__loadmore");
+            continue;
+        }
+        selected = picks.filter(p => p !== "__loadmore");
+        break;
+    }
+    return (0, utils_1.unique)(selected);
+}
+async function getFilesAtDepth({ baseDirs, depth, cfg, scanCache, verbose }) {
+    if (scanCache.has(depth)) {
+        logger_1.logger.debug(`[cache] depth=${depth} ✓`);
+        return scanCache.get(depth);
+    }
+    logger_1.logger.debug(`[scan]  depth=${depth} …`);
+    const files = [];
+    const effectiveCfg = { ...cfg, scanDepth: depth };
+    for (const base of baseDirs) {
+        const full = path_1.default.join(config_1.ROOT, base);
+        if (!fs_1.default.existsSync(full))
+            continue;
+        for (const f of (0, helpers_1.walk)(full, effectiveCfg, 0))
+            files.push(f.norm());
+    }
+    scanCache.set(depth, files);
+    logger_1.logger.debug(`[scan]  depth=${depth} found=${files.length}`);
+    return files;
+}

package/dist/cli/summary.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.showSummary = showSummary;
+exports.importSummary = importSummary;
+const logger_1 = require("../lib/logger");
+function showSummary({ outDir, fileName, entries }) {
+    logger_1.logger.debug(`🧩 Active Run → ${fileName} (${entries.length} entries)`);
+}
+function importSummary(result) {
+    logger_1.logger.debug(`\n🧩 Summary:
+ • Unique imports expected: ${result.stats.expected.size}
+ • Unique imports resolved: ${result.stats.resolved.size}
+`);
+}

package/dist/constants/config-loader.js

@@ -0,0 +1,90 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadProdexConfig = loadProdexConfig;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const default_config_1 = require("./default-config");
+const logger_1 = require("../lib/logger");
+/**
+ * 🧩 Load and merge Prodex configuration (v3)
+ *
+ * 1️⃣ Reads `prodex.json` if present.
+ * 2️⃣ Merges with `DEFAULT_PRODEX_CONFIG`.
+ * 3️⃣ Normalizes all path-like fields.
+ * 4️⃣ Applies CLI flag overrides.
+ */
+async function loadProdexConfig(flags = {}, cwd) {
+    const configPath = path_1.default.join(cwd, "prodex.json");
+    let userConfig = {};
+    // 1️⃣ Load config if present
+    try {
+        const content = fs_1.default.readFileSync(configPath, "utf8");
+        userConfig = JSON.parse(content);
+    }
+    catch (err) {
+        logger_1.logger.info("No prodex.json found — using defaults.");
+    }
+    // 2️⃣ Merge defaults → user config
+    const { output, entry, resolve, debug } = default_config_1.DEFAULT_PRODEX_CONFIG;
+    const cfg = {
+        ...default_config_1.DEFAULT_PRODEX_CONFIG,
+        ...userConfig,
+        output: { ...output, ...userConfig.output },
+        entry: {
+            ...entry,
+            ...userConfig.entry,
+            ui: { ...entry.ui, ...userConfig.entry?.ui },
+        },
+        resolve: { ...resolve, ...userConfig.resolve },
+        debug: { ...debug, ...userConfig.debug },
+        root: cwd,
+    };
+    // 4️⃣ Apply CLI flag overrides (if any)
+    applyFlagOverrides(cfg, flags);
+    return cfg;
+}
+/** Merge CLI flags into config where relevant. */
+/** Merge CLI flags into config where relevant. */
+function applyFlagOverrides(cfg, flags) {
+    if (!flags)
+        return;
+    const outputOverrides = {
+        name: (cfg, v) => (cfg.output.prefix = v),
+        txt: (cfg) => (cfg.output.format = "txt"),
+    };
+    const resolveOverrides = {
+        limit: (cfg, v) => (cfg.resolve.limit = v),
+        include: (cfg, v) => (cfg.resolve.include = v),
+        exclude: (cfg, v) => (cfg.resolve.exclude = v),
+    };
+    const entryOverrides = {
+        files: (cfg, v) => (cfg.entry.files = v),
+    };
+    const envOverrides = {
+        debug: (_, v) => (process.env.PRODEX_DEBUG = v ? "1" : "0"),
+        verbose: (_, v) => (process.env.PRODEX_VERBOSE = v ? "1" : "0"),
+    };
+    const overrideMap = {
+        ...outputOverrides,
+        ...resolveOverrides,
+        ...entryOverrides,
+        ...envOverrides,
+    };
+    // Apply all flag overrides dynamically
+    for (const [flag, value] of Object.entries(flags)) {
+        if (value == undefined)
+            continue;
+        const apply = overrideMap[flag];
+        if (apply)
+            apply(cfg, value);
+    }
+    // Conditional override rule:
+    // If files exist and include was null/undefined → clear include array
+    const hasFiles = Array.isArray(flags.files) ? flags.files.length > 0 : !!flags.files;
+    if (hasFiles && flags.include == null) {
+        cfg.resolve.include = [];
+    }
+}