mfer 3.2.4 → 4.0.0

package/README.md

@@ -24,7 +24,7 @@ A powerful CLI tool designed to simplify the management and execution of multipl
 - **Concurrent Execution**: Run multiple micro frontends simultaneously with organized output
 - **Group Management**: Organize micro frontends into logical groups for selective execution
 - **Git Integration**: Pull latest changes from all repositories with a single command
-- **Smart Configuration**: Interactive setup wizard with YAML-based configuration
+- **Smart Configuration**: Interactive setup wizard with TOML-based configuration
 - **Cross-Platform**: Works on Windows, macOS, and Linux
 - **Graceful Shutdown**: Clean termination of all processes with Ctrl+C
 
@@ -95,7 +95,7 @@ mfer pull frontend
 ### Quick Reference
 
 - [`mfer init`](#mfer-init) - Interactive setup wizard
-- [`mfer run`](#mfer-run-group_name) - Run micro frontend applications
+- [`mfer run`](#mfer-run-group_name) - Run micro frontend applications (supports per-MFE run modes)
 - [`mfer pull`](#mfer-pull-group_name) - Pull latest changes from git repositories
 - [`mfer install`](#mfer-install-group_name) - Install dependencies for micro frontends
 - [`mfer clone`](#mfer-clone-group_name) - Clone repositories that don't exist locally
@@ -127,20 +127,24 @@ Run micro frontend applications concurrently.
 
 **Options:**
 
-- `-c, --command <command>`: Custom command to run (default: npm start)
-- `-a, --async`: Run custom command concurrently instead of sequentially
+- `-c, --command <command>`: Custom command to run for all MFEs (default: npm start)
+- `-a, --async`: Run custom command concurrently instead of sequentially (only with `--command`)
+- `-m, --mode <mode_name>`: Run MFEs using a named mode from config (see [Per-MFE Run Modes](#per-mfe-run-modes))
 - `-s, --select`: Prompt to select which micro frontends to run
 
+> **Note:** `--mode` and `--command` are mutually exclusive.
+
 **Examples:**
 
 ```bash
-mfer run                    # Run all micro frontends with default command (npm start)
-mfer run frontend          # Run only frontend group with default command
-mfer run --command "npm ci" home    # Run custom command sequentially on home group
-mfer run -c "yarn install" shared  # Run yarn install sequentially on shared group
+mfer run                          # Run all MFEs with default command (npm start)
+mfer run frontend                 # Run frontend group with default command
+mfer run --mode mock              # Run all MFEs in mock mode (per-MFE commands from config)
+mfer run frontend --mode mock     # Run frontend group in mock mode
+mfer run --command "npm ci" home  # Run custom command sequentially on home group
+mfer run -c "yarn install" shared # Run yarn install sequentially on shared group
 mfer run --command "npm ci" --async home  # Run custom command concurrently on home group
-mfer run -c "yarn install" -a shared  # Run yarn install concurrently on shared group
-mfer run --command "npm run build" --select  # Select MFEs and run build command sequentially
+mfer run --command "npm run build" --select  # Select MFEs and run build sequentially
 ```
 
 ### `mfer pull [group_name]`
@@ -355,29 +359,27 @@ mfer lib install my-design-system --select # Select libraries from specific libr
 
 ## ⚙️ Configuration
 
-mfer uses a YAML configuration file located at `~/.mfer/config.yaml`. Here's an example structure:
-
-```yaml
-base_github_url: "https://github.com/your-username"
-mfe_directory: "/path/to/your/micro-frontends"
-lib_directory: "/path/to/your/internal-libs"
-libs:
-  - my-shared-utils
-  - my-design-system
-  - my-common-components
-groups:
-  all:
-    - my-main-app
-    - my-admin-panel
-    - my-shared-components
-  main:
-    - my-main-app
-    - my-shared-components
-  admin:
-    - my-admin-panel
-    - my-shared-components
+mfer uses a TOML configuration file located at `~/.mfer/config.toml`. Here's an example structure:
+
+```toml
+base_github_url = "https://github.com/your-username"
+mfe_directory = "/path/to/your/micro-frontends"
+lib_directory = "/path/to/your/internal-libs"
+libs = ["my-shared-utils", "my-design-system", "my-common-components"]
+
+[groups]
+all = ["my-main-app", "my-admin-panel", "my-shared-components"]
+main = ["my-main-app", "my-shared-components"]
+admin = ["my-admin-panel", "my-shared-components"]
+
+# optional, per-MFE configuration
+[[mfes.my-main-app.modes]]
+mode_name = "mock"
+command = "npm run start:mocked"
 ```
 
+> **Migrating from v3.x?** v4.0.0 is a breaking change: YAML config is no longer supported. Run `mfer config migrate` to convert your existing `~/.mfer/config.yaml` to TOML automatically.
+
 ### Configuration Options
 
 - **`base_github_url`**: Your GitHub base URL for repository operations
@@ -387,6 +389,38 @@ groups:
 - **`groups`**: Named collections of micro frontend projects
   - **`all`**: Default group containing all projects (required)
   - **Custom groups**: Any additional groups you want to create
+- **`mfes`**: Per-MFE configuration (optional). Each key is an MFE name matching one in `groups`.
+  - **`modes`**: Array of named run modes for the MFE. Each mode has:
+    - **`mode_name`**: Name used with `mfer run --mode <name>`
+    - **`command`**: The command to run for this MFE when the mode is active
+
+### Per-MFE Run Modes
+
+Run modes let individual MFEs use a different start command while the rest of the group continue using `npm start`. This is useful when some MFEs support a mocked/stubbed backend while others don't need it.
+
+**Config example** — `root-config` runs with a mocked API, everything else runs normally:
+
+```toml
+[groups]
+all = ["root-config", "mfe-nav", "mfe-dashboard"]
+
+[[mfes.root-config.modes]]
+mode_name = "mock"
+command = "npm run start:mocked"
+```
+
+**Usage:**
+
+```bash
+mfer run --mode mock
+# root-config → npm run start:mocked
+# mfe-nav     → npm start  (no mock mode defined, falls back to default)
+# mfe-dashboard → npm start
+```
+
+- MFEs that **do not** have the mode defined silently fall back to `npm start`.
+- If **no MFE** in the group has the requested mode, a warning is printed but the command still runs (all MFEs use `npm start`).
+- `--mode` cannot be combined with `--command`; they are mutually exclusive.
 
 ### Editing Configuration
 
@@ -402,12 +436,20 @@ You can edit your configuration in several ways:
 
    ```bash
    # On macOS/Linux
-   nano ~/.mfer/config.yaml
+   nano ~/.mfer/config.toml
 
    # On Windows
-   notepad %USERPROFILE%\.mfer\config.yaml
+   notepad %USERPROFILE%\.mfer\config.toml
    ```
 
+3. **Migrate a legacy YAML config**:
+
+   ```bash
+   mfer config migrate
+   ```
+
+   Converts `~/.mfer/config.yaml` → `~/.mfer/config.toml`. Prompts before overwriting an existing TOML file and optionally removes the legacy YAML afterward.
+
 ## 🎯 Use Cases
 
 ### Development Workflow
@@ -425,25 +467,12 @@ mfer run admin     # Start admin panel
 
 Organize your micro frontends into logical groups:
 
-```yaml
-groups:
-  all:
-    - main-app
-    - admin-panel
-    - user-dashboard
-    - shared-components
-    - design-system
-  core:
-    - main-app
-    - shared-components
-    - design-system
-  admin:
-    - admin-panel
-    - user-dashboard
-    - shared-components
-  ui:
-    - shared-components
-    - design-system
+```toml
+[groups]
+all = ["main-app", "admin-panel", "user-dashboard", "shared-components", "design-system"]
+core = ["main-app", "shared-components", "design-system"]
+admin = ["admin-panel", "user-dashboard", "shared-components"]
+ui = ["shared-components", "design-system"]
 ```
 
 ### Team Collaboration
@@ -456,11 +485,10 @@ groups:
 
 ### Custom Start Commands
 
-By default, mfer runs `npm start` in each project directory.
-You can currently only customize this by modifying the run command in the source code.
+By default, mfer runs `npm start` in each project directory. You can customize this in two ways:
 
-Adding configurable custom start commands is something I plan on adding in the near future.
-I also welcome anyone to open a PR for that!
+- **Same command for all MFEs**: use `--command` (e.g. `mfer run --command "yarn start"`)
+- **Per-MFE commands via modes**: define `mfes[name].modes` in config and use `--mode` (see [Per-MFE Run Modes](#per-mfe-run-modes))
 
 ### Environment Variables
 
@@ -544,4 +572,5 @@ Built with:
 - [Inquirer](https://github.com/SBoudrias/Inquirer.js) - Interactive prompts
 - [Concurrently](https://github.com/open-cli-tools/concurrently) - Process management
 - [Chalk](https://github.com/chalk/chalk) - Terminal styling
-- [YAML](https://github.com/eemeli/yaml) - Configuration parsing
+- [smol-toml](https://github.com/squirrelchat/smol-toml) - Configuration parsing
+- [YAML](https://github.com/eemeli/yaml) - Legacy config parsing for `mfer config migrate`

package/dist/commands/config/index.js

@@ -1,7 +1,9 @@
 import { Command } from "commander";
 import { listConfigCommand } from "./sub-commands/list-config.js";
 import { editConfigCommand } from "./sub-commands/edit-config.js";
+import { migrateConfigCommand } from "./sub-commands/migrate.js";
 const configCommand = new Command("config").description("configuration settings");
 configCommand.addCommand(listConfigCommand);
 configCommand.addCommand(editConfigCommand);
+configCommand.addCommand(migrateConfigCommand);
 export default configCommand;

package/dist/commands/config/sub-commands/migrate.js

@@ -0,0 +1,86 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { Command } from "commander";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import chalk from "chalk";
+import YAML from "yaml";
+import { stringify as stringifyToml } from "smol-toml";
+import { confirm } from "@inquirer/prompts";
+import { isParsedConfigValid, } from "../../../utils/config-utils.js";
+const yamlConfigPath = path.join(os.homedir(), ".mfer/config.yaml");
+const tomlConfigPath = path.join(os.homedir(), ".mfer/config.toml");
+export const migrateConfigCommand = new Command("migrate")
+    .description("migrate a legacy YAML config to TOML")
+    .action(() => __awaiter(void 0, void 0, void 0, function* () {
+    if (!fs.existsSync(yamlConfigPath)) {
+        console.log(`${chalk.red("Error")}: No YAML config found at ${yamlConfigPath}`);
+        return;
+    }
+    let parsed;
+    try {
+        parsed = YAML.parse(fs.readFileSync(yamlConfigPath, "utf8"));
+    }
+    catch (error) {
+        console.log(`${chalk.red("Error")}: Failed to parse YAML config\n${error}`);
+        return;
+    }
+    if (!parsed || typeof parsed !== "object") {
+        console.log(`${chalk.red("Error")}: YAML config is empty or invalid`);
+        return;
+    }
+    if (!isParsedConfigValid(parsed)) {
+        console.log(`${chalk.red("Error")}: YAML config is missing required fields or is structurally invalid. Migration aborted.`);
+        return;
+    }
+    if (fs.existsSync(tomlConfigPath)) {
+        try {
+            const overwrite = yield confirm({
+                message: `${tomlConfigPath} already exists. Overwrite?`,
+                default: false,
+            });
+            if (!overwrite) {
+                console.log(chalk.yellow("Migration cancelled."));
+                return;
+            }
+        }
+        catch (error) {
+            console.log(`${chalk.red("Error")}: Unable to prompt for overwrite\n${error}`);
+            return;
+        }
+    }
+    try {
+        fs.writeFileSync(tomlConfigPath, stringifyToml(parsed));
+    }
+    catch (error) {
+        console.log(`${chalk.red("Error")}: Failed to write TOML config\n${error}`);
+        return;
+    }
+    console.log(chalk.green(`Migrated config written to ${tomlConfigPath}`));
+    let removeOld = false;
+    try {
+        removeOld = yield confirm({
+            message: `Delete the legacy ${yamlConfigPath}?`,
+            default: false,
+        });
+    }
+    catch (error) {
+        console.log(`${chalk.yellow("Warning")}: Unable to prompt for legacy deletion — leaving legacy config in place\n${error}`);
+        return;
+    }
+    if (removeOld) {
+        fs.unlinkSync(yamlConfigPath);
+        console.log(chalk.green(`Removed ${yamlConfigPath}`));
+    }
+    else {
+        console.log(chalk.yellow(`Legacy config left in place at ${yamlConfigPath}. You can delete it manually.`));
+    }
+}));

package/dist/commands/init.js

@@ -33,7 +33,7 @@ function createAndSaveConfig(githubUsername, mfeDirectory, allGroup = [], libDir
     console.log(chalk.blue(`Config file saved to: ${configPath}`));
     console.log(chalk.yellow("You can edit the config file later using: mfer config edit"));
     if (allGroup.length === 0) {
-        console.log(chalk.yellow("\nNote: Placeholder repository names have been added to show proper YAML syntax."));
+        console.log(chalk.yellow("\nNote: Placeholder repository names have been added to show proper TOML syntax."));
         console.log(chalk.yellow("Please replace 'my_mfe_1' and 'my_mfe_2' with your actual repository names."));
     }
     if (libDirectory && libs.length > 0) {

package/dist/commands/run.js

@@ -12,15 +12,15 @@ import { configExists, currentConfig, warnOfMissingConfig, } from "../utils/conf
 import concurrently from "concurrently";
 import chalk from "chalk";
 import path from "path";
-import { promptForMFESelection } from "../utils/command-utils.js";
+import { promptForMFESelection, resolveRunCommand, } from "../utils/command-utils.js";
 import { spawn } from "child_process";
-const DEFAULT_RUN_COMMAND = "npm start";
 const runCommand = new Command("run")
     .description("run micro-frontend applications")
     .argument("[group_name]", "name of the group as specified in the configuration", "all")
     .option("-s, --select", "prompt to select which micro frontends to run")
     .option("-c, --command <command>", "custom command to run (default: npm start)")
     .option("-a, --async", "run custom command concurrently instead of sequentially (only works with --command option)")
+    .option("-m, --mode <mode_name>", "run MFEs using a named mode from config")
     .action((groupName, options) => __awaiter(void 0, void 0, void 0, function* () {
     if (!configExists) {
         warnOfMissingConfig();
@@ -33,11 +33,16 @@ const runCommand = new Command("run")
         console.log(`${messagePrefix}: custom command cannot be empty`);
         return;
     }
-    if (options.async && !options.command) {
+    if (options.async && !options.command && !options.mode) {
         const messagePrefix = chalk.red("Error");
         console.log(`${messagePrefix}: --async can only be used with --command option`);
         return;
     }
+    if (options.mode && options.command) {
+        const messagePrefix = chalk.red("Error");
+        console.log(`${messagePrefix}: --mode and --command cannot be used together`);
+        return;
+    }
     const group = currentConfig.groups[groupName];
     if (!group) {
         const messagePrefix = chalk.red("Error");
@@ -54,26 +59,42 @@ const runCommand = new Command("run")
     if (options.select) {
         selectedMFEs = yield promptForMFESelection(groupName, group);
     }
+    if (options.mode) {
+        const hasAnyMfeWithMode = selectedMFEs.some((mfe) => {
+            var _a, _b, _c;
+            return (_c = (_b = (_a = currentConfig.mfes) === null || _a === void 0 ? void 0 : _a[mfe]) === null || _b === void 0 ? void 0 : _b.modes) === null || _c === void 0 ? void 0 : _c.some((m) => m.mode_name === options.mode);
+        });
+        if (!hasAnyMfeWithMode) {
+            console.log(chalk.yellow(`Warning: no MFE in the selected group has a '${options.mode}' mode defined. All MFEs will use the default command.`));
+        }
+    }
     const mfeDir = currentConfig.mfe_directory;
-    const commandToRun = options.command || DEFAULT_RUN_COMMAND;
     const isAsync = options.async && options.command;
+    const mfeCommands = selectedMFEs.map((mfe) => ({
+        mfe,
+        command: options.command
+            ? options.command
+            : resolveRunCommand(mfe, options.mode, currentConfig),
+    }));
     const groupText = options.select
         ? `selected MFEs from group '${groupName}'`
         : `group '${groupName}'`;
     const commandText = options.command
-        ? `custom command '${commandToRun}'`
-        : "default command";
+        ? `custom command '${options.command}'`
+        : options.mode
+            ? `mode '${options.mode}'`
+            : "default command";
     console.log(chalk.green(`Running ${commandText} on micro frontends in ${groupText}...`));
     if (isAsync || !options.command) {
-        yield runConcurrently(selectedMFEs, commandToRun, mfeDir);
+        yield runConcurrently(mfeCommands, mfeDir);
     }
     else {
-        yield runSequentially(selectedMFEs, commandToRun, mfeDir);
+        yield runSequentially(mfeCommands, mfeDir);
     }
 }));
-function runSequentially(mfes, command, mfeDir) {
+function runSequentially(mfeCommands, mfeDir) {
     return __awaiter(this, void 0, void 0, function* () {
-        for (const mfe of mfes) {
+        for (const { mfe, command } of mfeCommands) {
             const cwd = path.join(mfeDir, mfe);
             console.log(chalk.blue(`\n[${mfe}] Running: ${command}`));
             try {
@@ -101,9 +122,9 @@ function runSequentially(mfes, command, mfeDir) {
         }
     });
 }
-function runConcurrently(mfes, command, mfeDir) {
+function runConcurrently(mfeCommands, mfeDir) {
     return __awaiter(this, void 0, void 0, function* () {
-        const commands = mfes.map((mfe) => ({
+        const commands = mfeCommands.map(({ mfe, command }) => ({
             command,
             name: mfe,
             cwd: path.join(mfeDir, mfe),

package/dist/index.js

@@ -9,11 +9,11 @@ import pullCommand from "./commands/pull.js";
 import libCommand from "./commands/lib/index.js";
 import updateCommand from "./commands/update.js";
 import { loadConfig } from "./utils/config-utils.js";
-import { checkForUpdateNotification } from "./utils/version-utils.js";
+import { checkForUpdateNotification, getInstalledVersion, } from "./utils/version-utils.js";
 program
     .name("mfer")
     .description("Micro Frontend Runner (mfer) - A CLI for running your project's micro frontends.")
-    .version("3.2.4", "-v, --version", "mfer CLI version")
+    .version(getInstalledVersion(), "-v, --version", "mfer CLI version")
     .hook("preAction", () => {
     console.log();
 })

package/dist/utils/command-utils.js

@@ -13,6 +13,14 @@ import { spawnSync } from "child_process";
 import concurrently from "concurrently";
 import path from "path";
 import fs from "fs";
+export const DEFAULT_RUN_COMMAND = "npm start";
+export function resolveRunCommand(mfe, modeName, config) {
+    var _a, _b, _c, _d;
+    if (!modeName)
+        return DEFAULT_RUN_COMMAND;
+    const mode = (_c = (_b = (_a = config.mfes) === null || _a === void 0 ? void 0 : _a[mfe]) === null || _b === void 0 ? void 0 : _b.modes) === null || _c === void 0 ? void 0 : _c.find((m) => m.mode_name === modeName);
+    return (_d = mode === null || mode === void 0 ? void 0 : mode.command) !== null && _d !== void 0 ? _d : DEFAULT_RUN_COMMAND;
+}
 export function promptForMFESelection(groupName, mfes) {
     return __awaiter(this, void 0, void 0, function* () {
         var _a, _b;

package/dist/utils/config-utils.js

@@ -1,45 +1,73 @@
 import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
-import YAML from "yaml";
+import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
 import chalk from "chalk";
 import { spawn } from "child_process";
-export const configPath = path.join(os.homedir(), ".mfer/config.yaml");
+export const configPath = path.join(os.homedir(), ".mfer/config.toml");
+export const legacyYamlConfigPath = path.join(os.homedir(), ".mfer/config.yaml");
 export const configExists = fs.existsSync(configPath);
+export const legacyYamlConfigExists = fs.existsSync(legacyYamlConfigPath);
 export let currentConfig;
 export const loadConfig = () => {
     if (configExists) {
         const configFile = fs.readFileSync(configPath, "utf8");
-        currentConfig = YAML.parse(configFile);
+        currentConfig = parseToml(configFile);
         return currentConfig;
     }
     return undefined;
 };
 export const warnOfMissingConfig = () => {
     if (!configExists) {
+        if (legacyYamlConfigExists) {
+            console.log(`${chalk.red("Error")}: No TOML configuration file detected, but a legacy YAML config was found at ${legacyYamlConfigPath}\n       Please run ${chalk.blue.bold("mfer config migrate")} to convert it to TOML`);
+            return;
+        }
         console.log(`${chalk.red("Error")}: No configuration file detected\n       Please run ${chalk.blue.bold("mfer init")} to create one`);
     }
 };
+export const isParsedConfigValid = (parsed) => {
+    const config = parsed;
+    const hasRequiredFields = Boolean(config &&
+        typeof config === "object" &&
+        config.base_github_url &&
+        config.mfe_directory &&
+        config.groups &&
+        typeof config.groups === "object" &&
+        config.groups.all &&
+        Array.isArray(config.groups.all) &&
+        config.groups.all.length > 0);
+    if (!hasRequiredFields)
+        return false;
+    if (config.lib_directory && (!config.libs || !Array.isArray(config.libs))) {
+        return false;
+    }
+    if (config.mfes && typeof config.mfes === "object") {
+        for (const mfeConfig of Object.values(config.mfes)) {
+            if (mfeConfig && mfeConfig.modes !== undefined) {
+                const modes = mfeConfig.modes;
+                if (!Array.isArray(modes))
+                    return false;
+                for (const mode of modes) {
+                    if (!mode ||
+                        typeof mode !== "object" ||
+                        !mode.mode_name ||
+                        !mode.command) {
+                        return false;
+                    }
+                }
+            }
+        }
+    }
+    return true;
+};
 export const isConfigValid = () => {
     if (!configExists) {
         return false;
     }
     try {
         const configFile = fs.readFileSync(configPath, "utf8");
-        const config = YAML.parse(configFile);
-        const hasRequiredFields = config &&
-            typeof config === "object" &&
-            config.base_github_url &&
-            config.mfe_directory &&
-            config.groups &&
-            typeof config.groups === "object" &&
-            config.groups.all &&
-            Array.isArray(config.groups.all) &&
-            config.groups.all.length > 0;
-        if (config.lib_directory && (!config.libs || !Array.isArray(config.libs))) {
-            return false;
-        }
-        return hasRequiredFields;
+        return isParsedConfigValid(parseToml(configFile));
     }
     catch (_a) {
         return false;
@@ -51,7 +79,7 @@ export const saveConfig = (newConfig) => {
         if (!fs.existsSync(configDir)) {
             fs.mkdirSync(configDir, { recursive: true });
         }
-        fs.writeFileSync(configPath, YAML.stringify(newConfig));
+        fs.writeFileSync(configPath, stringifyToml(newConfig));
     }
     catch (error) {
         console.log(`Error writing config file!\n\n${error}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mfer",
-  "version": "3.2.4",
+  "version": "4.0.0",
   "description": "CLI tool designed to sensibly run micro-frontends from the terminal.",
   "bin": {
     "mfer": "dist/index.js"
@@ -57,6 +57,7 @@
     "chalk": "^5.6.2",
     "commander": "^14.0.0",
     "concurrently": "^9.2.0",
+    "smol-toml": "^1.6.1",
     "yaml": "^2.8.0"
   },
   "files": [