configre 2.1.4 → 2.1.6

package/README.md

@@ -1,151 +1,126 @@
-# 🔧 Configre
+# Configre
 
-Welcome to Configre, the coolest way to manage your project's configuration with a twist of personality based on your environment! Whether you're in development, testing, or production, Configre seamlessly adjusts to your project's needs by loading specific configurations tailored to each environment. Say goodbye to manual config tweaks and hello to automatic, hassle-free setup! 🚀
+Define your defaults once. Let each environment describe what changes. Keep secrets alongside the settings they belong to.
 
-## ✨ Features
+Configre loads a base configuration, merges in a host or profile, and returns a plain JavaScript object. Configuration lives in `.cjs` files, so you get nested objects, comments, and ordinary JavaScript. Optional secret files follow the same structure and can be shared with your servers through encrypted files in Git.
 
-- **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 Only**: Config files must use the `.cjs` extension. This allows dynamic configuration values and comments, and works the same in both CommonJS and ESM projects.
+## Quick start
 
-## 🌟 Getting Started
+Requires **Node.js 22.13 or later**.
 
-To get started with Configre, follow these steps:
-
-1. **Install the Library**
-
-   Configre requires **Node.js 22.13 or later**. Add it to your project:
-
-   ```bash
-   npm install configre --save
-   ```
-
-> You can also add Configre as a skill for AI agentic development:
-> ```bash
-> npx skills add https://github.com/clasen/Configre --skill configre
-> ```   
-
-2. **Setup Your Configuration Files**
-
-   Organize your configuration files within a directory (e.g., `config`). Create a default configuration file and environment-specific files as needed.
-
-   - `index.cjs`: Your default configuration.
-   - `[hostname].cjs`: Override configurations for specific hosts.
-   - `[hostname].dev.cjs`: Development-specific configurations.
-
-   > **Note:** Config files must always use the `.cjs` extension; `.js` config files are not accepted. That way they work in both CommonJS and ESM projects and you can use `module.exports` in them.
-
-3. **Use Configre in Your Project**
-
-   Import and use Configre to load your configurations. The configuration path is required:
+```bash
+npm install configre
+```
 
-   ```javascript
-   import Configre from "configre";
-   import { join } from "node:path";
+Create `config/index.cjs` with your defaults:
 
-   const cfg = Configre(join(import.meta.dirname, "config"));
-   console.log(cfg.db); // Access your db configuration
-   ```
+```javascript
+module.exports = {
+    db: {
+        host: "localhost",
+        port: 5432
+    },
+    api: {
+        url: "https://api.example.com"
+    }
+};
+```
 
-   Prefer an absolute path anchored to the module, as above. Avoid deriving it from `process.cwd()` (for example, `path.join(process.cwd(), "config")`), because that can point to a different location depending on where the process is started.
+Load it from `app.mjs`, next to the `config` directory:
 
-   Configre is a native ES module. CommonJS consumers keep the same synchronous API, without accessing `.default`:
+```javascript
+import Configre from "configre";
+import { join } from "node:path";
 
-   ```javascript
-   const Configre = require("configre");
-   const { join } = require("node:path");
+const cfg = Configre(join(import.meta.dirname, "config"));
+console.log(cfg.db.port); // 5432
+```
 
-   const cfg = Configre(join(__dirname, "config"));
-   ```
+```bash
+node app.mjs
+```
 
-   Both module systems share the same implementation. Existing configuration files stay in `.cjs` format; Configre uses Node's `createRequire` only to load these files synchronously.
+The configuration path is required. Anchor it to your module so starting the process from another directory does not change which configuration it loads. Avoid building this path from `process.cwd()`.
 
-## 📚 Example
+Configre is a native ES module. CommonJS consumers can also use the synchronous API: `require("configre")` returns the function directly. Configuration files use `.cjs` and `module.exports` in either kind of project.
 
-Imagine you have the following structure in your `config` directory:
+## Configuration that builds on defaults
 
-- `index.cjs`: Contains default settings.
-- `myhostname.cjs`: Contains overrides for the host named `myhostname`.
+An environment should describe what changes. Everything else comes from the base.
 
-Your `index.cjs` might look like this:
+Add `config/production.cjs`:
 
 ```javascript
 module.exports = {
     db: {
-        host: 'localhost',
-        user: 'myuser',
-        password: 'mypassword'
-    },
-    api: {
-        key: 'development-api-key'
+        host: "db.internal",
+        ssl: true
     }
-}
+};
+```
+
+Select that profile:
+
+```bash
+node app.mjs --config=production
 ```
 
-And your `myhostname.cjs`:
+The resulting configuration contains:
 
 ```javascript
-module.exports = {
+{
     db: {
-        user: 'john',
-        password: 'johns-password'
+        host: "db.internal",
+        port: 5432,
+        ssl: true
+    },
+    api: {
+        url: "https://api.example.com"
     }
 }
 ```
 
-Configre merges these configurations based on your environment, making your app adaptable and easier to manage.
+`host` is overwritten, `port` is inherited, and `ssl` is added. The `api` object stays intact. A profile can extend nested objects without repeating their other fields.
 
-## 🎯 Forcing a hostname / config
+### Selecting a profile
 
-By default Configre uses the machine’s hostname to choose the config file (e.g. `config/<hostname>.cjs`). You can force which hostname or profile to use with the `--config=<hostname>` CLI argument:
+By default, Configre uses the machine's hostname. A machine named `web-01` loads `config/web-01.cjs`. Pass `--config=<profile>` to choose a name explicitly; the flag can appear alongside other application arguments.
 
-```bash
-node demo.js --config=staging
-node demo.js --config=production
-node demo.js --port=3000 --config=myhost --debug
-```
+| File | Role |
+| --- | --- |
+| `index.cjs` | Base configuration |
+| `<profile>.cjs` | Additions and overrides for the selected profile |
+| `<profile>.dev.cjs` | Preferred over `<profile>.cjs` when present |
 
-This loads `config/staging.cjs` (or `config/staging.dev.cjs`) instead of the one for the actual hostname. The `--config=` flag can appear anywhere in the command and works alongside other arguments.
+If no profile file exists, Configre uses the base configuration. When `production.dev.cjs` exists, it is selected **instead of** `production.cjs`; those two files do not merge. This selection depends on the files present, not on `NODE_ENV`.
 
-## 🔐 Shared secrets: follow the demo
+Objects merge recursively. Later values override matching fields. Arrays merge **by index**, rather than being replaced as a whole: `["a", "b"]` followed by `["c"]` becomes `["c", "b"]`.
 
-The [secrets demo](demo/secrets/) shows how to keep API keys out of your public configuration and share them with a server through Git. Use one checkout as the **administrator**, where you edit secrets, and another as the **server**, which reads the encrypted values.
+## Secrets, organized like your configuration
 
-Run the commands below from the repository root. In [demo/secrets/demo.js](demo/secrets/demo.js), the configuration is loaded with:
+Database credentials belong under `db`. API keys belong under `api`. Secret files keep that organization while separating sensitive values from public settings.
 
-```javascript
-import Configre from "../../index.js";
-import { join } from "node:path";
-
-const configPath = join(import.meta.dirname, "config");
-const cfg = Configre(configPath);
+```text
+config/
+  index.cjs               # Shared public settings
+  production.cjs          # Production additions and overrides
+  index.secret.cjs        # Shared secrets, edited locally
+  production.secret.cjs   # Production secrets, edited locally
 ```
 
-Secrets activate automatically when the base configuration or selected profile has a corresponding `.secret.cjs` file, or when `secrets.enc.json` already exists. No options are needed. Loading remains synchronous, and your application reads the result through ordinary properties such as `cfg.api.key`.
+A secret file exports only the fields it needs to supply. Your application reads them through ordinary properties such as `cfg.api.key`; there is no separate secrets API. Define sensitive fields in secret files; public configuration does not need placeholders for them.
 
-> The demo reports `API key configured:` without printing the key. Avoid logging `cfg` in your application: it contains the decrypted secrets. Use `cfg.print()` to log configuration with secret fields omitted.
+For `--config=production`, the merge order is:
 
-```javascript
-const cfg = Configre(configPath);
-cfg.print();
+```text
+index.cjs → production.cjs → index.secret.cjs → production.secret.cjs
 ```
 
-`print()` calls Configre's `log.debug`; enable its output with `DEBUG=Configre:*`.
-It omits fields supplied by the base and selected profile's `.secret.cjs` files,
-including when loaded from the encrypted file. Public siblings in nested objects
-remain visible; arrays supplied by secrets are omitted entirely. It does not
-modify the configuration or log automatically on load. `cfg.print()` logs its
-current values, including changes made after loading. The method is non-enumerable
-and does not appear in `Object.keys(cfg)`, object spreads or JSON output.
-`new Configre(configPath).print()` is also supported. If your configuration already
-has a field named `print`, that value is preserved; use the constructor API to print it.
-Sensitivity is determined by secret-file fields, not by names such as `password`
-or `token`: keep sensitive values in `.secret.cjs` files, not in public settings.
+Later layers win. Shared secrets can be extended or overwritten by profile secrets, just like public settings. Secret selection independently prefers `production.dev.secret.cjs` over `production.secret.cjs`; it does not merge the two variants.
 
-### 1. Start the demo on the administrator machine
+### Add your secrets
 
-For this walkthrough, use an empty public placeholder in [demo/secrets/config/index.cjs](demo/secrets/config/index.cjs):
+Create `config/index.secret.cjs` for shared values:
 
 ```javascript
 module.exports = {
@@ -155,175 +130,144 @@ module.exports = {
 };
 ```
 
-Create `demo/secrets/config/index.secret.cjs` yourself to enable secrets, initially with:
+For a production API key, create `config/production.secret.cjs`:
 
 ```javascript
-module.exports = {};
-```
-
-Then run:
-
-```bash
-node demo/secrets/demo.js
+module.exports = {
+    api: {
+        key: ""
+    }
+};
 ```
 
-For a new setup, Configre generates the encrypted file, recipients directory and Git exclusions alongside your existing configuration files:
+Fill in the values in these local files. The production key overrides the shared key when that profile is selected, while `api.url` still comes from the public configuration. Configre generates `secrets.enc.json` and adds Git exclusions for the editable secret files when your application runs.
 
-```text
-demo/secrets/config/
-  index.cjs          # Public configuration
-  index.secret.cjs   # Editable secrets you create yourself
-  recipients/        # Public keys of servers that register
-  secrets.enc.json   # Generated encrypted values
-  .gitignore         # Keeps .secret.cjs files out of Git
-```
+### Share with a server
 
-It also creates this OS user's identity outside the repository, at `~/.config/configre/identity.pem` and `identity.pub`.
+1. **Local:** run your application and push the generated encrypted file.
+2. **Server:** pull and run. On the first run, Configre automatically commits and pushes the server's public key as `recipients/<profile>.pub` (or `<hostname>.pub` when no profile is specified).
+3. **Local:** pull, run again to include that public key in the encrypted file, and push.
+4. **Server:** pull and restart. The secrets are now available through `cfg`.
 
-With the public placeholder empty and no secrets added, look for:
+The server needs Git push access for registration. Until the updated encrypted file arrives, Configre loads public settings only.
 
-```text
-API key configured: false
-```
+To update secrets later, edit them locally, run, and push. Pull and restart on the server. Registration happens only once per identity.
 
-**Configre never creates `.secret.cjs` files.** Without a secret counterpart for the base configuration or selected profile, and without an encrypted file, it loads only public settings and creates no identity or secret artifacts. A secret module contains only the fields you choose to override; public settings continue to come from `index.cjs`.
+**Profiles organize secrets; they do not isolate access.** Authorized identities can decrypt all profiles in the encrypted file. Pulling a new registration and publishing the updated encrypted file grants that identity access.
 
-These initialization steps describe a new setup. If `secrets.enc.json` already exists, Configre uses that encrypted file instead of resetting it. A checkout containing the encrypted file but no `.secret.cjs` files is treated as a server checkout.
+## Utilities
 
-### 2. Add an API key and publish the encrypted file
+### Inspect configuration with `cfg.print()`
 
-On the administrator machine, edit `demo/secrets/config/index.secret.cjs`:
+The returned configuration contains decrypted secrets. Use `cfg.print()` when inspecting it:
 
 ```javascript
-module.exports = {
-    api: {
-        key: ""
-    }
-};
+const cfg = Configre(join(import.meta.dirname, "config"));
+cfg.print();
 ```
 
-Replace the empty string with your actual key **in this local file**, then run the demo again:
+Enable its debug output with:
 
 ```bash
-node demo/secrets/demo.js
+DEBUG=Configre:* node app.mjs --config=production
 ```
 
-Configre updates `demo/secrets/config/secrets.enc.json`, merges the secret into the configuration, and the demo reports:
+`print()` omits fields supplied by the base and selected profile's secret files, including when those values come from the encrypted file. Public siblings remain visible; arrays supplied by secrets are omitted entirely. Omission is based on secret-file fields, not names such as `password` or `token`. Keep sensitive values in secret files.
 
-```text
-API key configured: true
-```
+It logs current values, including edits made after loading, without changing the configuration. It does not log automatically on load. The method is non-enumerable, so it stays out of `Object.keys(cfg)`, spreads, and JSON output. Spreads and JSON output still include the configuration's secret values.
 
-Commit and push the demo's public files, including `config/index.cjs`, the generated `config/.gitignore`, and `config/secrets.enc.json`. Keep `config/index.secret.cjs` on the administrator machine.
+The constructor API is also available:
 
-| File in `demo/secrets/config/` | Purpose | Share through Git? |
-| --- | --- | --- |
-| `index.cjs` | Public settings and empty placeholders | Yes |
-| `index.secret.cjs` | Values you edit on the administrator | No |
-| `secrets.enc.json` | Encrypted values generated by Configre | Yes |
-| `recipients/truco.pub` | Public identity of the server named `truco` | Yes; the server publishes it |
-| `.gitignore` | Excludes editable secret files | Yes |
+```javascript
+const config = new Configre(join(import.meta.dirname, "config"));
+const cfg = config.get();
+config.print();
+```
 
-### 3. Register the server as `truco`
+If your configuration already has a field named `print`, Configre preserves it. Use the constructor API to print in that case.
 
-On the server, clone or pull the repository **including `demo/secrets/config/secrets.enc.json`**. Use a branch with a configured upstream, Git author name/email, and credentials that allow a push without an interactive prompt. Before a new registration, the local branch must match its upstream.
+### Apply environment variables explicitly
 
-Run:
+Use `applyConfigEnv(cfg.env)` when a library reads its settings from `process.env`:
 
-```bash
-node demo/secrets/demo.js --config=truco
+```javascript
+import Configre, { applyConfigEnv } from "configre";
+import { join } from "node:path";
+
+const cfg = Configre(join(import.meta.dirname, "config"));
+applyConfigEnv(cfg.env);
 ```
 
-`--config=truco` selects the profile and names the public-key file. Without this flag, Configre uses the hostname.
+For CommonJS, use `const { applyConfigEnv } = require("configre")`.
 
-If this server is not authorized yet, Configre automatically:
+The helper converts values with `String(value)` and sets only variables that are undefined in `process.env`. Existing values, including empty strings, are preserved. An undefined `cfg.env` does nothing; null or undefined entries are skipped.
 
-1. Creates its local identity, if needed.
-2. Writes `demo/secrets/config/recipients/truco.pub`.
-3. Creates and pushes a commit containing only that public-key file.
-4. Logs a warning and continues with public configuration only until the administrator publishes an updated encrypted file.
+It rejects null, arrays and non-objects as `cfg.env`, empty keys, and object-valued entries. Entries are processed in order; an invalid entry throws without undoing previous assignments. Loading Configre does not call this helper automatically, and empty placeholders are never filled from environment variables automatically.
 
-Publishing a public key does not let the server decrypt the existing ciphertext. While authorization is pending, `cfg` preserves the public defaults and selected public profile; fields that exist only in the encrypted file are absent. Repeating the command does not publish another registration commit for the same key. If Git registration fails, Configre logs a warning and still returns public settings; the next Configre load retries registration.
+## Advanced reference
 
-Configre uses `log.info` when it creates identity files, writes Git exclusions, creates the recipients directory or a public-key file, updates the encrypted file, and successfully pushes the public key. Messages contain operation names and file paths, never secret values or key contents. These messages use the existing `Configre` LemonLog namespace; use `DEBUG=Configre:*` to display them. Unchanged files and previously published public keys do not generate another creation or publication log.
+<details>
+<summary>Secret formats, identities, Git behavior, and recovery</summary>
 
-### 4. Include the server in the encrypted file
+### Secret files and loading
 
-Back on the administrator machine:
+Secret `.cjs` modules execute locally on the machine where you edit them and are reloaded on each Configre call. They must export plain objects containing JSON-compatible objects, arrays, strings, finite numbers, booleans, and `null`. Functions, `undefined`, accessors, symbols, custom objects, circular references, and properties named `__proto__`, `constructor`, or `prototype` are rejected. Servers decrypt data without executing these modules.
 
-```bash
-git pull --ff-only
-node demo/secrets/demo.js
-```
+Secrets activate when the base or selected profile has a secret counterpart, or when the encrypted file already exists. Without either, loading public configuration creates no secret artifacts. Once active, all local profile secret files are encrypted together, including inactive profiles.
 
-The pull brings in `demo/secrets/config/recipients/truco.pub`. When the demo runs, Configre automatically includes that public key and regenerates `demo/secrets/config/secrets.enc.json`. There is no separate approval step.
+A selected profile's secret file can activate secrets without `index.secret.cjs`. A public profile alone never creates a secret counterpart. A missing profile uses the available base settings and base secrets. A checkout with an encrypted file and no editable secret files acts as a consumer. Existing ciphertext is read and validated before updates; it is not reset on startup. There is no `secrets` option, and function, constructor, ESM, and CommonJS usage share the same behavior.
 
-Commit and push the updated encrypted file. Then, on the server:
+For an individual configuration file, sidecars live beside it: `settings.secret.cjs`, `settings.cjs.recipients/`, and `settings.cjs.secrets.enc.json`. An extensionless path resolving to `settings.cjs` uses the same sidecars.
 
-```bash
-git pull --ff-only
-node demo/secrets/demo.js --config=truco
-```
+### Identities and registration
 
-The server can now decrypt the key, and the demo reports `API key configured: true`. It does not need `index.secret.cjs`; the value reaches `cfg.api.key` through the encrypted file.
+Automatic registration requires a Git checkout with a configured upstream, Git author name/email, and credentials that allow a non-interactive push. The branch must match its upstream before a new registration. Failed registrations are retried on the next load.
 
-**Repository write access allows a machine to register for all project secrets.** Configre publishes the server's public key automatically. Pulling changes and publishing the administrator's updated encrypted file remain part of your Git/deployment workflow.
+Each OS user has one identity, stored at `~/.config/configre/identity.pem` and `identity.pub`, reused across projects. Authorization is per project. A service running under another OS user needs its own registration.
 
-### 5. Update keys or use profile-specific secrets
+Recipient files must contain a single RSA-3072 public key in PEM format, with exponent 65537, as generated by Configre. Other extensions are ignored, and duplicate keys do not add recipients. The identity encrypting the file is always included.
 
-To change the shared API key, edit `demo/secrets/config/index.secret.cjs` on the administrator and run:
+Registration names must start with a letter or digit and contain only letters, digits, dots, underscores, or hyphens. If another key already occupies `production.pub`, registration stops without overwriting it, and configuration loading continues with a warning and public settings only. Use a distinct profile or resolve the key replacement explicitly.
 
-```bash
-node demo/secrets/demo.js
-```
+Registration uses an isolated Git index and publishes only the public-key file. It preserves unrelated staged and unstaged changes, runs no commit or pre-push hooks, and does not push local tags, merge, rebase, or force-push. Repeated loads do not publish another registration commit for the same key. Each Git command has a 30-second timeout. An authorized server loads secrets without Git commands or project writes.
 
-Commit and push the updated `secrets.enc.json`, then pull and restart the demo on the server. **You do not need to copy or register `truco.pub` again.** Its existing authorization also covers new keys you add later.
+Configre appends Git exclusions without removing existing rules, including when no repository exists yet. It refuses to proceed on the machine holding editable secrets if those modules are already tracked. It does not untrack files or rewrite history.
 
-For settings specific to `truco`, add `demo/secrets/config/truco.cjs` and create `truco.secret.cjs` yourself with that profile's secrets. The secret file activates secrets when `truco` is selected, even without `index.secret.cjs`. A public profile alone never creates a secret counterpart. Once secrets are active, all profile secret files, including inactive ones, are encrypted together when the administrator runs the demo.
+### Updates, revocation, and recovery
 
-For `--config=truco`, the merge order is:
+The editable `.secret.cjs` files are the source of truth for values; `recipients/` is the source of truth for authorization. To revoke a server, remove its public-key file, run Configre locally, and commit and push both the removal and the updated encrypted file. Remove the server's repository write access too if it must not register again. Revocation protects new encrypted versions. Rotate credentials at their providers to invalidate values a server already received.
 
-```text
-index.cjs → truco.cjs → index.secret.cjs → truco.secret.cjs
-```
+Removing all recipient files revokes them on the next local load; old ciphertext does not restore them. Recover accidentally deleted public-key files from Git before reloading. Missing Git exclusions and ciphertext are regenerated on the machine holding editable secrets, and existing secret modules are never overwritten.
 
-Later files override matching fields while preserving other fields. If `truco.dev.cjs` exists, it is selected instead of `truco.cjs`. Secret selection independently prefers `truco.dev.secret.cjs` over `truco.secret.cjs`; those two secret variants do not merge with each other. A missing profile uses the available base configuration and base secrets.
+Back up editable secrets and the private identity securely. Never share or commit `identity.pem`. On POSIX, the identity directory must have owner-only permissions (`0700`), and the private file must have owner-only permissions (`0600`). On Windows, protection depends on the user profile's filesystem permissions. Private identities and secret input files cannot be symlinks.
 
-To revoke this server, remove `demo/secrets/config/recipients/truco.pub`, run the demo on the administrator, and commit and push both the removal and the updated encrypted file. Remove the server's repository write access too if it must not register itself again. Revocation protects new encrypted versions; rotate the key at its provider to invalidate a credential the server already received.
+A corrupt or missing private identity is never silently replaced. Restore it from backup, or register a new identity on a consumer. A missing public file can be regenerated from the valid private key. Losing every authorized private key makes existing ciphertext unrecoverable; surviving editable secrets can be used to create a fresh encrypted file in a new setup.
 
-<details>
-<summary>File formats, Git behavior and recovery</summary>
-
-- Secret `.cjs` modules execute on the administrator and are reloaded on each Configre call. They must export plain objects containing JSON-compatible objects, arrays, strings, finite numbers, booleans and `null`. Functions, `undefined`, accessors, symbols, custom objects, circular references, and properties named `__proto__`, `constructor` or `prototype` are rejected. Consumers decrypt data without executing these modules.
-- Empty strings stay empty strings. Configre does not fill them from environment variables or populate `process.env`. The existing deep-merge behavior, including array merging, also applies to secrets.
-- Activation depends only on the existing files; there is no `secrets` option. The same behavior applies to `new Configre(configPath).get()` and CommonJS consumers.
-- Each OS user has one identity reused across projects; authorization is per project. A service running under another OS user needs its own registration. All authorized identities can decrypt all profiles in the project's encrypted file.
-- Public recipient files must contain a single RSA-3072 public key in PEM format, with exponent 65537, as generated by Configre. Other file extensions are ignored, and duplicate keys do not add recipients. The administrator is always included.
-- Registration uses an isolated Git index and publishes only the public-key file. It preserves unrelated staged and unstaged changes, runs no commit or pre-push hooks, and does not push local tags, merge, rebase or force-push. Failed registrations can be retried at the next startup; each Git command has a 30-second timeout. An authorized server loads secrets without Git commands or project writes.
-- Registration names must start with a letter or digit and contain only letters, digits, dots, underscores or hyphens. If another key already occupies `truco.pub`, registration stops without overwriting it, and configuration loading continues with a warning and public settings only; use a distinct profile or resolve the key replacement explicitly.
-- Configre appends Git exclusions without removing existing rules and refuses to proceed on the administrator if editable secret modules are already tracked. It does not untrack files or rewrite history. It also prepares `.gitignore` when no repository exists yet.
-- The administrator's `.secret.cjs` files are the source of truth for values, and `recipients/` is the source of truth for authorization. Removing all recipient files revokes them on the next administrator reload; old ciphertext does not restore them. Recover accidentally deleted public-key files from Git before reloading. Missing Git exclusions and ciphertext are regenerated on the administrator, and existing secret modules are never overwritten.
-- Back up the administrator's editable secrets and private identity securely. Never share or commit `identity.pem`. On POSIX, its directory must have owner-only permissions (`0700`) and the private file must have owner-only permissions (`0600`); on Windows, protection depends on the user profile's filesystem permissions. Private identities and secret input files cannot be symlinks.
-- A corrupt or missing private identity is never silently replaced. Restore it from backup, or register a new identity on a consumer. A missing public file can be regenerated from the valid private key. Losing every authorized private key makes existing ciphertext unrecoverable; an administrator with surviving editable secret files can create fresh ciphertext.
-- The encrypted JSON envelope uses AES-256-GCM with a fresh content key and nonce for each update, wrapping that key for each recipient with RSA-3072 / OAEP-SHA-256. Version and recipient metadata are authenticated. Invalid modules, malformed ciphertext and authentication failures stop loading without replacing the existing encrypted file.
-- Ciphertext is replaced atomically under an exclusive writer lock. Temporary vault files contain only encrypted data and public metadata. After a crash, remove a reported stale `.lock` only after confirming its writer has stopped. Unchanged values and recipient keys do not cause a rewrite.
-- For an individual configuration file, the same workflow uses sidecars beside that file: `settings.secret.cjs`, `settings.cjs.recipients/` and `settings.cjs.secrets.enc.json`. An extensionless path resolving to `settings.cjs` uses the same sidecars.
+### Encryption and writes
+
+The encrypted JSON envelope uses AES-256-GCM with a fresh content key and nonce for each update. That key is wrapped for each recipient with RSA-3072 / OAEP-SHA-256. Version and recipient metadata are authenticated. Invalid modules, malformed ciphertext, and authentication failures stop loading without replacing the existing encrypted file.
+
+Ciphertext is replaced atomically under an exclusive writer lock. Temporary files contain only encrypted data and public metadata. After a crash, remove a reported stale `.lock` only after confirming its writer has stopped. Unchanged values and recipient keys do not cause a rewrite.
+
+### Operational logs
+
+With `DEBUG=Configre:*`, Configre reports identity creation, Git exclusions, recipient registration, encrypted-file updates, and successful public-key publication. These operation messages contain names and paths, never secret values or key contents. Unchanged files and previously published keys do not generate another creation or publication log.
 
 </details>
 
-## 🤔 Why Configre?
+## Resources and contributions
 
-- **No More Manual Switching**: Automatically adjusts your configuration based on the environment.
-- **Clarity and Convenience**: Keep your configuration organized and easy to understand.
-- **Flexibility**: Supports dynamic configuration values for complex setups.
+Explore the [basic demo](https://github.com/clasen/Configre/blob/main/demo/demo.js), [ESM project demo](https://github.com/clasen/Configre/blob/main/demo/module/demo.js), or [secrets demo](https://github.com/clasen/Configre/blob/main/demo/secrets/demo.js).
 
-## 🤝 Contribute 
+To add the Configre skill to your coding agent:
 
-Found a bug or have a feature request? Contributions are welcome! Feel free to open an issue or submit a pull request.
+```bash
+npx skills add https://github.com/clasen/Configre --skill configre
+```
 
-Let's make Configre even better, together! 🎉
+Found a bug or a useful improvement? [Open an issue](https://github.com/clasen/Configre/issues) or submit a pull request. A small, reproducible example helps.
 
-## 📄 License
+## License
 
 The MIT License (MIT)
 

package/demo/secrets/config/index.cjs

@@ -1,5 +1,5 @@
 module.exports = {
-    api: {
-        key: ""
+    "api": {
+        "url": "https://api.example.com"
     }
-};
+}

package/index.js

@@ -9,6 +9,30 @@ import loadSecrets from "./secrets/index.js";
 const requireConfig = createRequire(import.meta.url);
 const log = lemonlog("Configre");
 
+function applyConfigEnv(env) {
+    if (env === undefined) {
+        return;
+    }
+    if (env === null || typeof env !== "object" || Array.isArray(env)) {
+        throw new TypeError("config.env must be a plain object");
+    }
+
+    for (const [key, value] of Object.entries(env)) {
+        if (key.length === 0) {
+            throw new TypeError("config.env keys must be non-empty strings");
+        }
+        if (value == null) {
+            continue;
+        }
+        if (typeof value === "object") {
+            throw new TypeError(`config.env.${key} must be a scalar`);
+        }
+        if (process.env[key] === undefined) {
+            process.env[key] = String(value);
+        }
+    }
+}
+
 function omitSecrets(settings, secrets) {
     for (const [key, value] of Object.entries(secrets)) {
         if (!Object.hasOwn(settings, key)) continue;
@@ -127,4 +151,6 @@ function Configre(path) {
     }
 }
 
-export { Configre as default, Configre as "module.exports" };
+Configre.applyConfigEnv = applyConfigEnv;
+
+export { Configre as default, Configre as "module.exports", applyConfigEnv };

package/package.json

@@ -1,14 +1,11 @@
 {
   "name": "configre",
-  "version": "2.1.4",
+  "version": "2.1.6",
   "description": "🔧 Effortlessly Tailor Your Settings",
   "type": "module",
   "engines": {
     "node": ">=22.13.0"
   },
-  "scripts": {
-    "test": "node --test"
-  },
   "dependencies": {
     "lemonlog": "^1.2.2"
   },
@@ -50,7 +47,6 @@
     "url": "https://github.com/clasen/Configre/issues"
   },
   "homepage": "https://github.com/clasen/Configre#readme",
-  "packageManager": "pnpm@11.9.0",
   "files": [
     "index.js",
     "merge.js",
@@ -66,5 +62,8 @@
     "demo/module/config/hostname.cjs",
     "demo/secrets/demo.js",
     "demo/secrets/config/index.cjs"
-  ]
-}
+  ],
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/skills/configre/SKILL.md

@@ -1,126 +1,100 @@
 ---
 name: configre
-description: Set up and manage environment-specific configuration in Node.js projects using the Configre library. Use when the user wants to add configuration management, create environment configs, set up hostname-based settings, or mentions "configre", "config files", "environment config", or "per-host settings".
+description: Set up or edit Configre configuration in Node.js projects, including profile overrides, encrypted secrets, safe printing, and explicit environment-variable application.
 metadata:
   category: configuration
-  tags: [nodejs, config, environment, settings, env]
+  tags: [nodejs, config, environment, settings, secrets]
 ---
 
 # Configre
 
-Environment-specific configuration manager for Node.js. Merges a default config with hostname or profile-based overrides using deep merge (lodash).
+Load public defaults, extend or overwrite them by profile, and merge optional secrets synchronously.
 
-## Instructions
+## Setup and loading
 
-### Step 1: Install the package
+Install with `npm install configre`; requires Node.js 22.13 or later.
+Configuration files use `.cjs` and `module.exports`, including in ESM projects.
+The path is required. Anchor it to the module; avoid deriving it from `process.cwd()`.
 
-Requires Node.js 22.13 or later. Configre is native ESM and supports synchronous CommonJS consumers through the same implementation.
+```javascript
+import Configre from "configre";
+import { join } from "node:path";
 
-```bash
-npm install configre --save
+const cfg = Configre(join(import.meta.dirname, "config"));
 ```
 
-### Step 2: Create the config directory
+Create `config/index.cjs` for defaults and `config/production.cjs` for additions or overrides.
+Keep sensitive public placeholders as `""`; put actual values in secret files.
+CommonJS supports `require("configre")` directly, without `.default` or `await`.
+`Configre(path)` returns configuration; `new Configre(path)` exposes `.get()` and `.print()`.
 
-Config files **must always use the `.cjs` extension**. This works in both CommonJS and ESM projects and allows using `module.exports`.
+## Profiles and merge behavior
 
-```
-project/
-├── config/
-│   ├── index.cjs          # Default settings (required)
-│   ├── myhostname.cjs     # Host-specific overrides (optional)
-│   └── myhostname.dev.cjs # Dev override for host (optional)
-```
-
-### Step 3: Write the default config (`config/index.cjs`)
-
-```javascript
-module.exports = {
-    db: {
-        host: 'localhost',
-        port: 5432,
-        user: 'dev',
-        password: 'dev-pass'
-    },
-    api: {
-        key: 'default-key',
-        url: 'http://localhost:3000'
-    }
-};
-```
+- Select with `--config=production` anywhere in the application arguments; otherwise use `os.hostname()`.
+- Prefer `<profile>.dev.cjs` over `<profile>.cjs` when present, independently of `NODE_ENV`.
+- Select one public profile; dev and regular variants do not merge. Missing profiles use defaults.
+- Objects merge recursively: preserve unspecified fields, override matching values, and add new fields.
+- Arrays merge by index and retain trailing entries; they are not replaced wholesale.
+- Merge order: public base → public profile → secret base → secret profile.
+- Independently prefer `<profile>.dev.secret.cjs` over `<profile>.secret.cjs`.
 
-### Step 4: Write host/profile overrides
+## Secrets
 
-Create `config/<hostname>.cjs` with only the keys that differ — they are deep-merged over defaults:
+Create `index.secret.cjs` for shared secrets and `<profile>.secret.cjs` for profile secrets:
 
 ```javascript
 module.exports = {
-    db: {
-        user: 'prod-user',
-        password: 'prod-secret'
-    }
+    db: { password: "" },
+    api: { key: "" }
 };
 ```
 
-### Step 5: Load the configuration
+- Secret modules supply only the needed fields; consumers read ordinary properties such as `cfg.api.key`.
+- Activate when the base or selected profile has a secret counterpart, or ciphertext already exists.
+- Without either condition, load public settings without identity access or secret artifacts.
+- Configre never creates editable secret modules. There is no `secrets` option.
+- Export plain objects containing JSON-compatible values; empty strings remain empty.
+- Reject functions, undefined, accessors, symbols, custom objects, cycles, sparse arrays, non-finite numbers, and keys named `__proto__`, `constructor`, or `prototype`.
+- Once active, encrypt all local profile secrets together; merge only the base and selected profile.
+- Every authorized identity can decrypt every profile. Profiles organize values, not access.
+- Editable secrets are authoritative for values; `recipients/` is authoritative for additional recipients.
+- With ciphertext and no editable secret modules, load as a consumer; deleting local modules does not clear secrets.
+- Individual `settings.cjs` files use `settings.secret.cjs`, `settings.cjs.secrets.enc.json`, and `settings.cjs.recipients/`; file mode has no secret profiles.
+
+### Sharing and updates
+
+1. Local: create secret files and run; Configre generates ciphertext and Git exclusions. Push the encrypted file.
+2. Server: pull and run; Configre automatically commits and pushes `recipients/<profile>.pub`.
+3. Local: pull, run to incorporate the public key, and push the updated ciphertext.
+4. Server: pull and restart. Later secret updates repeat the local run/push and server pull/restart.
+
+Registration needs a branch matching its upstream, Git author identity, and non-interactive push access.
+Pending authorization or failed registration returns public settings only; malformed secrets, identities, and ciphertext stop loading.
+Use isolated fixtures for verification unless live registration is authorized: loading can fetch, commit, and push.
+Registration preserves unrelated changes, skips hooks, rejects key-name collisions, and retries failures on later loads.
+Never commit editable secret modules or private identities; Configre rejects already tracked secret inputs.
+Identity files live under `~/.config/configre/`: `identity.pem` is private and `identity.pub` is public.
+Back up editable secrets and private identities; never reset damaged identities or ciphertext as a retry.
+To revoke access, remove the recipient key, reload locally, and publish; prevent re-registration and rotate previously shared credentials when required.
+
+## Print without secret fields
+
+Use `cfg.print()` with `DEBUG=Configre:*`, rather than logging the merged configuration.
+It logs current values without mutation or automatic printing on load; public siblings remain visible.
+Omit loaded secret-file fields recursively, including encrypted inputs; omit secret arrays entirely.
+Classification follows secret-file fields, not names: secrets copied elsewhere are not automatically detected.
+The method is non-enumerable; spreads and JSON still contain secrets and do not preserve the method.
+An existing `print` field is preserved; use `new Configre(configPath).print()` in that case.
+
+## Apply environment variables
 
 ```javascript
-import Configre from "configre";
-import { join } from "node:path";
-
-const cfg = Configre(join(import.meta.dirname, "config"));
-
-console.log(cfg.db.host); // from default
-console.log(cfg.db.user); // from host override
+import Configre, { applyConfigEnv } from "configre";
+const cfg = Configre(configPath);
+applyConfigEnv(cfg.env);
 ```
 
-CommonJS consumers can still use `const Configre = require("configre")` and `Configre(path.join(__dirname, "config"))`, without `.default` or `await`. Configuration files remain `.cjs` in either module system.
-
-The path argument is required. Prefer an absolute path anchored to the module. Do not recommend paths derived from `process.cwd()`, such as `path.join(process.cwd(), "config")`: they can point somewhere else when the process is launched from a different directory.
-
-To use a different config directory:
-
-```javascript
-const cfg = Configre(join(import.meta.dirname, "settings"));
-```
-
-## Profile resolution
-
-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.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.cjs` with project defaults, import Configre and load with `Configre(join(import.meta.dirname, "config"))`
-Result: merged config object ready to use
-
-**Example 2: Multi-environment**
-User says: "I need different database settings per server"
-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.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`
-- **Config files must use the `.cjs` extension** (`.js` is not accepted; works in both CommonJS and ESM projects)
-- **Required path**: always pass the config directory or file path; prefer an absolute module-relative path over a process-relative path
-- **Function vs constructor**: `Configre(path)` returns the merged config directly; `new Configre(path)` returns the instance (use `.get()` to retrieve config)
+Call explicitly after loading. Set only undefined `process.env` variables using `String(value)`; preserve existing values, including `""`.
+Omitted `cfg.env` does nothing; skip null/undefined entries. Reject null, arrays, non-objects, empty keys, and object values.
+Invalid entries throw without rolling back earlier assignments. CommonJS: `const { applyConfigEnv } = require("configre")`.
+For encryption, identity permissions, and recovery details, consult the [advanced reference](https://github.com/clasen/Configre#advanced-reference).

package/test/index.test.js

@@ -4,7 +4,65 @@ import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import test from "node:test";
-import Configre from "../index.js";
+import Configre, { applyConfigEnv } from "../index.js";
+
+test("applyConfigEnv fills missing variables without overwriting existing values", t => {
+    const env = {
+        CONFIGRE_TEST_ENV_TEXT: "value",
+        CONFIGRE_TEST_ENV_NUMBER: 0,
+        CONFIGRE_TEST_ENV_BOOLEAN: false,
+        CONFIGRE_TEST_ENV_EMPTY: "",
+        CONFIGRE_TEST_ENV_NULL: null,
+        CONFIGRE_TEST_ENV_UNDEFINED: undefined,
+        CONFIGRE_TEST_ENV_EXISTING: "replacement",
+        CONFIGRE_TEST_ENV_EXISTING_EMPTY: "replacement"
+    };
+    const original = Object.fromEntries(Object.keys(env).map(key => [key, process.env[key]]));
+    t.after(() => {
+        for (const [key, value] of Object.entries(original)) {
+            if (value === undefined) delete process.env[key];
+            else process.env[key] = value;
+        }
+    });
+    for (const key of Object.keys(env)) delete process.env[key];
+    process.env.CONFIGRE_TEST_ENV_EXISTING = "original";
+    process.env.CONFIGRE_TEST_ENV_EXISTING_EMPTY = "";
+
+    assert.equal(applyConfigEnv(env), undefined);
+    assert.equal(process.env.CONFIGRE_TEST_ENV_TEXT, "value");
+    assert.equal(process.env.CONFIGRE_TEST_ENV_NUMBER, "0");
+    assert.equal(process.env.CONFIGRE_TEST_ENV_BOOLEAN, "false");
+    assert.equal(process.env.CONFIGRE_TEST_ENV_EMPTY, "");
+    assert.equal(process.env.CONFIGRE_TEST_ENV_NULL, undefined);
+    assert.equal(process.env.CONFIGRE_TEST_ENV_UNDEFINED, undefined);
+    assert.equal(process.env.CONFIGRE_TEST_ENV_EXISTING, "original");
+    assert.equal(process.env.CONFIGRE_TEST_ENV_EXISTING_EMPTY, "");
+    applyConfigEnv({ CONFIGRE_TEST_ENV_TEXT: "replacement" });
+    assert.equal(process.env.CONFIGRE_TEST_ENV_TEXT, "value");
+    assert.equal(env.CONFIGRE_TEST_ENV_NUMBER, 0);
+    assert.equal(env.CONFIGRE_TEST_ENV_BOOLEAN, false);
+});
+
+test("applyConfigEnv accepts omitted configuration and rejects invalid inputs", () => {
+    assert.equal(applyConfigEnv(), undefined);
+    assert.equal(applyConfigEnv({}), undefined);
+    for (const env of [null, [], "text", 1, true, () => {}]) {
+        assert.throws(() => applyConfigEnv(env), {
+            name: "TypeError",
+            message: "config.env must be a plain object"
+        });
+    }
+    assert.throws(() => applyConfigEnv({ "": null }), {
+        name: "TypeError",
+        message: "config.env keys must be non-empty strings"
+    });
+    for (const value of [{ nested: true }, [], new Date()]) {
+        assert.throws(() => applyConfigEnv({ CONFIGRE_TEST_ENV_INVALID: value }), {
+            name: "TypeError",
+            message: "config.env.CONFIGRE_TEST_ENV_INVALID must be a scalar"
+        });
+    }
+});
 
 test("requires a config path", () => {
     assert.throws(
@@ -44,17 +102,25 @@ for (const format of ["commonjs", "module"]) {
         const entry = format === "commonjs" ? `
             const assert = require('node:assert/strict');
             const Configre = require('configre');
-            import('configre').then(module => assert.equal(module.default, Configre));
+            const { applyConfigEnv } = Configre;
+            import('configre').then(module => {
+                assert.equal(module.default, Configre);
+                assert.equal(module.applyConfigEnv, applyConfigEnv);
+            });
         ` : `
             import assert from 'node:assert/strict';
             import { createRequire } from 'node:module';
-            import Configre from 'configre';
+            import Configre, { applyConfigEnv } from 'configre';
             const require = createRequire(import.meta.url);
             assert.equal(require('configre'), Configre);
+            assert.equal(require('configre').applyConfigEnv, applyConfigEnv);
         `;
         const filename = path.join(directory, format === "commonjs" ? "consumer.cjs" : "consumer.mjs");
         fs.writeFileSync(filename, entry + `
             assert.equal(typeof Configre, 'function');
+            delete process.env.CONFIGRE_TEST_ENV_INTEROP;
+            applyConfigEnv({ CONFIGRE_TEST_ENV_INTEROP: 123 });
+            assert.equal(process.env.CONFIGRE_TEST_ENV_INTEROP, '123');
             const configPath = ${JSON.stringify(config)};
             const expected = { db: { host: 'localhost', port: 456 } };
             assert.deepEqual(Configre(configPath), expected);