@theowlops/boombot 0.0.0-stage → 1.1.1

package/dist/gateway/config.js

@@ -0,0 +1,427 @@
+import { join } from 'node:path';
+import { hashApiKey } from './auth.js';
+import { coerceChannelSection, defaultConfigDir, defaultConfigPath, readConfigObject, resolveConfigFilePath, } from './config-format.js';
+const DEFAULT_HOST = '127.0.0.1';
+const DEFAULT_PORT = 8787;
+/**
+ * Default config path (`~/.boombot/config.yml`). The real definition lives in
+ * `config-format.ts`, next to the file probe order; re-exported here so old
+ * call sites doing `import { defaultConfigPath } from './config.js'` don't break.
+ */
+export { defaultConfigPath };
+/** Default data directory: `~/.boombot/data`. */
+export function defaultDataDir(env = process.env) {
+    return join(defaultConfigDir(env), 'data');
+}
+function parsePort(raw) {
+    const n = typeof raw === 'number'
+        ? raw
+        : typeof raw === 'string'
+            ? Number.parseInt(raw, 10)
+            : Number.NaN;
+    if (!Number.isInteger(n) || n <= 0 || n > 65535)
+        return DEFAULT_PORT;
+    return n;
+}
+const CHANNEL_KINDS = [
+    'telegram',
+    'discord',
+    'slack',
+    'whatsapp',
+    'zalo',
+    'messenger',
+    'tiktok',
+];
+/**
+ * Reads the `channels` section.
+ *
+ * Rejects unknown channels: a misspelled channel name (`telego:`) used to be
+ * passed straight into the config, and the only symptom was that channel never
+ * running — no error, no warning. Each valid channel also goes through
+ * `coerceChannelSection` for YAML coercion and typo catching.
+ */
+function parseChannels(raw, configPath) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new Error('Gateway config "channels" must be an object');
+    }
+    const channels = {};
+    for (const [kind, section] of Object.entries(raw)) {
+        if (!CHANNEL_KINDS.includes(kind)) {
+            throw new Error(`Gateway config at ${configPath}: unknown channel "${kind}" (expected one of ${CHANNEL_KINDS.join(', ')})`);
+        }
+        channels[kind] = coerceChannelSection(kind, section, configPath);
+    }
+    return channels;
+}
+/**
+ * `ChannelConnectionConfig` fields loadable from the environment, per channel.
+ * Variable names derive from the rule `BOOMBOT_<KIND>_<FIELD_SNAKE>`, e.g.
+ * `BOOMBOT_SLACK_SIGNING_SECRET`, `BOOMBOT_MESSENGER_PAGE_ACCESS_TOKEN`.
+ *
+ * Deliberately excludes `enabled` and `allowlistChatIds`: they are structure,
+ * not secrets, and `allowlistChatIds` is an array — stuffing it into one env
+ * var would require inventing a string-splitting format, i.e. one more thing
+ * to mistype with no security gain.
+ *
+ * `accessToken` exists on both whatsapp and tiktok, so the channel prefix in
+ * the variable name is mandatory; without it the two channels would fight over
+ * one variable.
+ */
+const CHANNEL_ENV_FIELDS = [
+    ['telegram', 'botToken'],
+    ['discord', 'botToken'],
+    ['discord', 'guildId'],
+    ['discord', 'publicKey'],
+    ['slack', 'botToken'],
+    ['slack', 'signingSecret'],
+    ['slack', 'appToken'],
+    ['whatsapp', 'phoneNumberId'],
+    ['whatsapp', 'accessToken'],
+    ['whatsapp', 'verifyToken'],
+    ['whatsapp', 'appSecret'],
+    ['zalo', 'oaToken'],
+    ['zalo', 'appId'],
+    ['zalo', 'appSecret'],
+    ['zalo', 'bridgeUrl'],
+    ['messenger', 'pageAccessToken'],
+    ['messenger', 'appSecret'],
+    ['tiktok', 'appId'],
+    ['tiktok', 'clientSecret'],
+    ['tiktok', 'accessToken'],
+];
+function camelToSnake(field) {
+    return field.replace(/[A-Z]/g, (char) => `_${char.toLowerCase()}`);
+}
+/**
+ * Environment variable name for one field of one channel. Exported so
+ * `boombot setup` (writing) and `boombot doctor` (reading) share one rule —
+ * two places inventing their own names would drift apart sooner or later.
+ */
+export function channelEnvVar(kind, field) {
+    return `BOOMBOT_${kind.toUpperCase()}_${camelToSnake(field).toUpperCase()}`;
+}
+/**
+ * Assigns a dynamic-keyed field onto a channel section.
+ *
+ * `field` only comes from `CHANNEL_ENV_FIELDS`, where every value is a key
+ * that `ChannelConnectionConfig` declares as `string | undefined`, so the
+ * assignment is always semantically correct. TS can't verify dynamic keys, so
+ * it goes through `unknown` — the only place in this file that needs it. The
+ * section is copied before mutation so the caller's object is untouched.
+ */
+function setChannelField(channels, kind, field, value) {
+    const section = { ...channels[kind] };
+    section[field] = value;
+    return { ...channels, [kind]: section };
+}
+/**
+ * Merges channel credentials from the environment over the file's `channels`.
+ * Environment values win; fields absent from the environment keep the file's
+ * values.
+ *
+ * A channel never mentioned in `config.json` is still created when the
+ * environment has a token — that's the point: `config.json` should never
+ * mention any secret. With nothing from the environment, the old `channels`
+ * object is returned as-is (identity preserved, no empty object created).
+ */
+function mergeChannelEnv(channels, get) {
+    let merged = { ...channels };
+    let touched = false;
+    for (const [kind, field] of CHANNEL_ENV_FIELDS) {
+        const value = get(channelEnvVar(kind, field));
+        if (value === undefined || value === '')
+            continue;
+        merged = setChannelField(merged, kind, field, value);
+        touched = true;
+    }
+    return touched ? merged : channels;
+}
+const GUARD_MODES = ['strict', 'warn', 'off'];
+function parseGuardMode(raw, envValue, name) {
+    const fromEnv = typeof envValue === 'string' && envValue.length > 0 ? envValue : undefined;
+    const fromFile = typeof raw === 'string'
+        ? raw
+        : typeof raw === 'object' && raw !== null && !Array.isArray(raw)
+            ? raw.mode
+            : undefined;
+    const value = fromEnv ?? (typeof fromFile === 'string' ? fromFile : undefined) ?? 'warn';
+    if (!GUARD_MODES.includes(value)) {
+        throw new Error(`Gateway config "${name}" mode must be one of ${GUARD_MODES.join(', ')} (got ${JSON.stringify(value)})`);
+    }
+    return value;
+}
+/**
+ * Parse the `shell` section: `{ enabled?: boolean; projectRoot?: boolean }`.
+ * Env `BOOMBOT_SHELL_ENABLED=1`/`true` forces `enabled` on and
+ * `BOOMBOT_SHELL_PROJECT_ROOT=1`/`true` forces `projectRoot` on; anything
+ * else leaves the file value. Both default off — fail-closed.
+ */
+function parseShellConfig(raw, envEnabled, envProjectRoot, envBackend) {
+    const truthy = (value) => typeof value === 'string' && /^(1|true)$/i.test(value.trim());
+    let fromFileEnabled;
+    let fromFileProjectRoot;
+    let fromFileBackend;
+    if (typeof raw === 'object' && raw !== null && !Array.isArray(raw)) {
+        const section = raw;
+        if (typeof section.enabled === 'boolean')
+            fromFileEnabled = section.enabled;
+        else if (section.enabled !== undefined) {
+            throw new Error('Gateway config "shell.enabled" must be a boolean');
+        }
+        if (typeof section.projectRoot === 'boolean')
+            fromFileProjectRoot = section.projectRoot;
+        else if (section.projectRoot !== undefined) {
+            throw new Error('Gateway config "shell.projectRoot" must be a boolean');
+        }
+        fromFileBackend = section.backend;
+    }
+    else if (raw !== undefined) {
+        throw new Error('Gateway config "shell" must be an object');
+    }
+    const enabled = truthy(envEnabled) || fromFileEnabled === true;
+    const backend = envBackend ?? fromFileBackend ?? 'auto';
+    if (!['auto', 'native', 'subprocess'].includes(String(backend))) {
+        throw new Error('Gateway config "shell.backend" must be auto, native, or subprocess');
+    }
+    if (!enabled) {
+        // Fail-closed: without `enabled` there is no shell tool to point anywhere.
+        return undefined;
+    }
+    const projectRoot = truthy(envProjectRoot) || fromFileProjectRoot === true;
+    return {
+        enabled: true,
+        ...(projectRoot ? { projectRoot: true } : {}),
+        ...(backend === 'auto' ? {} : { backend: backend }),
+    };
+}
+/**
+ * Parse the `files` section: `{ root?: string }`. Env `BOOMBOT_FILES_ROOT`
+ * wins over the file value. The path is deliberately left unresolved here:
+ * a relative value has to be relative to the directory the gateway was
+ * started in, not to the config file, so `registerTurnTools` resolves it.
+ */
+function parseFilesConfig(raw, envRoot) {
+    let fromFile;
+    if (typeof raw === 'object' && raw !== null && !Array.isArray(raw)) {
+        const root = raw.root;
+        if (typeof root === 'string' && root.trim() !== '')
+            fromFile = root;
+        else if (root !== undefined) {
+            throw new Error('Gateway config "files.root" must be a non-empty string');
+        }
+    }
+    else if (raw !== undefined) {
+        throw new Error('Gateway config "files" must be an object');
+    }
+    const root = envRoot ?? fromFile;
+    return root === undefined ? undefined : { root };
+}
+function parseMcpConfig(raw, env) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new Error('Gateway config "mcp" must be an object');
+    }
+    const rawServers = raw.servers;
+    if (typeof rawServers !== 'object' || rawServers === null || Array.isArray(rawServers)) {
+        throw new Error('Gateway config "mcp.servers" must be an object');
+    }
+    const servers = {};
+    for (const [name, value] of Object.entries(rawServers)) {
+        if (!/^[a-z0-9][a-z0-9-]{0,31}$/.test(name)) {
+            throw new Error(`Gateway config MCP server name ${JSON.stringify(name)} is invalid`);
+        }
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            throw new Error(`Gateway config "mcp.servers.${name}" must be an object`);
+        }
+        const section = value;
+        if (section['command'] !== undefined &&
+            (typeof section['command'] !== 'string' || section['command'].trim() === '')) {
+            throw new Error(`Gateway config "mcp.servers.${name}.command" must be a non-empty string`);
+        }
+        const command = typeof section['command'] === 'string' && section['command'].trim() !== ''
+            ? section['command'].trim()
+            : undefined;
+        let url;
+        if (typeof section['url'] === 'string' && section['url'].trim() !== '') {
+            try {
+                const parsed = new URL(section['url']);
+                if ((parsed.protocol !== 'http:' && parsed.protocol !== 'https:') ||
+                    parsed.username !== '' || parsed.password !== '')
+                    throw new Error();
+                url = parsed.toString();
+            }
+            catch {
+                throw new Error(`Gateway config "mcp.servers.${name}.url" must be an absolute HTTP(S) URL`);
+            }
+        }
+        else if (section['url'] !== undefined) {
+            throw new Error(`Gateway config "mcp.servers.${name}.url" must be an absolute HTTP(S) URL`);
+        }
+        if ((command === undefined) === (url === undefined)) {
+            throw new Error(`Gateway config "mcp.servers.${name}" must define exactly one of command or url`);
+        }
+        if (section['args'] !== undefined &&
+            (!Array.isArray(section['args']) || !section['args'].every((item) => typeof item === 'string'))) {
+            throw new Error(`Gateway config "mcp.servers.${name}.args" must be an array of strings`);
+        }
+        if (section['cwd'] !== undefined &&
+            (typeof section['cwd'] !== 'string' || section['cwd'].trim() === '')) {
+            throw new Error(`Gateway config "mcp.servers.${name}.cwd" must be a non-empty string`);
+        }
+        if (section['enabled'] !== undefined && typeof section['enabled'] !== 'boolean') {
+            throw new Error(`Gateway config "mcp.servers.${name}.enabled" must be a boolean`);
+        }
+        const rawEnv = section['env'];
+        if (rawEnv !== undefined &&
+            (typeof rawEnv !== 'object' || rawEnv === null || Array.isArray(rawEnv) ||
+                !Object.values(rawEnv).every((item) => typeof item === 'string'))) {
+            throw new Error(`Gateway config "mcp.servers.${name}.env" must contain only string values`);
+        }
+        const rawHeaders = section['headers'];
+        if (rawHeaders !== undefined &&
+            (typeof rawHeaders !== 'object' || rawHeaders === null || Array.isArray(rawHeaders) ||
+                !Object.values(rawHeaders).every((item) => typeof item === 'string'))) {
+            throw new Error(`Gateway config "mcp.servers.${name}.headers" must contain only string values`);
+        }
+        const enabled = typeof section['enabled'] === 'boolean' ? { enabled: section['enabled'] } : {};
+        if (command !== undefined) {
+            if (rawHeaders !== undefined) {
+                throw new Error(`Gateway config "mcp.servers.${name}.headers" requires url transport`);
+            }
+            servers[name] = {
+                command,
+                ...(Array.isArray(section['args']) ? { args: section['args'] } : {}),
+                ...(typeof section['cwd'] === 'string' ? { cwd: section['cwd'] } : {}),
+                ...(rawEnv === undefined ? {} : { env: rawEnv }),
+                ...enabled,
+            };
+        }
+        else {
+            if (section['args'] !== undefined || section['cwd'] !== undefined || rawEnv !== undefined) {
+                throw new Error(`Gateway config "mcp.servers.${name}" cannot mix url with stdio options`);
+            }
+            servers[name] = {
+                url: url,
+                ...(rawHeaders === undefined ? {} : {
+                    headers: Object.fromEntries(Object.entries(rawHeaders).map(([header, value]) => {
+                        const variable = /^\$\{([A-Z_][A-Z0-9_]*)\}$/u.exec(value)?.[1];
+                        if (variable === undefined)
+                            return [header, value];
+                        const resolved = env[variable];
+                        if (resolved === undefined || resolved === '') {
+                            throw new Error(`Gateway config "mcp.servers.${name}.headers.${header}" requires environment variable ${variable}`);
+                        }
+                        return [header, resolved];
+                    })),
+                }),
+                ...enabled,
+            };
+        }
+    }
+    return { servers };
+}
+function parsePluginsConfig(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new Error('Gateway config "plugins" must be an object');
+    }
+    const section = raw;
+    if (section['root'] !== undefined &&
+        (typeof section['root'] !== 'string' || section['root'].trim() === '')) {
+        throw new Error('Gateway config "plugins.root" must be a non-empty string');
+    }
+    if (section['enabled'] !== undefined && typeof section['enabled'] !== 'boolean') {
+        throw new Error('Gateway config "plugins.enabled" must be a boolean');
+    }
+    if (section['config'] !== undefined &&
+        (typeof section['config'] !== 'object' || section['config'] === null || Array.isArray(section['config']))) {
+        throw new Error('Gateway config "plugins.config" must be an object');
+    }
+    return {
+        ...(typeof section['root'] === 'string' ? { root: section['root'] } : {}),
+        ...(typeof section['enabled'] === 'boolean' ? { enabled: section['enabled'] } : {}),
+        ...(section['config'] === undefined
+            ? {}
+            : { config: section['config'] }),
+    };
+}
+/**
+ * Operator key: prefers the plaintext copy in the environment/`.env`, hashed
+ * immediately at boot. This lets `boombot setup` write the key to `.env` and
+ * the operator can still read it back, instead of only a sha256 as before —
+ * losing the only printed copy meant losing access forever.
+ *
+ * An empty or whitespace-only key in the environment counts as UNSET, falling
+ * back to the file's hash. Treating it as valid would hash the empty string —
+ * i.e. a key anyone can guess. Trimming stray whitespace is also deliberate:
+ * keys from `generateApiKey` are hex, so leading/trailing whitespace can only
+ * be a typing mistake in `.env`, and it fails silently in exactly the
+ * mysterious-401 way.
+ */
+function resolveApiKeyHash(fileHash, envKey) {
+    const fromFile = typeof fileHash === 'string' && fileHash.length > 0 ? fileHash : undefined;
+    const plain = envKey?.trim();
+    return plain !== undefined && plain !== '' ? hashApiKey(plain) : fromFile;
+}
+/**
+ * Load the gateway config. `env` defaults to `process.env`; tests inject a
+ * plain object. Never logs secret values.
+ */
+export function loadConfig(env = process.env) {
+    /*
+     * This function does NOT read the `.env` file: `loadEnvFile` (env-file.ts)
+     * loads it into `process.env` at boot, BEFORE config is read. That gives the
+     * "real env vars > `.env` > config.json" precedence for free, while this
+     * function stays pure over its `env` parameter — so tests injecting an object
+     * never have to worry about the real `.env` in the test machine's home.
+     *
+     * Empty strings count as unset, so `BOOMBOT_PORT=` can't silently disable
+     * the file's value.
+     */
+    const get = (key) => {
+        const value = env[key];
+        return value !== undefined && value !== '' ? value : undefined;
+    };
+    /*
+     * These two values read `env` directly, NOT through `get()`: `$BOOMBOT_CONFIG`
+     * picks the config file itself, so letting it come from the `.env` file is a
+     * chicken-and-egg problem — you must know which file to read before you can
+     * read any file. Real environment variables are the only source for these two.
+     */
+    const configPath = resolveConfigFilePath(env);
+    const file = readConfigObject(configPath);
+    const fileHost = typeof file.host === 'string' && file.host.length > 0 ? file.host : undefined;
+    const host = get('BOOMBOT_HOST') ?? fileHost ?? DEFAULT_HOST;
+    const port = parsePort(get('BOOMBOT_PORT') ?? file.port);
+    const fileDataDir = typeof file.dataDir === 'string' && file.dataDir.length > 0 ? file.dataDir : undefined;
+    const dataDir = get('BOOMBOT_DATA_DIR') ?? fileDataDir ?? defaultDataDir(env);
+    const apiKeyHash = resolveApiKeyHash(file.apiKeyHash, get('BOOMBOT_API_KEY'));
+    const channels = mergeChannelEnv(parseChannels(file.channels, configPath), get);
+    const reasoningGuard = {
+        mode: parseGuardMode(file.reasoningGuard, get('BOOMBOT_REASONING_GUARD_MODE'), 'reasoningGuard'),
+    };
+    const harnessGuard = {
+        mode: parseGuardMode(file.harnessGuard, get('BOOMBOT_GUARD_MODE'), 'harnessGuard'),
+    };
+    const shell = parseShellConfig(file.shell, get('BOOMBOT_SHELL_ENABLED'), get('BOOMBOT_SHELL_PROJECT_ROOT'), get('BOOMBOT_SHELL_BACKEND'));
+    const files = parseFilesConfig(file.files, get('BOOMBOT_FILES_ROOT'));
+    const mcp = parseMcpConfig(file.mcp, env);
+    const plugins = parsePluginsConfig(file.plugins);
+    return {
+        host,
+        port,
+        dataDir,
+        apiKeyHash,
+        channels,
+        reasoningGuard,
+        harnessGuard,
+        shell,
+        files,
+        mcp,
+        plugins,
+    };
+}

package/dist/gateway/context.js

@@ -0,0 +1 @@
+export {};

package/dist/gateway/env-file.js

@@ -0,0 +1,129 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { defaultConfigDir } from './config-format.js';
+/**
+ * BoomBot's `.env` config layer.
+ *
+ * Why this file exists: channel tokens (bot token, signing secret, access
+ * token, app secret) sit in plaintext next to everything else in `config.json` —
+ * exactly the file people copy to other machines, paste into issues, and
+ * commit by accident. Splitting them into their own file, mode 0600, easy to
+ * gitignore and easy to rotate, is the correct operational shape; `config.json`
+ * then only keeps non-secret config (host, port, dataDir, guard mode, channel
+ * `enabled`/`allowlistChatIds`).
+ *
+ * Stated plainly so nobody feels safe by mistake: `.env` encrypts **nothing**.
+ * It's a text file with tight permissions — anyone who can read the disk can
+ * read it just like `config.json`, and on Windows `chmod` is a no-op (see
+ * SECURITY.md §5). What's actually encrypted at rest is the provider key
+ * (`providers.json` + `master.key`); don't downgrade those to here.
+ *
+ * Value precedence, high → low:
+ *   1. the process's real environment variables (`BOOMBOT_*`);
+ *   2. the `.env` file;
+ *   3. `~/.boombot/config.json`.
+ *
+ * This module only READS the file; merging the precedence lives in `loadConfig`
+ * in `config.ts`, so that function stays pure and testable by injecting a fake
+ * `env` without touching the global `process.env`.
+ */
+/** Default env file location: `~/.boombot/.env` (or `$BOOMBOT_ENV_FILE`). */
+export function defaultEnvPath() {
+    return join(defaultConfigDir(), '.env');
+}
+const KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ESCAPES = {
+    n: '\n',
+    r: '\r',
+    t: '\t',
+    '"': '"',
+    '\\': '\\',
+};
+/**
+ * One `.env` line: `KEY=value`, optional `export` prefix, value may be wrapped
+ * in single or double quotes. Returns `null` for blank lines and comments.
+ */
+function parseEnvLine(line, lineNumber, path) {
+    const trimmed = line.trim();
+    if (trimmed === '' || trimmed.startsWith('#'))
+        return null;
+    const body = trimmed.startsWith('export ')
+        ? trimmed.slice('export '.length).trim()
+        : trimmed;
+    const eq = body.indexOf('=');
+    if (eq === -1) {
+        throw new Error(`Env file at ${path}:${lineNumber} is not a KEY=value line`);
+    }
+    const key = body.slice(0, eq).trim();
+    if (!KEY_PATTERN.test(key)) {
+        throw new Error(`Env file at ${path}:${lineNumber} has an invalid key: ${JSON.stringify(key)}`);
+    }
+    return { key, value: unquote(body.slice(eq + 1).trim()) };
+}
+function unquote(rawValue) {
+    const quote = rawValue[0];
+    if ((quote === '"' || quote === "'") && rawValue.length >= 2 && rawValue.endsWith(quote)) {
+        const inner = rawValue.slice(1, -1);
+        // Single quotes are absolute literals (as in shell): no escape processing.
+        return quote === '"' ? inner.replace(/\\([nrt"\\])/g, (_, code) => ESCAPES[code] ?? code) : inner;
+    }
+    /*
+     * Unquoted: `#` only starts a comment after whitespace. Cutting at every `#`
+     * would truncate a secret containing that character, and what's lost is the
+     * token — failing silently, the hardest kind of bug to trace.
+     */
+    const comment = rawValue.search(/\s#/);
+    return comment === -1 ? rawValue : rawValue.slice(0, comment).trimEnd();
+}
+/**
+ * Reads a `.env` file into a flat map. A missing file is normal — returns `{}`
+ * because `.env` is optional. But a PRESENT file with a bad line throws with
+ * the line number, never silently skipped: a swallowed typo would surface as
+ * "channel not running" with an error message unrelated to the cause.
+ *
+ * Later lines override earlier ones with the same key. Real environment
+ * variables overriding the file is `loadConfig`'s job, not this module's.
+ */
+export function readEnvFile(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return {};
+        throw new Error(`Cannot read env file at ${path}: ${error.message}`);
+    }
+    const values = {};
+    const lines = raw.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+        const parsed = parseEnvLine(lines[index] ?? '', index + 1, path);
+        if (parsed)
+            values[parsed.key] = parsed.value;
+    }
+    return values;
+}
+/**
+ * Loads the `.env` file into `process.env`, setting only keys NOT already in
+ * the environment. That is the entire mechanism guaranteeing "real env vars
+ * beat `.env`" — no intermediate merging layer needed.
+ *
+ * Called exactly once at the top of `main.ts`, before any config read. Returns
+ * the number of keys set so the caller can log "loaded .env (n keys)" without
+ * re-reading the file; never log values.
+ *
+ * Writing straight into `process.env` is deliberate and is what dotenv does:
+ * everything downstream — `loadConfig`, each channel's transport, sub-services —
+ * just reads environment variables and never needs to know about this file.
+ */
+export function loadEnvFile(path = defaultEnvPath()) {
+    const values = readEnvFile(path);
+    let applied = 0;
+    for (const [key, value] of Object.entries(values)) {
+        if (process.env[key] !== undefined)
+            continue;
+        process.env[key] = value;
+        applied += 1;
+    }
+    return applied;
+}