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

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,oBAAoB,CAAC;AAE5B;;;;;;;;;;;;;;;;;;GAkBG;AACH,iBAAS,IAAI,IAAI,MAAM,CAAC,UAAU,CAAC;AACnC,iBAAS,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC;AAChD,iBAAS,IAAI,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAAC,UAAU,CAAC;AA0DvD,eAAe,IAAI,CAAC;AACpB,OAAO,EAAE,IAAI,EAAE,CAAC;AAGhB,YAAY,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,uBAAuB,CAAC;AAO/B,OAAO,EAEL,UAAU,EACV,iBAAiB,EACjB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,aAAa,EAElB,gBAAgB,EAChB,eAAe,EACf,sBAAsB,EACtB,sBAAsB,EACtB,WAAW,EAEX,YAAY,EACZ,YAAY,EACZ,WAAW,EAEX,QAAQ,EACR,YAAY,EACZ,QAAQ,EAER,YAAY,EACZ,YAAY,EAEZ,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,iBAAiB,EAEjB,YAAY,EACZ,aAAa,EACb,eAAe,GAChB,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACV,aAAa,EACb,cAAc,EACd,YAAY,EACZ,eAAe,EACf,SAAS,EACT,UAAU,EACV,SAAS,EACT,aAAa,EACb,YAAY,EACZ,OAAO,EACP,MAAM,EACN,OAAO,GACR,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;GAmBG;AACH;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAAG,cAAc,GAAG;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAErF,iBAAS,IAAI,IAAI,MAAM,CAAC,UAAU,CAAC;AACnC,iBAAS,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC;AAChD,iBAAS,IAAI,CAAC,IAAI,EAAE,uBAAuB,GAAG,MAAM,CAAC,UAAU,CAAC;AAiGhE,eAAe,IAAI,CAAC;AACpB,OAAO,EAAE,IAAI,EAAE,CAAC;AAGhB,YAAY,EAAE,cAAc,EAAE,CAAC"}

package/dist/index.js

@@ -1,35 +1,64 @@
-import { c as loadDotenvxConfig, i as loadEnv } from "./chunks/src-CDuEfaCY.js";
+import { C as serializeEnv, D as encryptValueAsymmetric, E as decryptValueAsymmetric, O as generateKeyPair, S as parseEnv, T as ENCRYPTED_PREFIX, _ as resolveEnvPaths, a as rotateFiles, b as expandRecord, c as defaultKeysPath, f as detectEnvironment, g as resolveCwdOrWorkspace, h as loadEnv, i as auditFiles, k as isEncrypted, l as readKeysFile, n as loadDotenvxConfig, o as decryptFiles, p as findWorkspaceRoot, r as BUILT_IN_PATTERNS, s as encryptFiles, u as writeKeysFile, w as toRecord, y as expandEnvSrc } from "./chunks/src-D0n2wHDg.js";
 //#region src/index.ts
 function envx(arg) {
-	const { config } = loadDotenvxConfig();
-	let opts;
-	if (arg === void 0) opts = {
-		envFiles: config.envFiles ? [...config.envFiles] : [".env"],
-		...config.cascade !== void 0 ? { cascade: config.cascade } : {},
-		...config.envPath !== void 0 ? { envPath: config.envPath } : {},
-		...config.override !== void 0 ? { override: config.override } : {},
-		...config.quiet !== void 0 ? { quiet: config.quiet } : {}
-	};
-	else if (typeof arg === "string") opts = {
-		envFiles: config.envFiles ? [...config.envFiles] : [".env"],
-		cascade: arg,
-		...config.envPath !== void 0 ? { envPath: config.envPath } : {},
-		...config.override !== void 0 ? { override: config.override } : {},
-		...config.quiet !== void 0 ? { quiet: config.quiet } : {}
-	};
-	else opts = {
-		envFiles: arg.envFiles ?? (config.envFiles ? [...config.envFiles] : [".env"]),
-		...arg.cascade !== void 0 ? { cascade: arg.cascade } : config.cascade !== void 0 ? { cascade: config.cascade } : {},
-		...arg.envPath !== void 0 ? { envPath: arg.envPath } : config.envPath !== void 0 ? { envPath: config.envPath } : {},
-		...arg.vault !== void 0 ? { vault: arg.vault } : {},
-		...arg.variables !== void 0 ? { variables: arg.variables } : {},
-		...arg.override !== void 0 ? { override: arg.override } : config.override !== void 0 ? { override: config.override } : {},
-		...arg.quiet !== void 0 ? { quiet: arg.quiet } : config.quiet !== void 0 ? { quiet: config.quiet } : {}
-	};
-	loadEnv(opts);
+	const { config: baseConfig } = loadDotenvxConfig();
+	const userOpts = arg === void 0 ? {} : typeof arg === "string" ? { cascade: arg } : arg;
+	let cfg = baseConfig;
+	if (userOpts.profile) {
+		const profile = cfg.profiles?.[userOpts.profile];
+		if (!profile) throw new Error(`[ENVX_UNKNOWN_PROFILE] '${userOpts.profile}' not found (available: ${Object.keys(cfg.profiles ?? {}).join(", ") || "none"})`);
+		cfg = {
+			...cfg,
+			...profile
+		};
+	}
+	const { profile: _drop, ...rest } = userOpts;
+	loadEnv(mergeOpts(cfg, rest));
 	return process.env;
 }
+/**
+* Per-field merge: caller-supplied option wins, falling through to the
+* matching config field, falling through to whatever default `loadEnv`
+* has built in. Fields the caller doesn't pass and the config doesn't
+* set are simply omitted from the merged options object.
+*/
+function mergeOpts(config, user) {
+	const out = {};
+	if (user.envFiles !== void 0) out.envFiles = user.envFiles;
+	else if (config.envFiles !== void 0) out.envFiles = [...config.envFiles];
+	if (user.envPath !== void 0) out.envPath = user.envPath;
+	else if (config.envPath !== void 0) out.envPath = config.envPath;
+	if (user.cascade !== void 0) out.cascade = user.cascade;
+	else if (config.cascade !== void 0) out.cascade = config.cascade;
+	if (user.vault !== void 0) out.vault = user.vault;
+	if (user.variables !== void 0) out.variables = user.variables;
+	if (user.override !== void 0) out.override = user.override;
+	else if (config.override !== void 0) out.override = config.override;
+	if (user.quiet !== void 0) out.quiet = user.quiet;
+	else if (config.quiet !== void 0) out.quiet = config.quiet;
+	if (user.autoDetect !== void 0) out.autoDetect = user.autoDetect;
+	else if (config.autoDetect !== void 0) out.autoDetect = config.autoDetect;
+	if (user.nodeEnvMap !== void 0) out.nodeEnvMap = user.nodeEnvMap;
+	else if (config.nodeEnvMap !== void 0) out.nodeEnvMap = config.nodeEnvMap;
+	if (user.required !== void 0) out.required = user.required;
+	else if (config.required !== void 0) out.required = config.required;
+	if (user.expand !== void 0) out.expand = user.expand;
+	else if (config.expand !== void 0) out.expand = config.expand;
+	if (user.defaults !== void 0) out.defaults = user.defaults;
+	else if (config.defaults !== void 0) out.defaults = config.defaults;
+	if (user.workspaceRoot !== void 0) out.workspaceRoot = user.workspaceRoot;
+	else if (config.workspaceRoot !== void 0) out.workspaceRoot = config.workspaceRoot;
+	if (user.schema !== void 0) out.schema = user.schema;
+	else if (config.schema !== void 0) out.schema = config.schema;
+	if (user.resolvers !== void 0) out.resolvers = user.resolvers;
+	else if (config.resolvers !== void 0) out.resolvers = config.resolvers;
+	if (user.publicPrefixes !== void 0) out.publicPrefixes = user.publicPrefixes;
+	else if (config.publicPrefixes !== void 0) out.publicPrefixes = config.publicPrefixes;
+	if (user.publicSource !== void 0) out.publicSource = user.publicSource;
+	else if (config.publicSource !== void 0) out.publicSource = config.publicSource;
+	return out;
+}
 //#endregion
-export { envx as default, envx };
+export { BUILT_IN_PATTERNS, ENCRYPTED_PREFIX, auditFiles, decryptFiles, decryptValueAsymmetric, envx as default, envx, defaultKeysPath, detectEnvironment, encryptFiles, encryptValueAsymmetric, expandEnvSrc, expandRecord, findWorkspaceRoot, generateKeyPair, isEncrypted, loadDotenvxConfig, parseEnv, readKeysFile, resolveCwdOrWorkspace, resolveEnvPaths, rotateFiles, serializeEnv, toRecord, writeKeysFile };
 
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["// #region -- Programmatic Entry Point ----------------------\n\nimport {\n  loadEnv,\n  loadDotenvxConfig,\n  type LoadEnvOptions,\n} from \"@honeycluster/libs\";\n\n/**\n * Load env files into `process.env` and return it.\n *\n * Modeled after the `dotenv` API but with explicit scoping. Three call\n * shapes:\n *\n * ```ts\n * import envx from \"@honeycluster/envx\";\n *\n * envx();              // load `.env` (auto-detect from NODE_ENV / VERCEL_ENV / NETLIFY)\n * envx(\"prod\");        // load `.env` with cascade=prod (.env, .env.prod, .env.local, .env.prod.local)\n * envx({ envFiles: [\"vault/.env.prod\"], envPath: \"vault\", quiet: false }); // full options\n * ```\n *\n * In all cases `process.env` is mutated and returned for ergonomic\n * destructuring. Config file discovery (`envx.config.{ts,js,json}` /\n * `package.json` `envx.config`) runs automatically; CLI-level options\n * still win when both are passed.\n */\nfunction envx(): NodeJS.ProcessEnv;\nfunction envx(scope: string): NodeJS.ProcessEnv;\nfunction envx(opts: LoadEnvOptions): NodeJS.ProcessEnv;\nfunction envx(arg?: string | LoadEnvOptions): NodeJS.ProcessEnv {\n  // Resolve config-file defaults first; CLI/programmatic args override.\n  const { config } = loadDotenvxConfig();\n\n  let opts: LoadEnvOptions;\n  if (arg === undefined) {\n    opts = {\n      envFiles: config.envFiles ? [...config.envFiles] : [\".env\"],\n      ...(config.cascade !== undefined ? { cascade: config.cascade } : {}),\n      ...(config.envPath !== undefined ? { envPath: config.envPath } : {}),\n      ...(config.override !== undefined ? { override: config.override } : {}),\n      ...(config.quiet !== undefined ? { quiet: config.quiet } : {}),\n    };\n  } else if (typeof arg === \"string\") {\n    // String form is a cascade scope shortcut: envx(\"prod\") loads\n    // .env, .env.prod, .env.local, .env.prod.local in that order.\n    opts = {\n      envFiles: config.envFiles ? [...config.envFiles] : [\".env\"],\n      cascade: arg,\n      ...(config.envPath !== undefined ? { envPath: config.envPath } : {}),\n      ...(config.override !== undefined ? { override: config.override } : {}),\n      ...(config.quiet !== undefined ? { quiet: config.quiet } : {}),\n    };\n  } else {\n    // Object form: caller's options layered over config defaults.\n    opts = {\n      envFiles:\n        arg.envFiles ?? (config.envFiles ? [...config.envFiles] : [\".env\"]),\n      ...(arg.cascade !== undefined\n        ? { cascade: arg.cascade }\n        : config.cascade !== undefined\n          ? { cascade: config.cascade }\n          : {}),\n      ...(arg.envPath !== undefined\n        ? { envPath: arg.envPath }\n        : config.envPath !== undefined\n          ? { envPath: config.envPath }\n          : {}),\n      ...(arg.vault !== undefined ? { vault: arg.vault } : {}),\n      ...(arg.variables !== undefined ? { variables: arg.variables } : {}),\n      ...(arg.override !== undefined\n        ? { override: arg.override }\n        : config.override !== undefined\n          ? { override: config.override }\n          : {}),\n      ...(arg.quiet !== undefined\n        ? { quiet: arg.quiet }\n        : config.quiet !== undefined\n          ? { quiet: config.quiet }\n          : {}),\n    };\n  }\n\n  loadEnv(opts);\n  return process.env;\n}\n\nexport default envx;\nexport { envx };\n\n// Re-export the types callers will need to type their own wrappers.\nexport type { LoadEnvOptions };\n\n// #endregion -----------------------------------------------\n"],"mappings":";;AA8BA,SAAS,KAAK,KAAkD;CAE9D,MAAM,EAAE,WAAW,mBAAmB;CAEtC,IAAI;CACJ,IAAI,QAAQ,KAAA,GACV,OAAO;EACL,UAAU,OAAO,WAAW,CAAC,GAAG,OAAO,SAAS,GAAG,CAAC,OAAO;EAC3D,GAAI,OAAO,YAAY,KAAA,IAAY,EAAE,SAAS,OAAO,SAAS,GAAG,EAAE;EACnE,GAAI,OAAO,YAAY,KAAA,IAAY,EAAE,SAAS,OAAO,SAAS,GAAG,EAAE;EACnE,GAAI,OAAO,aAAa,KAAA,IAAY,EAAE,UAAU,OAAO,UAAU,GAAG,EAAE;EACtE,GAAI,OAAO,UAAU,KAAA,IAAY,EAAE,OAAO,OAAO,OAAO,GAAG,EAAE;EAC9D;MACI,IAAI,OAAO,QAAQ,UAGxB,OAAO;EACL,UAAU,OAAO,WAAW,CAAC,GAAG,OAAO,SAAS,GAAG,CAAC,OAAO;EAC3D,SAAS;EACT,GAAI,OAAO,YAAY,KAAA,IAAY,EAAE,SAAS,OAAO,SAAS,GAAG,EAAE;EACnE,GAAI,OAAO,aAAa,KAAA,IAAY,EAAE,UAAU,OAAO,UAAU,GAAG,EAAE;EACtE,GAAI,OAAO,UAAU,KAAA,IAAY,EAAE,OAAO,OAAO,OAAO,GAAG,EAAE;EAC9D;MAGD,OAAO;EACL,UACE,IAAI,aAAa,OAAO,WAAW,CAAC,GAAG,OAAO,SAAS,GAAG,CAAC,OAAO;EACpE,GAAI,IAAI,YAAY,KAAA,IAChB,EAAE,SAAS,IAAI,SAAS,GACxB,OAAO,YAAY,KAAA,IACjB,EAAE,SAAS,OAAO,SAAS,GAC3B,EAAE;EACR,GAAI,IAAI,YAAY,KAAA,IAChB,EAAE,SAAS,IAAI,SAAS,GACxB,OAAO,YAAY,KAAA,IACjB,EAAE,SAAS,OAAO,SAAS,GAC3B,EAAE;EACR,GAAI,IAAI,UAAU,KAAA,IAAY,EAAE,OAAO,IAAI,OAAO,GAAG,EAAE;EACvD,GAAI,IAAI,cAAc,KAAA,IAAY,EAAE,WAAW,IAAI,WAAW,GAAG,EAAE;EACnE,GAAI,IAAI,aAAa,KAAA,IACjB,EAAE,UAAU,IAAI,UAAU,GAC1B,OAAO,aAAa,KAAA,IAClB,EAAE,UAAU,OAAO,UAAU,GAC7B,EAAE;EACR,GAAI,IAAI,UAAU,KAAA,IACd,EAAE,OAAO,IAAI,OAAO,GACpB,OAAO,UAAU,KAAA,IACf,EAAE,OAAO,OAAO,OAAO,GACvB,EAAE;EACT;CAGH,QAAQ,KAAK;CACb,OAAO,QAAQ"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["// #region -- Programmatic Entry Point ----------------------\n\nimport {\n  loadEnv,\n  loadDotenvxConfig,\n  type DotenvxConfig,\n  type LoadEnvOptions,\n} from \"@super-repo/envx-libs\";\n\n// Re-export the lib surface that consumers depend on (especially the\n// `auditFiles` API used by czar's `envxAuditPlugin`). Internal\n// packages `@super-repo/envx-libs` and `@super-repo/envx-common`\n// aren't on npm — `@super-repo/envx` is the only published entry, so\n// every public API has to be reachable from here.\nexport {\n  // Audit (plaintext-secret scanner)\n  auditFiles,\n  BUILT_IN_PATTERNS,\n  type AuditFinding,\n  type AuditOptions,\n  type SecretPattern,\n  // Crypto primitives\n  ENCRYPTED_PREFIX,\n  generateKeyPair,\n  encryptValueAsymmetric,\n  decryptValueAsymmetric,\n  isEncrypted,\n  // High-level operations\n  encryptFiles,\n  decryptFiles,\n  rotateFiles,\n  // Env-file parser\n  parseEnv,\n  serializeEnv,\n  toRecord,\n  // Variable expansion\n  expandRecord,\n  expandEnvSrc,\n  // Config + path resolution\n  loadDotenvxConfig,\n  findWorkspaceRoot,\n  resolveCwdOrWorkspace,\n  resolveEnvPaths,\n  detectEnvironment,\n  // Keys-file management\n  readKeysFile,\n  writeKeysFile,\n  defaultKeysPath,\n} from \"@super-repo/envx-libs\";\n\nexport type {\n  DotenvxConfig,\n  LoadEnvOptions,\n  ProcessedEnv,\n  ProcessingError,\n  ErrorCode,\n  RunOptions,\n  RunResult,\n  ExpandOptions,\n  ExpandResult,\n  EnvLine,\n  KvLine,\n  RawLine,\n} from \"@super-repo/envx-libs\";\n\n/**\n * Load env files into `process.env` and return it.\n *\n * Modeled after the `dotenv` API but with explicit scoping. Three call\n * shapes:\n *\n * ```ts\n * import envx from \"@super-repo/envx\";\n *\n * envx();              // load `.env` (auto-detect from NODE_ENV / VERCEL_ENV / NETLIFY)\n * envx(\"prod\");        // load `.env` with cascade=prod (.env, .env.prod, .env.local, .env.prod.local)\n * envx({ envFiles: [\"vault/.env.prod\"], envPath: \"vault\", quiet: false }); // full options\n * ```\n *\n * In all cases `process.env` is mutated and returned for ergonomic\n * destructuring. Config file discovery (`envx.config.{ts,js,json}` /\n * `package.json` `envx.config`) runs automatically; programmatic\n * options layer on top of the discovered config, with caller-supplied\n * fields winning per-field.\n */\n/**\n * Programmatic options accept everything `LoadEnvOptions` does plus an\n * optional `profile` name. When set, the matching `config.profiles[name]`\n * is merged onto the base config (per-field) before the user options\n * take over.\n */\nexport type EnvxProgrammaticOptions = LoadEnvOptions & { readonly profile?: string };\n\nfunction envx(): NodeJS.ProcessEnv;\nfunction envx(scope: string): NodeJS.ProcessEnv;\nfunction envx(opts: EnvxProgrammaticOptions): NodeJS.ProcessEnv;\nfunction envx(arg?: string | EnvxProgrammaticOptions): NodeJS.ProcessEnv {\n  const { config: baseConfig } = loadDotenvxConfig();\n  const userOpts: EnvxProgrammaticOptions =\n    arg === undefined\n      ? {}\n      : typeof arg === \"string\"\n        ? { cascade: arg }\n        : arg;\n  let cfg: DotenvxConfig = baseConfig;\n  if (userOpts.profile) {\n    const profile = cfg.profiles?.[userOpts.profile];\n    if (!profile) {\n      throw new Error(\n        `[ENVX_UNKNOWN_PROFILE] '${userOpts.profile}' not found (available: ${\n          Object.keys(cfg.profiles ?? {}).join(\", \") || \"none\"\n        })`,\n      );\n    }\n    cfg = { ...cfg, ...profile };\n  }\n  // Strip `profile` before passing to mergeOpts — it's not a LoadEnvOptions field.\n  const { profile: _drop, ...rest } = userOpts;\n  void _drop;\n  loadEnv(mergeOpts(cfg, rest));\n  return process.env;\n}\n\n/**\n * Per-field merge: caller-supplied option wins, falling through to the\n * matching config field, falling through to whatever default `loadEnv`\n * has built in. Fields the caller doesn't pass and the config doesn't\n * set are simply omitted from the merged options object.\n */\nfunction mergeOpts(\n  config: DotenvxConfig,\n  user: LoadEnvOptions,\n): LoadEnvOptions {\n  const out: { -readonly [K in keyof LoadEnvOptions]: LoadEnvOptions[K] } = {};\n\n  // env-file selection\n  if (user.envFiles !== undefined) out.envFiles = user.envFiles;\n  else if (config.envFiles !== undefined) out.envFiles = [...config.envFiles];\n\n  if (user.envPath !== undefined) out.envPath = user.envPath;\n  else if (config.envPath !== undefined) out.envPath = config.envPath;\n\n  if (user.cascade !== undefined) out.cascade = user.cascade;\n  else if (config.cascade !== undefined) out.cascade = config.cascade;\n\n  if (user.vault !== undefined) out.vault = user.vault;\n\n  if (user.variables !== undefined) out.variables = user.variables;\n\n  // load behavior\n  if (user.override !== undefined) out.override = user.override;\n  else if (config.override !== undefined) out.override = config.override;\n\n  if (user.quiet !== undefined) out.quiet = user.quiet;\n  else if (config.quiet !== undefined) out.quiet = config.quiet;\n\n  // auto-detection\n  if (user.autoDetect !== undefined) out.autoDetect = user.autoDetect;\n  else if (config.autoDetect !== undefined) out.autoDetect = config.autoDetect;\n\n  if (user.nodeEnvMap !== undefined) out.nodeEnvMap = user.nodeEnvMap;\n  else if (config.nodeEnvMap !== undefined) out.nodeEnvMap = config.nodeEnvMap;\n\n  // post-load behavior\n  if (user.required !== undefined) out.required = user.required;\n  else if (config.required !== undefined) out.required = config.required;\n\n  if (user.expand !== undefined) out.expand = user.expand;\n  else if (config.expand !== undefined) out.expand = config.expand;\n\n  if (user.defaults !== undefined) out.defaults = user.defaults;\n  else if (config.defaults !== undefined) out.defaults = config.defaults;\n\n  // advanced\n  if (user.workspaceRoot !== undefined) out.workspaceRoot = user.workspaceRoot;\n  else if (config.workspaceRoot !== undefined) out.workspaceRoot = config.workspaceRoot;\n\n  if (user.schema !== undefined) out.schema = user.schema;\n  else if (config.schema !== undefined) out.schema = config.schema;\n\n  if (user.resolvers !== undefined) out.resolvers = user.resolvers;\n  else if (config.resolvers !== undefined) out.resolvers = config.resolvers;\n\n  if (user.publicPrefixes !== undefined) out.publicPrefixes = user.publicPrefixes;\n  else if (config.publicPrefixes !== undefined) out.publicPrefixes = config.publicPrefixes;\n\n  if (user.publicSource !== undefined) out.publicSource = user.publicSource;\n  else if (config.publicSource !== undefined) out.publicSource = config.publicSource;\n\n  return out;\n}\n\nexport default envx;\nexport { envx };\n\n// Re-export the types callers will need to type their own wrappers.\nexport type { LoadEnvOptions };\n\n// #endregion -----------------------------------------------\n"],"mappings":"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"}

package/docs/auto-detection.md

@@ -0,0 +1,217 @@
+# Auto-detection
+
+When `--env` is left at its default (`[".env"]`) and no `envFiles` is set in config, envx auto-detects the deployment environment from well-known platform signals and rewrites the env-file suffix accordingly. This page walks through every input shape with the resulting file load.
+
+The implementation is `detectEnvironment()` — bundled into this package's dist via Vite.
+
+## Precedence
+
+```
+1. VERCEL    →  detection from VERCEL_ENV
+2. NETLIFY   →  detection from CONTEXT
+3. NODE_ENV  →  built-in map, then lowercased passthrough
+4. (none)    →  .env  (no rewrite)
+```
+
+The first signal that fires wins. So a Vercel build with `NODE_ENV=development` set to a non-default still reads `VERCEL_ENV` first.
+
+## Worked examples
+
+### No platform signals (typical local dev)
+
+```sh
+unset VERCEL VERCEL_ENV NETLIFY CONTEXT NODE_ENV
+envx -- node app.js
+```
+
+| signal     | value     |
+|------------|-----------|
+| (none)     | —         |
+
+→ Detected: **`root`** → loads **`.env`**.
+
+### Local dev with NODE_ENV
+
+```sh
+NODE_ENV=development envx -- node app.js
+```
+
+| signal      | value         |
+|-------------|---------------|
+| `NODE_ENV`  | `development` |
+
+→ Built-in map matches `development → "dev"` → loads **`.env.dev`**.
+
+### Staging environment via NODE_ENV (no config required)
+
+```sh
+NODE_ENV=staging envx -- pnpm test
+```
+
+| signal      | value     |
+|-------------|-----------|
+| `NODE_ENV`  | `staging` |
+
+`staging` isn't in the built-in map, so envx **passes it through lowercased**. → Loads **`.env.staging`**.
+
+The same rule applies to any value: `NODE_ENV=qa` → `.env.qa`, `NODE_ENV=preview` → `.env.preview`, `NODE_ENV=PROD` → `.env.prod` (lowercased — built-in map normalizes the canonical names anyway).
+
+### Vercel preview build
+
+```sh
+# Set by Vercel automatically:
+VERCEL=1
+VERCEL_ENV=preview
+```
+
+| signal       | value     |
+|--------------|-----------|
+| `VERCEL`     | `1`       |
+| `VERCEL_ENV` | `preview` |
+
+→ Detected: **`dev`** → loads **`.env.dev`**.
+
+`VERCEL_ENV=development` and `VERCEL_ENV=preview` both map to `dev`. Only `VERCEL_ENV=production` maps to `prod`.
+
+### Vercel production build
+
+```sh
+VERCEL=1
+VERCEL_ENV=production
+```
+
+→ Detected: **`prod`** → loads **`.env.prod`**.
+
+### Netlify production build
+
+```sh
+NETLIFY=true
+CONTEXT=production
+```
+
+→ Detected: **`prod`** → loads **`.env.prod`**.
+
+### Netlify preview / branch deploy
+
+```sh
+NETLIFY=true
+CONTEXT=deploy-preview
+# or:  CONTEXT=branch-deploy
+```
+
+→ Detected: **`dev`** → loads **`.env.dev`**.
+
+Any other Netlify `CONTEXT` value also resolves to `dev` (Netlify uses `production` only for the canonical site).
+
+### NODE_ENV with custom mapping
+
+```ts
+// envx.config.ts
+export default {
+  nodeEnvMap: {
+    production: "prod",
+    development: "dev",
+    local: "local",
+    // your additions:
+    qa: "qa-prod",          // NODE_ENV=qa loads .env.qa-prod, not .env.qa
+    preview: "",            // NODE_ENV=preview loads .env (no suffix)
+    "2025-prod": "prod",    // alias an arbitrary value
+  },
+}
+```
+
+```sh
+NODE_ENV=qa envx -- node app.js
+```
+
+→ Map override hits `qa → "qa-prod"` → loads **`.env.qa-prod`**.
+
+```sh
+NODE_ENV=preview envx -- node app.js
+```
+
+→ Map override hits `preview → ""` (empty string = no suffix) → loads **`.env`**.
+
+### Disabling auto-detection entirely
+
+```ts
+// envx.config.ts
+export default { autoDetect: false }
+```
+
+```sh
+NODE_ENV=production envx -- node app.js
+```
+
+→ Auto-detection is off → loads **`.env`** regardless of platform signals. Pass `--env` explicitly when you want a different file.
+
+## Verifying what envx will do
+
+`envx info` prints the resolved settings, the platform signals it sees, the detected environment, and the active `NODE_ENV → suffix` map. Use it as a sanity check before deploying.
+
+```sh
+envx info
+```
+
+Sample output:
+
+```
+envx info
+────────────────────────────────────────────────────────────
+Workspace
+  cwd            /repo/apps/web
+  workspace root /repo
+
+Config
+  source         /repo/envx.config.ts
+  origin         auto
+
+Resolved settings
+  envFiles       [".env"]
+  envPath        (none)
+  cascade        (off)
+  envKeysFile    /repo/.env.keys  (default: cwd-first, ws-root fallback)
+  override       false
+  quiet          true
+  autoDetect     true
+
+Platform signals (process.env)
+  VERCEL         (unset)
+  VERCEL_ENV     (unset)
+  NETLIFY        (unset)
+  CONTEXT        (unset)
+  NODE_ENV       staging
+
+Auto-detection
+  source         NODE_ENV
+  detected       staging
+  → env file     .env.staging
+
+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)
+
+Resolved env file paths (would be loaded in this order)
+  .env.staging  →  /repo/.env.staging
+```
+
+## Summary table
+
+| input                                          | detected   | file       |
+|------------------------------------------------|------------|------------|
+| nothing                                        | `root`     | `.env`     |
+| `NODE_ENV=production`                          | `prod`     | `.env.prod`|
+| `NODE_ENV=development`                         | `dev`      | `.env.dev` |
+| `NODE_ENV=local`                               | `local`    | `.env.local`|
+| `NODE_ENV=staging`                             | `staging`  | `.env.staging`|
+| `NODE_ENV=QA` (uppercased)                     | `qa`       | `.env.qa`  |
+| `VERCEL=1, VERCEL_ENV=production`              | `prod`     | `.env.prod`|
+| `VERCEL=1, VERCEL_ENV=preview`                 | `dev`      | `.env.dev` |
+| `VERCEL=1` (no `VERCEL_ENV`)                   | `dev`      | `.env.dev` |
+| `NETLIFY=true, CONTEXT=production`             | `prod`     | `.env.prod`|
+| `NETLIFY=true, CONTEXT=deploy-preview`         | `dev`      | `.env.dev` |
+| `NETLIFY=true, CONTEXT=branch-deploy`          | `dev`      | `.env.dev` |
+| `autoDetect: false` (any signals)              | `root`     | `.env`     |

package/docs/configuration.md

@@ -0,0 +1,224 @@
+# Configuration
+
+envx settings come from four layers, resolved per-field with CLI flags winning. This page documents the schema, the discovery walk, and the merge rules.
+
+The full schema is the `DotenvxConfig` interface — bundled into this package's dist and importable from the CLI's bundled types.
+
+## The schema
+
+```ts
+// envx.config.ts
+export default {
+  // ── env-file selection ─────────────────────────────────
+  envFiles: [".env", ".env.local"],   // bypass auto-detect; explicit list
+  envPath: "vault",                    // workspace-relative subdir (cwd-first, ws-root fallback)
+  cascade: true,                       // boolean: cascade using the auto-detected env name
+                                       // (CLI `--cascade <name>` overrides with an explicit string)
+  variables: ["DEBUG=1"],              // KEY=VALUE overrides applied after load
+
+  // ── encryption keys ────────────────────────────────────
+  envKeysFile: ".env.keys",            // overrides the cwd-first / workspace fallback default
+
+  // ── load behavior ──────────────────────────────────────
+  override: false,                     // false: existing process.env wins
+                                       // true:  env files win (incompatible with cascade)
+  quiet: true,                         // suppress dotenv's load-line output
+
+  // ── auto-detection ─────────────────────────────────────
+  autoDetect: true,                    // false disables Vercel/Netlify/NODE_ENV detection
+  nodeEnvMap: {                         // override the NODE_ENV → suffix mapping
+    production: "prod",                 // (built-ins shown — yours layer on top)
+    development: "dev",
+    local: "local",
+    qa: "qa-prod",                      // NODE_ENV=qa → .env.qa-prod
+    preview: "",                        // NODE_ENV=preview → .env (no suffix)
+  },
+
+  // ── post-load behavior ─────────────────────────────────
+  required: ["DATABASE_URL", "API_KEY"], // fail-fast: exit 1 if any are unset after load
+  expand: true,                          // auto-resolve ${VAR} references against process.env
+  defaults: {                            // applied AFTER files + variables, only for unset keys
+    LOG_LEVEL: "info",
+    PORT: "3000",
+  },
+
+  // ── advanced ───────────────────────────────────────────
+  workspaceRoot: "/abs/path/to/repo",   // escape hatch — skip findWorkspaceRoot() walk-up
+}
+```
+
+All fields are optional. Anything you omit falls through to the built-in default for that field — see [auto-detection](./auto-detection.md) for the per-field defaults.
+
+### Field reference
+
+| field          | type                          | default                        | meaning |
+|----------------|-------------------------------|--------------------------------|---------|
+| `envFiles`     | `string[]`                    | `[".env"]` (with auto-detect)  | Files to load. Bare names get the `.env.` prefix. Bypasses auto-detection. |
+| `envPath`      | `string`                      | _(none)_                        | Subdirectory to look in. Cwd-first; falls back to `<workspaceRoot>/<envPath>`. |
+| `cascade`      | `boolean`                     | `false`                        | When `true`, expand each base file into `.env.<env>.local`, `.env.local`, `.env.<env>`, `.env` — where `<env>` is the auto-detected name. CLI `--cascade <name>` overrides with an explicit string. |
+| `variables`    | `string[]`                    | `[]`                           | `KEY=VALUE` overrides applied after env files load. |
+| `envKeysFile`  | `string`                      | `.env.keys` (cwd-first walk-up)| Path to the keys file. Cwd-first with workspace-root fallback. |
+| `override`     | `boolean`                     | `false`                        | When `true`, env file values overwrite existing `process.env`. Conflicts with `cascade`. |
+| `quiet`        | `boolean`                     | `true`                         | Suppress dotenv's `Loading environment from:` lines. |
+| `autoDetect`   | `boolean`                     | `true`                         | Toggle Vercel/Netlify/NODE_ENV detection. |
+| `nodeEnvMap`   | `Record<string, string>`      | see below                      | Override the `NODE_ENV → suffix` map. |
+| `required`     | `string[]`                    | `[]`                           | Keys that MUST be set in `process.env` after envx finishes. Missing values cause `process.exit(1)`. |
+| `expand`       | `boolean`                     | `false`                        | Auto-resolve `${VAR}` / `$VAR` references against `process.env` after files + variables load. |
+| `defaults`     | `Record<string, string>`      | `{}`                           | Fallback values applied only to keys still unset after files + variables. Different from `variables`, which always overrides. |
+| `workspaceRoot`| `string`                      | _(auto-detect)_                | Explicit workspace root, skipping `findWorkspaceRoot()` walk-up. Useful for non-standard layouts. |
+
+### Built-in `nodeEnvMap`
+
+```ts
+{
+  production: "prod",
+  development: "dev",
+  local: "local",
+}
+```
+
+Anything **not** in the map (after merging your overrides) passes through as the lowercased `NODE_ENV` value — `staging` → `.env.staging`, `qa` → `.env.qa`. Use empty string `""` to force "no suffix" for a specific value (`preview: ""` → `NODE_ENV=preview` loads `.env`).
+
+## Discovery walk
+
+envx finds **one** config file per invocation (no merging across files) in this exact order:
+
+```
+1. --config <path>                       (CLI only — wins if present)
+2. package.json#envx.config: "<path>"     (walks UP from cwd to /)
+3. envx.config.{ts,mts,js,mjs,cjs,json}   (cwd ONLY — does not walk up)
+4. (none)                                 (built-in defaults)
+```
+
+The first match wins; we don't merge multiple files together. This means:
+
+- A `package.json#envx.config` reference anywhere from cwd up to `/` will be picked up. Use this to point sub-packages at a workspace-root config: `{ "envx": { "config": "../../envx.config.ts" } }`.
+- A bare `envx.config.ts` at the workspace root is **only** found if `cwd` happens to be the workspace root itself. Sub-packages don't auto-discover it — they need a `package.json#envx.config` reference.
+
+`package.json#envx.config` only accepts a string path (not an inline object). This keeps the manifest free of secret-related fields and forces config to be a single file you can lint and review.
+
+### Programmatic API uses the same discovery
+
+`envx()` and `envx({...})` from `@super-repo/envx` run the same `loadDotenvxConfig()` discovery as the CLI. The only difference is step 1 (`--config`) is unavailable; programmatic callers pass options directly to `envx({...})`. Programmatic args play the same role as CLI flags — see [Per-field merge](#per-field-merge) below.
+
+### Example: per-package overrides
+
+Because `envx.config.*` is **cwd-only**, sub-packages need a `package.json#envx.config` reference to find a workspace-root config. The minimal monorepo layout looks like:
+
+```
+/repo
+├── envx.config.ts                          ← workspace defaults
+├── packages/
+│   ├── api/
+│   │   └── package.json                     ← { "envx": { "config": "../../envx.config.ts" } }
+│   └── docker-builder/
+│       ├── envx.config.ts                   ← package-specific overrides
+│       └── package.json                     ← (no envx.config field needed — local file is in cwd)
+```
+
+Running `envx -- node app.js` from `/repo/packages/api`:
+- Discovery step 2 walks up `packages/api/package.json` → `packages/package.json` → `/repo/package.json`. The first one is read first; its `envx.config` field points at `../../envx.config.ts`, which resolves to `/repo/envx.config.ts`. **Match — that file is loaded.**
+
+Running the same command from `/repo/packages/docker-builder`:
+- Discovery step 2 walks up the package.jsons. None has an `envx.config` field. No match.
+- Discovery step 3 looks for `envx.config.*` in cwd (`/repo/packages/docker-builder/`). **Match — that file is loaded.**
+
+Configs don't merge across the walk — the first one found is the **only** one read. If you want true workspace-root + package-level layering, that's a feature we don't currently have.
+
+## Per-field merge
+
+Within a single invocation, each setting is resolved **independently** through these layers:
+
+```
+For each setting field (envFiles, cascade, envPath, envKeysFile,
+                       override, quiet, autoDetect, nodeEnvMap, …):
+
+  1. Did the CLI flag — or programmatic arg — set this field?   → use that, stop
+  2. Is it set in the loaded config?                            → use that, stop
+  3. Otherwise                                                    → use the built-in default
+```
+
+So you can mix layers freely:
+
+```sh
+# Config provides envFiles + nodeEnvMap; CLI overrides only `cascade`.
+envx --cascade prod -- node app.js
+```
+
+```ts
+// envx.config.ts
+export default {
+  envFiles: [".env", "vault/.env.prod"],
+  nodeEnvMap: { qa: "qa-prod" },
+}
+```
+
+Effective settings:
+
+| field       | value                              | source           |
+|-------------|------------------------------------|------------------|
+| `envFiles`  | `[".env", "vault/.env.prod"]`       | config           |
+| `cascade`   | `"prod"` (string overrides config's boolean) | CLI flag |
+| `envPath`   | _(none)_                            | default          |
+| `nodeEnvMap`| `{ qa: "qa-prod", + built-ins }`    | config (merged)  |
+| `override`  | `false`                             | default          |
+| `quiet`     | `true`                              | default          |
+| `autoDetect`| `true`                              | default          |
+
+## Load pipeline
+
+When `envx run` (or any subcommand that calls `loadEnv`) executes, the steps run in this exact order:
+
+```
+1. resolve workspaceRoot         (config field, else findWorkspaceRoot())
+2. resolve env file paths        (envFiles → .env. prefix, cascade expansion)
+3. load each env file            (encrypted values decrypted with .env.keys)
+                                  → mutates process.env (subject to `override`)
+4. apply `variables`             (-v KEY=VALUE on CLI / variables in config)
+                                  → unconditional overwrite of process.env
+5. apply `defaults`              (only for keys still undefined)
+                                  → fills holes; never overwrites
+6. expand `${VAR}` references     (when `expand: true`)
+                                  → in-place substitution against process.env
+7. enforce `required`             (any unset → log + process.exit(1))
+```
+
+Implications:
+- `variables` beats `defaults` — variables always overwrite, defaults only fill in.
+- `expand` runs AFTER `defaults`, so a default like `URL: "${HOST}/api"` can resolve.
+- `required` runs LAST, so it sees the final shape of `process.env`. A key that was unset in the env file but provided by `defaults` will pass the `required` check.
+
+## Variable-value precedence (after files load)
+
+This is separate from setting precedence. Once envx has resolved settings and loaded the env files, the actual values that end up in `process.env` follow this order:
+
+```
+Final value of process.env.SOME_KEY is the FIRST hit, top-down:
+
+  1. `-v SOME_KEY=…` passed on the CLI                    (always wins)
+  2. Existing process.env.SOME_KEY when override=false    (the default)
+     OR, when override=true:
+     The most-specific env file's value                   (cascade order)
+  3. The next-most-specific env file's value
+  4. … all the way down the cascade
+  5. unset
+```
+
+`-v` is **not** a config layer — it's a post-load mutation of `process.env`. Use it for one-off injections; use `envFiles` / `cascade` to swap whole environments.
+
+## Validation
+
+The config is parsed by `normalize()` in `config.ts`. Unknown fields are silently dropped (so adding a typo won't error — it'll just have no effect). Wrong types for known fields are dropped too:
+
+| input                                  | result                                       |
+|----------------------------------------|----------------------------------------------|
+| `envFiles: ".env"` (string, not array) | dropped — must be `string[]`                 |
+| `nodeEnvMap: { qa: 42 }`               | the entry is dropped (value must be string)  |
+| `unknown: "field"`                     | silently dropped                              |
+
+If you want strict validation in CI, run `envx info` and grep for the field — the displayed value tells you whether envx accepted it. (A future addition could be a `--strict` flag that errors on unknowns; not currently implemented.)
+
+## See also
+
+- [Auto-detection](./auto-detection.md) — every signal shape walked through with examples.
+- [Recipes](./recipes.md) — common monorepo layouts with the exact config files.