Wrapper around help text #11

yorinasub17 · 2018-10-07T04:49:30Z

This adds the wrapped help text printer to gruntwork-cli and a function to create a new cli.App that takes advantage of it.

Sample output:

Main help

Original

NAME:
   houston - A CLI tool for interacting with Gruntwork Houston that you can use to authenticate to AWS on the CLI and to SSH to your EC2 Instances.

USAGE:
   houston [global options] command [command options] [arguments...]

VERSION:
   snapshot

COMMANDS:
     exec       Execute a command with temporary AWS credentials obtained by logging into Gruntwork Houston
     ssh        Connect to an EC2 instance via SSH with your public key.
     configure  Configure houston CLI options.
     profiles   Show a status of all the defined profiles.
     start      Start the background HTTP server process so it can cache your AWS credentials. Note: the exec command starts the HTTP server process automatically.
     stop       Stop the background HTTP server process.
     status     Show the status of the background HTTP server process.
     help, h    Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --help, -h     show help
   --version, -v  print the version

New:

Usage: houston [--help] [--version] command [options] [args]

A CLI tool for interacting with Gruntwork Houston that you can use to
authenticate to AWS on the CLI and to SSH to your EC2 Instances.

Commands:

   exec       Execute a command with temporary AWS credentials obtained by
              logging into Gruntwork Houston
   ssh        Connect to an EC2 instance via SSH with your public key.
   configure  Configure houston CLI options.
   profiles   Show a status of all the defined profiles.
   start      Start the background HTTP server process so it can cache your
              AWS credentials. Note: the exec command starts the HTTP server
              process automatically.
   stop       Stop the background HTTP server process.
   status     Show the status of the background HTTP server process.
   help, h    Shows a list of commands or help for one command

Command help

Original:

NAME:
   houston exec - Execute a command with temporary AWS credentials obtained by logging into Gruntwork Houston

USAGE:
   houston exec [OPTIONS] <profile> -- <command>

DESCRIPTION:
   The exec command makes it easier to use CLI tools that need AWS credentials, such as aws, terraform, and packer. Here's how it works:

   1. The first time you run this command for a <profile>, it will open your web browser and have you login to your Identity Provider (i.e., Google, ADFS, Okta).
   2. After login, the Identity Provider will redirect you to the Gruntwork Houston web console, where you will pick the AWS IAM Role you want to use.
   3. Gruntwork Houston will fetch temporary AWS credentials for this IAM Role and POST them back to houston CLI running on your computer.
   4. The houston CLI will set those credentials as the appropriate environment variables and execute <command>.
   5. The houston CLI will cache those credentials in memory, so all subsequent commands will execute without going through the login flow (until those credentials expire).

EXAMPLES:

   houston exec dev -- aws s3 ls
   houston exec prod -- terraform apply
   houston exec stage -- packer build server.json

OPTIONS:
   --config value, -c value  The configuration file for houston (default: "/Users/yoriy/.houston/houston.yml")
   --port value              The TCP port the http server is running on (default: 41170)

New:

Usage: houston exec [options] <profile> -- <command>

The exec command makes it easier to use CLI tools that need AWS credentials,
such as aws, terraform, and packer. Here's how it works:

  1. The first time you run this command for a <profile>, it will open your web
  browser and have you login to your Identity Provider (i.e., Google, ADFS,
  Okta).
  2. After login, the Identity Provider will redirect you to the Gruntwork
  Houston web console, where you will pick the AWS IAM Role you want to use.
  3. Gruntwork Houston will fetch temporary AWS credentials for this IAM Role
  and POST them back to houston CLI running on your computer.
  4. The houston CLI will set those credentials as the appropriate environment
  variables and execute <command>.
  5. The houston CLI will cache those credentials in memory, so all subsequent
  commands will execute without going through the login flow (until those
  credentials expire).

Examples:

   houston exec dev -- aws s3 ls
   houston exec prod -- terraform apply
   houston exec stage -- packer build server.json

Options:

   --config value, -c value  The configuration file for houston (default:
                             "/Users/yoriy/.houston/houston.yml")
   --port value              The TCP port the http server is running on (default:
                             41170)

brikis98

Very nice! 👍

brikis98 · 2018-10-07T12:39:20Z

entrypoint/help_utils.go

+
+const HELP_TEXT_LINE_WIDTH = 80
+
+const CLI_APP_HELP_TEMPLATE = `Usage: {{.HelpName}} {{range $index, $option := .VisibleFlags}}[{{$option.GetName | PrefixedFirstFlagName}}] {{end}}{{if .Commands}}command [options]{{end}} {{if .ArgsUsage}}{{.ArgsUsage}}{{else}}[args]{{end}}{{if .Description}}


What is different about these templates than the default urfave ones? May be worth mentioning in a comment.

brikis98 · 2018-10-07T12:40:45Z

entrypoint/help_utils.go

+//    text := "one two three"
+//    out := SplitKeepDelimiter(re, text)
+//    out == ["one ", "two ", "three"]
+func SplitKeepDelimiter(re *regexp.Regexp, str string) (out []string) {


Why declare out in the return value?

Also, does SplitAfterN not do the same thing?

Why declare out in the return value?

No strong reason, just that I noticed a few places in sample go code preferring to declare in return value if you are just going to var out. Is it generally preferable to declare return vars in the function?

Also, does SplitAfterN not do the same thing?

strings.SplitAfter does do the same thing, but it requires a specific substring. Here, we need to split on regex because the separator is volatile (at least one whitespace char) and so there is no exact match string that can be used.

Is it generally preferable to declare return vars in the function?

I don't know what "idiomatic" Go code does (TBH, I'm not sure it's mature enough of a language for that to be well defined), but I find it easier to read and reason about the code if all variable declarations are in the body of the method, rather than some there and some in the return value.

strings.SplitAfter does do the same thing, but it requires a specific substring. Here, we need to split on regex because the separator is volatile (at least one whitespace char) and so there is no exact match string that can be used.

Ah, gotcha.

Renamed this func to RegexpSplitAfter to make it clearer that this is the regex version of strings.SplitAfter.

brikis98 · 2018-10-07T12:48:29Z

entrypoint/help_utils.go

+}
+
+// Wrap text to line width, while preserving any indentation
+func TabAwareWrapText(text string, lineWidth int, tab string) string {


Add some examples to the comments to provide context on what this function is doing

brikis98 · 2018-10-07T12:50:35Z

entrypoint/entrypoint.go

+func NewApp() *cli.App {
+	cli.HelpPrinter = WrappedHelpPrinter
+	cli.AppHelpTemplate = CLI_APP_HELP_TEMPLATE
+	cli.CommandHelpTemplate = CLI_COMMAND_HELP_TEMPLATE


Hm, in some of our apps, we overwrite these help templates. E.g., Terragrunt: https://github.com/gruntwork-io/terragrunt/blob/master/cli/cli_app.go#L151 (note, we have not yet migrated Terragrunt to use gruntwork-cli under the hood, so it's just an example). Will the wrapped help text work for these apps?

That should work. Actually, these are global variables in urfave/cli that are read in as part of the help command, so a later overwrites will take precedence. You just have to override after the NewApp call, as opposed to before:

cli := entrypoint.NewAll() cli.AppHelpTemplate = HELP_TEMPLATE

That said, it doesn't handle the elastic tabstop output table so for that example the output is not so nice (pasted below). Once I switched the template to raw tabs, it looked better so may not be worth generalizing.

No tabs:

DESCRIPTION: terragrunt - Terragrunt is a thin wrapper for Terraform that provides extra tools for working with multiple Terraform modules, remote state, and locking. For documentation, see https://github.com/gruntwork-io/terragrunt/. USAGE: terragrunt <COMMAND> COMMANDS: plan-all Display the plans of a 'stack' by running 'terragrunt plan' in each subfolder apply-all Apply a 'stack' by running 'terragrunt apply' in each subfolder output-all Display the outputs of a 'stack' by running 'terragrunt output' in each subfolder destroy-all Destroy a 'stack' by running 'terragrunt destroy' in each subfolder validate-all Validate 'stack' by running 'terragrunt validate' in each subfolder * Terragrunt forwards all other commands directly to Terraform GLOBAL OPTIONS: terragrunt-config Path to the Terragrunt config file. Default is terraform.tfvars. terragrunt-tfpath Path to the Terraform binary. Default is terraform (on PATH). terragrunt-no-auto-init Don't automatically run 'terraform init' during other terragrunt commands. You must run 'terragrunt init' manually. terragrunt-no-auto-retry Don't automatically re-run command in case of transient errors. terragrunt-non-interactive Assume "yes" for all prompts. terragrunt-working-dir The path to the Terraform templates. Default is current directory. terragrunt-download-dir The path where to download Terraform code. Default is .terragrunt-cache in the working directory. terragrunt-source Download Terraform configurations from the specified source into a temporary folder, and run Terraform in that temporary folder. terragrunt-source-update Delete the contents of the temporary folder to clear out any old, cached source code before downloading new source code into it. terragrunt-iam-role Assume the specified IAM role before executing Terraform. Can also be set via the TERRAGRUNT_IAM_ROLE environment variable. terragrunt-ignore-dependency-errors *-all commands continue processing components even if a dependency fails. terragrunt-exclude-dir Unix-style glob of directories to exclude when running *-all commands VERSION: AUTHOR(S): Gruntwork <www.gruntwork.io>

with tabs

DESCRIPTION: [65/7627] terragrunt - Terragrunt is a thin wrapper for Terraform that provides extra tools for working with multiple Terraform modules, remote state, and locking. For documentation, see https://github.com/gruntwork-io/terragrunt/. USAGE: terragrunt <COMMAND> COMMANDS: plan-all Display the plans of a 'stack' by running 'terragrunt plan' in each subfolder apply-all Apply a 'stack' by running 'terragrunt apply' in each subfolder output-all Display the outputs of a 'stack' by running 'terragrunt output' in each subfolder destroy-all Destroy a 'stack' by running 'terragrunt destroy' in each subfolder validate-all Validate 'stack' by running 'terragrunt validate' in each subfolder * Terragrunt forwards all other commands directly to Terraform GLOBAL OPTIONS: terragrunt-config Path to the Terragrunt config file. Default is terraform.tfvars. terragrunt-tfpath Path to the Terraform binary. Default is terraform (on PATH). terragrunt-no-auto-init Don't automatically run 'terraform init' during other terragrunt commands. You must run 'terragrunt init' manually. terragrunt-no-auto-retry Don't automatically re-run command in case of transient errors. terragrunt-non-interactive Assume "yes" for all prompts. terragrunt-working-dir The path to the Terraform templates. Default is current directory. terragrunt-download-dir The path where to download Terraform code. Default is .terragrunt-cache in the working directory. terragrunt-source Download Terraform configurations from the specified source into a temporary folder, and run Terraform in that temporary folder. terragrunt-source-update Delete the contents of the temporary folder to clear out any old, cached source code before downloading new source code into it. terragrunt-iam-role Assume the specified IAM role before executing Terraform. Can also be set via the TERRAGRUNT_IAM_ROLE environment variable. terragrunt-ignore-dependency-errors *-all commands continue processing components even if a dependency fails. terragrunt-exclude-dir Unix-style glob of directories to exclude when running *-all commands VERSION: AUTHOR(S): Gruntwork <www.gruntwork.io>

brikis98 · 2018-10-07T13:08:33Z

entrypoint/help_utils.go

+	//       char.
+	tabLength := 8
+	currentLineLength := TabAwareStringLength(wrapped, tabLength)
+	for _, word := range words[1:] {


In general, this sort of code can be easier to read and maintain if written recursively:

func TabAwareWrapText(words []string, lineWidth int, tab string, outputLinesSoFar []string): string { if len(words) == 0 { return strings.Join(outputLinesSoFar, "\n") } head = words[0] tail = words[1:] if lineLengthExceeded(outputLinesSoFar, head, lineWidth) { return TabAwareWrapText(tail, lineWidth, tab, addWordOnNewLine(outputLinesSoFar, head)) } else { return TabAwareWrapText(tail, lineWidth, tab, addWordToExistingLine(outputLinesSoFar, head)) } }

Not sure it's worth refactoring in this case, as (a) Go isn't exactly a functional programming language and (b) I'm not sure it does tail call optimization, which may be a problem with long strings.

Agree. I was going to write recursively, but then I learned that the maintainers of Go isn't too keen on supporting tail call optimization so opted not to. Sad :(

Gah. Stupid Go.

brikis98 · 2018-10-07T13:10:02Z

entrypoint/help_utils_test.go

+	}
+}
+
+var wrapTextTests = []struct {


Probably a good idea to add some real-world help text (with many lines) as tests, such as the ones in the PR description.

yorinasub17 · 2018-10-07T15:31:41Z

UPDATE:

Comments describing difference of these templates vs the default ones
Add a text that came out of urfave/cli into unit test
No more return type declared variables
TabAwareWrapText => IndentAwareWrapText (the latter is a more accurate name)
Comment with example of what IndentAwareWrapText is doing
Make linewidth a non const so that it can be overridden.
SplitKeepDelimiter => RegexpSplitAfter

TODO:

Unit test for the actual printer (the main func) checking for
- Using the new templates as opposed to the default
- Overriding linewidth
- Real world example

yorinasub17 · 2018-10-08T21:54:05Z

Ok added some unit tests with real world examples for the overall printers. @brikis98 Ready for final review before merge!

brikis98

This looks great. Nice work!

brikis98 · 2018-10-08T21:56:14Z

README.md

-      app := cli.NewApp()
+      // Create a new CLI app. This will return a urfave/cli App with some
+      // common initialization.
+      app := entrypoint.NewApp()


Make sure to call out this change in the release notes!

Just to clarify, you mean https://github.com/gruntwork-io/gruntwork-cli/releases and newsletter and not a special file in here that tracks changes? Also, this should be a minor release (0.2.0) because it is a backwards compatible feature release right?

Yes on all counts!

brikis98 · 2018-10-08T21:56:42Z

entrypoint/entrypoint_test.go

+
+`
+
+const EXPECTED_EXEC_CMD_HELP_OUT_120_LINES = `Usage: houston exec [options] <profile> -- <command>


Nice tests 👍

yorinasub17 · 2018-10-08T22:23:48Z

Ok merging and doing a release! Thanks!

Wrapper around help text

856132f

yorinasub17 force-pushed the yori-help-utils branch from ff5026a to 856132f Compare October 7, 2018 04:51

brikis98 reviewed Oct 7, 2018

View reviewed changes

yorinasub17 force-pushed the yori-help-utils branch from 77fa72f to cbbcb92 Compare October 7, 2018 15:26

Address comments

9e4c64a

yorinasub17 force-pushed the yori-help-utils branch from cbbcb92 to 9e4c64a Compare October 7, 2018 15:34

Integration testing for printers

e77f227

brikis98 approved these changes Oct 8, 2018

View reviewed changes

yorinasub17 merged commit a972613 into master Oct 8, 2018

yorinasub17 deleted the yori-help-utils branch October 8, 2018 22:23


		const HELP_TEXT_LINE_WIDTH = 80

		const CLI_APP_HELP_TEMPLATE = `Usage: {{.HelpName}} {{range $index, $option := .VisibleFlags}}[{{$option.GetName \| PrefixedFirstFlagName}}] {{end}}{{if .Commands}}command [options]{{end}} {{if .ArgsUsage}}{{.ArgsUsage}}{{else}}[args]{{end}}{{if .Description}}


		`

		const EXPECTED_EXEC_CMD_HELP_OUT_120_LINES = `Usage: houston exec [options] <profile> -- <command>

Wrapper around help text #11

Wrapper around help text #11

Uh oh!

Conversation

yorinasub17 commented Oct 7, 2018

Sample output:

Main help

Command help

Uh oh!

brikis98 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yorinasub17 Oct 7, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

No tabs:

with tabs

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yorinasub17 commented Oct 7, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yorinasub17 commented Oct 8, 2018

Uh oh!

brikis98 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yorinasub17 commented Oct 8, 2018

Uh oh!

Uh oh!

yorinasub17 Oct 7, 2018 •

edited

Loading

yorinasub17 commented Oct 7, 2018 •

edited

Loading