@super-repo/envx 0.2.3-b.2 → 0.2.3-b.4

package/docs/recipes.md

@@ -0,0 +1,234 @@
+# Monorepo recipes
+
+Concrete layouts for the most common envx-in-a-monorepo setups. Each recipe lists the directory tree, the config files, and the commands you'd run.
+
+## Recipe 1: Single workspace `.env.keys`, vault subdirectory
+
+The most common shape — encrypted env files live in `vault/` at the workspace root, with one `.env.keys` (gitignored) covering everything.
+
+```
+/repo
+├── .env.keys                          ← gitignored, holds private keys for every vault file
+├── pnpm-workspace.yaml
+├── envx.config.ts                     ← workspace-level defaults
+├── vault/
+│   ├── .env                            ← committed, encrypted
+│   ├── .env.dev                        ← committed, encrypted
+│   ├── .env.prod                       ← committed, encrypted
+│   └── .env.staging                    ← committed, encrypted
+└── packages/
+    ├── api/
+    │   └── package.json
+    └── web/
+        └── package.json
+```
+
+```ts
+// /repo/envx.config.ts
+export default {
+  envPath: "vault",      // every command pulls from vault/
+}
+```
+
+```sh
+# Commands run from any package directory — envx walks up to find the config.
+cd /repo/packages/api
+
+envx encrypt -e .env.prod              # writes vault/.env.prod + updates /repo/.env.keys
+envx -- pnpm start                     # auto-detects environment, loads vault/.env.<detected>
+envx --cascade prod -- node app.js     # layers vault/.env, vault/.env.prod, etc.
+envx rotate                            # rotates the keypair for vault/.env
+envx info                              # shows what envx resolved
+```
+
+`.gitignore` should contain `.env.keys` (and any `.env.*.local` if you use cascades).
+
+## Recipe 2: Per-package overrides on top of workspace defaults
+
+Some packages have additional environment files that don't belong at the workspace root (e.g. a Docker image-builder that pulls from a separate vault).
+
+```
+/repo
+├── envx.config.ts                     ← workspace defaults
+├── vault/
+│   └── .env                           ← shared by most packages
+└── packages/
+    ├── api/                           ← inherits /repo/envx.config.ts
+    │   └── package.json
+    └── docker-builder/
+        ├── envx.config.ts             ← package-local override
+        ├── vault/
+        │   └── .env.image             ← only relevant to this package
+        └── package.json
+```
+
+```ts
+// /repo/envx.config.ts
+export default {
+  envPath: "vault",
+}
+```
+
+```ts
+// /repo/packages/docker-builder/envx.config.ts
+export default {
+  envFiles: [".env.image"],
+  envPath: "vault",
+}
+```
+
+When run from `packages/docker-builder/`, envx finds the package-local config first and uses it. From `packages/api/`, envx walks up and uses the workspace config. Configs **don't merge** across the walk — the closest one wins entirely.
+
+## Recipe 3: NODE_ENV-driven environments without `--env` everywhere
+
+You want `pnpm start` to load `.env.dev`, `pnpm start:prod` to load `.env.prod`, and `NODE_ENV=staging pnpm test` to load `.env.staging` — all without typing `--env` each time.
+
+```ts
+// /repo/envx.config.ts
+export default {
+  // No envFiles → auto-detect kicks in.
+  // No nodeEnvMap override needed — staging passes through automatically.
+}
+```
+
+```jsonc
+// /repo/package.json
+{
+  "scripts": {
+    "start":      "envx -- node app.js",                    // → .env (no NODE_ENV)
+    "start:dev":  "NODE_ENV=development envx -- node app.js", // → .env.dev
+    "start:prod": "NODE_ENV=production  envx -- node app.js", // → .env.prod
+    "test:staging": "NODE_ENV=staging envx -- vitest run"     // → .env.staging
+  }
+}
+```
+
+If your team uses non-canonical names (`qa`, `preview`, …), envx loads `.env.<value>` automatically — no config change needed.
+
+## Recipe 4: Custom `NODE_ENV` mapping
+
+You want `NODE_ENV=qa` to load `.env.qa-prod` (because QA actually shares prod's external services), and `NODE_ENV=preview` to load just `.env` (no per-environment overrides).
+
+```ts
+// /repo/envx.config.ts
+export default {
+  envPath: "vault",
+  nodeEnvMap: {
+    qa: "qa-prod",
+    preview: "",        // empty = no suffix → .env
+  },
+}
+```
+
+```sh
+NODE_ENV=qa envx -- node app.js
+# Loads vault/.env.qa-prod (or walks up if missing)
+
+NODE_ENV=preview envx -- node app.js
+# Loads vault/.env  (no preview-specific file)
+```
+
+Verify with `envx info`:
+
+```
+NODE_ENV → suffix mapping
+  development    → .env.dev          (default)
+  local          → .env.local        (default)
+  production     → .env.prod         (default)
+  qa             → .env.qa-prod      (config)
+  preview        → (no suffix → .env) (config)
+```
+
+## Recipe 5: CI without committing `.env.keys`
+
+In CI (GitHub Actions, Vercel, Netlify, …), the `.env.keys` file isn't checked in. Inject the private keys via the platform's secret store and write them out at job start.
+
+### GitHub Actions
+
+```yaml
+# .github/workflows/ci.yml
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - run: pnpm install --frozen-lockfile
+
+      # Materialize .env.keys from secrets — one entry per encrypted file.
+      - name: Write .env.keys
+        run: |
+          cat > .env.keys <<EOF
+          ENVX_PRIVATE_KEY="${{ secrets.ENVX_PRIVATE_KEY }}"
+          ENVX_PRIVATE_KEY_PROD="${{ secrets.ENVX_PRIVATE_KEY_PROD }}"
+          ENVX_PRIVATE_KEY_STAGING="${{ secrets.ENVX_PRIVATE_KEY_STAGING }}"
+          EOF
+
+      - run: NODE_ENV=staging pnpm test
+```
+
+The `.env.keys` lands at the repo root; envx finds it via the cwd-first walk-up regardless of which package the test runs in.
+
+### Vercel / Netlify
+
+These platforms set `VERCEL_ENV` / `CONTEXT` automatically, so envx auto-detects the right `.env.<env>` without `NODE_ENV`. Inject `.env.keys` via their secret-file or env-var mechanism.
+
+For per-environment private keys, set them as project env vars and write `.env.keys` in your build step:
+
+```sh
+# Vercel build command
+echo "ENVX_PRIVATE_KEY_PROD=$ENVX_PRIVATE_KEY_PROD" > .env.keys && pnpm build
+```
+
+## Recipe 6: Programmatic embed with custom config
+
+You're building a CLI of your own and want to embed envx's loading + auto-detect without the user having to install envx separately.
+
+```ts
+import envx from "@super-repo/envx";
+
+// Same shape as envx.config.ts:
+envx({
+  envFiles: ["vault/.env.prod"],
+  envPath: "vault",
+  override: true,
+  autoDetect: false,                  // we're picking files explicitly
+  variables: ["MY_TOOL_VERSION=1.2.3"],
+});
+
+// process.env is now populated; carry on.
+```
+
+For full control over which yargs commands you re-export, pull `createCli` from the `/commands` subpath:
+
+```ts
+import { createCli } from "@super-repo/envx/commands";
+
+createCli(process.argv.slice(2)).parseSync();
+```
+
+## Recipe 7: Migrating an existing dotenvx project
+
+You have a project using `@dotenvx/dotenvx` directly and want to switch.
+
+1. **Install:**
+   ```sh
+   pnpm add @super-repo/envx
+   pnpm remove @dotenvx/dotenvx
+   ```
+
+2. **Rename references:** `dotenvx encrypt` → `envx encrypt`, `dotenvx run` → `envx run`. The `dotenvx-proxy` bin in this package is a direct passthrough to the upstream dotenvx CLI if you need to keep specific commands working during migration.
+
+3. **Keys file:** existing `.env.keys` files **work as-is**. envx reads `DOTENV_PRIVATE_KEY*` and `DOTENV_PUBLIC_KEY*` as fallbacks — no rename needed. New encrypts will use the canonical `ENVX_PRIVATE_KEY*` / `ENVX_PUBLIC_KEY*` names; you can migrate the existing entries opportunistically (or never).
+
+4. **Verify:**
+   ```sh
+   envx info
+   envx -- node app.js   # same behavior as before
+   ```
+
+If anything decrypts under dotenvx but not envx (or vice versa), they're not actually wire-compatible and we should know — open an issue.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@super-repo/envx",
   "description": "A global executable to run applications with the ENV variables witin a monorepo loaded by dotenvx",
-  "version": "0.2.3-b.2",
+  "version": "0.2.3-b.4",
   "type": "module",
   "bin": {
     "envx": "./dist/cli.js",
@@ -26,7 +26,9 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "README.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -58,8 +60,8 @@
     "vite": "^8.0.11",
     "vite-plugin-dts": "^5.0.0",
     "vitest": "^4.1.5",
-    "@super-repo/envx-common": "0.0.1",
     "@super-repo/envx-libs": "0.0.1",
-    "@super-repo/cli": "0.2.3-b.2"
+    "@super-repo/cli": "0.2.3-b.4",
+    "@super-repo/envx-common": "0.0.1"
   }
 }

package/dist/chunks/commands-B8vc6UKO.js

@@ -1,354 +0,0 @@
-import { a as resolveEnvPaths, c as loadDotenvxConfig, d as encryptFiles, f as parseEnv, i as loadEnv, l as expandEnvSrc, n as findWorkspaceRoot, o as validateCmdVariable, p as isEncrypted, r as listEnvFiles, s as log, t as writeProcessed, u as decryptFiles } from "./src-CDuEfaCY.js";
-import * as fs from "fs";
-import * as path from "path";
-import yargs from "yargs";
-import { execSync } from "child_process";
-//#region src/commands/debug.ts
-var debugCommand = {
-	command: "debug",
-	describe: "Show which env files would be loaded and which variables would be applied, without loading them.",
-	handler: (argv) => {
-		const paths = resolveEnvPaths({
-			envFiles: argv["env"],
-			cascade: argv["cascade"]
-		});
-		const rawVars = argv["variables"];
-		const variables = rawVars ? Object.fromEntries(rawVars.map(validateCmdVariable)) : {};
-		log.info(`Paths: ${JSON.stringify(paths)}`);
-		log.info(`Variables: ${JSON.stringify(variables)}`);
-	}
-};
-//#endregion
-//#region src/commands/decrypt.ts
-/** Mirror of `dotenvx decrypt` from upstream — see also encrypt.ts. */
-var decryptCommand = {
-	command: "decrypt",
-	describe: "Decrypt the values in one or more .env files in place using the matching private key in .env.keys.",
-	builder: (yargs) => yargs.option("env-keys-file", {
-		alias: "fk",
-		type: "string",
-		describe: "Path to the .env.keys file (default: ./.env.keys at cwd, regardless of --dir / --env-path)."
-	}).option("key", {
-		alias: "k",
-		type: "array",
-		string: true,
-		describe: "Specific keys (or picomatch globs) to decrypt. Default: all keys."
-	}).option("exclude-key", {
-		alias: "ek",
-		type: "array",
-		string: true,
-		describe: "Keys (or picomatch globs) to leave encrypted."
-	}).option("stdout", {
-		type: "boolean",
-		default: false,
-		describe: "Write the decrypted env contents to stdout instead of saving in place."
-	}).help("h").alias("h", "help"),
-	handler: (argv) => {
-		const envFiles = argv["env"] ?? [".env"];
-		const keys = argv["key"];
-		const excludeKeys = argv["exclude-key"];
-		const envKeysFile = argv["env-keys-file"];
-		const stdout = argv["stdout"] ?? false;
-		const result = decryptFiles({
-			envFiles,
-			...keys ? { keys } : {},
-			...excludeKeys ? { excludeKeys } : {},
-			...envKeysFile ? { envKeysFile } : {}
-		});
-		let hadError = false;
-		for (const processed of result.processedEnvs) {
-			if (processed.error) {
-				hadError = true;
-				log.error(`${processed.envFilepath}: ${processed.error.message}`);
-				if (processed.error.help) log.dim(processed.error.help);
-				continue;
-			}
-			if (stdout) process.stdout.write(processed.envSrc);
-		}
-		if (!stdout) {
-			const { written } = writeProcessed(result.processedEnvs);
-			for (const w of written) log.success(`decrypted ${w}`);
-			if (written.length === 0 && result.unchangedFilepaths.length > 0 && !hadError) log.dim(`no changes (${result.unchangedFilepaths.join(", ")})`);
-		}
-		if (hadError) process.exitCode = 1;
-	}
-};
-//#endregion
-//#region src/commands/encrypt.ts
-/**
-* Mirrors the upstream `dotenvx encrypt` flags so existing muscle
-* memory carries over. The `--env` global doubles as the file list
-* (the upstream calls it `--env-file`); this CLI keeps a single
-* canonical name across subcommands.
-*/
-var encryptCommand = {
-	command: "encrypt",
-	describe: "Encrypt the values in one or more .env files. Generates a private key in .env.keys on first run.",
-	builder: (yargs) => yargs.option("env-keys-file", {
-		alias: "fk",
-		type: "string",
-		describe: "Path to the .env.keys file (default: ./.env.keys at cwd, regardless of --dir / --env-path)."
-	}).option("key", {
-		alias: "k",
-		type: "array",
-		string: true,
-		describe: "Specific keys (or picomatch globs) to encrypt. Default: all keys."
-	}).option("exclude-key", {
-		alias: "ek",
-		type: "array",
-		string: true,
-		describe: "Keys (or picomatch globs) to leave plaintext."
-	}).option("stdout", {
-		type: "boolean",
-		default: false,
-		describe: "Write the encrypted env contents to stdout instead of saving in place."
-	}).help("h").alias("h", "help"),
-	handler: (argv) => {
-		const envFiles = argv["env"] ?? [".env"];
-		const keys = argv["key"];
-		const excludeKeys = argv["exclude-key"];
-		const envKeysFile = argv["env-keys-file"];
-		const stdout = argv["stdout"] ?? false;
-		const result = encryptFiles({
-			envFiles,
-			...keys ? { keys } : {},
-			...excludeKeys ? { excludeKeys } : {},
-			...envKeysFile ? { envKeysFile } : {}
-		});
-		let hadError = false;
-		for (const processed of result.processedEnvs) {
-			if (processed.error) {
-				hadError = true;
-				log.error(`${processed.envFilepath}: ${processed.error.message}`);
-				if (processed.error.help) log.dim(processed.error.help);
-				continue;
-			}
-			if (stdout) {
-				process.stdout.write(processed.envSrc);
-				continue;
-			}
-			if (processed.privateKeyAdded) log.success(`key added to .env.keys (${processed.privateKeyName ?? "<unknown>"})`);
-		}
-		if (!stdout) {
-			const { written } = writeProcessed(result.processedEnvs);
-			for (const w of written) log.success(`encrypted ${w}`);
-			if (written.length === 0 && result.unchangedFilepaths.length > 0 && !hadError) log.dim(`no changes (${result.unchangedFilepaths.join(", ")})`);
-		}
-		if (hadError) process.exitCode = 1;
-	}
-};
-//#endregion
-//#region src/commands/expand.ts
-/**
-* Decrypts (when needed) and expands variable references in an env
-* file. Mirrors the workflow `decrypt-vault` action — but cycle-safe,
-* supports `${VAR:-default}` / `${VAR:?msg}`, and never silently
-* truncates after N passes.
-*/
-var expandCommand = {
-	command: "expand",
-	describe: "Decrypt (if needed) and expand ${VAR}/$VAR references in an env file. Outputs to stdout by default.",
-	builder: (yargs) => yargs.option("output", {
-		type: "string",
-		describe: "Write the expanded result to this file (default: stdout)."
-	}).option("env-keys-file", {
-		alias: "fk",
-		type: "string",
-		describe: "Path to .env.keys (default: ./.env.keys at cwd, regardless of --dir / --env-path)."
-	}).option("on-missing", {
-		type: "string",
-		choices: [
-			"leave",
-			"empty",
-			"throw"
-		],
-		default: "leave",
-		describe: "How to handle ${UNRESOLVED_VAR}: leave it literal, substitute empty, or fail."
-	}).help("h").alias("h", "help"),
-	handler: (argv) => {
-		const envFiles = argv["env"] ?? [".env"];
-		if (envFiles.length !== 1) {
-			log.error(`expand operates on a single env file at a time; got ${String(envFiles.length)}.`);
-			process.exit(1);
-		}
-		const envFile = envFiles[0];
-		const filepath = path.resolve(envFile);
-		if (!fs.existsSync(filepath)) {
-			log.error(`env file not found: ${envFile}`);
-			process.exit(1);
-		}
-		let envSrc = fs.readFileSync(filepath, "utf8");
-		if (parseEnv(envSrc).some((l) => l.type === "kv" && isEncrypted(l.value))) {
-			const envKeysFile = argv["env-keys-file"];
-			const processed = decryptFiles({
-				envFiles: [envFile],
-				...envKeysFile ? { envKeysFile } : {}
-			}).processedEnvs[0];
-			if (processed?.error) {
-				log.error(`${envFile}: ${processed.error.message}`);
-				if (processed.error.help) log.dim(processed.error.help);
-				process.exit(1);
-			}
-			envSrc = processed.envSrc;
-		}
-		const onMissing = argv["on-missing"];
-		const result = expandEnvSrc(envSrc, { onMissing });
-		for (const v of result.unresolved) log.warn(`unresolved variable: ${v}`);
-		for (const cycle of result.cycles) log.warn(`cycle: ${cycle.join(" → ")}`);
-		const output = argv["output"];
-		if (output) {
-			fs.writeFileSync(path.resolve(output), result.envSrc);
-			log.success(`expanded ${envFile} → ${output}`);
-		} else {
-			process.stdout.write(result.envSrc);
-			if (!result.envSrc.endsWith("\n")) process.stdout.write("\n");
-		}
-	}
-};
-//#endregion
-//#region src/commands/print.ts
-var printCommand = {
-	command: "print <variable>",
-	describe: "Load env files and print the value of a single variable.",
-	builder: (yargs) => yargs.positional("variable", {
-		describe: "Name of the variable to print",
-		type: "string",
-		demandOption: true
-	}),
-	handler: (argv) => {
-		loadEnv({
-			envFiles: argv["env"],
-			variables: argv["variables"],
-			cascade: argv["cascade"],
-			vault: argv["vault"],
-			envPath: argv["env-path"],
-			override: argv["override"],
-			quiet: argv["quiet"]
-		});
-		const name = argv["variable"];
-		const value = process.env[name];
-		process.stdout.write(value != null ? `${value}\n` : "\n");
-	}
-};
-//#endregion
-//#region src/commands/run.ts
-var runCommand = {
-	command: "run [command..]",
-	aliases: ["$0"],
-	describe: "Load env files into process.env and execute a command. Default subcommand — `dotenvx-run [command]` is equivalent.",
-	builder: (yargs) => yargs.positional("command", {
-		describe: "Command to execute after loading env files",
-		type: "string",
-		array: true
-	}),
-	handler: (argv) => {
-		const command = (argv["command"] ?? []).join(" ");
-		loadEnv({
-			envFiles: argv["env"],
-			variables: argv["variables"],
-			cascade: argv["cascade"],
-			vault: argv["vault"],
-			envPath: argv["env-path"],
-			override: argv["override"],
-			quiet: argv["quiet"]
-		});
-		if (!command) return;
-		log.info(`Running: ${command}`);
-		try {
-			execSync(command, { stdio: "inherit" });
-			log.success(`Command completed: ${command}`);
-		} catch (error) {
-			const msg = error instanceof Error ? error.message : String(error);
-			log.error(`Command failed: ${msg}`);
-			process.exit(1);
-		}
-	}
-};
-//#endregion
-//#region src/commands/index.ts
-/**
-* Build the yargs CLI for `dotenvx-run`. Global options (env, variables,
-* cascade, vault, override, quiet) are registered on the root so every
-* subcommand inherits them.
-*/
-function createCli(argvInput) {
-	return yargs(argvInput).scriptName("envx").usage("$0 <command> [options]").option("config", {
-		alias: "c",
-		type: "string",
-		describe: "Path to an envx config file (default: discovered from package.json `envx.config` or envx.config.{ts,js,json})."
-	}).option("env", {
-		alias: "e",
-		type: "array",
-		describe: "Env files to load. Default: [\".env\"] (or `envFiles` from config; or every .env* under --env-path when set). Auto-detects environment when omitted."
-	}).option("env-path", {
-		alias: ["dir", "d"],
-		type: "string",
-		describe: "Subdirectory of the workspace root holding the env files (e.g. `vault`). When set and --env is omitted, every .env* file in that directory is included."
-	}).option("variables", {
-		alias: "v",
-		type: "array",
-		describe: "Inline variables in the form name=value (repeatable).",
-		default: []
-	}).option("cascade", {
-		type: "string",
-		describe: "Cascade load order: .env, .env.<cascade>, .env.local, .env.<cascade>.local"
-	}).option("vault", {
-		alias: "va",
-		type: "boolean",
-		describe: "Shortcut for `--env-path vault`."
-	}).option("override", {
-		alias: "o",
-		type: "boolean",
-		describe: "Override existing process.env values. Conflicts with --cascade."
-	}).option("quiet", {
-		alias: "q",
-		type: "boolean",
-		describe: "Suppress dotenv's own output."
-	}).middleware((argv) => {
-		const configPath = argv["config"];
-		let loaded;
-		try {
-			loaded = loadDotenvxConfig({ ...configPath ? { configPath } : {} });
-		} catch (e) {
-			log.error(`config error: ${e.message}`);
-			process.exit(1);
-		}
-		if (loaded.source) log.dim(`config: ${loaded.source} (${loaded.origin})`);
-		const cfg = loaded.config;
-		if (argv["cascade"] === void 0 && cfg.cascade !== void 0) argv["cascade"] = cfg.cascade;
-		if (argv["override"] === void 0) argv["override"] = cfg.override ?? false;
-		if (argv["quiet"] === void 0) argv["quiet"] = cfg.quiet ?? true;
-		if (argv["vault"] === void 0) argv["vault"] = false;
-		if (argv["env-keys-file"] === void 0 && cfg.envKeysFile !== void 0) argv["env-keys-file"] = cfg.envKeysFile;
-		if (argv["env-path"] === void 0) {
-			if (cfg.envPath !== void 0) argv["env-path"] = cfg.envPath;
-			else if (argv["vault"]) argv["env-path"] = "vault";
-		}
-		const userPassedEnv = Array.isArray(argv["env"]) && argv["env"].length > 0;
-		let files;
-		if (userPassedEnv) files = argv["env"];
-		else if (cfg.envFiles && cfg.envFiles.length > 0) files = [...cfg.envFiles];
-		else if (typeof argv["env-path"] === "string") {
-			const subdir = argv["env-path"];
-			const wsRoot = findWorkspaceRoot();
-			const discovered = listEnvFiles(path.resolve(wsRoot, subdir));
-			if (discovered.length > 0) {
-				files = discovered;
-				log.dim(`env-path ${subdir}: discovered ${String(discovered.length)} file(s) — ${discovered.join(", ")}`);
-			} else {
-				files = [".env"];
-				log.warn(`env-path ${subdir}: no .env* files found; falling back to [".env"]`);
-			}
-		} else files = [".env"];
-		if (typeof argv["env-path"] === "string") {
-			const wsRoot = findWorkspaceRoot();
-			const dir = path.resolve(wsRoot, argv["env-path"]);
-			files = files.map((f) => path.isAbsolute(f) ? f : path.join(dir, f));
-		}
-		argv["env"] = files;
-	}).command(runCommand).command(printCommand).command(debugCommand).command(encryptCommand).command(decryptCommand).command(expandCommand).help("h").alias("h", "help").version().strictCommands().demandCommand(0).recommendCommands().epilog("Examples:\n  envx -- node app.js                # load .env (auto-detected) and run\n  envx --env dev -- pnpm start       # load .env.dev\n  envx print DATABASE_URL            # print one variable\n  envx debug --cascade prod          # show resolved paths\n  envx encrypt -e .env.prod          # encrypt values in .env.prod\n  envx decrypt -e .env.prod -k FOO   # decrypt only FOO\n  envx expand -e vault/.env.prod     # decrypt + expand to stdout\n  envx -c ./my.config.json run -- node app.js");
-}
-//#endregion
-export { createCli as t };
-
-//# sourceMappingURL=commands-B8vc6UKO.js.map