@saasak/tool-env 1.0.1 → 1.1.0

package/README.md

@@ -14,10 +14,11 @@
 
 ## TODOs
 
-[] Handle encryption
-[] Handle variable composition everywhere (not just in overrides)
-[] Create runtime library to read vars (even encrypted)
-[] Handle env.local files
+- [x] Handle encryption
+- [ ] Fix not scoped package detection (if one package is not scope, it fails with pkg.name something)
+- [ ] Handle variable composition everywhere (not just in overrides)
+- [x] Create runtime library to read vars (even encrypted)
+- [x] Handle env.local files
 
 ## Open questions
 
@@ -46,6 +47,26 @@ or
 WRENV_TARGET=staging bun run env:update
 ```
 
+### Writing all environments
+
+Use `--target all` to write environment files for all configured environments at once.
+This creates suffixed files using conventional names (`.env.development`, `.env.staging`, `.env.production`) instead of a single `.env` file.
+
+Internal names are mapped to conventional output names:
+- `dev` → `.env.development`
+- `preprod` → `.env.staging`
+- `production` → `.env.production`
+
+```bash
+wrenv --secret ~/.big-secret write --target all
+```
+
+This is useful for:
+- CI/CD pipelines that need all environment configurations
+- Docker builds that copy environment-specific files
+- Pre-generating all env files for deployment
+- Compatibility with Next.js, Vite, and other frameworks that use conventional env file names
+
 you can also pass the secret via an env variable (Even though it is not really encouraged)
 ```bash
 WRENV_SECRET=super-secret WRENV_TARGET=prod npm run env:update

package/bin/index.js

@@ -1,46 +1,40 @@
+#!/usr/bin/env node
+
 import minimist from 'minimist';
 import fs from 'fs-extra';
 import path from 'path';
 import { execa } from 'execa';
 
+import { encrypt, isEncrypted } from '../src/utils-crypto.js';
 import { buildEnv } from '../src/utils-env.js';
 import { findMonorepoPackages } from '../src/utils-pkg.js';
-import { encrypt, isEncrypted } from '../src/utils-crypto.js';
+import { resolveTarget, verifyCanDecrypt, getOutputName } from '../src/core.js';
 
-const args = minimist(process.argv.slice(2));
+const args = minimist(process.argv.slice(2), { '--': true });
 const __root = process.cwd();
 
 const command = args._[0] || 'write';
 
 const secret = args.secret
-	? (args.secret === 'stdin' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(args.secret, 'utf8'))
+	? (args.secret === 'stdin' ? fs.readFileSync(0, 'utf8').trim() : fs.readFileSync(args.secret, 'utf8').trim())
 	: process.env.WRENV_SECRET || process.env.TARGET_SECRET || '';
 
 const envPath = args.env || '.env.json';
 const envFile = path.resolve(__root, envPath);
 
-if (!fs.existsSync(envFile)) {
+// Check env file exists for commands that need it
+const commandsRequiringEnvFile = ['write', 'show', 'encrypt', 'besafe', 'add'];
+if (commandsRequiringEnvFile.includes(command) && !fs.existsSync(envFile)) {
 	console.error('No env file found.');
 	process.exit(1);
 }
 
-const DEFAULT_ENV = 'dev';
-const targets = {
-	"development": "dev",
-	"dev": "dev",
-	"staging": "preprod",
-	"pp": "preprod",
-	"preprod": "preprod",
-	"prod": "production",
-	"production": "production",
-}
-
 async function showCommand() {
 	if (!secret) {
 		console.log('Secret not provided. Use --secret flag or WRENV_SECRET env variable.');
 	}
 
-	const target = targets[args.target || process.env.WRENV_TARGET || process.env.TARGET_ENV] || DEFAULT_ENV;
+	const target = resolveTarget(args.target);
 
 	const envContent = fs.readFileSync(envFile, 'utf8');
 	const env = JSON.parse(envContent);
@@ -48,11 +42,12 @@ async function showCommand() {
 	const rootPkgPath = path.resolve(__root, 'package.json');
 	const rootPkgContent = fs.readFileSync(rootPkgPath, 'utf8');
 	const rootPkg = JSON.parse(rootPkgContent);
+
 	const scope = rootPkg.name.split('/')[0];
+	const [_, ...foundPackages] = findMonorepoPackages(__root, scope);
 
-	const [_, ...foundPackages] = await findMonorepoPackages(__root, scope);
 	const deps = [
-		...foundPackages.map((pkg) => ({
+		...foundPackages.filter(Boolean).map((pkg) => ({
 			name: pkg.name.replace(`${scope}/`, ''),
 			dir: pkg.dir,
 		})),
@@ -61,9 +56,10 @@ async function showCommand() {
 			dir: __root,
 		},
 	];
+
 	const depsName = deps.map((dep) => dep.name);
 
-	const allowedEnvs = env && env.envs && Array.isArray(env.envs) ? env.envs : [DEFAULT_ENV];
+	const allowedEnvs = env && env.envs && Array.isArray(env.envs) ? env.envs : ['dev'];
 	const targetEnv = allowedEnvs.find((env) => env === target);
 	if (!targetEnv) {
 		console.error(`Target env "${target}" is not allowed.`);
@@ -88,7 +84,7 @@ async function writeCommand() {
 		console.log('Secret not provided. Use --secret flag or WRENV_SECRET env variable.');
 	}
 
-	const target = targets[args.target || process.env.WRENV_TARGET || process.env.TARGET_ENV] || DEFAULT_ENV;
+	const target = resolveTarget(args.target);
 
 	const envContent = fs.readFileSync(envFile, 'utf8');
 	const env = JSON.parse(envContent);
@@ -111,21 +107,29 @@ async function writeCommand() {
 	];
 	const depsName = deps.map((dep) => dep.name);
 
-	const allowedEnvs = env && env.envs && Array.isArray(env.envs) ? env.envs : [DEFAULT_ENV];
-	const targetEnv = allowedEnvs.find((env) => env === target);
-	if (!targetEnv) {
-		console.error(`Target env "${target}" is not allowed.`);
-		process.exit(1);
-	}
+	const allowedEnvs = env && env.envs && Array.isArray(env.envs) ? env.envs : ['dev'];
 
-	const allEnvs = buildEnv(secret, targetEnv, env, depsName);
+	// Handle 'all' target: write all environments with suffixed filenames
+	const isAllTarget = target === 'all';
+	const targetEnvs = isAllTarget ? allowedEnvs : [target];
 
-	for await (const dep of deps) {
-		const pkgEnv = Object.entries(allEnvs[dep.name] || {})
-			.map(([key, value]) => `${key}=${value}`)
-			.join('\n')
-		console.log(`Writing env file for ${dep.name} in ${dep.dir} with target ${targetEnv}`);
-		await fs.writeFile(path.join(dep.dir, '.env'), pkgEnv);
+	for (const targetEnv of targetEnvs) {
+		if (!allowedEnvs.includes(targetEnv)) {
+			console.error(`Target env "${targetEnv}" is not allowed.`);
+			process.exit(1);
+		}
+
+		const allEnvs = buildEnv(secret, targetEnv, env, depsName);
+
+		for await (const dep of deps) {
+			const pkgEnv = Object.entries(allEnvs[dep.name] || {})
+				.map(([key, value]) => `${key}=${value}`)
+				.join('\n')
+			// Use suffixed filename (.env.{outputName}) for 'all', plain .env otherwise
+			const filename = isAllTarget ? `.env.${getOutputName(targetEnv)}` : '.env';
+			console.log(`Writing ${filename} for ${dep.name} in ${dep.dir}`);
+			await fs.writeFile(path.join(dep.dir, filename), pkgEnv);
+		}
 	}
 }
 
@@ -138,6 +142,15 @@ async function encryptCommand() {
 		return;
 	}
 
+	// Verify we can decrypt all existing encrypted values before encrypting new ones
+	const verification = verifyCanDecrypt(env, secret);
+	if (!verification.success) {
+		console.error(`Cannot encrypt: the provided secret cannot decrypt existing encrypted value at "${verification.path}".`);
+		console.error('This would result in a file with mixed encryption passwords.');
+		console.error('Please provide the correct secret that was used for existing encrypted values.');
+		process.exit(1);
+	}
+
 	if (env.variables) {
 		for (const [varName, varValue] of Object.entries(env.variables)) {
 			for (const [envKey, envVal] of Object.entries(varValue)) {
@@ -164,27 +177,30 @@ async function encryptCommand() {
 }
 
 async function besafeCommand() {
-	const relativeEnvPath = path.relative(__root, envFile);
+	// Find git root to ensure we're in a repository and use correct base path
+	const { stdout: gitRoot, exitCode: gitCheck } = await execa('git', ['rev-parse', '--show-toplevel'], { cwd: __root, reject: false });
+	if (gitCheck !== 0) {
+		return;
+	}
 
-	try {
-		const { stdout: stagedDiff } = await execa('git', ['diff', '--cached', '--name-only', '--', relativeEnvPath], { cwd: __root, reject: false });
-		const { stdout: unstagedDiff } = await execa('git', ['diff', '--name-only', '--', relativeEnvPath], { cwd: __root, reject: false });
-		const { stdout: untracked } = await execa('git', ['ls-files', '--others', '--exclude-standard', '--', relativeEnvPath], { cwd: __root, reject: false });
+	const relativeEnvPath = path.relative(gitRoot, envFile);
 
-		if (!stagedDiff?.trim() && !unstagedDiff?.trim() && !untracked?.trim()) {
-			return;
-		}
-	} catch (error) {
+	// Check if file has any changes (staged, unstaged, or untracked)
+	const { stdout: staged } = await execa('git', ['diff', '--cached', '--name-only', '--', relativeEnvPath], { cwd: gitRoot, reject: false });
+	const { stdout: unstaged } = await execa('git', ['diff', '--name-only', '--', relativeEnvPath], { cwd: gitRoot, reject: false });
+	const { stdout: untracked } = await execa('git', ['ls-files', '--others', '--exclude-standard', '--', relativeEnvPath], { cwd: gitRoot, reject: false });
+
+	if (!staged?.trim() && !unstaged?.trim() && !untracked?.trim()) {
 		return;
 	}
 
-	await encrypt();
+	await encryptCommand();
 
 	if (!secret) {
-		console.error('Warning: potential security risk: secret not provided. Variables WERE NOT be encrypted.');
+		console.error('Warning: potential security risk: secret not provided. Variables WERE NOT encrypted.');
 	}
 
-	await execa('git', ['add', relativeEnvPath], { cwd: __root });
+	await execa('git', ['add', relativeEnvPath], { cwd: gitRoot });
 }
 
 async function addCommand() {
@@ -220,18 +236,76 @@ async function addCommand() {
 	await fs.writeFile(envFile, JSON.stringify(env, null, 2));
 }
 
+async function runCommand() {
+	const commandParts = args['--'] || [];
+	const [cmd, ...cmdArgs] = commandParts;
+
+	if (!cmd) {
+		console.error('Usage: wrenv run [options] -- <command> [args...]');
+		process.exit(1);
+	}
+
+	// Load environment variables
+	let envVars = {};
+	try {
+		const { loadEnvJson, loadLocalOverrides, resolveTarget, resolveSecret } = await import('../src/core.js');
+
+		const resolvedSecret = args.secret
+			? (args.secret === 'stdin' ? fs.readFileSync(0, 'utf8').trim() : fs.readFileSync(args.secret, 'utf8').trim())
+			: process.env.WRENV_SECRET || process.env.TARGET_SECRET || null;
+
+		const target = resolveTarget(args.target);
+
+		envVars = loadEnvJson({
+			secret: resolvedSecret,
+			targetEnv: target,
+			envPath: args.env,
+		});
+
+		// Apply .env.local overrides only in dev mode (security: prevent local overrides in production)
+		if (target === 'dev') {
+			const localOverrides = loadLocalOverrides();
+			for (const [key, value] of Object.entries(localOverrides)) {
+				if (Object.hasOwn(envVars, key)) {
+					envVars[key] = value;
+				}
+			}
+		}
+	} catch (error) {
+		console.error(`wrenv: ${error.message}`);
+		process.exit(1);
+	}
+
+	// Use execa for cross-platform compatibility with minimal overhead
+	const subprocess = execa(cmd, cmdArgs, {
+		stdio: 'inherit',
+		env: { ...process.env, ...envVars },
+		reject: false,
+	});
+
+	// Forward signals to child process
+	const forwardSignal = (signal) => subprocess.kill(signal);
+	process.on('SIGTERM', () => forwardSignal('SIGTERM'));
+	process.on('SIGINT', () => forwardSignal('SIGINT'));
+	process.on('SIGHUP', () => forwardSignal('SIGHUP'));
+
+	const result = await subprocess;
+	process.exit(result.exitCode ?? 0);
+}
+
 function helpCommand() {
 	console.log('Usage: wrenv [command] [options]\n');
 	console.log('Commands:');
 	console.log('  write          Write .env files for all packages (default)');
 	console.log('  show           Show environment variables without writing files');
+	console.log('  run            Run a command with injected environment variables');
 	console.log('  encrypt        Encrypt all unencrypted variables in .env.json');
 	console.log('  besafe         Encrypt and stage .env.json if it has changes');
 	console.log('  add <var>      Add a new variable with environment-specific values');
 	console.log('  help           Show this help message\n');
 	console.log('Options:');
 	console.log('  --secret <path|stdin>  Path to secret file or "stdin" to read from stdin');
-	console.log('  --target <env>         Target environment (dev, staging, prod, etc.)');
+	console.log('  --target <env>         Target environment (dev, staging, prod, all)');
 	console.log('  --env <path>           Path to env file (default: .env.json)\n');
 	console.log('Environment Variables:');
 	console.log('  WRENV_SECRET           Secret for encryption/decryption');
@@ -242,7 +316,10 @@ function helpCommand() {
 	console.log('  wrenv --secret ~/.big-secret write --target dev');
 	console.log('  wrenv --secret stdin write < ~/.big-secret');
 	console.log('  wrenv show --target prod');
+	console.log('  wrenv run --target prod -- node server.js');
+	console.log('  wrenv run -- npm test --coverage');
 	console.log('  wrenv add NEW_VAR +fallback=value +dev=dev_value +production=prod_value');
+	console.log('  wrenv write --target all   # writes .env.development, .env.staging, .env.production');
 }
 
 const commands = {
@@ -251,6 +328,7 @@ const commands = {
 	besafe: besafeCommand,
 	encrypt: encryptCommand,
 	add: addCommand,
+	run: runCommand,
 	help: helpCommand,
 };
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@saasak/tool-env",
   "license": "MIT",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "author": "dev@saasak.studio",
   "description": "A small util to manage environment variables for your monorepo",
   "keywords": [
@@ -10,7 +10,7 @@
     "env"
   ],
   "type": "module",
-  "main": "bin/index.js",
+  "main": "src/index.js",
   "files": [
     "bin",
     "src"
@@ -22,5 +22,12 @@
     "execa": "8.0.1",
     "fs-extra": "11.2.0",
     "minimist": "1.2.8"
+  },
+  "devDependencies": {
+    "vitest": "^1.6.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }

package/src/core.js

@@ -0,0 +1,446 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { decrypt, isEncrypted } from './utils-crypto.js';
+import { buildEnv } from './utils-env.js';
+import { findMonorepoPackages } from './utils-pkg.js';
+
+/**
+ * @typedef {Object.<string, string>} EnvRecord
+ * Key-value pairs of environment variable name to value
+ */
+
+/**
+ * @typedef {Object} LoadOptions
+ * @property {string} [targetEnv] - Target environment (e.g. 'dev', 'production')
+ * @property {string} [secret] - Secret for decryption (or file://path to read from file)
+ * @property {string} [envPath] - Path to env.json file (default: '.env.json')
+ * @property {string} [cwd] - Working directory (default: process.cwd())
+ * @property {boolean} [applyToProcess] - Whether to apply to process.env (default: true)
+ */
+
+/**
+ * @typedef {Object} LoadEnvJsonOptions
+ * @property {string} [secret] - Secret for decryption (or file://path)
+ * @property {string} [targetEnv] - Target environment
+ * @property {string} [envPath] - Path to env.json file (default: '.env.json')
+ * @property {string} [cwd] - Working directory (default: process.cwd())
+ */
+
+/**
+ * @typedef {Object} VerifyResult
+ * @property {boolean} success - Whether verification passed
+ * @property {string|null} [path] - Path to the failed encrypted value
+ * @property {string} [error] - Error message if verification failed
+ */
+
+/** @type {string} */
+const DEFAULT_ENV = 'dev';
+
+/**
+ * Mapping of environment name aliases to canonical names
+ * Note: 'all' is a special target that writes all environments (write command only)
+ * @type {Object.<string, string>}
+ */
+const targets = {
+	"development": "dev",
+	"dev": "dev",
+	"staging": "preprod",
+	"pp": "preprod",
+	"preprod": "preprod",
+	"prod": "production",
+	"production": "production",
+	"all": "all",
+};
+
+/**
+ * Mapping of internal environment names to conventional output file names
+ * Used when writing .env files with 'all' target
+ * @type {Object.<string, string>}
+ */
+const outputNames = {
+	"dev": "development",
+	"preprod": "staging",
+	"production": "production",
+};
+
+/**
+ * Get the conventional output file name for an internal environment name
+ * Falls back to the internal name if no mapping exists
+ * @param {string} internalName - Internal environment name (e.g. 'dev', 'preprod')
+ * @returns {string} - Conventional output name (e.g. 'development', 'staging')
+ */
+export function getOutputName(internalName) {
+	return outputNames[internalName] || internalName;
+}
+
+/**
+ * Resolve target environment with fallback chain:
+ * param -> WRENV_TARGET -> TARGET_ENV -> NODE_ENV (mapped) -> 'dev'
+ * @param {string} [targetParam] - Explicit target environment parameter
+ * @returns {string} - Resolved target environment
+ */
+export function resolveTarget(targetParam) {
+	if (targetParam) {
+		return targets[targetParam] || targetParam;
+	}
+
+	const envTarget = process.env.WRENV_TARGET || process.env.TARGET_ENV;
+	if (envTarget) {
+		return targets[envTarget] || envTarget;
+	}
+
+	const nodeEnv = process.env.NODE_ENV;
+	if (nodeEnv && targets[nodeEnv]) {
+		return targets[nodeEnv];
+	}
+
+	return DEFAULT_ENV;
+}
+
+/**
+ * Resolve target environment aliases:
+ * param -> allowedEnvs
+ * @param {string[]} [allowedEnvs] - 4rray of allowed environments to resolve against (e.g. ['dev', 'preprod', 'production'])
+ * @returns {string[]} - Resolved target sliases environment
+ */
+export function resolveTargetAliases(allowedEnvs) {
+	const allowedAliases = allowedEnvs.flatMap(
+		(env => Object.entries(targets)
+			.find(([_, val]) => val === env)
+			.map(([alias]) => alias)
+		)
+	)
+
+	return Array.from(new Set(allowedAliases));
+}
+
+
+/**
+ * Resolve secret with support for file:// prefix
+ * Falls back to WRENV_SECRET or TARGET_SECRET environment variables
+ * @param {string} [secretParam] - Secret string or file path (with file:// prefix)
+ * @returns {string|null} - Resolved secret or null if not provided
+ * @throws {Error} - If file:// path cannot be read
+ */
+export function resolveSecret(secretParam) {
+	if (!secretParam) {
+		return process.env.WRENV_SECRET || process.env.TARGET_SECRET || null;
+	}
+
+	if (secretParam.startsWith('file://')) {
+		const filePath = secretParam.slice(7);
+		try {
+			return fs.readFileSync(filePath, 'utf8').trim();
+		} catch (error) {
+			throw new Error(`Failed to read secret from file: ${filePath}`);
+		}
+	}
+
+	return secretParam;
+}
+
+/**
+ * Parse .env file content into key-value pairs
+ * Supports standard KEY=value format with basic quote handling
+ * @param {string} content - Raw .env file content
+ * @returns {EnvRecord} - Parsed key-value pairs
+ */
+export function parseEnvFile(content) {
+	/** @type {EnvRecord} */
+	const result = {};
+	const lines = content.split('\n');
+
+	for (const line of lines) {
+		const trimmed = line.trim();
+
+		// Skip empty lines and comments
+		if (!trimmed || trimmed.startsWith('#')) {
+			continue;
+		}
+
+		// Find the first = sign
+		const eqIndex = trimmed.indexOf('=');
+		if (eqIndex === -1) {
+			continue;
+		}
+
+		const key = trimmed.slice(0, eqIndex).trim();
+		let value = trimmed.slice(eqIndex + 1).trim();
+
+		// Remove surrounding quotes if present
+		if ((value.startsWith('"') && value.endsWith('"')) ||
+			(value.startsWith("'") && value.endsWith("'"))) {
+			value = value.slice(1, -1);
+		}
+
+		if (key) {
+			result[key] = value;
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Find the nearest package.json traversing upward from cwd and return its name (without scope)
+ * @param {string} cwd - Starting directory
+ * @param {string} scope - Package scope (e.g. '@saasak')
+ * @returns {string} - Package name without scope, or 'root' as fallback
+ */
+function findNearestPackageName(cwd, scope) {
+	let currentDir = cwd;
+
+	while (currentDir !== path.dirname(currentDir)) { // Stop at filesystem root
+		const pkgPath = path.join(currentDir, 'package.json');
+		if (fs.existsSync(pkgPath)) {
+			try {
+				const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+				if (pkg.name) {
+					// Return name without scope prefix
+					return pkg.name.replace(`${scope}/`, '');
+				}
+			} catch (e) {
+				// Continue traversing upward
+			}
+		}
+		currentDir = path.dirname(currentDir);
+	}
+
+	return 'root'; // fallback
+}
+
+/**
+ * Load .env.local file if it exists
+ * @param {string} [cwd] - Working directory (default: process.cwd())
+ * @returns {EnvRecord} - Local overrides or empty object
+ */
+export function loadLocalOverrides(cwd = process.cwd()) {
+	const localEnvPath = path.join(cwd, '.env.local');
+
+	if (!fs.existsSync(localEnvPath)) {
+		return {};
+	}
+
+	try {
+		const content = fs.readFileSync(localEnvPath, 'utf8');
+		return parseEnvFile(content);
+	} catch (error) {
+		return {};
+	}
+}
+
+/**
+ * Find the monorepo root by looking for the env.json file, traversing upward from cwd
+ * @param {string} cwd - Starting directory
+ * @param {string} envPath - Name of the env file (e.g. '.env.json')
+ * @returns {string|null} - Path to monorepo root, or null if not found
+ */
+function findMonorepoRoot(cwd, envPath) {
+	let currentDir = cwd;
+
+	while (currentDir !== path.dirname(currentDir)) {
+		const envFilePath = path.join(currentDir, envPath);
+		if (fs.existsSync(envFilePath)) {
+			return currentDir;
+		}
+		currentDir = path.dirname(currentDir);
+	}
+
+	return null;
+}
+
+/**
+ * Load environment configuration from env.json file
+ * Automatically detects the current package and returns its specific env vars
+ * @param {LoadEnvJsonOptions} [options] - Options object
+ * @returns {EnvRecord} - Decrypted environment variables for the current package
+ * @throws {Error} - If env file not found or target env not allowed
+ */
+export function loadEnvJson(options = {}) {
+	const {
+		secret: secretParam,
+		targetEnv: targetParam,
+		envPath = '.env.json',
+		cwd = process.cwd()
+	} = options;
+
+	const secret = resolveSecret(secretParam);
+	const targetEnv = resolveTarget(targetParam);
+
+	// Find the monorepo root (where env.json lives)
+	const monorepoRoot = findMonorepoRoot(cwd, envPath);
+	if (!monorepoRoot) {
+		throw new Error(`No env file found (searched upward from ${cwd})`);
+	}
+
+	const envFile = path.join(monorepoRoot, envPath);
+	const envContent = fs.readFileSync(envFile, 'utf8');
+	const env = JSON.parse(envContent);
+
+	const allowedEnvs = env && env.envs && Array.isArray(env.envs) ? env.envs : [DEFAULT_ENV];
+	const resolvedTarget = allowedEnvs.find((e) => e === targetEnv);
+
+	if (!resolvedTarget) {
+		throw new Error(`Target env "${targetEnv}" is not allowed. Allowed: ${allowedEnvs.join(', ')}`);
+	}
+
+	// Get scope from monorepo root package.json
+	const rootPkgPath = path.join(monorepoRoot, 'package.json');
+	let scope = '';
+	/** @type {string[]} */
+	let depsName = ['root'];
+
+	if (fs.existsSync(rootPkgPath)) {
+		try {
+			const rootPkgContent = fs.readFileSync(rootPkgPath, 'utf8');
+			const rootPkg = JSON.parse(rootPkgContent);
+			scope = rootPkg.name.split('/')[0];
+
+			const foundPackages = findMonorepoPackages(monorepoRoot, scope);
+			depsName = [
+				...foundPackages.map((pkg) => pkg.name.replace(`${scope}/`, '')),
+				'root'
+			];
+		} catch (error) {
+			// Not a monorepo or error parsing, use default
+		}
+	}
+
+	const allEnvs = buildEnv(secret, resolvedTarget, env, depsName);
+
+	// Find the current package name from nearest package.json
+	const currentPackageName = findNearestPackageName(cwd, scope);
+
+	// Return env for current package (with fallback to root)
+	return allEnvs[currentPackageName] || allEnvs.root || {};
+}
+
+/**
+ * Main load function - loads env.json and applies .env.local overrides
+ * Applies values to process.env and returns the final config object
+ * @param {LoadOptions} [options] - Options object
+ * @returns {EnvRecord} - Final environment configuration
+ * @throws {Error} - If env file not found or target env not allowed
+ * @example
+ * // Basic usage - loads from cwd, applies to process.env
+ * const config = load();
+ *
+ * @example
+ * // With options
+ * const config = load({
+ *   targetEnv: 'production',
+ *   secret: 'file://./secret.txt',
+ *   applyToProcess: false
+ * });
+ */
+export function load(options = {}) {
+	const {
+		targetEnv,
+		secret,
+		envPath,
+		cwd = process.cwd(),
+		applyToProcess = true
+	} = options;
+
+	// Resolve target first to determine if we're in dev mode
+	const resolvedTarget = resolveTarget(targetEnv);
+
+	// Load env.json config
+	const envConfig = loadEnvJson({
+		secret,
+		targetEnv: resolvedTarget,
+		envPath,
+		cwd
+	});
+
+	// Load .env.local overrides only in dev mode (security: prevent local overrides in production)
+	const localOverrides = resolvedTarget === 'dev'
+		? loadLocalOverrides(cwd)
+		: {};
+
+	// Merge: env.json values, then .env.local overrides (local takes precedence)
+	// Note: .env.local only overrides env.json values, not existing process.env
+	/** @type {EnvRecord} */
+	const finalConfig = { ...envConfig };
+
+	for (const [key, value] of Object.entries(localOverrides)) {
+		if (Object.prototype.hasOwnProperty.call(envConfig, key)) {
+			finalConfig[key] = value;
+		}
+	}
+
+	// Apply to process.env if requested
+	if (applyToProcess) {
+		for (const [key, value] of Object.entries(finalConfig)) {
+			process.env[key] = value;
+		}
+	}
+
+	return finalConfig;
+}
+
+/**
+ * @typedef {Object} EncryptedValueInfo
+ * @property {string} path - Path to the encrypted value (e.g. 'variables.API_KEY.dev')
+ * @property {string} value - The encrypted value
+ */
+
+/**
+ * Verify that all encrypted values in the env can be decrypted with the provided secret
+ * This prevents mixed-encryption scenarios where different passwords are used
+ * @param {Object} env - The env configuration object (parsed env.json)
+ * @param {string} secret - The secret to use for decryption (already resolved, not file:// path)
+ * @returns {VerifyResult} - Verification result with success status
+ */
+export function verifyCanDecrypt(env, secret) {
+	/** @type {EncryptedValueInfo[]} */
+	const encryptedValues = [];
+
+	if (!secret) {
+		return { success: false, path: null, error: 'No secret provided' };
+	}
+
+	// Collect all encrypted values from variables
+	if (env.variables) {
+		for (const [varName, varValue] of Object.entries(env.variables)) {
+			for (const [envKey, envVal] of Object.entries(varValue)) {
+				if (typeof envVal === 'string' && isEncrypted(envVal)) {
+					encryptedValues.push({ path: `variables.${varName}.${envKey}`, value: envVal });
+				}
+			}
+		}
+	}
+
+	// Collect all encrypted values from overrides
+	if (env.overrides) {
+		for (const [pkgName, pkgOverrides] of Object.entries(env.overrides)) {
+			for (const [varName, varValue] of Object.entries(pkgOverrides)) {
+				for (const [envKey, envVal] of Object.entries(varValue)) {
+					if (typeof envVal === 'string' && isEncrypted(envVal)) {
+						encryptedValues.push({ path: `overrides.${pkgName}.${varName}.${envKey}`, value: envVal });
+					}
+				}
+			}
+		}
+	}
+
+	// If no encrypted values exist, verification passes (first-time encryption)
+	if (encryptedValues.length === 0) {
+		return { success: true };
+	}
+
+	// Try to decrypt each encrypted value
+	for (const { path, value } of encryptedValues) {
+		try {
+			decrypt(value, secret);
+		} catch (error) {
+			return {
+				success: false,
+				path,
+				error: error.message
+			};
+		}
+	}
+
+	return { success: true };
+}

package/src/index.js

@@ -0,0 +1,42 @@
+/**
+ * @saasak/tool-env - Environment variable management for monorepos
+ * 
+ * Main module exports for programmatic usage.
+ * 
+ * @example
+ * // Basic usage - load env vars and apply to process.env
+ * import { load } from '@saasak/tool-env';
+ * const config = load();
+ * 
+ * @example
+ * // Load with specific options
+ * import { load } from '@saasak/tool-env';
+ * const config = load({
+ *   targetEnv: 'production',
+ *   secret: 'file://./secret.txt',
+ *   applyToProcess: false
+ * });
+ * 
+ * @module @saasak/tool-env
+ */
+
+// Core functions for loading and resolving environment configuration
+export { 
+	load, 
+	loadEnvJson, 
+	loadLocalOverrides, 
+	parseEnvFile,
+	resolveTarget, 
+	resolveSecret,
+	verifyCanDecrypt,
+	getOutputName
+} from './core.js';
+
+// Re-export crypto utilities for encryption/decryption
+export { encrypt, decrypt, isEncrypted } from './utils-crypto.js';
+
+// Re-export env building utilities
+export { buildEnv } from './utils-env.js';
+
+// Re-export package utilities
+export { findMonorepoPackages } from './utils-pkg.js';

package/src/utils-crypto.js

@@ -3,18 +3,29 @@ import crypto from 'crypto';
 // Constants for AES-256-GCM encryption
 // GCM provides authenticated encryption (confidentiality + integrity)
 // Using 256-bit keys for strong security
+
+/** @type {string} */
 const ENCRYPTION_PREFIX = '$enc$';
+/** @type {string} */
 const ALGORITHM = 'aes-256-gcm';
-const IV_LENGTH = 16; // 128 bits
-const SALT_LENGTH = 64; // 512 bits
-const TAG_LENGTH = 16; // 128 bits
-const KEY_LENGTH = 32; // 256 bits
-const ITERATIONS = 100000; // PBKDF2 iterations
+/** @type {number} 128 bits */
+const IV_LENGTH = 16;
+/** @type {number} 512 bits */
+const SALT_LENGTH = 64;
+/** @type {number} 128 bits */
+const TAG_LENGTH = 16;
+/** @type {number} 256 bits */
+const KEY_LENGTH = 32;
+/** @type {number} PBKDF2 iterations */
+const ITERATIONS = 100000;
 
 /**
  * Derive a 256-bit key from a secret using PBKDF2
  * This ensures consistent key generation from variable-length secrets
  * and adds computational cost to prevent brute-force attacks
+ * @param {string} secret - The secret passphrase
+ * @param {Buffer} salt - Random salt for key derivation
+ * @returns {Buffer} - Derived 256-bit key
  */
 function deriveKey(secret, salt) {
 	return crypto.pbkdf2Sync(secret, salt, ITERATIONS, KEY_LENGTH, 'sha256');
@@ -24,6 +35,9 @@ function deriveKey(secret, salt) {
  * Encrypt a string value using AES-256-GCM
  * Returns a string with format: $enc$<base64(salt+iv+ciphertext+tag)>
  * Each encryption uses a unique salt and IV, so the same plaintext produces different ciphertexts
+ * @param {string} plaintext - The string to encrypt
+ * @param {string} secret - The secret passphrase for encryption
+ * @returns {string} - Encrypted string with $enc$ prefix, or original value if empty
  */
 export function encrypt(plaintext, secret) {
 	if (!plaintext) return plaintext;
@@ -50,6 +64,10 @@ export function encrypt(plaintext, secret) {
  * Decrypt an encrypted string
  * Strips the prefix and decodes the base64 payload
  * GCM authentication tag ensures the data hasn't been tampered with
+ * @param {string} encrypted - The encrypted string (with $enc$ prefix)
+ * @param {string} secret - The secret passphrase for decryption
+ * @returns {string} - Decrypted plaintext, or original value if not encrypted
+ * @throws {Error} - If decryption fails (wrong secret or corrupted data)
  */
 export function decrypt(encrypted, secret) {
 	if (!encrypted || !isEncrypted(encrypted)) {
@@ -83,8 +101,9 @@ export function decrypt(encrypted, secret) {
 /**
  * Check if a string is encrypted by looking for the prefix
  * This allows the system to detect encrypted values without attempting decryption
+ * @param {unknown} value - The value to check
+ * @returns {boolean} - True if the value is an encrypted string
  */
 export function isEncrypted(value) {
 	return typeof value === 'string' && value.startsWith(ENCRYPTION_PREFIX);
 }
-

package/src/utils-env.js

@@ -1,14 +1,52 @@
 import { decrypt, isEncrypted } from './utils-crypto.js';
 
-// ========================================
-// Helpers for core logic
-// ========================================
+/**
+ * @typedef {Object} EnvVariableValue
+ * @property {string} [@@] - Fallback value for all environments
+ * @property {string} [dev] - Value for dev environment
+ * @property {string} [preprod] - Value for preprod environment
+ * @property {string} [production] - Value for production environment
+ */
 
+/**
+ * @typedef {Object.<string, EnvVariableValue>} EnvVariables
+ */
+
+/**
+ * @typedef {Object.<string, Object.<string, EnvVariableValue>>} EnvOverrides
+ */
+
+/**
+ * @typedef {Object} EnvConfig
+ * @property {string[]} [envs] - List of allowed environment names
+ * @property {EnvVariables} variables - Environment variables by name
+ * @property {EnvOverrides} [overrides] - Package-specific overrides
+ */
+
+/**
+ * @typedef {Object.<string, string>} EnvRecord
+ * Key-value pairs of environment variable name to value
+ */
+
+/**
+ * @typedef {Object.<string, EnvRecord>} AllEnvs
+ * Environment variables grouped by package name
+ */
+
+/**
+ * Build environment variables for all packages
+ * @param {string} secret - Secret for decrypting encrypted values
+ * @param {string} target - Target environment (e.g. 'dev', 'production')
+ * @param {EnvConfig} env - The env.json configuration object
+ * @param {string[]} names - List of package names to build env for
+ * @returns {AllEnvs} - Environment variables grouped by package name
+ */
 export function buildEnv(secret, target, env, names) {
 	const variablesForAllTargets = env.variables;
 	const overrides = env.overrides || {};
 
 	// For each variable, extract the value for the target env
+	/** @type {EnvRecord} */
 	const variables = Object.entries(variablesForAllTargets).reduce((acc, entry) => {
 		const [key, value] = entry;
 		return {
@@ -22,6 +60,7 @@ export function buildEnv(secret, target, env, names) {
 	// allVars is an object with the package name as key
 	// and the variables as value like so
 	// => { [name]: { [variable]: value } }
+	/** @type {AllEnvs} */
 	const allVars = names.reduce((acc, name) => {
 		acc[name] = {
 			...variables,
@@ -34,8 +73,15 @@ export function buildEnv(secret, target, env, names) {
 	return allVars;
 }
 
+/**
+ * Parse package-specific overrides for a target environment
+ * @param {string} secret - Secret for decrypting encrypted values
+ * @param {string} target - Target environment
+ * @param {Object.<string, EnvVariableValue>} [overrides] - Package overrides
+ * @param {EnvRecord} vars - Base variables for reference substitution
+ * @returns {EnvRecord} - Parsed override values
+ */
 function parseOverrides(secret, target, overrides, vars) {
-	if (!secret) return {};
 	if (!overrides) return {};
 
 	return Object.entries(overrides).reduce((acc, entry) => {
@@ -45,12 +91,18 @@ function parseOverrides(secret, target, overrides, vars) {
 		if (value === null) return acc;
 
 		acc[key] = Array.isArray(value)
-			? value.map(v => vars[v] || v).join('')
-			: value
+			? value.map(v => Object.prototype.hasOwnProperty.call(vars, v) ? vars[v] : v).join('')
+			: value;
 		return acc;
 	}, {});
 }
 
+/**
+ * Extract and decrypt a value if needed
+ * @param {string} secret - Secret for decryption
+ * @param {string} value - Value to extract (may be encrypted)
+ * @returns {string} - Decrypted/plain value, or empty string if no secret
+ */
 function extractValue(secret, value) {
 	if (!isEncrypted(value)) return value;
 	if (!secret) return '';

package/src/utils-pkg.js

@@ -1,68 +1,85 @@
 import path from 'path';
 import fs from 'fs-extra';
 
-export async function findMonorepoPackages(rootDir, scope = null, maxDepth = 4) {
-	const packages = [];
-
-	async function processPackage(pkgPath, pkgDir) {
-		try {
-			const pkgContent = await fs.readFile(pkgPath, 'utf8');
-			const pkg = JSON.parse(pkgContent);
-
-			if (scope && !pkg.name?.startsWith(`${scope}/`)) {
-				return null;
-			}
-
-			return {
-				name: pkg.name,
-				dir: pkgDir,
-			};
-		} catch (err) {
+/**
+ * @typedef {Object} PackageInfo
+ * @property {string} name - Package name (e.g. '@scope/package-name')
+ * @property {string} dir - Absolute path to the package directory
+ */
+
+/**
+ * Try to read and parse a package.json, returning PackageInfo if valid and matches scope
+ * @param {string} dir - Directory containing package.json
+ * @param {string|null} scope - Package scope to filter by
+ * @returns {PackageInfo|null}
+ */
+function readPackageInfo(dir, scope) {
+	const pkgPath = path.join(dir, 'package.json');
+
+	try {
+		if (!fs.existsSync(pkgPath)) return null;
+
+		const pkg = fs.readJsonSync(pkgPath);
+
+		if (scope && !pkg.name?.startsWith(`${scope}/`)) {
 			return null;
 		}
-	}
-
-	async function traverse(dir, currentDepth = 0) {
-		if (currentDepth > maxDepth) return;
-
-		try {
-			const entries = await fs.readdir(dir, { withFileTypes: true });
-
-			for (const entry of entries) {
-				const fullPath = path.join(dir, entry.name);
-
-				if (entry.name === 'node_modules' || entry.isSymbolicLink()) {
-					continue;
-				}
-
-				if (!entry.isDirectory()) continue;
 
-				const pkgPath = path.join(fullPath, 'package.json');
-				const exists = await fs.pathExists(pkgPath);
-
-				if (exists) {
-					const pkg = await processPackage(pkgPath, fullPath);
-					packages.push(pkg);
-				}
-
-				await traverse(fullPath, currentDepth + 1);
-			}
-		} catch (err) {
-			return;
-		}
+		return { name: pkg.name, dir };
+	} catch {
+		return null;
 	}
+}
 
-	const rootPkgPath = path.join(rootDir, 'package.json');
-	const exists = await fs.pathExists(rootPkgPath);
-
-	if (!exists) return [];
+/**
+ * Get valid subdirectories (excluding node_modules and symlinks)
+ * @param {string} dir - Directory to list
+ * @returns {string[]} - Array of absolute paths to subdirectories
+ */
+function getSubdirectories(dir) {
+	try {
+		return fs
+			.readdirSync(dir, { withFileTypes: true })
+			.filter(
+				(entry) =>
+					entry.isDirectory() &&
+					!entry.isSymbolicLink() &&
+					entry.name !== 'node_modules'
+			)
+			.map((entry) => path.join(dir, entry.name));
+	} catch {
+		return [];
+	}
+}
 
-	const pkg = await processPackage(rootPkgPath, rootDir);
+/**
+ * Recursively collect packages from a directory tree
+ * @param {string} dir - Directory to search
+ * @param {string|null} scope - Package scope to filter by
+ * @param {number} depth - Remaining depth to traverse
+ * @returns {PackageInfo[]}
+ */
+function collectPackages(dir, scope, depth) {
+	if (depth < 0) return [];
+
+	return getSubdirectories(dir).flatMap((subdir) => {
+		const pkg = readPackageInfo(subdir, scope);
+		const nested = collectPackages(subdir, scope, depth - 1);
+		return pkg ? [pkg, ...nested] : nested;
+	});
+}
 
-	if (!pkg) return [];
+/**
+ * Find all packages in a monorepo by traversing the directory tree
+ * @param {string} rootDir - Root directory to start searching from
+ * @param {string|null} [scope=null] - Package scope to filter by (e.g. '@saasak')
+ * @param {number} [maxDepth=4] - Maximum directory depth to traverse
+ * @returns {PackageInfo[]} - Array of found packages (root package first, no nulls)
+ */
+export function findMonorepoPackages(rootDir, scope = null, maxDepth = 4) {
+	const rootPkg = readPackageInfo(rootDir, scope);
 
-	packages.push(pkg);
-	await traverse(rootDir, 0);
+	if (!rootPkg) return [];
 
-	return packages;
+	return [rootPkg, ...collectPackages(rootDir, scope, maxDepth)];
 }