@saasak/tool-env 0.0.3 → 1.0.0

package/README.md

@@ -0,0 +1,77 @@
+# Env management
+
+## Warnings
+
+- Make sure to have the git hook setup OR TO add any new variable viw the dedicated subcommand
+- Obviously do not commit your password file
+- In variable composition, the "static" parts are NOT encrypted (static part should never contain sensitive information)
+
+## Goals
+
+- Centralize env variables definitions
+- Allow explicit variables composition
+- Good DX (setup and forget)
+
+## TODOs
+
+[] Handle encryption
+[] Handle variable composition everywhere (not just in overrides)
+[] Create runtime library to read vars (even encrypted)
+[] Handle env.local files
+
+## Open questions
+
+- Should we write all the env with the next.js convention ?
+- How to handle adding a var easily in an encrypted context ?
+- Should we split BUILD / RUN variables ?
+
+## Examples
+
+in package.json (root)
+```json
+{
+	"scripts": {
+		"postinstall": "wrenv --secret ~/.big-secret write --target dev",
+		"env:update": "wrenv --secret ~/.big-secret write"
+	}
+}
+```
+
+and then later
+```bash
+pnpm run env:update --target prod
+```
+or
+```bash
+WRENV_TARGET=staging bun run env:update
+```
+
+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
+```
+
+or via stdin
+```bash
+cat ~/.big-secret | wrenv --secret=stdin write --target=dev
+wrenv --secret stdin --target=dev < ~/.big-secret
+```
+
+## Git hooks
+
+Wrenv provide a git hook (to be configured independently with the solution of your choosing) to encrypt all added variables
+So in `.git/hooks/pre-commit` you can add
+```bash
+bun run wrenv --secret ~/.big-secret besafe
+```
+This will run on the .env.json file and make sure all variables are encrypted.
+This way you can add new variables and make sure they don't leak, offering minimum friction.
+
+/!\ You must make sure to add this hook OR to always add var via the dedicated subcommand `wrenv add`
+
+
+## Add a variable
+
+To add a new variable use the `add` subcommand
+```bash
+wrenv --secret=~/.big-secret add NEW_VAR +fallback=@@_VALUE +dev=DEV_VALUE +production=PROD_VALUE

package/bin/index.js

@@ -1,12 +1,29 @@
 import minimist from 'minimist';
 import fs from 'fs-extra';
 import path from 'path';
-import { $ } from 'execa';
+import { execa } from 'execa';
+
+import { buildEnv } from '../src/utils-env.js';
+import { findMonorepoPackages } from '../src/utils-pkg.js';
+import { encrypt, isEncrypted } from '../src/utils-crypto.js';
 
 const args = minimist(process.argv.slice(2));
 const __root = process.cwd();
 
-// Here we fetch the target env from cli args
+const command = args._[0] || 'write';
+
+const secret = args.secret
+	? (args.secret === 'stdin' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(args.secret, 'utf8'))
+	: process.env.WRENV_SECRET || process.env.TARGET_SECRET || '';
+
+const envPath = args.env || '.env.json';
+const envFile = path.resolve(__root, envPath);
+
+if (!fs.existsSync(envFile)) {
+	console.error('No env file found.');
+	process.exit(1);
+}
+
 const DEFAULT_ENV = 'dev';
 const targets = {
 	"development": "dev",
@@ -17,187 +34,237 @@ const targets = {
 	"prod": "production",
 	"production": "production",
 }
-const target = targets[args.target] || DEFAULT_ENV;
 
-// Here we fetch the master env.json file
-// from which we will build all the .env files
-const envPath = args.env || '.env.json';
-const maybeEnvFile = path.resolve(__root, envPath);
-const envFile = fs.existsSync(maybeEnvFile) ? maybeEnvFile : null;
+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 envContent = fs.readFileSync(envFile, 'utf8');
+	const env = JSON.parse(envContent);
+
+	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] = await findMonorepoPackages(__root, scope);
+	const deps = [
+		...foundPackages.map((pkg) => ({
+			name: pkg.name.replace(`${scope}/`, ''),
+			dir: pkg.dir,
+		})),
+		{
+			name: 'root',
+			dir: __root,
+		},
+	];
+	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 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')
+		console.log('~~~~~~~~~~~~~~~~~~~~~~~~~~~~');
+		console.log(`=== ENV for ${dep.name} in ${dep.dir} with target ${targetEnv}`);
+		console.log(pkgEnv);
+	}
 
-if (!envFile) {
-	console.error('No env file found.');
-	process.exit(1);
 }
 
-const envContent = fs.readFileSync(envFile, 'utf8');
-const env = JSON.parse(envContent);
-
-// Here we fetch the root package.json file
-// And all packages that live in the monorepo
-// So we can extract names and directories
-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 packageList = await $`pnpm ls -r --depth=-1`
-const packageDirs = packageList.stdout
-    .split('\n')
-    .filter((line) => !!line)
-    .map((line) => line.split(' ')[1]);
-
-const [_, ...depPkgs] = packageDirs;
-const deps = depPkgs.map((pkgDir) => {
-	const pkgFile = fs.readFileSync(path.join(pkgDir, 'package.json'));
-	const pkg = JSON.parse(pkgFile);
-	return {
-		name: pkg.name.replace(`${scope}/`, ''),
-		dir: pkgDir,
-	};
-}).concat({
-	name: 'root',
-	dir: __root,
-});
-
-const depsName = deps.map((dep) => dep.name);
-
-// Here we do a check to see if target env is described
-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);
+async function writeCommand() {
+	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 envContent = fs.readFileSync(envFile, 'utf8');
+	const env = JSON.parse(envContent);
+
+	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] = await findMonorepoPackages(__root, scope);
+	const deps = [
+		...foundPackages.map((pkg) => ({
+			name: pkg.name.replace(`${scope}/`, ''),
+			dir: pkg.dir,
+		})),
+		{
+			name: 'root',
+			dir: __root,
+		},
+	];
+	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 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')
+		console.log(`Writing env file for ${dep.name} in ${dep.dir} with target ${targetEnv}`);
+		await fs.writeFile(path.join(dep.dir, '.env'), pkgEnv);
+	}
 }
 
-// Here we build the env object which will be used
-// and which contains all the variables for all packages
-const allEnvs = buildEnv(targetEnv, env, depsName);
-
-// Here we write the .env files for each package to disk
-// This should not influence the vcs state as those env files
-// should be ignored by it
-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);
+async function encryptCommand() {
+	const envContent = fs.readFileSync(envFile, 'utf8');
+	const env = JSON.parse(envContent);
+
+	if (!secret) {
+		console.error('Cannot encrypt env file: secret not provided. Doing nothing');
+		return;
+	}
+
+	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)) {
+					env.variables[varName][envKey] = encrypt(envVal, secret);
+				}
+			}
+		}
+	}
+
+	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)) {
+						env.overrides[pkgName][varName][envKey] = encrypt(envVal, secret);
+					}
+				}
+			}
+		}
+	}
+
+	await fs.writeFile(envFile, JSON.stringify(env, null, 2));
 }
 
-// ========================================
-// Helpers for core logic
-// ========================================
-
-function buildEnv(target, env, names) {
-	const variablesForAllTargets = env.variables;
-	const overrides = env.overrides || {};
-	const sections = env.sections || {};
-
-	// For each variables, extract the value for the target env
-	const variables = Object.entries(variablesForAllTargets).reduce((acc, entry) => {
-		const [key, value] = entry;
-		return {
-			...acc,
-			[key]: value[target] || value['@@'] || ''
-		};
-	}, {});
-
-	// For each package, get all variables
-	// compute the overrides and merge them
-	// allVars is an object with the package name as key
-	// and the variables as value like so
-	// => { [name]: { [variable]: value } }
-	const allVars = names.reduce((acc, name) => {
-		acc[name] = {
-			...variables,
-			...parseOverrides(target, overrides[name], variables)
-		};
-
-		return acc;
-	}, {});
-
-	// For each package, get all dependencies of variables
-	// For instance and for clarity, backoffice can include all vars
-	// from the api, and the api can include all vars from the core
-	const allDeps = names.reduce((acc, name) => ({
-		...acc,
-		[name]: parseSectionDeps(name, sections).reverse()
-	}), {})
-
-	// For each package, get all variable names from the dependencies
-	// and from the package itself and merge them
-	const allSections = Object.entries(allDeps).reduce((acc, entry) => {
-		const [key, deps] = entry;
-
-		// For all deps, get the variable names
-		const depVars = deps.filter(Boolean).reduce((_acc, dep) => {
-			const vars = parseSectionVars(dep, sections)
-			return [..._acc, ...vars];
-		}, []);
-
-		// For the current section, get the variable names
-		const nameVars = parseSectionVars(key, sections)
-
-		// Merge all variables names, and for each variable name,
-		// get the value from the allVars object
-		return {
-			...acc,
-			[key]: [...depVars, ...nameVars].reduce((_acc, variable) => {
-				if (!allVars[key] || allVars[key][variable] === null) return _acc;
-
-				return { ..._acc, [variable]: allVars[key][variable] };
-			}, {})
-		};
-	}, {});
-
-
-	return allSections;
-}
+async function besafeCommand() {
+	const relativeEnvPath = path.relative(__root, envFile);
 
-function parseOverrides(target, overrides, vars) {
-	if (!overrides) 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 });
 
-	return Object.entries(overrides).reduce((acc, entry) => {
-		const [key, val] = entry;
-		const value = val[target] || val['@@'] || '';
+		if (!stagedDiff?.trim() && !unstagedDiff?.trim() && !untracked?.trim()) {
+			return;
+		}
+	} catch (error) {
+		return;
+	}
 
-		if (value === null) return acc;
+	await encrypt();
 
-		acc[key] = Array.isArray(value)
-			? value.map(v => vars[v] || v).join('')
-			: value
-		return acc;
-	}, {});
+	if (!secret) {
+		console.error('Warning: potential security risk: secret not provided. Variables WERE NOT be encrypted.');
+	}
+
+	await execa('git', ['add', relativeEnvPath], { cwd: __root });
 }
 
-function parseSectionDeps(name, sections, collected = []) {
-	if (!sections || !sections[name]) return [];
-
-	const collectedWithSelf = Array.from(new Set([...collected, name]));
-	const deps = sections[name]
-		.filter((key) => key.startsWith('@@'))
-		.map((key) => key.split('@@')[1])
-		.filter((key) => !collectedWithSelf.includes(key));
-
-	if (!deps.length) return [];
-
-	const uniquelyCollected = Array.from(new Set([...collected, ...deps]));
-	return [
-		...deps,
-		...deps.map(
-			(dep) => parseSectionDeps(
-				dep,
-				sections,
-				uniquelyCollected
-			)
-		).flat(),
-	];
+async function addCommand() {
+	const varName = args._[1];
+	if (!varName) {
+		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.');
+	}
+
+	const envContent = fs.readFileSync(envFile, 'utf8');
+	const env = JSON.parse(envContent);
+
+	if (!env.variables) {
+		env.variables = {};
+	}
+
+	if (!env.variables[varName]) {
+		env.variables[varName] = {};
+	}
+
+	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;
+		env.variables[varName][envKey] = secret ? encrypt(value, secret) : value;
+	}
+
+	await fs.writeFile(envFile, JSON.stringify(env, null, 2));
+}
+
+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('  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('  --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 add NEW_VAR +fallback=value +dev=dev_value +production=prod_value');
 }
 
-function parseSectionVars(name, sections) {
-	if (!sections || !sections[name]) return [];
+const commands = {
+	write: writeCommand,
+	show: showCommand,
+	besafe: besafeCommand,
+	encrypt: encryptCommand,
+	add: addCommand,
+	help: helpCommand,
+};
+
+const commandFunction = commands[command];
+
+if (!commandFunction) {
+	console.error(`Unknown command: ${command}\n`);
+	helpCommand();
+	process.exit(1);
+}
 
-	return sections[name]
-		.filter((key) => !key.startsWith('@@'))
+try {
+	await commandFunction();
+} catch (error) {
+	console.error(error.message);
+	process.exit(1);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@saasak/tool-env",
   "license": "MIT",
-  "version": "0.0.3",
+  "version": "1.0.0",
   "author": "dev@saasak.studio",
   "description": "A small util to manage environment variables for your monorepo",
   "keywords": [