@saasak/tool-env 1.1.0 → 1.2.0

package/bin/index.js

@@ -1,65 +1,72 @@
 #!/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 { resolveTarget, verifyCanDecrypt, getOutputName } from '../src/core.js';
-
-const args = minimist(process.argv.slice(2), { '--': true });
+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 {
+	resolveTarget,
+	resolveSecret,
+	verifyCanDecrypt,
+	getOutputName,
+	load,
+} from "../src/core.js";
+
+const args = minimist(process.argv.slice(2), { "--": true });
 const __root = process.cwd();
 
-const command = args._[0] || 'write';
+const command = args._[0] || "write";
 
-const secret = args.secret
-	? (args.secret === 'stdin' ? fs.readFileSync(0, 'utf8').trim() : fs.readFileSync(args.secret, 'utf8').trim())
-	: process.env.WRENV_SECRET || process.env.TARGET_SECRET || '';
+const secret = resolveSecret(args.secret);
 
-const envPath = args.env || '.env.json';
+const envPath = args.env || ".env.json";
 const envFile = path.resolve(__root, envPath);
 
 // Check env file exists for commands that need it
-const commandsRequiringEnvFile = ['write', 'show', 'encrypt', 'besafe', 'add'];
+const commandsRequiringEnvFile = ["write", "show", "encrypt", "besafe", "add"];
 if (commandsRequiringEnvFile.includes(command) && !fs.existsSync(envFile)) {
-	console.error('No env file found.');
+	console.error("No env file found.");
 	process.exit(1);
 }
 
 async function showCommand() {
 	if (!secret) {
-		console.log('Secret not provided. Use --secret flag or WRENV_SECRET env variable.');
+		console.log(
+			"Secret not provided. Use --secret flag or WRENV_SECRET env variable.",
+		);
 	}
 
 	const target = resolveTarget(args.target);
 
-	const envContent = fs.readFileSync(envFile, 'utf8');
+	const envContent = fs.readFileSync(envFile, "utf8");
 	const env = JSON.parse(envContent);
 
-	const rootPkgPath = path.resolve(__root, 'package.json');
-	const rootPkgContent = fs.readFileSync(rootPkgPath, 'utf8');
+	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 scope = rootPkg.name.split("/")[0];
 	const [_, ...foundPackages] = findMonorepoPackages(__root, scope);
 
 	const deps = [
 		...foundPackages.filter(Boolean).map((pkg) => ({
-			name: pkg.name.replace(`${scope}/`, ''),
+			name: pkg.name.replace(`${scope}/`, ""),
 			dir: pkg.dir,
 		})),
 		{
-			name: 'root',
+			name: "root",
 			dir: __root,
 		},
 	];
 
 	const depsName = deps.map((dep) => dep.name);
 
-	const allowedEnvs = env && env.envs && Array.isArray(env.envs) ? env.envs : ['dev'];
+	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.`);
@@ -71,46 +78,50 @@ async function showCommand() {
 	for await (const dep of deps) {
 		const pkgEnv = Object.entries(allEnvs[dep.name] || {})
 			.map(([key, value]) => `${key}=${value}`)
-			.join('\n')
-		console.log('~~~~~~~~~~~~~~~~~~~~~~~~~~~~');
-		console.log(`=== ENV for ${dep.name} in ${dep.dir} with target ${targetEnv}`);
+			.join("\n");
+		console.log("~~~~~~~~~~~~~~~~~~~~~~~~~~~~");
+		console.log(
+			`=== ENV for ${dep.name} in ${dep.dir} with target ${targetEnv}`,
+		);
 		console.log(pkgEnv);
 	}
-
 }
 
 async function writeCommand() {
 	if (!secret) {
-		console.log('Secret not provided. Use --secret flag or WRENV_SECRET env variable.');
+		console.log(
+			"Secret not provided. Use --secret flag or WRENV_SECRET env variable.",
+		);
 	}
 
 	const target = resolveTarget(args.target);
 
-	const envContent = fs.readFileSync(envFile, 'utf8');
+	const envContent = fs.readFileSync(envFile, "utf8");
 	const env = JSON.parse(envContent);
 
-	const rootPkgPath = path.resolve(__root, 'package.json');
-	const rootPkgContent = fs.readFileSync(rootPkgPath, 'utf8');
+	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 scope = rootPkg.name.split("/")[0];
 
 	const [_, ...foundPackages] = await findMonorepoPackages(__root, scope);
 	const deps = [
 		...foundPackages.map((pkg) => ({
-			name: pkg.name.replace(`${scope}/`, ''),
+			name: pkg.name.replace(`${scope}/`, ""),
 			dir: pkg.dir,
 		})),
 		{
-			name: 'root',
+			name: "root",
 			dir: __root,
 		},
 	];
 	const depsName = deps.map((dep) => dep.name);
 
-	const allowedEnvs = env && env.envs && Array.isArray(env.envs) ? env.envs : ['dev'];
+	const allowedEnvs =
+		env && env.envs && Array.isArray(env.envs) ? env.envs : ["dev"];
 
 	// Handle 'all' target: write all environments with suffixed filenames
-	const isAllTarget = target === 'all';
+	const isAllTarget = target === "all";
 	const targetEnvs = isAllTarget ? allowedEnvs : [target];
 
 	for (const targetEnv of targetEnvs) {
@@ -124,9 +135,11 @@ async function writeCommand() {
 		for await (const dep of deps) {
 			const pkgEnv = Object.entries(allEnvs[dep.name] || {})
 				.map(([key, value]) => `${key}=${value}`)
-				.join('\n')
+				.join("\n");
 			// Use suffixed filename (.env.{outputName}) for 'all', plain .env otherwise
-			const filename = isAllTarget ? `.env.${getOutputName(targetEnv)}` : '.env';
+			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);
 		}
@@ -134,27 +147,35 @@ async function writeCommand() {
 }
 
 async function encryptCommand() {
-	const envContent = fs.readFileSync(envFile, 'utf8');
+	const envContent = fs.readFileSync(envFile, "utf8");
 	const env = JSON.parse(envContent);
 
 	if (!secret) {
-		console.error('Cannot encrypt env file: secret not provided. Doing nothing');
+		console.error(
+			"Cannot encrypt env file: secret not provided. Doing nothing",
+		);
 		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.');
+		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)) {
-				if (typeof envVal === 'string' && !isEncrypted(envVal)) {
+				if (typeof envVal === "string" && !isEncrypted(envVal)) {
 					env.variables[varName][envKey] = encrypt(envVal, secret);
 				}
 			}
@@ -165,7 +186,7 @@ async function encryptCommand() {
 		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)) {
+					if (typeof envVal === "string" && !isEncrypted(envVal)) {
 						env.overrides[pkgName][varName][envKey] = encrypt(envVal, secret);
 					}
 				}
@@ -178,7 +199,11 @@ async function encryptCommand() {
 
 async function besafeCommand() {
 	// 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 });
+	const { stdout: gitRoot, exitCode: gitCheck } = await execa(
+		"git",
+		["rev-parse", "--show-toplevel"],
+		{ cwd: __root, reject: false },
+	);
 	if (gitCheck !== 0) {
 		return;
 	}
@@ -186,9 +211,21 @@ async function besafeCommand() {
 	const relativeEnvPath = path.relative(gitRoot, envFile);
 
 	// 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 });
+	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;
@@ -197,24 +234,28 @@ async function besafeCommand() {
 	await encryptCommand();
 
 	if (!secret) {
-		console.error('Warning: potential security risk: secret not provided. Variables WERE NOT encrypted.');
+		console.error(
+			"Warning: potential security risk: secret not provided. Variables WERE NOT encrypted.",
+		);
 	}
 
-	await execa('git', ['add', relativeEnvPath], { cwd: gitRoot });
+	await execa("git", ["add", relativeEnvPath], { cwd: gitRoot });
 }
 
 async function addCommand() {
 	const varName = args._[1];
 	if (!varName) {
-		console.error('Variable name is required.');
+		console.error("Variable name is required.");
 		process.exit(1);
 	}
 
 	if (!secret) {
-		console.error('Warning: potential security risk: secret not provided. Variable WILL NOT be encrypted.');
+		console.error(
+			"Warning: potential security risk: secret not provided. Variable WILL NOT be encrypted.",
+		);
 	}
 
-	const envContent = fs.readFileSync(envFile, 'utf8');
+	const envContent = fs.readFileSync(envFile, "utf8");
 	const env = JSON.parse(envContent);
 
 	if (!env.variables) {
@@ -226,10 +267,10 @@ async function addCommand() {
 	}
 
 	for (const arg of args._.slice(2)) {
-		if (!arg.startsWith('+')) continue;
-		const [key, ...valueParts] = arg.slice(1).split('=');
-		const value = valueParts.join('=');
-		const envKey = key === 'fallback' ? '@@' : key;
+		if (!arg.startsWith("+")) continue;
+		const [key, ...valueParts] = arg.slice(1).split("=");
+		const value = valueParts.join("=");
+		const envKey = key === "fallback" ? "@@" : key;
 		env.variables[varName][envKey] = secret ? encrypt(value, secret) : value;
 	}
 
@@ -237,40 +278,23 @@ async function addCommand() {
 }
 
 async function runCommand() {
-	const commandParts = args['--'] || [];
+	const commandParts = args["--"] || [];
 	const [cmd, ...cmdArgs] = commandParts;
 
 	if (!cmd) {
-		console.error('Usage: wrenv run [options] -- <command> [args...]');
+		console.error("Usage: wrenv run [options] -- <command> [args...]");
 		process.exit(1);
 	}
 
-	// Load environment variables
+	// Load environment variables (without applying to current process.env)
 	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,
+		envVars = load({
+			secret: resolveSecret(args.secret),
+			targetEnv: args.target,
 			envPath: args.env,
+			applyToProcess: false,
 		});
-
-		// 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);
@@ -278,48 +302,66 @@ async function runCommand() {
 
 	// Use execa for cross-platform compatibility with minimal overhead
 	const subprocess = execa(cmd, cmdArgs, {
-		stdio: 'inherit',
+		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'));
+	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, 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');
-	console.log('  WRENV_TARGET           Target environment');
-	console.log('  TARGET_SECRET          Alias for WRENV_SECRET');
-	console.log('  TARGET_ENV             Alias for WRENV_TARGET\n');
-	console.log('Examples:');
-	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');
+	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, 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");
+	console.log("  WRENV_TARGET           Target environment");
+	console.log("  TARGET_SECRET          Alias for WRENV_SECRET");
+	console.log("  TARGET_ENV             Alias for WRENV_TARGET\n");
+	console.log("Examples:");
+	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 = {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@saasak/tool-env",
   "license": "MIT",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "author": "dev@saasak.studio",
   "description": "A small util to manage environment variables for your monorepo",
   "keywords": [
@@ -11,6 +11,7 @@
   ],
   "type": "module",
   "main": "src/index.js",
+  "types": "src/index.d.ts",
   "files": [
     "bin",
     "src"

package/src/core.js

@@ -1,8 +1,8 @@
-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';
+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
@@ -34,7 +34,19 @@ import { findMonorepoPackages } from './utils-pkg.js';
  */
 
 /** @type {string} */
-const DEFAULT_ENV = 'dev';
+const DEFAULT_ENV = "dev";
+
+/**
+ * Environment variables that must never be injected by .env.json content.
+ * These control wrenv's own behavior and must not be overridden.
+ * @type {Set<string>}
+ */
+export const RESERVED_ENV_VARS = new Set([
+	"WRENV_TARGET",
+	"WRENV_SECRET",
+	"TARGET_ENV",
+	"TARGET_SECRET",
+]);
 
 /**
  * Mapping of environment name aliases to canonical names
@@ -42,14 +54,14 @@ const DEFAULT_ENV = 'dev';
  * @type {Object.<string, string>}
  */
 const targets = {
-	"development": "dev",
-	"dev": "dev",
-	"staging": "preprod",
-	"pp": "preprod",
-	"preprod": "preprod",
-	"prod": "production",
-	"production": "production",
-	"all": "all",
+	development: "dev",
+	dev: "dev",
+	staging: "preprod",
+	pp: "preprod",
+	preprod: "preprod",
+	prod: "production",
+	production: "production",
+	all: "all",
 };
 
 /**
@@ -58,9 +70,9 @@ const targets = {
  * @type {Object.<string, string>}
  */
 const outputNames = {
-	"dev": "development",
-	"preprod": "staging",
-	"production": "production",
+	dev: "development",
+	preprod: "staging",
+	production: "production",
 };
 
 /**
@@ -104,39 +116,52 @@ export function resolveTarget(targetParam) {
  * @returns {string[]} - Resolved target sliases environment
  */
 export function resolveTargetAliases(allowedEnvs) {
-	const allowedAliases = allowedEnvs.flatMap(
-		(env => Object.entries(targets)
+	const allowedAliases = allowedEnvs.flatMap((env) =>
+		Object.entries(targets)
 			.find(([_, val]) => val === env)
-			.map(([alias]) => alias)
-		)
-	)
+			.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
+ * Resolve secret with unified fallback chain:
+ * param (stdin | file:// | file path | literal) -> WRENV_SECRET -> TARGET_SECRET -> null
+ *
+ * If reading from stdin or a file:// path fails, falls back to env vars.
+ * A bare string that is not a readable file is treated as a literal secret.
+ *
+ * @param {string} [secretParam] - Secret source: "stdin", "file://path", file path, or literal string
+ * @returns {string} - Resolved secret or empty string if not provided
  */
 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}`);
+	if (secretParam) {
+		if (secretParam === "stdin") {
+			try {
+				const value = fs.readFileSync(0, "utf8").trim();
+				if (value) return value;
+			} catch (_) {
+				// fall through to env vars
+			}
+		} else if (secretParam.startsWith("file://")) {
+			try {
+				const value = fs.readFileSync(secretParam.slice(7), "utf8").trim();
+				if (value) return value;
+			} catch (_) {
+				// fall through to env vars
+			}
+		} else {
+			try {
+				return fs.readFileSync(secretParam, "utf8").trim();
+			} catch (_) {
+				// Not a readable file path — treat as literal secret string
+				return secretParam;
+			}
 		}
 	}
 
-	return secretParam;
+	return process.env.WRENV_SECRET || process.env.TARGET_SECRET || "";
 }
 
 /**
@@ -148,18 +173,18 @@ export function resolveSecret(secretParam) {
 export function parseEnvFile(content) {
 	/** @type {EnvRecord} */
 	const result = {};
-	const lines = content.split('\n');
+	const lines = content.split("\n");
 
 	for (const line of lines) {
 		const trimmed = line.trim();
 
 		// Skip empty lines and comments
-		if (!trimmed || trimmed.startsWith('#')) {
+		if (!trimmed || trimmed.startsWith("#")) {
 			continue;
 		}
 
 		// Find the first = sign
-		const eqIndex = trimmed.indexOf('=');
+		const eqIndex = trimmed.indexOf("=");
 		if (eqIndex === -1) {
 			continue;
 		}
@@ -168,8 +193,10 @@ export function parseEnvFile(content) {
 		let value = trimmed.slice(eqIndex + 1).trim();
 
 		// Remove surrounding quotes if present
-		if ((value.startsWith('"') && value.endsWith('"')) ||
-			(value.startsWith("'") && value.endsWith("'"))) {
+		if (
+			(value.startsWith('"') && value.endsWith('"')) ||
+			(value.startsWith("'") && value.endsWith("'"))
+		) {
 			value = value.slice(1, -1);
 		}
 
@@ -190,14 +217,15 @@ export function parseEnvFile(content) {
 function findNearestPackageName(cwd, scope) {
 	let currentDir = cwd;
 
-	while (currentDir !== path.dirname(currentDir)) { // Stop at filesystem root
-		const pkgPath = path.join(currentDir, 'package.json');
+	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'));
+				const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
 				if (pkg.name) {
 					// Return name without scope prefix
-					return pkg.name.replace(`${scope}/`, '');
+					return pkg.name.replace(`${scope}/`, "");
 				}
 			} catch (e) {
 				// Continue traversing upward
@@ -206,7 +234,7 @@ function findNearestPackageName(cwd, scope) {
 		currentDir = path.dirname(currentDir);
 	}
 
-	return 'root'; // fallback
+	return "root"; // fallback
 }
 
 /**
@@ -215,14 +243,14 @@ function findNearestPackageName(cwd, scope) {
  * @returns {EnvRecord} - Local overrides or empty object
  */
 export function loadLocalOverrides(cwd = process.cwd()) {
-	const localEnvPath = path.join(cwd, '.env.local');
+	const localEnvPath = path.join(cwd, ".env.local");
 
 	if (!fs.existsSync(localEnvPath)) {
 		return {};
 	}
 
 	try {
-		const content = fs.readFileSync(localEnvPath, 'utf8');
+		const content = fs.readFileSync(localEnvPath, "utf8");
 		return parseEnvFile(content);
 	} catch (error) {
 		return {};
@@ -260,8 +288,8 @@ export function loadEnvJson(options = {}) {
 	const {
 		secret: secretParam,
 		targetEnv: targetParam,
-		envPath = '.env.json',
-		cwd = process.cwd()
+		envPath = ".env.json",
+		cwd = process.cwd(),
 	} = options;
 
 	const secret = resolveSecret(secretParam);
@@ -274,32 +302,35 @@ export function loadEnvJson(options = {}) {
 	}
 
 	const envFile = path.join(monorepoRoot, envPath);
-	const envContent = fs.readFileSync(envFile, 'utf8');
+	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 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(', ')}`);
+		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 = '';
+	const rootPkgPath = path.join(monorepoRoot, "package.json");
+	let scope = "";
 	/** @type {string[]} */
-	let depsName = ['root'];
+	let depsName = ["root"];
 
 	if (fs.existsSync(rootPkgPath)) {
 		try {
-			const rootPkgContent = fs.readFileSync(rootPkgPath, 'utf8');
+			const rootPkgContent = fs.readFileSync(rootPkgPath, "utf8");
 			const rootPkg = JSON.parse(rootPkgContent);
-			scope = rootPkg.name.split('/')[0];
+			scope = rootPkg.name.split("/")[0];
 
 			const foundPackages = findMonorepoPackages(monorepoRoot, scope);
 			depsName = [
-				...foundPackages.map((pkg) => pkg.name.replace(`${scope}/`, '')),
-				'root'
+				...foundPackages.map((pkg) => pkg.name.replace(`${scope}/`, "")),
+				"root",
 			];
 		} catch (error) {
 			// Not a monorepo or error parsing, use default
@@ -339,7 +370,7 @@ export function load(options = {}) {
 		secret,
 		envPath,
 		cwd = process.cwd(),
-		applyToProcess = true
+		applyToProcess = true,
 	} = options;
 
 	// Resolve target first to determine if we're in dev mode
@@ -350,13 +381,12 @@ export function load(options = {}) {
 		secret,
 		targetEnv: resolvedTarget,
 		envPath,
-		cwd
+		cwd,
 	});
 
 	// Load .env.local overrides only in dev mode (security: prevent local overrides in production)
-	const localOverrides = resolvedTarget === 'dev'
-		? loadLocalOverrides(cwd)
-		: {};
+	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
@@ -369,6 +399,15 @@ export function load(options = {}) {
 		}
 	}
 
+	// - Reserved vars (WRENV_*, TARGET_*) are never injected
+	// - NODE_ENV is only injected if not already set
+	for (const key of RESERVED_ENV_VARS) {
+		delete finalConfig[key];
+	}
+	if (process.env.NODE_ENV) {
+		delete finalConfig.NODE_ENV;
+	}
+
 	// Apply to process.env if requested
 	if (applyToProcess) {
 		for (const [key, value] of Object.entries(finalConfig)) {
@@ -397,15 +436,18 @@ export function verifyCanDecrypt(env, secret) {
 	const encryptedValues = [];
 
 	if (!secret) {
-		return { success: false, path: null, error: 'No secret provided' };
+		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 });
+				if (typeof envVal === "string" && isEncrypted(envVal)) {
+					encryptedValues.push({
+						path: `variables.${varName}.${envKey}`,
+						value: envVal,
+					});
 				}
 			}
 		}
@@ -416,8 +458,11 @@ export function verifyCanDecrypt(env, secret) {
 		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 (typeof envVal === "string" && isEncrypted(envVal)) {
+						encryptedValues.push({
+							path: `overrides.${pkgName}.${varName}.${envKey}`,
+							value: envVal,
+						});
 					}
 				}
 			}
@@ -437,7 +482,7 @@ export function verifyCanDecrypt(env, secret) {
 			return {
 				success: false,
 				path,
-				error: error.message
+				error: error.message,
 			};
 		}
 	}

package/src/index.d.ts

@@ -0,0 +1,82 @@
+/** Key-value pairs of environment variable name to value */
+export type EnvRecord = Record<string, string>;
+
+export interface LoadOptions {
+  /** Target environment (e.g. 'dev', 'preprod', 'production') */
+  targetEnv?: string;
+  /** Secret for decryption: "stdin", "file://path", file path, or literal string */
+  secret?: string;
+  /** Path to env.json file (default: '.env.json') */
+  envPath?: string;
+  /** Working directory (default: process.cwd()) */
+  cwd?: string;
+  /** Whether to apply resolved vars to process.env (default: true) */
+  applyToProcess?: boolean;
+}
+
+/**
+ * Load environment variables from .env.json with optional .env.local overrides.
+ * By default, applies resolved variables to process.env.
+ */
+export function load(options?: LoadOptions): EnvRecord;
+
+/**
+ * Load environment configuration from .env.json without .env.local overrides.
+ */
+export function loadEnvJson(options?: {
+  secret?: string;
+  targetEnv?: string;
+  envPath?: string;
+  cwd?: string;
+}): EnvRecord;
+
+/** Load .env.local overrides if the file exists */
+export function loadLocalOverrides(cwd?: string): EnvRecord;
+
+/** Parse .env file content into key-value pairs */
+export function parseEnvFile(content: string): EnvRecord;
+
+/**
+ * Resolve target environment with fallback chain:
+ * param -> WRENV_TARGET -> TARGET_ENV -> NODE_ENV (mapped) -> 'dev'
+ */
+export function resolveTarget(targetParam?: string): string;
+
+/**
+ * Resolve secret with fallback chain:
+ * param (stdin | file:// | file path | literal) -> WRENV_SECRET -> TARGET_SECRET -> ''
+ */
+export function resolveSecret(secretParam?: string): string;
+
+/** Get the conventional output file name for an internal environment name */
+export function getOutputName(internalName: string): string;
+
+/** Verify that all encrypted values can be decrypted with the provided secret */
+export function verifyCanDecrypt(env: object, secret: string): {
+  success: boolean;
+  path?: string | null;
+  error?: string;
+};
+
+/** Encrypt a plaintext value with the given secret */
+export function encrypt(value: string, secret: string): string;
+
+/** Decrypt an encrypted value with the given secret */
+export function decrypt(value: string, secret: string): string;
+
+/** Check if a value is encrypted */
+export function isEncrypted(value: string): boolean;
+
+/** Build environment variables for all packages from an env config */
+export function buildEnv(
+  secret: string,
+  target: string,
+  env: object,
+  names: string[],
+): Record<string, EnvRecord>;
+
+/** Find all packages in a monorepo */
+export function findMonorepoPackages(
+  root: string,
+  scope: string,
+): Array<{ name: string; dir: string }>;

package/src/utils-env.js

@@ -1,11 +1,9 @@
-import { decrypt, isEncrypted } from './utils-crypto.js';
+import { decrypt, isEncrypted } from "./utils-crypto.js";
 
 /**
- * @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
+ * Environment-specific values for a single variable.
+ * Keys are environment names (e.g. 'dev', 'production') or '@@' for the fallback.
+ * @typedef {Object.<string, string>} EnvVariableValue
  */
 
 /**
@@ -47,13 +45,16 @@ export function buildEnv(secret, target, env, names) {
 
 	// 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 {
-			...acc,
-			[key]: extractValue(secret, value[target] || value['@@'] || '')
-		};
-	}, {});
+	const variables = Object.entries(variablesForAllTargets).reduce(
+		(acc, entry) => {
+			const [key, value] = entry;
+			return {
+				...acc,
+				[key]: extractValue(secret, value[target] || value["@@"] || ""),
+			};
+		},
+		{},
+	);
 
 	// For each package, get all variables
 	// compute the overrides and merge them
@@ -64,7 +65,7 @@ export function buildEnv(secret, target, env, names) {
 	const allVars = names.reduce((acc, name) => {
 		acc[name] = {
 			...variables,
-			...parseOverrides(secret, target, overrides[name], variables)
+			...parseOverrides(secret, target, overrides[name], variables),
 		};
 
 		return acc;
@@ -77,7 +78,7 @@ export function buildEnv(secret, target, env, names) {
  * 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 {Object.<string, EnvVariableValue>} overrides - Package overrides (may be undefined)
  * @param {EnvRecord} vars - Base variables for reference substitution
  * @returns {EnvRecord} - Parsed override values
  */
@@ -86,12 +87,16 @@ function parseOverrides(secret, target, overrides, vars) {
 
 	return Object.entries(overrides).reduce((acc, entry) => {
 		const [key, val] = entry;
-		const value = extractValue(secret, val[target] || val['@@'] || '');
+		const value = extractValue(secret, val[target] || val["@@"] || "");
 
 		if (value === null) return acc;
 
 		acc[key] = Array.isArray(value)
-			? value.map(v => Object.prototype.hasOwnProperty.call(vars, v) ? vars[v] : v).join('')
+			? value
+					.map((v) =>
+						Object.prototype.hasOwnProperty.call(vars, v) ? vars[v] : v,
+					)
+					.join("")
 			: value;
 		return acc;
 	}, {});
@@ -105,6 +110,6 @@ function parseOverrides(secret, target, overrides, vars) {
  */
 function extractValue(secret, value) {
 	if (!isEncrypted(value)) return value;
-	if (!secret) return '';
+	if (!secret) return "";
 	return decrypt(value, secret);
 }