netlify-cli 11.4.0 → 11.5.0

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "netlify-cli",
-  "version": "11.4.0",
+  "version": "11.5.0",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "netlify-cli",
-      "version": "11.4.0",
+      "version": "11.5.0",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "netlify-cli",
   "description": "Netlify command line tool",
-  "version": "11.4.0",
+  "version": "11.5.0",
   "author": "Netlify Inc.",
   "contributors": [
     "@whitep4nth3r (https://twitter.com/whitep4nth3r)",
@@ -46,6 +46,7 @@
     "Erez Rokah (https://www.erezro.com)",
     "Erica Pisani <pisani.erica@gmail.com>",
     "Evans Hauser (https://twitter.com/evanshauser)",
+    "Ewan Valentine <ewan.valentine89@gmail.com> (http://ewanvalentine.io)",
     "Finn Woelm (https://twitter.com/FinnWoelm)",
     "Flxbot",
     "Gavin Henderson <gavin.henderson@hotmail.co.uk> (https://twitter.com/gavinhenderson5)",

package/src/commands/build/build.js

@@ -2,7 +2,7 @@ const process = require('process')
 
 // @ts-check
 const { getBuildOptions, runBuild } = require('../../lib/build')
-const { error, exit, generateNetlifyGraphJWT, getEnvelopeEnv, getToken } = require('../../utils')
+const { error, exit, generateNetlifyGraphJWT, getEnvelopeEnv, getToken, normalizeContext } = require('../../utils')
 
 /**
  * @param {import('../../lib/build').BuildConfig} options
@@ -85,7 +85,12 @@ const createBuildCommand = (program) =>
   program
     .command('build')
     .description('(Beta) Build on your local machine')
-    .option('--context <context>', 'Specify a build context', process.env.CONTEXT || 'production')
+    .option(
+      '--context <context>',
+      'Specify a build context or branch (contexts: "production", "deploy-preview", "branch-deploy", "dev")',
+      normalizeContext,
+      process.env.CONTEXT || 'production',
+    )
     .option('--dry', 'Dry run: show instructions without running them', false)
     .option('-o, --offline', 'disables any features that require network access', false)
     .addExamples(['netlify build'])

package/src/commands/dev/dev-exec.js

@@ -1,7 +1,6 @@
-const { Option } = require('commander')
 const execa = require('execa')
 
-const { getEnvelopeEnv, injectEnvVariables } = require('../../utils')
+const { getEnvelopeEnv, injectEnvVariables, normalizeContext } = require('../../utils')
 
 /**
  * The dev:exec command
@@ -32,10 +31,11 @@ const createDevExecCommand = (program) =>
   program
     .command('dev:exec')
     .argument('<...cmd>', `the command that should be executed`)
-    .addOption(
-      new Option('--context <context>', 'Specify a deploy context for environment variables')
-        .choices(['production', 'deploy-preview', 'branch-deploy', 'dev'])
-        .default('dev'),
+    .option(
+      '--context <context>',
+      'Specify a deploy context or branch for environment variables (contexts: "production", "deploy-preview", "branch-deploy", "dev")',
+      normalizeContext,
+      'dev',
     )
     .description(
       'Exec command\nRuns a command within the netlify dev environment, e.g. with env variables from any installed addons',

package/src/commands/dev/dev.js

@@ -45,6 +45,7 @@ const {
   injectEnvVariables,
   log,
   normalizeConfig,
+  normalizeContext,
   openBrowser,
   processOnExit,
   startLiveTunnel,
@@ -684,10 +685,11 @@ const createDevCommand = (program) => {
       `Local dev server\nThe dev command will run a local dev server with Netlify's proxy and redirect rules`,
     )
     .option('-c ,--command <command>', 'command to run')
-    .addOption(
-      new Option('--context <context>', 'Specify a deploy context for environment variables')
-        .choices(['production', 'deploy-preview', 'branch-deploy', 'dev'])
-        .default('dev'),
+    .option(
+      '--context <context>',
+      'Specify a deploy context or branch for environment variables (contexts: "production", "deploy-preview", "branch-deploy", "dev")',
+      normalizeContext,
+      'dev',
     )
     .option('-p ,--port <port>', 'port of netlify dev', (value) => Number.parseInt(value))
     .option('--targetPort <port>', 'port of target app server', (value) => Number.parseInt(value))

package/src/commands/env/env-get.js

@@ -1,7 +1,7 @@
 // @ts-check
 const { Option } = require('commander')
 
-const { chalk, error, getEnvelopeEnv, log, logJson } = require('../../utils')
+const { AVAILABLE_CONTEXTS, chalk, error, getEnvelopeEnv, log, logJson, normalizeContext } = require('../../utils')
 
 /**
  * The env:get command
@@ -42,7 +42,8 @@ const envGet = async (name, options, command) => {
   }
 
   if (!value) {
-    const withContext = `in the ${chalk.magenta(context)} context`
+    const contextType = AVAILABLE_CONTEXTS.includes(context) ? 'context' : 'branch'
+    const withContext = `in the ${chalk.magenta(context)} ${contextType}`
     const withScope = scope === 'any' ? '' : ` and the ${chalk.magenta(scope)} scope`
     log(`No value set ${withContext}${withScope} for environment variable ${chalk.yellow(name)}`)
     return false
@@ -60,16 +61,23 @@ const createEnvGetCommand = (program) =>
   program
     .command('env:get')
     .argument('<name>', 'Environment variable name')
-    .addOption(
-      new Option('-c, --context <context>', 'Specify a deploy context')
-        .choices(['production', 'deploy-preview', 'branch-deploy', 'dev'])
-        .default('dev'),
+    .option(
+      '-c, --context <context>',
+      'Specify a deploy context or branch (contexts: "production", "deploy-preview", "branch-deploy", "dev")',
+      normalizeContext,
+      'dev',
     )
     .addOption(
       new Option('-s, --scope <scope>', 'Specify a scope')
         .choices(['builds', 'functions', 'post_processing', 'runtime', 'any'])
         .default('any'),
     )
+    .addExamples([
+      'netlify env:get MY_VAR # get value for MY_VAR in dev context',
+      'netlify env:get MY_VAR --context production',
+      'netlify env:get MY_VAR --context branch:staging',
+      'netlify env:get MY_VAR --scope functions',
+    ])
     .description('Get resolved value of specified environment variable (includes netlify.toml)')
     .action(async (name, options, command) => {
       await envGet(name, options, command)

package/src/commands/env/env-list.js

@@ -5,7 +5,16 @@ const { Option } = require('commander')
 const inquirer = require('inquirer')
 const isEmpty = require('lodash/isEmpty')
 
-const { chalk, error, getEnvelopeEnv, getHumanReadableScopes, log, logJson } = require('../../utils')
+const {
+  AVAILABLE_CONTEXTS,
+  chalk,
+  error,
+  getEnvelopeEnv,
+  getHumanReadableScopes,
+  log,
+  logJson,
+  normalizeContext,
+} = require('../../utils')
 
 const [logUpdatePromise, ansiEscapesPromise] = [import('log-update'), import('ansi-escapes')]
 
@@ -77,7 +86,8 @@ const envList = async (options, command) => {
   }
 
   const forSite = `for site ${chalk.green(siteInfo.name)}`
-  const withContext = isUsingEnvelope ? `in the ${chalk.magenta(options.context)} context` : ''
+  const contextType = AVAILABLE_CONTEXTS.includes(context) ? 'context' : 'branch'
+  const withContext = isUsingEnvelope ? `in the ${chalk.magenta(options.context)} ${contextType}` : ''
   const withScope = isUsingEnvelope && scope !== 'any' ? `and ${chalk.yellow(options.scope)} scope` : ''
   if (isEmpty(environment)) {
     log(`No environment variables set ${forSite} ${withContext} ${withScope}`)
@@ -122,16 +132,23 @@ const envList = async (options, command) => {
 const createEnvListCommand = (program) =>
   program
     .command('env:list')
-    .addOption(
-      new Option('-c, --context <context>', 'Specify a deploy context')
-        .choices(['production', 'deploy-preview', 'branch-deploy', 'dev'])
-        .default('dev'),
+    .option(
+      '-c, --context <context>',
+      'Specify a deploy context or branch (contexts: "production", "deploy-preview", "branch-deploy", "dev")',
+      normalizeContext,
+      'dev',
     )
     .addOption(
       new Option('-s, --scope <scope>', 'Specify a scope')
         .choices(['builds', 'functions', 'post_processing', 'runtime', 'any'])
         .default('any'),
     )
+    .addExamples([
+      'netlify env:list # list variables with values in the dev context and with any scope',
+      'netlify env:list --context production',
+      'netlify env:list --context branch:staging',
+      'netlify env:list --scope functions',
+    ])
     .description('Lists resolved environment variables for site (includes netlify.toml)')
     .action(async (options, command) => {
       await envList(options, command)

package/src/commands/env/env-set.js

@@ -1,9 +1,16 @@
 // @ts-check
 const { Option } = require('commander')
 
-const { chalk, error, log, logJson, translateFromEnvelopeToMongo } = require('../../utils')
-
-const AVAILABLE_SCOPES = ['builds', 'functions', 'runtime', 'post_processing']
+const {
+  AVAILABLE_CONTEXTS,
+  AVAILABLE_SCOPES,
+  chalk,
+  error,
+  log,
+  logJson,
+  normalizeContext,
+  translateFromEnvelopeToMongo,
+} = require('../../utils')
 
 /**
  * The env:set command
@@ -52,10 +59,11 @@ const envSet = async (key, value, options, command) => {
   }
 
   const withScope = scope ? ` scoped to ${chalk.white(scope)}` : ''
+  const contextType = AVAILABLE_CONTEXTS.includes(context || 'all') ? 'context' : 'branch'
   log(
     `Set environment variable ${chalk.yellow(`${key}${value ? '=' : ''}${value}`)}${withScope} in the ${chalk.magenta(
       context || 'all',
-    )} context`,
+    )} ${contextType}`,
   )
 }
 
@@ -93,7 +101,10 @@ const setInEnvelope = async ({ api, context, key, scope, siteInfo, value }) => {
   const contexts = context || ['all']
   const scopes = scope || AVAILABLE_SCOPES
 
-  let values = contexts.map((ctx) => ({ context: ctx, value }))
+  // if the passed context is unknown, it is actually a branch name
+  let values = contexts.map((ctx) =>
+    AVAILABLE_CONTEXTS.includes(ctx) ? { context: ctx, value } : { context: 'branch', context_parameter: ctx, value },
+  )
 
   const existing = envelopeVariables.find((envVar) => envVar.key === key)
 
@@ -144,13 +155,11 @@ const createEnvSetCommand = (program) =>
     .command('env:set')
     .argument('<key>', 'Environment variable key')
     .argument('[value]', 'Value to set to', '')
-    .addOption(
-      new Option('-c, --context <context...>', 'Specify a deploy context (default: all contexts)').choices([
-        'production',
-        'deploy-preview',
-        'branch-deploy',
-        'dev',
-      ]),
+    .option(
+      '-c, --context <context...>',
+      'Specify a deploy context or branch (contexts: "production", "deploy-preview", "branch-deploy", "dev") (default: all contexts)',
+      // spread over an array for variadic options
+      (context, previous = []) => [...previous, normalizeContext(context)],
     )
     .addOption(
       new Option('-s, --scope <scope...>', 'Specify a scope (default: all scopes)').choices([

package/src/commands/env/env-unset.js

@@ -1,9 +1,13 @@
-const { Option } = require('commander')
-
 // @ts-check
-const { chalk, error, log, logJson, translateFromEnvelopeToMongo } = require('../../utils')
-
-const AVAILABLE_CONTEXTS = ['production', 'deploy-preview', 'branch-deploy', 'dev']
+const {
+  AVAILABLE_CONTEXTS,
+  chalk,
+  error,
+  log,
+  logJson,
+  normalizeContext,
+  translateFromEnvelopeToMongo,
+} = require('../../utils')
 
 /**
  * The env:unset command
@@ -44,7 +48,8 @@ const envUnset = async (key, options, command) => {
     return false
   }
 
-  log(`Unset environment variable ${chalk.yellow(key)} in the ${chalk.magenta(context || 'all')} context`)
+  const contextType = AVAILABLE_CONTEXTS.includes(context || 'all') ? 'context' : 'branch'
+  log(`Unset environment variable ${chalk.yellow(key)} in the ${chalk.magenta(context || 'all')} ${contextType}`)
 }
 
 /**
@@ -98,8 +103,10 @@ const unsetInEnvelope = async ({ api, context, key, siteInfo }) => {
   const params = { accountId, siteId, key }
   try {
     if (context) {
-      // if context(s) are passed, delete the matching contexts, and the `all` context
-      const values = variable.values.filter((val) => [...contexts, 'all'].includes(val.context))
+      // if context(s) are passed, delete the matching contexts / branches, and the `all` context
+      const values = variable.values.filter((val) =>
+        [...contexts, 'all'].includes(val.context_parameter || val.context),
+      )
       if (values) {
         await Promise.all(values.map((value) => api.deleteEnvVarValue({ ...params, id: value.id })))
         // if this was the `all` context, we need to create 3 values in the other contexts
@@ -107,7 +114,9 @@ const unsetInEnvelope = async ({ api, context, key, siteInfo }) => {
           const newContexts = AVAILABLE_CONTEXTS.filter((ctx) => !context.includes(ctx))
           const allValue = values[0].value
           await Promise.all(
-            newContexts.map((ctx) => api.setEnvVarValue({ ...params, body: { context: ctx, value: allValue } })),
+            newContexts
+              .filter((ctx) => ctx !== 'all')
+              .map((ctx) => api.setEnvVarValue({ ...params, body: { context: ctx, value: allValue } })),
           )
         }
       }
@@ -134,13 +143,11 @@ const createEnvUnsetCommand = (program) =>
     .command('env:unset')
     .aliases(['env:delete', 'env:remove'])
     .argument('<key>', 'Environment variable key')
-    .addOption(
-      new Option('-c, --context <context...>', 'Specify a deploy context (default: all contexts)').choices([
-        'production',
-        'deploy-preview',
-        'branch-deploy',
-        'dev',
-      ]),
+    .option(
+      '-c, --context <context...>',
+      'Specify a deploy context or branch (contexts: "production", "deploy-preview", "branch-deploy", "dev") (default: all contexts)',
+      // spread over an array for variadic options
+      (context, previous = []) => [...previous, normalizeContext(context)],
     )
     .addExamples([
       'netlify env:unset VAR_NAME # unset in all contexts',

package/src/utils/env/index.js

@@ -1,10 +1,46 @@
+const { error } = require('../command-helpers')
+
+const AVAILABLE_CONTEXTS = ['all', 'production', 'deploy-preview', 'branch-deploy', 'dev']
+const AVAILABLE_SCOPES = ['builds', 'functions', 'runtime', 'post_processing']
+
+/**
+ * @param {string|undefined} context - The deploy context or branch of the environment variable value
+ * @returns {Array<string|undefined>} The normalized context or branch name
+ */
+const normalizeContext = (context) => {
+  if (!context) {
+    return context
+  }
+  const CONTEXT_SYNONYMS = {
+    dp: 'deploy-preview',
+    prod: 'production',
+  }
+  context = context.toLowerCase()
+  if (context in CONTEXT_SYNONYMS) {
+    context = CONTEXT_SYNONYMS[context]
+  }
+  const forbiddenContexts = AVAILABLE_CONTEXTS.map((ctx) => `branch:${ctx}`)
+  if (forbiddenContexts.includes(context)) {
+    error(`The context ${context} includes a reserved keyword and is not allowed`)
+  }
+  context = context.replace(/^branch:/, '')
+  return context
+}
+
 /**
  * Finds a matching environment variable value from a given context
  * @param {Array<object>} values - An array of environment variable values from Envelope
- * @param {enum<dev,branch-deploy,deploy-preview,production>} context - The deploy context of the environment variable value
- * @returns {object<context: enum<dev,branch-deploy,deploy-preview,production>, value: string>} The matching environment variable value object
+ * @param {string} context - The deploy context or branch of the environment variable value
+ * @returns {object<context: enum<dev,branch-deploy,deploy-preview,production,branch>, context_parameter: <string>, value: string>} The matching environment variable value object
  */
-const findValueFromContext = (values, context) => values.find((val) => [context, 'all'].includes(val.context))
+const findValueInValues = (values, context) =>
+  values.find((val) => {
+    if (!AVAILABLE_CONTEXTS.includes(context)) {
+      // the "context" option passed in is actually the name of a branch
+      return val.context === 'all' || val.context_parameter === context
+    }
+    return [context, 'all'].includes(val.context)
+  })
 
 /**
  * Finds environment variables that match a given source
@@ -45,7 +81,7 @@ const fetchEnvelopeItems = async function ({ accountId, api, key, siteId }) {
 
 /**
  * Filters and sorts data from Envelope by a given context and/or scope
- * @param {enum<dev,branch-deploy,deploy-preview,production>} context - The deploy context of the environment variable value
+ * @param {string} context - The deploy context or branch of the environment variable value
  * @param {Array<object>} envelopeItems - An array of environment variables from the Envelope service
  * @param {enum<any,builds,functions,runtime,post_processing>} scope - The scope of the environment variables
  * @param {enum<general,account,addons,ui,configFile>} source - The source of the environment variable
@@ -58,7 +94,8 @@ const fetchEnvelopeItems = async function ({ accountId, api, key, siteId }) {
  *     value: 'bar',
  *   },
  *   BAZ: {
- *     context: 'dev',
+ *     context: 'branch',
+ *     branch: 'staging',
  *     scopes: ['runtime'],
  *     sources: ['account'],
  *     value: 'bang',
@@ -68,18 +105,19 @@ const fetchEnvelopeItems = async function ({ accountId, api, key, siteId }) {
 const formatEnvelopeData = ({ context = 'dev', envelopeItems = [], scope = 'any', source }) =>
   envelopeItems
     // filter by context
-    .filter(({ values }) => Boolean(findValueFromContext(values, context)))
+    .filter(({ values }) => Boolean(findValueInValues(values, context)))
     // filter by scope
     .filter(({ scopes }) => (scope === 'any' ? true : scopes.includes(scope)))
     // sort alphabetically, case insensitive
     .sort((left, right) => (left.key.toLowerCase() < right.key.toLowerCase() ? -1 : 1))
     // format the data
     .reduce((acc, cur) => {
-      const { context: ctx, value } = findValueFromContext(cur.values, context)
+      const { context: ctx, context_parameter: branch, value } = findValueInValues(cur.values, context)
       return {
         ...acc,
         [cur.key]: {
           context: ctx,
+          branch,
           scopes: cur.scopes,
           sources: [source],
           value,
@@ -90,7 +128,7 @@ const formatEnvelopeData = ({ context = 'dev', envelopeItems = [], scope = 'any'
 /**
  * Collects env vars from multiple sources and arranges them in the correct order of precedence
  * @param {object} api - The api singleton object
- * @param {enum<dev,branch-deploy,deploy-preview,production>} context - The deploy context of the environment variable
+ * @param {string} context - The deploy context or branch of the environment variable
  * @param {object} env - The dictionary of environment variables
  * @param {string} key - If present, fetch a single key (case-sensitive)
  * @param {enum<any,builds,functions,runtime,post_processing>} scope - The scope of the environment variables
@@ -130,7 +168,7 @@ const getEnvelopeEnv = async ({ api, context = 'dev', env, key = '', scope = 'an
  * @returns {string} A human-readable, comma-separated list of scopes
  */
 const getHumanReadableScopes = (scopes) => {
-  const AVAILABLE_SCOPES = {
+  const HUMAN_SCOPES = {
     builds: 'Builds',
     functions: 'Functions',
     post_processing: 'Post processing',
@@ -141,11 +179,11 @@ const getHumanReadableScopes = (scopes) => {
     // env vars specified in netlify.toml are present in the `builds` and `post_processing` scope
     return 'Builds, Post processing'
   }
-  if (scopes.length === Object.keys(AVAILABLE_SCOPES).length) {
+  if (scopes.length === Object.keys(HUMAN_SCOPES).length) {
     // shorthand instead of listing every available scope
     return 'All'
   }
-  return scopes.map((scope) => AVAILABLE_SCOPES[scope]).join(', ')
+  return scopes.map((scope) => HUMAN_SCOPES[scope]).join(', ')
 }
 
 /**
@@ -156,7 +194,7 @@ const getHumanReadableScopes = (scopes) => {
 const translateFromMongoToEnvelope = (env = {}) => {
   const envVars = Object.entries(env).map(([key, value]) => ({
     key,
-    scopes: ['builds', 'functions', 'runtime', 'post_processing'],
+    scopes: AVAILABLE_SCOPES,
     values: [
       {
         context: 'all',
@@ -171,14 +209,14 @@ const translateFromMongoToEnvelope = (env = {}) => {
 /**
  * Translates an Envelope env into a Mongo env
  * @param {Array<object>} envVars - The array of Envelope env vars
- * @param {enum<dev,branch-deploy,deploy-preview,production>} context - The deploy context of the environment variable
+ * @param {string} context - The deploy context or branch of the environment variable
  * @returns {object} The env object as compatible with Mongo
  */
 const translateFromEnvelopeToMongo = (envVars = [], context = 'dev') =>
   envVars
     .sort((left, right) => (left.key.toLowerCase() < right.key.toLowerCase() ? -1 : 1))
     .reduce((acc, cur) => {
-      const envVar = cur.values.find((val) => [context, 'all'].includes(val.context))
+      const envVar = cur.values.find((val) => [context, 'all'].includes(val.context_parameter || val.context))
       if (envVar && envVar.value) {
         return {
           ...acc,
@@ -189,11 +227,14 @@ const translateFromEnvelopeToMongo = (envVars = [], context = 'dev') =>
     }, {})
 
 module.exports = {
-  findValueFromContext,
+  AVAILABLE_CONTEXTS,
+  AVAILABLE_SCOPES,
+  findValueInValues,
   filterEnvBySource,
   formatEnvelopeData,
   getEnvelopeEnv,
   getHumanReadableScopes,
+  normalizeContext,
   translateFromEnvelopeToMongo,
   translateFromMongoToEnvelope,
 }