@maestro-js/config 1.0.0-alpha.0

package/README.md

@@ -0,0 +1,198 @@
+# @maestro-js/config
+
+Standalone configuration loader that reads `.env` files (plaintext or AES-256-GCM encrypted), imports a TypeScript or JavaScript config module, and writes the resolved key-value pairs into `process.env`. Zero `@maestro-js` dependencies.
+
+## Quick Setup
+
+```ts
+import { Config } from '@maestro-js/config'
+
+// Load config into process.env (existing keys are NOT overwritten)
+await Config.loadConfigFile({
+  rootDir: process.cwd(),
+  configName: 'app',
+  envName: 'production',
+  encryptionKey: process.env.MAESTRO_ENV_ENCRYPTION_KEY ?? null
+})
+```
+
+Or auto-load at startup without application code:
+
+```bash
+node --import @maestro-js/config/load --config app --env production --root /path/to/project
+```
+
+## API Reference
+
+### ConfigOptions
+
+Every primary function accepts this options object:
+
+```ts
+type ConfigOptions = {
+  rootDir: string           // Project root directory
+  configName: string        // Config file name without extension (looked up in <rootDir>/config/)
+  envName: string | null    // Environment name (.env.<envName>) or null for .env
+  encryptionKey: string | null  // 64-char hex key for encrypted .env files, or null
+}
+```
+
+### Config.loadConfigFile(options: ConfigOptions): Promise<void>
+
+Read the `.env` file, import the config file, and write the resolved values into `process.env`. Keys already present in `process.env` are not overwritten.
+
+### Config.getConfig(options: ConfigOptions): Promise<NodeJS.Dict<string>>
+
+Same as `loadConfigFile` but returns the resolved config object without modifying `process.env`.
+
+### Config.getEnvVars(options): NodeJS.Dict<string>
+
+Read and parse an env file (plaintext or encrypted). Returns `{}` if no env file is found. Throws if an encrypted file is found but no `encryptionKey` is provided.
+
+```ts
+Config.getEnvVars({ rootDir: '.', envName: null, encryptionKey: null })
+// => { FOO: 'bar', BAZ: 'qux' }
+```
+
+### Config.resolveConfig(module: any): Promise<NodeJS.Dict<string>>
+
+Normalize an imported config module into a flat string dictionary. Handles four export shapes: named exports, default object, default sync function, and default async function. Numbers and booleans are stringified. Objects and arrays throw.
+
+### Config.generateEncryptedEnvFile(options): void
+
+Read a plaintext `.env` file and write its AES-256-GCM encrypted counterpart (`.env.encrypted` or `.env.<envName>.encrypted`).
+
+```ts
+Config.generateEncryptedEnvFile({
+  rootDir: process.cwd(),
+  envName: null,
+  encryptionKey: key
+})
+```
+
+### Config.generateDecryptedEnvFile(options): void
+
+Read an encrypted `.env.encrypted` file and write the decrypted plaintext. Throws if the target file already exists unless `force: true`.
+
+```ts
+Config.generateDecryptedEnvFile({
+  rootDir: process.cwd(),
+  envName: 'production',
+  encryptionKey: key,
+  force: true
+})
+```
+
+### Config.generateEncryptionKey(): string
+
+Generate a cryptographically random 32-byte key as a 64-character hex string.
+
+```ts
+const key = Config.generateEncryptionKey()
+// => '7a3f8b2c...' (64 hex chars)
+```
+
+### Config.Resolve<T> (type utility)
+
+Extract the resolved key-value shape from a config module type. Use in an `environment.d.ts` file to make `process.env` type-safe.
+
+```ts
+import type { Config } from '@maestro-js/config'
+import type appConfig from './config/app.ts'
+
+declare global {
+  namespace NodeJS {
+    interface ProcessEnv extends Config.Resolve<typeof appConfig> {}
+  }
+}
+```
+
+## Common Patterns
+
+### Config file with named exports
+
+Place config files in `<rootDir>/config/`. Supported extensions: `.mts`, `.cts`, `.ts`, `.mjs`, `.cjs`, `.js`.
+
+```ts
+// config/app.ts
+export const DB_HOST = 'localhost'
+export const DB_PORT = '3306'
+export const DEBUG = true  // stringified to 'true'
+```
+
+### Config file as a function (derive values from .env)
+
+When the config exports a function, it receives the merged env vars (process.env values take precedence over .env file values).
+
+```ts
+// config/app.ts
+export default (env: Record<string, string | undefined>) => ({
+  DATABASE_URL: `mysql://${env.DB_USER}:${env.DB_PASS}@${env.DB_HOST}:${env.DB_PORT}/${env.DB_NAME}`,
+  API_KEY: env.API_KEY
+})
+```
+
+### Async config function
+
+```ts
+// config/app.ts
+export default async (env: Record<string, string | undefined>) => {
+  return {
+    SECRET: env.SECRET,
+    COMPUTED: await someAsyncOperation()
+  }
+}
+```
+
+### Env file resolution order
+
+When `envName` is provided (e.g., `'production'`), files are checked in this order:
+1. `.env.production`
+2. `.env.production.encrypted`
+3. `.env`
+4. `.env.encrypted`
+
+When `envName` is null:
+1. `.env`
+2. `.env.encrypted`
+
+### Encryption round-trip
+
+```ts
+const key = Config.generateEncryptionKey()
+
+// Encrypt: reads .env, writes .env.encrypted
+Config.generateEncryptedEnvFile({ rootDir: '.', envName: null, encryptionKey: key })
+
+// Decrypt: reads .env.encrypted, writes .env
+Config.generateDecryptedEnvFile({ rootDir: '.', envName: null, encryptionKey: key, force: true })
+```
+
+Encrypted values use the format `<iv_base64>.<authTag_base64>.<ciphertext_base64>` per key.
+
+### Auto-load entry point
+
+The `@maestro-js/config/load` export is a standalone script intended for `node --import`. It parses CLI arguments and calls `Config.loadConfigFile`.
+
+CLI flags:
+- `--config <name>` (required) -- config file name without extension
+- `--env <name>` -- environment name
+- `--key <hex>` -- encryption key (falls back to `MAESTRO_ENV_ENCRYPTION_KEY` env var)
+- `--root <path>` -- project root (defaults to `process.cwd()`)
+
+## Cross-Package Integration
+
+Config is a standalone package with zero `@maestro-js` dependencies. It is used by:
+
+- **CLI** -- The Maestro CLI uses `Config.generateEncryptedEnvFile`, `Config.generateDecryptedEnvFile`, and `Config.generateEncryptionKey` for the `env:encrypt`, `env:decrypt`, and `env:gen-key` commands.
+- **Application boot** -- Applications use `Config.loadConfigFile` (or `node --import @maestro-js/config/load`) to populate `process.env` before initializing other Maestro packages that read from `process.env`.
+- **Type safety** -- The `Config.Resolve` utility type lets applications create a typed `process.env` derived from the config module shape.
+
+## Testing
+
+```bash
+pnpm --filter @maestro-js/config test
+cd packages/config && npx beartest ./tests/config.test.ts
+```
+
+Tests use `beartest-js` with `expect`. They create temporary directories, write config/env files, and verify loading, encryption round-trips, and error cases.

package/dist/chunk-AVYD4MV2.js

@@ -0,0 +1,187 @@
+// src/index.ts
+import "async_hooks";
+import { createCipheriv, createDecipheriv, randomBytes } from "crypto";
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import { parseEnv } from "util";
+async function getConfig({ rootDir, configName, envName, encryptionKey }) {
+  const env = getEnvVars({ rootDir, envName, encryptionKey });
+  const configFilePath = getConfigFilePath({ rootDir, configName });
+  if (!configFilePath) {
+    return env;
+  }
+  const config = await resolveConfig(import(configFilePath), env);
+  return config;
+}
+async function loadConfigFile(options) {
+  const config = await getConfig(options);
+  for (const [key, value] of Object.entries(config)) {
+    if (process.env[key] === void 0) {
+      process.env[key] = value;
+    }
+  }
+}
+function resolveEnvValues(dotEnvFileValues) {
+  const processKeys = Object.keys(process.env);
+  const envFileKeys = Object.keys(dotEnvFileValues);
+  return Object.fromEntries(
+    [.../* @__PURE__ */ new Set([...processKeys, ...envFileKeys])].map((key) => [key, process.env[key] ?? dotEnvFileValues[key]])
+  );
+}
+async function resolveConfig(module, env) {
+  let config = await module;
+  if (config && typeof config === "object" && "default" in config) {
+    config = config.default;
+  }
+  const raw = typeof config === "function" ? await config(resolveEnvValues(env)) : config;
+  const result = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (typeof value === "string") {
+      result[key] = value;
+    } else if (typeof value === "number" || typeof value === "boolean") {
+      result[key] = String(value);
+    } else if (value != null) {
+      throw new Error(
+        `Config key "${key}" has unsupported type ${typeof value}. Only string, number, and boolean values are allowed.`
+      );
+    }
+  }
+  return result;
+}
+var CONFIG_EXTENSIONS = [".mts", ".cts", ".ts", ".mjs", ".cjs", ".js"];
+function getConfigFilePath({ rootDir, configName }) {
+  for (const ext of CONFIG_EXTENSIONS) {
+    const filePath = join(rootDir, "config", `${configName}${ext}`);
+    if (existsSync(filePath)) {
+      return filePath;
+    }
+  }
+  return null;
+}
+function getEnvVars({
+  rootDir,
+  envName,
+  encryptionKey
+}) {
+  const envFile = getEnvFilePath({ rootDir, envName });
+  if (!envFile) {
+    return {};
+  }
+  const envFileContents = readFileSync(envFile, "utf-8");
+  const isEncrypted = envFile.endsWith(".encrypted");
+  if (isEncrypted) {
+    if (!encryptionKey) {
+      throw new Error(`Cannot decrypt ${envFile}. Provide an encryption key via --key or MAESTRO_ENV_ENCRYPTION_KEY`);
+    } else {
+      const decrypted = decryptEnvFileContents(envFileContents, encryptionKey);
+      return decrypted;
+    }
+  } else {
+    const parsed = parseEnv(envFileContents);
+    return parsed;
+  }
+}
+function generateEncryptedEnvFile({
+  rootDir,
+  envName: envNameParam,
+  encryptionKey
+}) {
+  const envName = envNameParam || process.env.ENV_NAME || null;
+  const sourcePath = join(rootDir, envFileName(envName));
+  const destPath = join(rootDir, encryptedEnvFileName(envName));
+  const contents = readFileSync(sourcePath, "utf-8");
+  parseEnv(contents);
+  const encrypted = encryptEnvFileContents(contents, encryptionKey);
+  writeFileSync(destPath, envRecordToFileContents(encrypted));
+}
+function generateDecryptedEnvFile({
+  rootDir,
+  envName: envNameParam,
+  encryptionKey,
+  force
+}) {
+  const envName = envNameParam || process.env.ENV_NAME || null;
+  const sourcePath = join(rootDir, encryptedEnvFileName(envName));
+  const destPath = join(rootDir, envFileName(envName));
+  if (!force && existsSync(destPath)) {
+    throw new Error(`${destPath} already exists. Use force to overwrite.`);
+  }
+  const contents = readFileSync(sourcePath, "utf-8");
+  const decrypted = decryptEnvFileContents(contents, encryptionKey);
+  writeFileSync(destPath, envRecordToFileContents(decrypted));
+}
+function generateEncryptionKey() {
+  return randomBytes(32).toString("hex");
+}
+function envFileName(envName) {
+  return envName ? `.env.${envName}` : ".env";
+}
+function encryptedEnvFileName(envName) {
+  return `${envFileName(envName)}.encrypted`;
+}
+function envRecordToFileContents(env) {
+  return Object.entries(env).map(([key, value]) => `${key}=${value}`).join("\n");
+}
+function validateEncryptionKey(encryptionKey) {
+  const keyBuffer = Buffer.from(encryptionKey, "hex");
+  if (keyBuffer.length !== 32) {
+    throw new Error(`Encryption key must be 32 bytes (64 hex characters), got ${keyBuffer.length} bytes`);
+  }
+  return keyBuffer;
+}
+function encryptEnvFileContents(envFileContents, encryptionKey) {
+  const env = parseEnv(envFileContents);
+  const keyBuffer = validateEncryptionKey(encryptionKey);
+  const result = {};
+  for (const [name, value] of Object.entries(env)) {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", keyBuffer, iv);
+    const ciphertext = Buffer.concat([cipher.update(value, "utf-8"), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    result[name] = `${iv.toString("base64")}.${authTag.toString("base64")}.${ciphertext.toString("base64")}`;
+  }
+  return result;
+}
+function decryptEnvFileContents(envFileContents, encryptionKey) {
+  const env = parseEnv(envFileContents);
+  const keyBuffer = validateEncryptionKey(encryptionKey);
+  const result = {};
+  for (const [name, value] of Object.entries(env)) {
+    const parts = value.split(".");
+    if (parts.length !== 3) {
+      throw new Error(`Invalid encrypted value format for key "${name}"`);
+    }
+    const [ivB64, authTagB64, ciphertextB64] = parts;
+    const iv = Buffer.from(ivB64, "base64");
+    const authTag = Buffer.from(authTagB64, "base64");
+    const ciphertext = Buffer.from(ciphertextB64, "base64");
+    const decipher = createDecipheriv("aes-256-gcm", keyBuffer, iv);
+    decipher.setAuthTag(authTag);
+    result[name] = decipher.update(ciphertext).toString("utf-8") + decipher.final("utf-8");
+  }
+  return result;
+}
+function getEnvFilePath({ rootDir, envName: envNameParam }) {
+  const envName = envNameParam || process.env.ENV_NAME;
+  const candidates = envName ? [envFileName(envName), encryptedEnvFileName(envName), envFileName(null), encryptedEnvFileName(null)] : [envFileName(null), encryptedEnvFileName(null)];
+  for (const fileName of candidates) {
+    const filePath = join(rootDir, fileName);
+    if (existsSync(filePath)) {
+      return filePath;
+    }
+  }
+  return null;
+}
+var Config = {
+  getConfig,
+  resolveConfig,
+  loadConfigFile,
+  getEnvVars,
+  generateEncryptedEnvFile,
+  generateDecryptedEnvFile,
+  generateEncryptionKey
+};
+
+export {
+  Config
+};

package/dist/index.d.ts

@@ -0,0 +1,87 @@
+type ConfigOptions = {
+    rootDir: string;
+    configName: string;
+    envName: string | null;
+    encryptionKey: string | null;
+};
+/** Reads the `.env` file, imports the config file, and returns the resolved config. Does not modify `process.env`. */
+declare function getConfig({ rootDir, configName, envName, encryptionKey }: ConfigOptions): Promise<NodeJS.Dict<string>>;
+/** Reads the `.env` file, imports the config file, and writes the result into `process.env`. Keys already present are not overwritten. */
+declare function loadConfigFile(options: ConfigOptions): Promise<void>;
+/** Normalizes an imported config module into a flat string dictionary. Handles default exports, named exports, sync/async functions. */
+declare function resolveConfig(module: any, env: NodeJS.Dict<string>): Promise<NodeJS.Dict<string>>;
+/** Reads and parses an env file (plaintext or encrypted). Returns `{}` if no env file is found. */
+declare function getEnvVars({ rootDir, envName, encryptionKey }: {
+    rootDir: string;
+    envName: string | null;
+    encryptionKey: string | null;
+}): NodeJS.Dict<string>;
+/** Reads a plaintext `.env` file and writes its AES-256-GCM encrypted counterpart. */
+declare function generateEncryptedEnvFile({ rootDir, envName: envNameParam, encryptionKey }: {
+    rootDir: string;
+    envName: string | null;
+    encryptionKey: string;
+}): void;
+/** Reads an encrypted `.env.encrypted` file and writes the decrypted plaintext. Throws if the target exists unless `force` is true. */
+declare function generateDecryptedEnvFile({ rootDir, envName: envNameParam, encryptionKey, force }: {
+    rootDir: string;
+    envName: string | null;
+    encryptionKey: string;
+    force?: boolean;
+}): void;
+/** Generates a cryptographically random 32-byte key as a 64-character hex string. */
+declare function generateEncryptionKey(): string;
+type ConfigValue = Record<string, string | undefined>;
+type Unwrap<T> = T extends (...any: any[]) => Promise<infer R> ? R : T extends (...any: any[]) => infer R ? R : T;
+declare const Config: {
+    getConfig: typeof getConfig;
+    resolveConfig: typeof resolveConfig;
+    loadConfigFile: typeof loadConfigFile;
+    getEnvVars: typeof getEnvVars;
+    generateEncryptedEnvFile: typeof generateEncryptedEnvFile;
+    generateDecryptedEnvFile: typeof generateDecryptedEnvFile;
+    generateEncryptionKey: typeof generateEncryptionKey;
+};
+/**
+ * Configuration loader for Node.js applications.
+ *
+ * Reads `.env` files (plaintext or AES-256-GCM encrypted) and imports a TypeScript or JavaScript
+ * config file whose exported values are written to `process.env`. When the config file exports a
+ * function, it receives the parsed `.env` vars as its argument, so you can derive computed values
+ * (e.g., building a database URL from individual host/port/user parts). Existing `process.env`
+ * keys take precedence and are not overwritten.
+ *
+ * Config has zero `@maestro-js` dependencies. It is a standalone utility used by the CLI for
+ * `env:encrypt`, `env:decrypt`, and `env:gen-key` commands, and by applications at boot time
+ * via `node --import @maestro-js/config/load`.
+ *
+ * @example
+ * ```ts
+ * import { Config } from '@maestro-js/config'
+ *
+ * // Load config into process.env
+ * await Config.loadConfigFile({
+ *   rootDir: process.cwd(),
+ *   configName: 'app',
+ *   envName: 'production',
+ *   encryptionKey: process.env.MAESTRO_ENV_ENCRYPTION_KEY ?? null
+ * })
+ *
+ * // Or get config without modifying process.env
+ * const config = await Config.getConfig({ rootDir: '.', configName: 'app', envName: null, encryptionKey: null })
+ * ```
+ */
+declare namespace Config {
+    /**
+     * Extracts the resolved key-value shape from a config module type. Handles all four export shapes:
+     * named exports, default object, default sync function, and default async function. Use it in an
+     * `environment.d.ts` file to make `process.env` type-safe.
+     */
+    type Resolve<T extends ConfigValue | ((...any: any[]) => ConfigValue) | ((...any: any[]) => Promise<ConfigValue>) | {
+        default: ConfigValue | ((...any: any[]) => ConfigValue) | ((...any: any[]) => Promise<ConfigValue>);
+    }> = T extends {
+        default: infer D;
+    } ? Unwrap<D> : Unwrap<T>;
+}
+
+export { Config };

package/dist/index.js

@@ -0,0 +1,6 @@
+import {
+  Config
+} from "./chunk-AVYD4MV2.js";
+export {
+  Config
+};

package/dist/load.d.ts

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

package/dist/load.js

@@ -0,0 +1,23 @@
+import {
+  Config
+} from "./chunk-AVYD4MV2.js";
+
+// src/load.ts
+import "path";
+var { configName, envName, encryptionKey, rootDir } = parseArgs(process.argv);
+await Config.loadConfigFile({ rootDir, configName, envName, encryptionKey });
+function parseArgs(argv) {
+  const configName2 = getArgValue(argv, "--config");
+  if (!configName2) {
+    throw new Error("Missing required --config <name> argument");
+  }
+  const envName2 = getArgValue(argv, "--env") ?? null;
+  const encryptionKey2 = getArgValue(argv, "--key") ?? process.env["MAESTRO_ENV_ENCRYPTION_KEY"] ?? null;
+  const rootDir2 = getArgValue(argv, "--root") ?? process.cwd();
+  return { configName: configName2, envName: envName2, encryptionKey: encryptionKey2, rootDir: rootDir2 };
+}
+function getArgValue(argv, flag) {
+  const index = argv.indexOf(flag);
+  if (index === -1 || index + 1 >= argv.length) return void 0;
+  return argv[index + 1];
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@maestro-js/config",
+  "description": "Configuration loader for .env files and TypeScript/JavaScript config modules with AES-256-GCM encryption support. Use when working with @maestro-js/config, including loading config into process.env, reading/writing encrypted .env files, creating config modules, deriving computed env values, and generating encryption keys. Key capabilities: load config files, parse .env files (plaintext or encrypted), encrypt/decrypt env files, generate encryption keys, resolve config modules (named exports, default exports, sync/async functions), type-safe process.env via Config.Resolve utility type, and auto-load via node --import @maestro-js/config/load.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./load": {
+      "types": "./dist/load.d.ts",
+      "default": "./dist/load.js"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.11"
+  },
+  "version": "1.0.0-alpha.0",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "repository": "https://github.com/Marcato-Partners/maestro-js",
+  "scripts": {
+    "build": "tsup",
+    "watch": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "beartest ./tests/**/*",
+    "format": "prettier --write src/ tests/",
+    "lint": "prettier --check src/ tests/"
+  }
+}