configre 1.1.8 → 1.1.10

package/README.md

@@ -4,7 +4,7 @@ Welcome to Configre, the coolest way to manage your project's configuration with
 
 ## ✨ Features
 
-- **Environment-Specific Configurations**: Automatically loads configurations based on the hostname or a custom profile passed via command line arguments.
+- **Environment-Specific Configurations**: Automatically loads configurations based on the hostname or a custom profile forced via `--config=<profile>` CLI argument.
 - **Fallback to Defaults**: Uses a default configuration as a baseline, ensuring your application always has the necessary settings.
 - **Easy Integration**: A simple setup process that integrates effortlessly into any project.
 - **Support for `.cjs` Config Files**: Config files must use the `.cjs` extension. This allows dynamic configuration values and comments, and works the same in both CommonJS and ESM projects.
@@ -80,6 +80,17 @@ module.exports = {
 
 Configre merges these configurations based on your environment, making your app adaptable and easier to manage.
 
+## 🎯 Forcing a Profile
+
+You can override the hostname-based profile detection by passing `--config=<profile>` anywhere in the CLI arguments:
+
+```bash
+node app.js --config=staging
+node app.js --port=3000 --config=production --debug
+```
+
+This loads `config/staging.cjs` (or `config/staging.dev.cjs`) regardless of the hostname. The `--config=` flag is safe to use alongside any other arguments.
+
 ## 🤔 Why Configre?
 
 - **No More Manual Switching**: Automatically adjusts your configuration based on the environment.

package/index.js

@@ -12,7 +12,8 @@ class ConfigreClass {
         ]);
         
         this.dirname = path;
-        this.profile = process.argv.length > 2 ? process.argv[2] : os.hostname();
+        const configArg = process.argv.find(arg => arg.startsWith('--config='));
+        this.profile = configArg ? configArg.slice('--config='.length) : os.hostname();
         this.profileSettings = this.loadProfileSettings();
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "configre",
-  "version": "1.1.8",
+  "version": "1.1.10",
   "description": "🔧 Effortlessly Tailor Your Settings",
   "dependencies": {
     "lemonlog": "^1.0.2",

package/skills/configre/SKILL.md

@@ -20,23 +20,17 @@ npm install configre --save
 
 ### Step 2: Create the config directory
 
+Config files **must always use the `.cjs` extension**. This works in both CommonJS and ESM projects and allows using `module.exports`.
+
 ```
 project/
 ├── config/
-│   ├── index.js          # Default settings (required)
-│   ├── myhostname.js     # Host-specific overrides (optional)
-│   └── myhostname.dev.js # Dev override for host (optional)
+│   ├── index.cjs          # Default settings (required)
+│   ├── myhostname.cjs     # Host-specific overrides (optional)
+│   └── myhostname.dev.cjs # Dev override for host (optional)
 ```
 
-If the project uses `"type": "module"` in `package.json`, create `config/package.json`:
-
-```json
-{ "type": "commonjs" }
-```
-
-This is needed because config files use `module.exports`.
-
-### Step 3: Write the default config (`config/index.js`)
+### Step 3: Write the default config (`config/index.cjs`)
 
 ```javascript
 module.exports = {
@@ -55,7 +49,7 @@ module.exports = {
 
 ### Step 4: Write host/profile overrides
 
-Create `config/<hostname>.js` with only the keys that differ — they are deep-merged over defaults:
+Create `config/<hostname>.cjs` with only the keys that differ — they are deep-merged over defaults:
 
 ```javascript
 module.exports = {
@@ -83,31 +77,40 @@ const cfg = require("configre")(__dirname + "/settings");
 
 ## Profile resolution
 
-Configre determines the active profile from `process.argv[2]` (CLI argument) or `os.hostname()` as fallback. It then checks for overrides in this order (first match wins):
+Configre determines the active profile by looking for a `--config=<profile>` argument anywhere in `process.argv`, or falls back to `os.hostname()`. It then checks for overrides in this order (first match wins):
 
-1. `config/<profile>.dev.js` or `.cjs` — dev override
-2. `config/<profile>.js` or `.cjs` — production override
+1. `config/<profile>.dev.cjs` — dev override
+2. `config/<profile>.cjs` — production override
 3. No match — uses defaults only
 
+To force a specific profile at runtime:
+
+```bash
+node app.js --config=staging
+node app.js --port=3000 --config=production --debug
+```
+
+Using `--config=` (instead of a positional argument) avoids conflicts with other CLI flags.
+
 ## Examples
 
 **Example 1: Basic setup**
 User says: "Add configuration management to my Node.js project"
-Actions: install configre, create `config/index.js` with project defaults, load with `require("configre")()`
+Actions: install configre, create `config/index.cjs` with project defaults, load with `require("configre")()`
 Result: merged config object ready to use
 
 **Example 2: Multi-environment**
 User says: "I need different database settings per server"
-Actions: create `config/index.js` with defaults, create `config/<hostname>.js` per server with db overrides
+Actions: create `config/index.cjs` with defaults, create `config/<hostname>.cjs` per server with db overrides
 Result: each server automatically loads its own config based on hostname
 
 **Example 3: Custom profile via CLI**
 User says: "I want to run my app with a staging config"
-Actions: create `config/staging.js`, run app with `node app.js staging`
-Result: staging overrides are merged over defaults
+Actions: create `config/staging.cjs`, run app with `node app.js --config=staging`
+Result: staging overrides are merged over defaults, without conflicting with other CLI arguments
 
 ## Key behaviors
 
 - **Deep merge**: nested objects merge recursively via lodash `_.merge`
-- **Both `.js` and `.cjs`** extensions are supported for all config files
+- **Config files must use the `.cjs` extension** (works in both CommonJS and ESM projects)
 - **Function vs constructor**: `Configre(path)` returns the merged config directly; `new Configre(path)` returns the instance (use `.get()` to retrieve config)