update docs, change doc generation script to include sub commands

Author: chris-olszewski

DOCS.md

@@ -52,7 +52,7 @@ Add a few lines to your `package.json`. Your [account id](https://console.aws.am
 
 ### Environments
 
-Environments for a shep project are defined by the aliases on the functions associated with a project. Environments are created through `shep deploy --env new_env` and managed by using the `shep config` commands. Shep takes a strong stance against having different environments for different functions. If shep detects that some of your functions have different aliases, it will immediately error until you remedy the issue. Most issues can be automatically fixed by using `shep config sync`, the only issues this can't solve are conflicting environment variable values. Conflicting value issues can be solved by using `shep config set my_env CONFLICT_VARIABLE=value`.
+Environments for a shep project are defined by the aliases on the functions associated with a project. Environments are created through `shep deploy --env new_env` and managed by using the `shep config` commands. Shep takes a strong stance against having different environments for different functions within a project. If you attempt a command which requires the listing of environments and there is a mismatch detected, then shep will throw a `EnvironmentMistmach` error until you remedy the issue. Most issues can be automatically fixed by using `shep config sync`, the only issues this can't solve are conflicting environment variable values. Conflicting value issues can be solved by using `shep config set my_env CONFLICT_VARIABLE=value`.
 
 ### Custom Builds Commands
 

README.md

@@ -1,23 +1,36 @@
-const shep = require('./lib/index')
 const { execSync } = require('child_process')
+const { readdirSync, statSync } = require('fs')
 
 console.log(`### \`shep\``)
 console.log('```')
 console.log(execSync(`./cli.js --help`).toString().replace(/cli\.js/, 'shep').trim())
 console.log('```')
 
-for (var cmd in shep) {
-  if (cmd !== 'version') {
-    let help = execSync(`./cli.js ${camelCaseToSpace(cmd)} --help`).toString().replace(/cli\.js/, 'shep').trim()
-    console.log(`#### \`shep ${camelCaseToSpace(cmd)}\``)
-    console.log('```')
-    console.log(help)
-    console.log('```')
-  }
+const commandDir = './src/commands'
+const mainCommands = readdirSync(commandDir)
+const subCommands = mainCommands
+      .filter(isDir)
+      .map(findSubCommands)
+      .reduce(flatten)
+const allCommands = mainCommands.concat(subCommands).map((c) => c.replace(/\.js/g, '')).sort()
+
+allCommands.forEach((command) => {
+  let help = execSync(`./cli.js ${command} --help`).toString().replace(/cli\.js/, 'shep').trim()
+  console.log(`#### \`shep ${command}\``)
+  console.log('```')
+  console.log(help)
+  console.log('```')
+})
+
+function isDir (path) {
+  return statSync(`${commandDir}/${path}`).isDirectory()
+}
+
+function findSubCommands (path) {
+  return readdirSync(`${commandDir}/${path}`)
+  .map((c) => `${path} ${c}`)
 }
 
-function camelCaseToSpace (str) {
-  return str.split('')
-    .map(x => /[A-Z]/.test(x) ? ` ${x.toLowerCase()}` : x)
-    .reduce((sum, cur) => sum + cur, '')
+function flatten (acc, arr) {
+  return acc.concat(arr)
 }

docs.js

@@ -82,4 +82,4 @@ json, and it should live inside the `/environments` directory
 
 ## Migrating from shep 3.X to shep 4.0
 
-- Shep 4.0 now handles environment variables in AWS. See the docs for `shep config` to add, remove, list, and sync environment variables for your functions.
+- Shep 4.0 now handles environment variables in the configuration of AWS Lambda Functions. If you have no undeployed changes in your `/environments` directory, then you should be able to safely delete the directory and use your exisiting project with shep `4.0.0`. See the docs for `shep config` to add, remove, list, and sync environment variables for your functions.

migration.md

@@ -3,14 +3,15 @@ import configDump from '../../config-dump'
 import * as load from '../../util/load'
 import merge from 'lodash.merge'
 
-export const command = 'dump [env]'
+export const command = 'dump'
 export const desc = 'Prints all common environmental variables and differences'
 export function builder (yargs) {
   return yargs
   .pkgConf('shep', process.cwd())
   .boolean('json')
+  .describe('env', 'Specifies which environment to dump, if not provided an interactive menu will display the options')
   .describe('json', 'Formats output as JSON')
-  .example('shep config dump beta', 'Print to console all environment variables of environment `beta` in JSON format')
+  .example('shep config dump --env beta', 'Print to console all environment variables of environment `beta` in JSON format')
 }
 
 export async function handler (opts) {

src/commands/config/dump.js

@@ -3,12 +3,13 @@ import configList from '../../config-list'
 import * as load from '../../util/load'
 import merge from 'lodash.merge'
 
-export const command = 'list [env] [function]'
+export const command = 'list [function]'
 export const desc = 'List environment variables on AWS for an alias'
 export function builder (yargs) {
   return yargs
   .pkgConf('shep', process.cwd())
-  .example('shep config beta foo', 'List environment variables for function "foo" beta alias')
+  .describe('env', 'Specifies which environment. If not provided an interactive menu will display the options')
+  .example('shep config list --env beta foo', 'List environment variables for function "foo" beta alias')
 }
 
 export async function handler (opts) {

src/commands/config/list.js

@@ -3,12 +3,13 @@ import configRemove from '../../config-remove'
 import * as load from '../../util/load'
 import merge from 'lodash.merge'
 
-export const command = 'remove <env> <vars...>'
+export const command = 'remove <vars...>'
 export const desc = 'Remove environment variables for alias on AWS'
 export function builder (yargs) {
   return yargs
   .pkgConf('shep', process.cwd())
-  .example('shep config remove beta NEW_VARIABLE', 'Removes NEW_VARIABLE from all functions with beta alias')
+  .describe('env', 'Specifies which environment to remove variables from. If not provided an interactive menu will display the options')
+  .example('shep config remove --env beta NEW_VARIABLE', 'Removes NEW_VARIABLE from all functions with beta alias')
 }
 
 export async function handler (opts) {
@@ -27,9 +28,7 @@ export async function handler (opts) {
     inquirer.prompt(questions.filter((q) => !opts[q.name]))
     .then((inputs) => merge({}, inputs, opts))
     .then(configRemove)
-  } else {
-    if (!opts.env) { console.log('no API found, cannot load available aliases') }
-
-    configRemove(opts)
+  } else if (!opts.env) {
+    throw new Error('Unable to load environments, please provide a specific one via the --env flag')
   }
 }

src/commands/config/remove.js

@@ -3,12 +3,12 @@ import configSet from '../../config-set'
 import * as load from '../../util/load'
 import merge from 'lodash.merge'
 
-export const command = 'set <env> <vars...>'
+export const command = 'set <vars...>'
 export const desc = 'Set environment variables for alias on AWS'
 export function builder (yargs) {
   return yargs
   .pkgConf('shep', process.cwd())
-  .example('shep config set beta FOO=bar', 'Set environment variable FOO with value BAR for alias beta')
+  .example('shep config set --env beta FOO=bar', 'Set environment variable FOO with value BAR for alias beta')
 }
 
 export async function handler (opts) {

src/commands/config/set.js

@@ -3,19 +3,19 @@ import logs from '../logs'
 import * as load from '../util/load'
 import merge from 'lodash.merge'
 
-export const command = 'logs [stage] [name]'
+export const command = 'logs [name]'
 export const desc = 'Streams logs from the specified version of a function'
 export function builder (yargs) {
   return yargs
   .pkgConf('shep', process.cwd())
-  .describe('stage', 'Name of stage to use')
+  .describe('env', 'Specifies which environment to use. If not provided an interactive menu will display the options.')
   .describe('name', 'Name of function to use')
   .describe('region', 'Name of region to use, uses region in `package.json` if not given')
   .boolean('stream')
   .default('stream', true)
   .describe('stream', 'Stream logs')
   .example('shep logs', 'Launch an interactive CLI')
-  .example('shep logs production foo', 'Shows logs for the `foo` function in the production environment')
+  .example('shep logs --env production foo', 'Shows logs for the `foo` function in the production environment')
 }
 
 export async function handler (opts) {
@@ -25,8 +25,8 @@ export async function handler (opts) {
   if (envs && envs.length > 0) {
     questions = [
       {
-        name: 'stage',
-        message: 'Stage',
+        name: 'env',
+        message: 'Environment',
         type: 'list',
         choices: () => envs
       },
@@ -37,17 +37,8 @@ export async function handler (opts) {
         choices: () => load.funcs()
       }
     ]
-  } else {
-    if (!opts.env) { console.log('no API found, cannot load available aliases') }
-
-    questions = [
-      {
-        name: 'name',
-        message: 'Function',
-        type: 'list',
-        choices: () => load.funcs()
-      }
-    ]
+  } else if (!opts.env) {
+    throw new Error('Unable to load environments, please provide a specific one via the --env flag')
   }
 
   inquirer.prompt(questions.filter((q) => !opts[q.name]))

src/commands/logs.js

@@ -8,7 +8,7 @@ import genName from '../util/generate-name'
 
 export default function (opts) {
   const functionName = genName(opts.name).fullName
-  const aliasName = opts.stage
+  const aliasName = opts.env
   const stream = opts.stream
   const region = opts.region || pkg().shep.region
 

src/logs/index.js

@@ -20,7 +20,9 @@ export async function envs () {
           .concat(acc.filter((alias) => aliasSet.indexOf(alias) === -1))
 
     if (missingAliases.length !== 0) {
-      throw new Error('Mismatched aliases found, please run `shep config sync` to ensure all functions have the same environment')
+      const err = new Error('Mismatched aliases found, please run `shep config sync` to ensure all functions have the same environment')
+      err.name = 'EnvironmentMistmach'
+      throw err
     }
 
     return acc

src/util/load.js

@@ -52,7 +52,7 @@ test([allFlags, noFlags], 'doctor', doctorParser, doctorArgs)
 td.replace('../../src/logs')
 const logsParser = yargs.command(require('../../src/commands/logs'))
 const logsArgs = {
-  stage: 'development',
+  env: 'development',
   name: 'myfunction',
   region: 'mordor',
   stream: 'true'
@@ -129,7 +129,7 @@ td.replace('../../src/config-remove')
 const removeParser = yargs.command(require('../../src/commands/config/remove'))
 
 test('config remove command', (t) => {
-  removeParser.parse('remove development MY_KEY OTHER_KEY', (err, argv, output) => {
+  removeParser.parse('remove --env development MY_KEY OTHER_KEY', (err, argv, output) => {
     err ? t.fail(err) : t.pass()
   })
 })
@@ -138,7 +138,7 @@ td.replace('../../src/config-set')
 const setParser = yargs.command(require('../../src/commands/config/set'))
 
 test('config set command', (t) => {
-  setParser.parse('set development FOO=bar', (err, argv, output) => {
+  setParser.parse('set --env development FOO=bar', (err, argv, output) => {
     err ? t.fail(err) : t.pass()
   })
 })