@dotenvx/dotenvx 0.20.1 → 0.21.0

package/README.md

@@ -162,8 +162,8 @@ More examples
   ```sh
   $ echo "HELLO=World" > .env
 
-  $ dotenvx run --quiet -- sh -c 'echo $HELLO'
-  World
+  $ dotenvx run --quiet -- sh -c 'echo Hello $HELLO'
+  Hello World
   ```
 
   </details>

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.20.1",
+  "version": "0.21.0",
   "name": "@dotenvx/dotenvx",
   "description": "a better dotenv–from the creator of `dotenv`",
   "author": "@motdotla",
@@ -42,6 +42,7 @@
     "ora": "^5.4.1",
     "undici": "^5.28.3",
     "update-notifier": "^5.1.0",
+    "which": "^4.0.0",
     "winston": "^3.11.0",
     "xxhashjs": "^0.2.2"
   },

package/src/cli/actions/decrypt.js

@@ -1,10 +1,10 @@
 const fs = require('fs')
+const dotenv = require('dotenv')
 
-const main = require('./../../lib/main')
 const logger = require('./../../shared/logger')
 const helpers = require('./../helpers')
 const createSpinner = require('./../../shared/createSpinner')
-const parseEncryptionKeyFromDotenvKey = require('./../../lib/helpers/parseEncryptionKeyFromDotenvKey')
+const libDecrypt = require('./../../lib/helpers/decrypt')
 
 const spinner = createSpinner('decrypting')
 
@@ -37,8 +37,8 @@ async function decrypt () {
     process.exit(1)
   }
 
-  const dotenvKeys = (main.configDotenv({ path: keysFilepath }).parsed || {})
-  const dotenvVault = (main.configDotenv({ path: vaultFilepath }).parsed || {})
+  const dotenvKeys = dotenv.configDotenv({ path: keysFilepath }).parsed
+  const dotenvVault = dotenv.configDotenv({ path: vaultFilepath }).parsed
 
   Object.entries(dotenvKeys).forEach(([dotenvKey, value]) => {
     // determine environment
@@ -51,10 +51,8 @@ async function decrypt () {
 
     // give warning if not found
     if (ciphertext && ciphertext.length >= 1) {
-      const key = parseEncryptionKeyFromDotenvKey(value.trim())
-
       // Decrypt
-      const decrypted = main.decrypt(ciphertext, key)
+      const decrypted = libDecrypt(ciphertext, value.trim())
 
       // envFilename
       let envFilename = `.env.${environment}`

package/src/cli/actions/genexample.js

@@ -1,6 +1,6 @@
 const fs = require('fs')
-const helpers = require('./../helpers')
 const main = require('./../../lib/main')
+const helpers = require('./../helpers')
 const logger = require('./../../shared/logger')
 const createSpinner = require('./../../shared/createSpinner')
 
@@ -8,84 +8,44 @@ const spinner = createSpinner('generating')
 
 const ENCODING = 'utf8'
 
-async function genexample () {
+async function genexample (directory) {
   spinner.start()
   await helpers.sleep(500) // better dx
 
+  logger.debug(`directory: ${directory}`)
+
   const options = this.opts()
   logger.debug(`options: ${JSON.stringify(options)}`)
 
-  let optionEnvFile = options.envFile
-  if (!Array.isArray(optionEnvFile)) {
-    optionEnvFile = [optionEnvFile]
-  }
-
-  // must be at least one .env* file
-  if (optionEnvFile.length < 1) {
-    spinner.fail('no .env* files found')
-    logger.help('? add one with [echo "HELLO=World" > .env] and then run [dotenvx genexample]')
-    process.exit(1)
-  }
-
-  const keys = new Set()
-  const addedKeys = new Set()
+  try {
+    const {
+      envExampleFile,
+      envFile,
+      exampleFilepath,
+      addedKeys
+    } = main.genexample(directory, options.envFile)
 
-  for (const envFilepath of optionEnvFile) {
-    const filepath = helpers.resolvePath(envFilepath)
+    logger.verbose(`loading env from ${envFile}`)
 
-    logger.verbose(`loading env from ${filepath}`)
+    // TODO: display pre-existing
+    // TODO: display added/appended/injected
 
-    try {
-      const src = fs.readFileSync(filepath, { encoding: ENCODING })
-      const parsed = main.parse(src)
-      Object.keys(parsed).forEach(key => { keys.add(key) })
-    } catch (e) {
-      // calculate development help message depending on state of repo
-      const vaultFilepath = helpers.resolvePath('.env.vault')
-      let developmentHelp = '? in development: add one with [echo "HELLO=World" > .env] and re-run [dotenvx genexample]'
-      if (fs.existsSync(vaultFilepath)) {
-        developmentHelp = '? in development: use [dotenvx decrypt] to decrypt .env.vault to .env and then re-run [dotenvx genexample]'
-      }
+    fs.writeFileSync(exampleFilepath, envExampleFile, ENCODING)
 
-      switch (e.code) {
-        // missing .env
-        case 'ENOENT':
-          logger.warn(`missing ${envFilepath} file (${filepath})`)
-          logger.help(developmentHelp)
-          break
-
-        // unhandled error
-        default:
-          logger.warn(e)
-          break
-      }
-    }
-  }
-
-  const exampleFilename = '.env.example'
-  const exampleFilepath = helpers.resolvePath(exampleFilename)
-  if (!fs.existsSync(exampleFilepath)) {
-    logger.verbose(`creating ${exampleFilename}`)
-    fs.writeFileSync(exampleFilename, `# ${exampleFilename}\n`)
-  }
-
-  const currentEnvExample = (main.configDotenv({ path: exampleFilepath }).parsed || {})
-  const keysArray = Array.from(keys)
-
-  keysArray.forEach(key => {
-    if (key in currentEnvExample) {
-      logger.verbose(`pre-existing ${key} in ${exampleFilename}`)
+    if (addedKeys.length > 0) {
+      spinner.succeed(`updated .env.example (${addedKeys.length})`)
     } else {
-      addedKeys.add(key)
-      logger.verbose(`appending ${key} to ${exampleFilename}`)
-      fs.appendFileSync('.env.example', `${key}=""\n`, ENCODING)
+      spinner.done('no changes (.env.example)')
     }
-  })
-
-  if (addedKeys.size > 0) {
-    spinner.succeed(`updated ${exampleFilename} (${addedKeys.size})`)
-  } else {
-    spinner.done(`no changes (${exampleFilename})`)
+  } catch (error) {
+    spinner.fail(error.message)
+    if (error.help) {
+      logger.help(error.help)
+    }
+    if (error.code) {
+      logger.debug(`ERROR_CODE: ${error.code}`)
+    }
+    process.exit(1)
   }
 }
 

package/src/cli/actions/run.js

@@ -1,14 +1,11 @@
-const fs = require('fs')
 const path = require('path')
 const execa = require('execa')
+const which = require('which')
 const logger = require('./../../shared/logger')
-const helpers = require('./../helpers')
-const main = require('./../../lib/main')
-const parseEncryptionKeyFromDotenvKey = require('./../../lib/helpers/parseEncryptionKeyFromDotenvKey')
 
 const RunDefault = require('./../../lib/services/runDefault')
+const RunVault = require('./../../lib/services/runVault')
 
-const ENCODING = 'utf8'
 const REPORT_ISSUE_LINK = 'https://github.com/dotenvx/dotenvx/issues/new'
 
 const executeCommand = async function (commandArgs, env) {
@@ -39,8 +36,13 @@ const executeCommand = async function (commandArgs, env) {
   }
 
   try {
-    const systemCommandPath = execa.sync('which', [commandArgs[0]]).stdout
-    logger.debug(`system command path [${systemCommandPath}]`)
+    let systemCommandPath = commandArgs[0]
+    try {
+      systemCommandPath = which.sync(`${commandArgs[0]}`)
+      logger.debug(`expanding process command to [${systemCommandPath} ${commandArgs.slice(1).join(' ')}]`)
+    } catch (e) {
+      logger.debug(`could not expand process command. using [${systemCommandPath} ${commandArgs.slice(1).join(' ')}]`)
+    }
 
     // commandProcess = execa(commandArgs[0], commandArgs.slice(1), {
     commandProcess = execa(systemCommandPath, commandArgs.slice(1), {
@@ -80,31 +82,6 @@ const executeCommand = async function (commandArgs, env) {
   }
 }
 
-const _parseCipherTextFromDotenvKeyAndParsedVault = function (dotenvKey, parsedVault) {
-  // Parse DOTENV_KEY. Format is a URI
-  let uri
-  try {
-    uri = new URL(dotenvKey)
-  } catch (e) {
-    throw new Error(`INVALID_DOTENV_KEY: ${e.message}`)
-  }
-
-  // Get environment
-  const environment = uri.searchParams.get('environment')
-  if (!environment) {
-    throw new Error('INVALID_DOTENV_KEY: Missing environment part')
-  }
-
-  // Get ciphertext payload
-  const environmentKey = `DOTENV_VAULT_${environment.toUpperCase()}`
-  const ciphertext = parsedVault[environmentKey] // DOTENV_VAULT_PRODUCTION
-  if (!ciphertext) {
-    throw new Error(`NOT_FOUND_DOTENV_ENVIRONMENT: cannot locate environment ${environmentKey} in your .env.vault file`)
-  }
-
-  return ciphertext
-}
-
 async function run () {
   const commandArgs = this.args
   logger.debug(`process command [${commandArgs.join(' ')}]`)
@@ -114,56 +91,46 @@ async function run () {
 
   // load from .env.vault file
   if (process.env.DOTENV_KEY && process.env.DOTENV_KEY.length > 0) {
-    const envVaultFilepath = options.envVaultFile // .env.vault
-    const filepath = helpers.resolvePath(envVaultFilepath)
+    try {
+      const {
+        envVaultFile,
+        parsed,
+        injected,
+        preExisted,
+        uniqueInjectedKeys
+      } = new RunVault(options.envVaultFile, options.env, process.env.DOTENV_KEY, options.overload).run()
+
+      logger.verbose(`loading env from encrypted ${envVaultFile} (${path.resolve(envVaultFile)})`)
+      logger.debug(`decrypting encrypted env from ${envVaultFile} (${path.resolve(envVaultFile)})`)
+
+      // debug parsed
+      logger.debug(parsed)
+
+      // verbose/debug injected key/value
+      for (const [key, value] of Object.entries(injected)) {
+        logger.verbose(`${key} set`)
+        logger.debug(`${key} set to ${value}`)
+      }
 
-    if (!fs.existsSync(filepath)) {
-      logger.error(`you set DOTENV_KEY but your .env.vault file is missing: ${filepath}`)
-    } else {
-      logger.verbose(`loading env from encrypted ${filepath}`)
-
-      try {
-        const src = fs.readFileSync(filepath, { encoding: ENCODING })
-        const parsedVault = main.parse(src)
-
-        logger.debug(`decrypting encrypted env from ${filepath}`)
-        // handle scenario for comma separated keys - for use with key rotation
-        // example: DOTENV_KEY="dotenv://:key_1234@dotenvx.com/vault/.env.vault?environment=prod,dotenv://:key_7890@dotenvx.com/vault/.env.vault?environment=prod"
-        const dotenvKeys = process.env.DOTENV_KEY.split(',')
-        const length = dotenvKeys.length
-
-        let decrypted
-        for (let i = 0; i < length; i++) {
-          try {
-            // Get full dotenvKey
-            const dotenvKey = dotenvKeys[i].trim()
-
-            const key = parseEncryptionKeyFromDotenvKey(dotenvKey)
-            const ciphertext = _parseCipherTextFromDotenvKeyAndParsedVault(dotenvKey, parsedVault)
-
-            // Decrypt
-            decrypted = main.decrypt(ciphertext, key)
-
-            break
-          } catch (error) {
-            // last key
-            if (i + 1 >= length) {
-              throw error
-            }
-            // try next key
-          }
-        }
-        logger.debug(decrypted)
-        const parsed = main.parseExpand(decrypted)
-        const result = main.inject(process.env, parsed, options.overload)
+      // verbose/debug preExisted key/value
+      for (const [key, value] of Object.entries(preExisted)) {
+        logger.verbose(`${key} pre-exists (protip: use --overload to override)`)
+        logger.debug(`${key} pre-exists as ${value} (protip: use --overload to override)`)
+      }
 
-        logger.successv(`injecting env (${result.injected.size}) from encrypted ${envVaultFilepath}`)
-      } catch (e) {
-        logger.error(e)
+      logger.successv(`injecting env (${uniqueInjectedKeys.length}) from encrypted ${envVaultFile}`)
+    } catch (error) {
+      logger.error(error.message)
+      if (error.help) {
+        logger.help(error.help)
       }
     }
   } else {
-    const { files, readableFilepaths, uniqueInjectedKeys } = new RunDefault(options.envFile, options.env, options.overload).run()
+    const {
+      files,
+      readableFilepaths,
+      uniqueInjectedKeys
+    } = new RunDefault(options.envFile, options.env, options.overload).run()
 
     for (const file of files) {
       const filepath = file.filepath

package/src/cli/dotenvx.js

@@ -95,6 +95,7 @@ program.command('prebuild')
 // dotenvx genexample
 program.command('genexample')
   .description('generate .env.example')
+  .argument('[directory]', 'directory to generate from', '.')
   .option('-f, --env-file <paths...>', 'path(s) to your env file(s)', '.env')
   .action(require('./actions/genexample'))
 

package/src/lib/helpers/changed.js

@@ -0,0 +1,10 @@
+const decrypt = require('./decrypt')
+const hash = require('./hash')
+
+function changed (ciphertext, raw, dotenvKey) {
+  const decrypted = decrypt(ciphertext, dotenvKey)
+
+  return hash(decrypted) !== hash(raw)
+}
+
+module.exports = changed

package/src/lib/helpers/decrypt.js

@@ -0,0 +1,25 @@
+const dotenv = require('dotenv')
+
+const parseEncryptionKeyFromDotenvKey = require('./parseEncryptionKeyFromDotenvKey')
+
+function decrypt (ciphertext, dotenvKey) {
+  const key = parseEncryptionKeyFromDotenvKey(dotenvKey)
+
+  try {
+    return dotenv.decrypt(ciphertext, key)
+  } catch (e) {
+    const error = new Error('[DECRYPTION_FAILED] Unable to decrypt .env.vault with DOTENV_KEY.')
+    error.code = 'DECRYPTION_FAILED'
+    error.help = '[DECRYPTION_FAILED] Run with debug flag [dotenvx run --debug -- yourcommand] or manually run [echo $DOTENV_KEY] to compare it to the one in .env.keys.'
+    error.debug = `[DECRYPTION_FAILED] DOTENV_KEY is ${dotenvKey}`
+
+    switch (e.code) {
+      case 'DECRYPTION_FAILED':
+        throw error
+      default:
+        throw e
+    }
+  }
+}
+
+module.exports = decrypt

package/src/lib/helpers/dotenvVault.js

@@ -1,10 +1,8 @@
 const path = require('path')
-const crypto = require('crypto')
-const xxhash = require('xxhashjs')
-const dotenv = require('dotenv')
 
-const XXHASH_SEED = 0xABCD
-const NONCE_BYTES = 12
+const encrypt = require('./encrypt')
+const changed = require('./changed')
+const guessEnvironment = require('./guessEnvironment')
 
 class DotenvVault {
   constructor (dotenvFiles = {}, dotenvKeys = {}, dotenvVaults = {}) {
@@ -19,14 +17,14 @@ class DotenvVault {
     const addedDotenvFilenames = new Set()
 
     for (const [filepath, raw] of Object.entries(this.dotenvFiles)) {
-      const environment = this._guessEnvironment(filepath)
+      const environment = guessEnvironment(filepath)
       const vault = `DOTENV_VAULT_${environment.toUpperCase()}`
 
       let ciphertext = this.dotenvVaults[vault]
       const dotenvKey = this.dotenvKeys[`DOTENV_KEY_${environment.toUpperCase()}`]
 
-      if (!ciphertext || ciphertext.length === 0 || this._changed(dotenvKey, ciphertext, raw)) {
-        ciphertext = this._encrypt(dotenvKey, raw)
+      if (!ciphertext || ciphertext.length === 0 || changed(ciphertext, raw, dotenvKey)) {
+        ciphertext = encrypt(raw, dotenvKey)
         this.dotenvVaults[vault] = ciphertext
         addedVaults.add(vault) // for info logging to user
 
@@ -54,98 +52,6 @@ class DotenvVault {
       addedDotenvFilenames: [...addedDotenvFilenames] // return set as array
     }
   }
-
-  _guessEnvironment (filepath) {
-    const filename = path.basename(filepath)
-    const parts = filename.split('.')
-    const possibleEnvironment = parts[2] // ['', 'env', environment', 'previous']
-
-    if (!possibleEnvironment || possibleEnvironment.length === 0) {
-      return 'development'
-    }
-
-    return possibleEnvironment
-  }
-
-  _changed (dotenvKey, ciphertext, raw) {
-    const decrypted = this._decrypt(dotenvKey, ciphertext)
-
-    return this._hash(decrypted) !== this._hash(raw)
-  }
-
-  _encrypt (dotenvKey, raw) {
-    const key = this._parseEncryptionKeyFromDotenvKey(dotenvKey)
-
-    // set up nonce
-    const nonce = crypto.randomBytes(NONCE_BYTES)
-
-    // set up cipher
-    const cipher = crypto.createCipheriv('aes-256-gcm', key, nonce)
-
-    // generate ciphertext
-    let ciphertext = ''
-    ciphertext += cipher.update(raw, 'utf8', 'hex')
-    ciphertext += cipher.final('hex')
-    ciphertext += cipher.getAuthTag().toString('hex')
-
-    // prepend nonce
-    ciphertext = nonce.toString('hex') + ciphertext
-
-    // base64 encode output
-    return Buffer.from(ciphertext, 'hex').toString('base64')
-  }
-
-  _decrypt (dotenvKey, ciphertext) {
-    const key = this._parseEncryptionKeyFromDotenvKey(dotenvKey)
-
-    try {
-      return dotenv.decrypt(ciphertext, key)
-    } catch (e) {
-      const decryptionFailedError = new Error('[DECRYPTION_FAILED] Unable to decrypt .env.vault with DOTENV_KEY.')
-      decryptionFailedError.code = 'DECRYPTION_FAILED'
-      decryptionFailedError.help = '[DECRYPTION_FAILED] Run with debug flag [dotenvx run --debug -- yourcommand] or manually run [echo $DOTENV_KEY] to compare it to the one in .env.keys.'
-      decryptionFailedError.debug = `[DECRYPTION_FAILED] DOTENV_KEY is ${dotenvKey}`
-
-      switch (e.code) {
-        case 'DECRYPTION_FAILED':
-          throw decryptionFailedError
-        default:
-          throw e
-      }
-    }
-  }
-
-  _parseEncryptionKeyFromDotenvKey (dotenvKey) {
-    // Parse DOTENV_KEY. Format is a URI
-    let uri
-    try {
-      uri = new URL(dotenvKey)
-    } catch (e) {
-      const code = 'INVALID_DOTENV_KEY'
-      const message = `INVALID_DOTENV_KEY: ${e.message}`
-      const error = new Error(message)
-      error.code = code
-
-      throw error
-    }
-
-    // Get decrypt key
-    const key = uri.password
-    if (!key) {
-      const code = 'INVALID_DOTENV_KEY'
-      const message = 'INVALID_DOTENV_KEY: Missing key part'
-      const error = new Error(message)
-      error.code = code
-
-      throw error
-    }
-
-    return Buffer.from(key.slice(-64), 'hex')
-  }
-
-  _hash (str) {
-    return xxhash.h32(str, XXHASH_SEED).toString(16)
-  }
 }
 
 module.exports = DotenvVault

package/src/lib/helpers/encrypt.js

@@ -0,0 +1,29 @@
+const crypto = require('crypto')
+
+const parseEncryptionKeyFromDotenvKey = require('./parseEncryptionKeyFromDotenvKey')
+
+const NONCE_BYTES = 12
+
+function encrypt (raw, dotenvKey) {
+  const key = parseEncryptionKeyFromDotenvKey(dotenvKey)
+
+  // set up nonce
+  const nonce = crypto.randomBytes(NONCE_BYTES)
+
+  // set up cipher
+  const cipher = crypto.createCipheriv('aes-256-gcm', key, nonce)
+
+  // generate ciphertext
+  let ciphertext = ''
+  ciphertext += cipher.update(raw, 'utf8', 'hex')
+  ciphertext += cipher.final('hex')
+  ciphertext += cipher.getAuthTag().toString('hex')
+
+  // prepend nonce
+  ciphertext = nonce.toString('hex') + ciphertext
+
+  // base64 encode output
+  return Buffer.from(ciphertext, 'hex').toString('base64')
+}
+
+module.exports = encrypt

package/src/lib/helpers/findEnvFiles.js

@@ -0,0 +1,27 @@
+const fs = require('fs')
+
+const RESERVED_ENV_FILES = ['.env.vault', '.env.project', '.env.keys', '.env.me', '.env.x', '.env.example']
+
+function findEnvFiles (directory) {
+  try {
+    const files = fs.readdirSync(directory)
+    const envFiles = files.filter(file =>
+      file.startsWith('.env') &&
+      !file.endsWith('.previous') &&
+      !RESERVED_ENV_FILES.includes(file)
+    )
+
+    return envFiles
+  } catch (e) {
+    if (e.code === 'ENOENT') {
+      const error = new Error(`missing directory (${directory})`)
+      error.code = 'MISSING_DIRECTORY'
+
+      throw error
+    } else {
+      throw e
+    }
+  }
+}
+
+module.exports = findEnvFiles

package/src/lib/helpers/guessEnvironment.js

@@ -0,0 +1,15 @@
+const path = require('path')
+
+function guessEnvironment (filepath) {
+  const filename = path.basename(filepath)
+  const parts = filename.split('.')
+  const possibleEnvironment = parts[2] // ['', 'env', environment', 'previous']
+
+  if (!possibleEnvironment || possibleEnvironment.length === 0) {
+    return 'development'
+  }
+
+  return possibleEnvironment
+}
+
+module.exports = guessEnvironment

package/src/lib/helpers/hash.js

@@ -0,0 +1,9 @@
+const xxhash = require('xxhashjs')
+
+const XXHASH_SEED = 0xABCD // DO NOT CHANGE
+
+function hash (str) {
+  return xxhash.h32(str, XXHASH_SEED).toString(16)
+}
+
+module.exports = hash

package/src/lib/helpers/inject.js

@@ -0,0 +1,27 @@
+function inject (processEnv = {}, parsed = {}, overload = false) {
+  const injected = {}
+  const preExisted = {}
+
+  // set processEnv
+  for (const key of Object.keys(parsed)) {
+    if (processEnv[key]) {
+      if (overload === true) {
+        processEnv[key] = parsed[key]
+
+        injected[key] = parsed[key] // track injected key/value
+      } else {
+        preExisted[key] = processEnv[key] // track preExisted key/value
+      }
+    } else {
+      processEnv[key] = parsed[key]
+      injected[key] = parsed[key] // track injected key/value
+    }
+  }
+
+  return {
+    injected,
+    preExisted
+  }
+}
+
+module.exports = inject

package/src/lib/helpers/parseEnvironmentFromDotenvKey.js

@@ -0,0 +1,19 @@
+function parseEnvironmentFromDotenvKey (dotenvKey) {
+  // Parse DOTENV_KEY. Format is a URI
+  let uri
+  try {
+    uri = new URL(dotenvKey)
+  } catch (e) {
+    throw new Error(`INVALID_DOTENV_KEY: ${e.message}`)
+  }
+
+  // Get environment
+  const environment = uri.searchParams.get('environment')
+  if (!environment) {
+    throw new Error('INVALID_DOTENV_KEY: Missing environment part')
+  }
+
+  return environment
+}
+
+module.exports = parseEnvironmentFromDotenvKey

package/src/lib/helpers/parseExpand.js

@@ -0,0 +1,30 @@
+const dotenv = require('dotenv')
+const dotenvExpand = require('dotenv-expand')
+
+function parseExpand (src, overload) {
+  const parsed = dotenv.parse(src)
+
+  // consider moving this logic straight into dotenv-expand
+  let inputParsed = {}
+  if (overload) {
+    inputParsed = { ...process.env, ...parsed }
+  } else {
+    inputParsed = { ...parsed, ...process.env }
+  }
+
+  const expandPlease = {
+    processEnv: {},
+    parsed: inputParsed
+  }
+  const expanded = dotenvExpand.expand(expandPlease).parsed
+
+  // but then for logging only log the original keys existing in parsed. this feels unnecessarily complex - like dotenv-expand should support the ability to inject additional `process.env` or objects as it sees fit to the object it wants to expand
+  const result = {}
+  for (const key in parsed) {
+    result[key] = expanded[key]
+  }
+
+  return result
+}
+
+module.exports = parseExpand

package/src/lib/main.js

@@ -1,112 +1,26 @@
 const logger = require('./../shared/logger')
 const dotenv = require('dotenv')
-const dotenvExpand = require('dotenv-expand')
 
 // services
 const Encrypt = require('./services/encrypt')
 const Ls = require('./services/ls')
 const Get = require('./services/get')
+const Genexample = require('./services/genexample')
 
+// proxies to dotenv
 const config = function (options) {
   return dotenv.config(options)
 }
 
-const decrypt = function (encrypted, keyStr) {
-  try {
-    return dotenv.decrypt(encrypted, keyStr)
-  } catch (e) {
-    switch (e.code) {
-      case 'DECRYPTION_FAILED':
-        // more helpful error when decryption fails
-        logger.error('[DECRYPTION_FAILED] Unable to decrypt .env.vault with DOTENV_KEY.')
-        logger.help('[DECRYPTION_FAILED] Run with debug flag [dotenvx run --debug -- yourcommand] or manually run [echo $DOTENV_KEY] to compare it to the one in .env.keys.')
-        logger.debug(`[DECRYPTION_FAILED] DOTENV_KEY is ${process.env.DOTENV_KEY}`)
-        process.exit(1)
-        break
-      default:
-        throw e
-    }
-  }
-}
-
 const configDotenv = function (options) {
   return dotenv.configDotenv(options)
 }
 
 const parse = function (src) {
-  const result = dotenv.parse(src)
-
-  logger.debug(result)
-
-  return result
-}
-
-const parseExpand = function (src, overload) {
-  const parsed = dotenv.parse(src)
-
-  // consider moving this logic straight into dotenv-expand
-  let inputParsed = {}
-  if (overload) {
-    inputParsed = { ...process.env, ...parsed }
-  } else {
-    inputParsed = { ...parsed, ...process.env }
-  }
-
-  const expandPlease = {
-    processEnv: {},
-    parsed: inputParsed
-  }
-  const expanded = dotenvExpand.expand(expandPlease).parsed
-
-  // but then for logging only log the original keys existing in parsed. this feels unnecessarily complex - like dotenv-expand should support the ability to inject additional `process.env` or objects as it sees fit to the object it wants to expand
-  const result = {}
-  for (const key in parsed) {
-    result[key] = expanded[key]
-  }
-
-  logger.debug(result)
-
-  return result
-}
-
-const inject = function (processEnv = {}, parsed = {}, overload = false) {
-  if (typeof parsed !== 'object') {
-    throw new Error('OBJECT_REQUIRED: Please check the parsed argument being passed to inject')
-  }
-
-  const injected = new Set()
-  const preExisting = new Set()
-
-  // set processEnv
-  for (const key of Object.keys(parsed)) {
-    if (Object.prototype.hasOwnProperty.call(processEnv, key)) {
-      if (overload === true) {
-        processEnv[key] = parsed[key]
-        injected.add(key)
-
-        logger.verbose(`${key} set`)
-        logger.debug(`${key} set to ${parsed[key]}`)
-      } else {
-        preExisting.add(key)
-
-        logger.verbose(`${key} pre-exists (protip: use --overload to override)`)
-        logger.debug(`${key} pre-exists as ${processEnv[key]} (protip: use --overload to override)`)
-      }
-    } else {
-      processEnv[key] = parsed[key]
-      injected.add(key)
-
-      logger.verbose(`${key} set`)
-      logger.debug(`${key} set to ${parsed[key]}`)
-    }
-  }
-
-  return {
-    injected,
-    preExisting
-  }
+  return dotenv.parse(src)
 }
 
+// actions related
 const encrypt = function (directory, envFile) {
   return new Encrypt(directory, envFile).run()
 }
@@ -115,18 +29,43 @@ const ls = function (directory, envFile) {
   return new Ls(directory, envFile).run()
 }
 
+const genexample = function (directory, envFile) {
+  return new Genexample(directory, envFile).run()
+}
+
 const get = function (key, envFile, overload, all) {
   return new Get(key, envFile, overload, all).run()
 }
 
+// misc/cleanup
+const decrypt = function (encrypted, keyStr) {
+  try {
+    return dotenv.decrypt(encrypted, keyStr)
+  } catch (e) {
+    switch (e.code) {
+      case 'DECRYPTION_FAILED':
+        // more helpful error when decryption fails
+        logger.error('[DECRYPTION_FAILED] Unable to decrypt .env.vault with DOTENV_KEY.')
+        logger.help('[DECRYPTION_FAILED] Run with debug flag [dotenvx run --debug -- yourcommand] or manually run [echo $DOTENV_KEY] to compare it to the one in .env.keys.')
+        logger.debug(`[DECRYPTION_FAILED] DOTENV_KEY is ${process.env.DOTENV_KEY}`)
+        process.exit(1)
+        break
+      default:
+        throw e
+    }
+  }
+}
+
 module.exports = {
+  // dotenv proxies
   config,
   configDotenv,
-  decrypt,
   parse,
-  parseExpand,
-  inject,
+  // actions related
   encrypt,
   ls,
-  get
+  get,
+  genexample,
+  // misc/cleanup
+  decrypt
 }

package/src/lib/services/encrypt.js

@@ -6,12 +6,13 @@ const DotenvKeys = require('./../helpers/dotenvKeys')
 const DotenvVault = require('./../helpers/dotenvVault')
 
 const ENCODING = 'utf8'
-const RESERVED_ENV_FILES = ['.env.vault', '.env.project', '.env.keys', '.env.me', '.env.x']
+
+const findEnvFiles = require('../helpers/findEnvFiles')
 
 class Encrypt {
   constructor (directory = '.', envFile) {
     this.directory = directory
-    this.envFile = envFile || this._findEnvFiles()
+    this.envFile = envFile || findEnvFiles(directory)
     // calculated
     this.envKeysFilepath = path.resolve(this.directory, '.env.keys')
     this.envVaultFilepath = path.resolve(this.directory, '.env.vault')
@@ -112,17 +113,6 @@ class Encrypt {
 
     return dotenv.configDotenv(options).parsed
   }
-
-  _findEnvFiles () {
-    const files = fs.readdirSync(this.directory)
-    const envFiles = files.filter(file =>
-      file.startsWith('.env') &&
-      !file.endsWith('.previous') &&
-      !RESERVED_ENV_FILES.includes(file)
-    )
-
-    return envFiles
-  }
 }
 
 module.exports = Encrypt

package/src/lib/services/genexample.js

@@ -0,0 +1,94 @@
+const fs = require('fs')
+const path = require('path')
+const dotenv = require('dotenv')
+
+const ENCODING = 'utf8'
+
+const findEnvFiles = require('../helpers/findEnvFiles')
+
+class Genexample {
+  constructor (directory = '.', envFile) {
+    this.directory = directory
+    this.envFile = envFile || findEnvFiles(directory)
+  }
+
+  run () {
+    if (this.envFile.length < 1) {
+      const code = 'MISSING_ENV_FILES'
+      const message = 'no .env* files found'
+      const help = '? add one with [echo "HELLO=World" > .env] and then run [dotenvx genexample]'
+
+      const error = new Error(message)
+      error.code = code
+      error.help = help
+      throw error
+    }
+
+    const keys = new Set()
+    const addedKeys = new Set()
+    const envFilepaths = this._envFilepaths()
+
+    for (const envFilepath of envFilepaths) {
+      const filepath = path.resolve(this.directory, envFilepath)
+      if (!fs.existsSync(filepath)) {
+        const code = 'MISSING_ENV_FILE'
+        const message = `file does not exist at [${filepath}]`
+        const help = `? add it with [echo "HELLO=World" > ${envFilepath}] and then run [dotenvx genexample]`
+
+        const error = new Error(message)
+        error.code = code
+        error.help = help
+        throw error
+      }
+
+      const parsed = dotenv.configDotenv({ path: filepath }).parsed
+      for (const key of Object.keys(parsed)) {
+        keys.add(key)
+      }
+    }
+
+    let envExampleFile = ''
+    const exampleFilename = '.env.example'
+    const exampleFilepath = path.resolve(this.directory, exampleFilename)
+    if (!fs.existsSync(exampleFilepath)) {
+      envExampleFile += `# ${exampleFilename}\n`
+    } else {
+      envExampleFile = fs.readFileSync(exampleFilepath, ENCODING)
+    }
+
+    const currentEnvExample = dotenv.configDotenv({ path: exampleFilepath }).parsed
+    const injected = {}
+    const preExisted = {}
+
+    for (const key of [...keys]) {
+      if (key in currentEnvExample) {
+        preExisted[key] = currentEnvExample[key]
+      } else {
+        envExampleFile += `${key}=""\n`
+
+        addedKeys.add(key)
+
+        injected[key] = ''
+      }
+    }
+
+    return {
+      envExampleFile,
+      envFile: this.envFile,
+      exampleFilepath,
+      addedKeys: [...addedKeys],
+      injected,
+      preExisted
+    }
+  }
+
+  _envFilepaths () {
+    if (!Array.isArray(this.envFile)) {
+      return [this.envFile]
+    }
+
+    return this.envFile
+  }
+}
+
+module.exports = Genexample

package/src/lib/services/runDefault.js

@@ -1,10 +1,11 @@
 const fs = require('fs')
 const path = require('path')
-const dotenv = require('dotenv')
-const dotenvExpand = require('dotenv-expand')
 
 const ENCODING = 'utf8'
 
+const inject = require('./../helpers/inject')
+const parseExpand = require('./../helpers/parseExpand')
+
 class RunDefault {
   constructor (envFile = '.env', env = [], overload = false) {
     this.envFile = envFile
@@ -24,10 +25,10 @@ class RunDefault {
       row.string = env
 
       try {
-        const parsed = this._parseExpand(env)
+        const parsed = parseExpand(env, this.overload)
         row.parsed = parsed
 
-        const { injected, preExisted } = this._inject(process.env, parsed)
+        const { injected, preExisted } = inject(process.env, parsed, this.overload)
         row.injected = injected
         row.preExisted = preExisted
 
@@ -51,10 +52,10 @@ class RunDefault {
         const src = fs.readFileSync(filepath, { encoding: ENCODING })
         readableFilepaths.add(envFilepath)
 
-        const parsed = this._parseExpand(src)
+        const parsed = parseExpand(src, this.overload)
         row.parsed = parsed
 
-        const { injected, preExisted } = this._inject(process.env, parsed)
+        const { injected, preExisted } = inject(process.env, parsed, this.overload)
         row.injected = injected
         row.preExisted = preExisted
 
@@ -98,58 +99,6 @@ class RunDefault {
 
     return this.env
   }
-
-  _parseExpand (src) {
-    const parsed = dotenv.parse(src)
-
-    // consider moving this logic straight into dotenv-expand
-    let inputParsed = {}
-    if (this.overload) {
-      inputParsed = { ...process.env, ...parsed }
-    } else {
-      inputParsed = { ...parsed, ...process.env }
-    }
-
-    const expandPlease = {
-      processEnv: {},
-      parsed: inputParsed
-    }
-    const expanded = dotenvExpand.expand(expandPlease).parsed
-
-    // but then for logging only log the original keys existing in parsed. this feels unnecessarily complex - like dotenv-expand should support the ability to inject additional `process.env` or objects as it sees fit to the object it wants to expand
-    const result = {}
-    for (const key in parsed) {
-      result[key] = expanded[key]
-    }
-
-    return result
-  }
-
-  _inject (processEnv = {}, parsed = {}) {
-    const injected = {}
-    const preExisted = {}
-
-    // set processEnv
-    for (const key of Object.keys(parsed)) {
-      if (processEnv[key]) {
-        if (this.overload === true) {
-          processEnv[key] = parsed[key]
-
-          injected[key] = parsed[key] // track injected key/value
-        } else {
-          preExisted[key] = processEnv[key] // track preExisted key/value
-        }
-      } else {
-        processEnv[key] = parsed[key]
-        injected[key] = parsed[key] // track injected key/value
-      }
-    }
-
-    return {
-      injected,
-      preExisted
-    }
-  }
 }
 
 module.exports = RunDefault

package/src/lib/services/runVault.js

@@ -0,0 +1,136 @@
+const fs = require('fs')
+const path = require('path')
+const dotenv = require('dotenv')
+
+const inject = require('./../helpers/inject')
+const decrypt = require('./../helpers/decrypt')
+const parseExpand = require('./../helpers/parseExpand')
+const parseEnvironmentFromDotenvKey = require('./../helpers/parseEnvironmentFromDotenvKey')
+
+const ENCODING = 'utf8'
+
+class RunVault {
+  constructor (envVaultFile = '.env.vault', env = [], DOTENV_KEY = '', overload = false) {
+    this.DOTENV_KEY = DOTENV_KEY
+    this.envVaultFile = envVaultFile
+    this.env = env
+    this.overload = overload
+  }
+
+  run () {
+    const filepath = path.resolve(this.envVaultFile)
+    if (!fs.existsSync(filepath)) {
+      const code = 'MISSING_ENV_VAULT_FILE'
+      const message = `you set DOTENV_KEY but your .env.vault file is missing: ${filepath}`
+      const error = new Error(message)
+      error.code = code
+      throw error
+    }
+
+    if (this.DOTENV_KEY.length < 1) {
+      const code = 'MISSING_DOTENV_KEY'
+      const message = `your DOTENV_KEY appears to be blank: '${this.DOTENV_KEY}'`
+      const error = new Error(message)
+      error.code = code
+      throw error
+    }
+
+    const strings = []
+    const uniqueInjectedKeys = new Set()
+
+    const envs = this._envs()
+    for (const env of envs) {
+      const row = {}
+      row.string = env
+
+      const parsed = parseExpand(env, this.overload)
+      row.parsed = parsed
+
+      const { injected, preExisted } = inject(process.env, parsed, this.overload)
+      row.injected = injected
+      row.preExisted = preExisted
+
+      for (const key of Object.keys(injected)) {
+        uniqueInjectedKeys.add(key) // track uniqueInjectedKeys across multiple files
+      }
+
+      strings.push(row)
+    }
+
+    let decrypted
+    const dotenvKeys = this._dotenvKeys()
+    const parsedVault = this._parsedVault(filepath)
+    for (let i = 0; i < dotenvKeys.length; i++) {
+      try {
+        const dotenvKey = dotenvKeys[i].trim() // dotenv://key_1234@...?environment=prod
+
+        decrypted = this._decrypted(dotenvKey, parsedVault)
+
+        break
+      } catch (error) {
+        // last key
+        if (i + 1 >= dotenvKeys.length) {
+          throw error
+        }
+        // try next key
+      }
+    }
+
+    // parse this. it's the equivalent of the .env file
+    const parsed = parseExpand(decrypted, this.overload)
+    const { injected, preExisted } = inject(process.env, parsed, this.overload)
+
+    for (const key of Object.keys(injected)) {
+      uniqueInjectedKeys.add(key) // track uniqueInjectedKeys across multiple files
+    }
+
+    return {
+      envVaultFile: this.envVaultFile, // filepath
+      strings,
+      dotenvKeys,
+      decrypted,
+      parsed,
+      injected,
+      preExisted,
+      uniqueInjectedKeys: [...uniqueInjectedKeys]
+    }
+  }
+
+  // handle scenario for comma separated keys - for use with key rotation
+  // example: DOTENV_KEY="dotenv://:key_1234@dotenvx.com/vault/.env.vault?environment=prod,dotenv://:key_7890@dotenvx.com/vault/.env.vault?environment=prod"
+  _dotenvKeys () {
+    return this.DOTENV_KEY.split(',')
+  }
+
+  _decrypted (dotenvKey, parsedVault) {
+    const environment = parseEnvironmentFromDotenvKey(dotenvKey)
+
+    // DOTENV_KEY_PRODUCTION
+    const environmentKey = `DOTENV_VAULT_${environment.toUpperCase()}`
+    const ciphertext = parsedVault[environmentKey]
+    if (!ciphertext) {
+      const error = new Error(`NOT_FOUND_DOTENV_ENVIRONMENT: cannot locate environment ${environmentKey} in your .env.vault file`)
+      error.code = 'NOT_FOUND_DOTENV_ENVIRONMENT'
+
+      throw error
+    }
+
+    return decrypt(ciphertext, dotenvKey)
+  }
+
+  // { "DOTENV_VAULT_DEVELOPMENT": "<ciphertext>" }
+  _parsedVault (filepath) {
+    const src = fs.readFileSync(filepath, { encoding: ENCODING })
+    return dotenv.parse(src)
+  }
+
+  _envs () {
+    if (!Array.isArray(this.env)) {
+      return [this.env]
+    }
+
+    return this.env
+  }
+}
+
+module.exports = RunVault