configre 2.1.4 → 2.1.5

package/README.md

@@ -1,151 +1,128 @@
-# 🔧 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,
+        password: ""
+    },
+    api: {
+        key: ""
+    }
+};
+```
 
-   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,
+        password: "",
+        ssl: true
+    },
+    api: {
+        key: ""
     }
 }
 ```
 
-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 still reads `cfg.db.password` and `cfg.api.key`; there is no separate secrets API.
 
-> 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 +132,144 @@ module.exports = {
 };
 ```
 
-Create `demo/secrets/config/index.secret.cjs` yourself to enable secrets, initially with:
+For a production database credential, create `config/production.secret.cjs`:
 
 ```javascript
-module.exports = {};
-```
-
-Then run:
-
-```bash
-node demo/secrets/demo.js
+module.exports = {
+    db: {
+        password: ""
+    }
+};
 ```
 
-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. 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.5",
   "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,14 +1,14 @@
 ---
 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 and manage Configre configuration in Node.js projects, including hostname/profile overrides, encrypted shared secrets, recipient registration, and configuration printing with secret fields omitted. Use when adopting Configre or working on its configuration files, secret sharing, or print() API.
 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).
+Environment-specific configuration manager for Node.js. Merges public defaults, hostname or profile overrides, and optional secrets synchronously using its own deep-merge implementation.
 
 ## Instructions
 
@@ -40,15 +40,17 @@ module.exports = {
         host: 'localhost',
         port: 5432,
         user: 'dev',
-        password: 'dev-pass'
+        password: ""
     },
     api: {
-        key: 'default-key',
+        key: "",
         url: 'http://localhost:3000'
     }
 };
 ```
 
+Keep credentials in `.secret.cjs` files. Public settings should contain explicit empty placeholders, not real credentials or automatic environment-variable fallbacks.
+
 ### Step 4: Write host/profile overrides
 
 Create `config/<hostname>.cjs` with only the keys that differ — they are deep-merged over defaults:
@@ -56,8 +58,7 @@ Create `config/<hostname>.cjs` with only the keys that differ — they are deep-
 ```javascript
 module.exports = {
     db: {
-        user: 'prod-user',
-        password: 'prod-secret'
+        user: 'prod-user'
     }
 };
 ```
@@ -90,7 +91,7 @@ Configre determines the active profile by looking for a `--config=<profile>` arg
 
 1. `config/<profile>.dev.cjs` — dev override
 2. `config/<profile>.cjs` — production override
-3. No match — uses defaults only
+3. No match — uses public defaults; available secrets still apply
 
 To force a specific profile at runtime:
 
@@ -101,6 +102,85 @@ node app.js --port=3000 --config=production --debug
 
 Using `--config=` (instead of a positional argument) avoids conflicts with other CLI flags.
 
+## Shared secrets
+
+### Activation and file layout
+
+Secret support activates when the base config or selected profile has a corresponding `.secret.cjs` file, or when an encrypted file already exists. There is no `secrets` option. Without either condition, Configre loads public settings without accessing an identity or creating secret artifacts. Configre never creates editable `.secret.cjs` modules itself; create them only when secret support is wanted.
+
+For a config directory:
+
+```text
+config/
+├── index.cjs
+├── production.cjs
+├── index.secret.cjs          # Administrator-only base secrets
+├── production.secret.cjs     # Optional administrator-only profile secrets
+├── production.dev.secret.cjs # Optional preferred secret profile variant
+├── secrets.enc.json          # Generated ciphertext; share through Git
+├── recipients/*.pub          # Public recipient keys; share through Git
+└── .gitignore                # Generated exclusions for editable secrets
+```
+
+For an individual `settings.cjs` config file, sidecars are `settings.secret.cjs`, `settings.cjs.secrets.enc.json`, and `settings.cjs.recipients/`, beside the config file. An extensionless path resolving to that file uses the same sidecars. File mode selects the base secret module, not profile secret modules.
+
+Secret modules export a plain object containing only JSON-compatible values. For example, create `config/index.secret.cjs` with empty values for the administrator to fill privately:
+
+```javascript
+module.exports = {
+    db: { password: "" },
+    api: { key: "" }
+};
+```
+
+Empty strings remain empty. Configre does not fill values from the environment or populate `process.env`. Functions, `undefined`, accessors, symbols, custom objects, circular references, non-finite numbers, sparse arrays, and keys named `__proto__`, `constructor`, or `prototype` are rejected in secret modules.
+
+### Merge order
+
+For `--config=production`, later layers override earlier ones:
+
+```text
+index.cjs → selected public profile → index.secret.cjs → selected secret profile
+```
+
+Public selection prefers `production.dev.cjs` over `production.cjs`. Independently, secret selection prefers `production.dev.secret.cjs` over `production.secret.cjs`; dev and regular variants do not merge together. A selected profile secret can activate secrets without `index.secret.cjs`. Once activated, directory mode encrypts all local `.secret.cjs` files, including inactive profiles, while only base and selected profile values enter the returned config.
+
+### Administrator and server workflow
+
+1. On the administrator, create the needed `.secret.cjs` files and load Configre. It creates or reuses the machine identity, prepares Git exclusions and `recipients/`, and writes `secrets.enc.json`. Editable secrets must not already be tracked by Git; Configre refuses to proceed if they are. It does not untrack files or rewrite history.
+2. Share the public configuration, generated `.gitignore`, recipient public keys, and ciphertext through Git. Keep editable secret modules and the private identity local. A server with ciphertext and no editable secret modules decrypts the bundle without executing secret modules.
+3. On an unauthorized server, loading Configre attempts to publish `recipients/<profile>.pub` through Git. New registration requires a branch matching its upstream, Git author identity, and credentials that work without an interactive prompt. Profile names must start with a letter or digit and contain only letters, digits, dots, underscores, or hyphens.
+4. On the administrator, pull the public-key registration, reload Configre, and publish the updated ciphertext. The server then pulls it and reloads Configre. Publishing a public key alone does not authorize decryption. Any authorized recipient can decrypt the whole bundle, including other profiles; profiles are not access-control boundaries.
+
+Loading an unauthorized server config can fetch, create a public-key commit, and push it. Account for these side effects before using application startup as a verification command; use isolated fixtures for local checks unless the requested work authorizes live registration. Configre preserves unrelated staged and unstaged changes through an isolated index, runs no commit or pre-push hooks, and does not merge, rebase, force-push, or publish local tags. Already published matching keys do not create another registration commit. Conflicting keys for the same profile are not overwritten. Failed registration is retried on a later load; each registration Git command has a 30-second timeout.
+
+While authorization is pending, Configre warns and returns public settings only: public placeholders remain and encrypted-only fields are absent. Registration failure also permits public-only startup. Do not assume successful application startup proves secrets were loaded; verify required credentials without printing their values. Invalid secret modules, damaged identities, malformed ciphertext, and authentication failures stop loading instead of silently resetting data.
+
+### Updates, revocation, and identity
+
+- The administrator's local `.secret.cjs` files are authoritative for values; `recipients/` is authoritative for additional recipients. Reloading updates ciphertext when values or recipients change. Unchanged inputs do not rewrite it; existing editable modules are never overwritten. Deleting every local secret module while retaining ciphertext switches to consumer behavior rather than clearing the bundle.
+- To revoke a recipient, remove its public-key file on the administrator, reload, and distribute the new ciphertext. The current administrator is always included. Remove repository write access too if the machine must not register again. Old ciphertext and previously obtained credentials remain usable; rotate affected credentials when revocation requires it.
+- Identity files live at `~/.config/configre/identity.pem` (private) and `identity.pub` (public). Share only the public key. Back up editable secrets and the private identity securely. On POSIX, the identity directory must have owner-only permissions (`0700`) and the private key owner-only permissions (`0600`). Private identities and secret input files cannot be symlinks.
+- A missing public identity can be regenerated from a valid private key. A corrupt private identity, or a missing private identity with an existing public key, is not silently replaced. Restore the identity or deliberately register a new one. Losing all authorized private keys makes existing ciphertext unrecoverable.
+- Configre uses AES-256-GCM and RSA-3072/OAEP-SHA-256 for encryption and recipient key wrapping. Ciphertext is replaced atomically under a writer lock. If a stale lock is reported after a crash, confirm its writer has stopped before removing it; do not reset ciphertext or identities as a retry strategy.
+
+## Print configuration without secret fields
+
+Use `print()` instead of logging the merged config object, which contains decrypted secrets:
+
+```javascript
+const cfg = Configre(join(import.meta.dirname, "config"));
+cfg.print();
+```
+
+`print()` calls Configre's LemonLog `log.debug`. Enable output with `DEBUG=Configre:*`; the `--debug` argument alone does not enable these logs. File creation, ciphertext updates, and public-key publication use `log.info`; authorization failures use `log.warn`, in the same namespace.
+
+- `cfg.print()` prints current values, including edits made after loading, without modifying `cfg` or logging automatically on load.
+- Fields present in loaded base or selected profile secret modules are omitted, including when read from ciphertext. Public sibling fields remain visible; arrays supplied by secrets are omitted entirely and emptied secret objects are removed.
+- Classification is by secret-file fields, not names such as `password` or `token`. Sensitive values placed only in public settings or copied to another field are not automatically detected. Keep them in secret modules and do not treat `print()` as a general-purpose redactor.
+- The method is non-enumerable: it does not appear in `Object.keys(cfg)`, object spreads, or JSON output. Those operations still include secret data, so do not use them as redaction. A spread or JSON round trip does not preserve the method.
+- `new Configre(configPath).print()` is also supported and prints the instance's merged settings. `.get()` still returns plain configuration data. If a configuration already has its own `print` field, that value is preserved; use the constructor's `print()` method instead.
+
 ## Examples
 
 **Example 1: Basic setup**
@@ -120,7 +200,7 @@ Result: staging overrides are merged over defaults, without conflicting with oth
 
 ## Key behaviors
 
-- **Deep merge**: nested objects merge recursively via lodash `_.merge`
+- **Deep merge**: nested plain objects merge recursively using Configre's own implementation; arrays merge by index and retain existing trailing entries rather than being replaced wholesale
 - **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)
+- **Function vs constructor**: `Configre(path)` returns the merged config with non-enumerable `print()` when that field is available; `new Configre(path)` returns the instance with `.get()` and `.print()`

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);