rbcli 0.3.3 → 0.4.0

data/docs/whoami/index.xml

@@ -1,12 +0,0 @@
-<?xml version="1.0" encoding="utf-8" standalone="yes"?>
-<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
-  <channel>
-    <title>My Letter To You on RBCli Documentation</title>
-    <link>https://akhoury6.github.io/rbcli/whoami/</link>
-    <description>Recent content in My Letter To You on RBCli Documentation</description>
-    <generator>Hugo 0.125.1</generator>
-    <language>en-us</language>
-    <lastBuildDate></lastBuildDate>
-    <atom:link href="https://akhoury6.github.io/rbcli/whoami/index.xml" rel="self" type="application/rss+xml" />
-  </channel>
-</rss>

data/docs-src/archetypes/default.md

@@ -1,6 +0,0 @@
----
-title: "{{ replace .Name "-" " " | title }}"
-date: {{ .Date }}
-draft: true
----
-

data/docs-src/config.toml

@@ -1,37 +0,0 @@
-## Theme Documentation: https://learn.netlify.com/en/
-
-baseURL = "https://akhoury6.github.io/rbcli/"
-languageCode = "en-us"
-title = "RBCli Documentation"
-theme = "hugo-theme-learn"
-
-[params]
-# Can be "red", "blue", or "green", or comment out for purple
-themeVariant = "blue"
-
-[[menu.shortcuts]]
-name = "<i class='fab fa-github'></i> Github repo"
-identifier = "github"
-url = "https://github.com/akhoury6/rbcli"
-weight = 10
-
-#[[menu.shortcuts]]
-#name = "<i class='fas fa-camera'></i> Showcases"
-#url = "/showcase"
-#weight = 11
-
-[[menu.shortcuts]]
-name = "<i class='far fa-gem'></i> Rubygems"
-identifier = "rubygems"
-url = "https://rubygems.org/gems/rbcli"
-weight = 20
-
-#[[menu.shortcuts]]
-#name = "<i class='fas fa-bullhorn'></i> Credits"
-#url = "/credits"
-#weight = 30
-
-
-# For search functionality
-[outputs]
-home = [ "HTML", "RSS", "JSON"]

data/docs-src/content/_index.md

@@ -1,40 +0,0 @@
-# This is RBCli
-
-
-As technologists today, we work with the command line a lot. We script a lot. We write tools to share with each other to make our lives easier. We even write applications to make up for missing features in the 3rd party software that we buy. Unfortunately, when writing CLI tools, this process has typically been very painful. We've been working with low-level frameworks for decades; frameworks like `getopt` (1980) and `curses` (1977). They fit their purpose well; they were both computationally lightweight for the computers of the day, and they gave engineers full control and flexibility when it came to how things were built. Over the years, we've used them to settle on several design patterns that we know work well. Patterns as to what a CLI command looks like, what a config file looks like, what remote execution looks like, and even how to use locks (mutexes, semaphores, etc) to control application flow and data atomicity. Yet we're stuck writing the same low-level code anytime we want to write our tooling. Not anymore.
-
-Enter RBCli. RBCli is a framework to quickly develop advanced command-line tools in Ruby. It has been written from the ground up with the needs of the modern technologist in mind, designed to make advanced CLI tool development as painless as possible. In RBCli, low-level code has been wrapped and/or replaced with higher-level methods. Much of the functionality has even been reduced to single methods: for example, it takes just one declaration to define, load, and generate a user's config file at the appropriate times. Many other features are automated and require no work by the engineer. These make RBCli a fundamental re-thining of how we develop CLI tools, enabling the rapid development of applications for everyone from hobbyists to enterprises.
-
-
-Some of its key features include:
-
-* __Simple DSL Interface__: To cut down on the amount of code that needs to be written, RBCli has a DSL that is designed to cut to the chase. This makes the work a lot less tedious.
-  
-* __Multiple Levels of Parameters and Arguments__: Forget about writing parsers for command-line options, or about having to differentiate between parameters and arguments. All of that work is taken care of.
-
-* __Config File Generation__: Easily piece together a default configuration even with declarations in different parts of the code. Then the user can generate their own configuration, and it gets stored in whatever location you'd like.
-
-* __Multiple Hooks and Entry Points__: Define commands, pre-execution hooks, post-execution hooks, and first_run hooks to quickly and easily customize the flow of your application code.
-
-* __Logging__: Keep track of all instances of your tool through logging. Logs can go to STDOUT, STDERR, or a given file, making them compatible with log aggregators such as Splunk, Logstash, and many others.
-
-* __Local State Storage__: Easily manage a set of data that persists between runs. You get access to a hash that is automatically kept in-sync with a file on disk.
-
-* __Remote State__: It works just like Local State Storage, but store the data on a remote server! It can be used in tandem with Local State Storage or on its own. Currently supports AWS DyanmoDB.  
-
-* __State Locking and Sharing__: Share remote state safely between users with built-in locking! When enabled, it makes sure that only one user is accessing the data at any given time.
-
-* __Automatic Update Notifications__: Just provide the gem name or git repo, and RBCli will take care of notifying users!
-
-* __External Script Wrapping__: High-level wrapping for Bash scripts, or any other applcication you'd like to wrap into a command.
-
-* __Project Structure and Generators__: Create a well-defined project directory structure which organizes your code and allows you to package and distribute your application as a Gem. Generators can also help speed up the process of creating new commands, scripts, and hooks!
-
-* __Remote Execution__: Automatically execute commands on remote machines via SSH
-
-* __Interactive Commands__: Automatically prompt users for paramter values if not given on the command line. This pattern allows for easy user interaction while still allowing scripting without the use of _expect_.
-
-If you're just getting started with RBCli, take a look at the [Tutorial][tutorial]. Or take a look at the [Advanced] menu to look through RBCli's additional featureset.
-
-[tutorial]: {{< ref "tutorial" >}}
-[advanced]: {{< ref "advanced" >}}

data/docs-src/content/advanced/_index.md

@@ -1,11 +0,0 @@
-+++
-title = "Advanced"
-date = 2019-06-20T15:08:08-04:00
-weight = 20
-chapter = true
-#pre = "<b>X. </b>"
-+++
-
-# Advanced Features
-
-This section describes the more advanced feature of RBCli. Mastering them will make you a CLI tool Ninja.

data/docs-src/content/advanced/automatic_updates.md

@@ -1,46 +0,0 @@
----
-title: "Automatic Updates"
-date: 2019-06-20T15:07:21-04:00
-draft: false
----
-
-RBCli can automatically notify users when an update is available. If `force_update` is set (see below), RBCli can halt execution until the user updates their application.
-
-Two sources are currently supported: __Github__ (including Enterprise) and __RubyGems__.
-
-## GitHub Update Check
-
-The GitHub update check works best when paired with GitHub's best practices on releases, where new releases are tagged on master with the format __vX.X.X__. See [Github's release documentation][github_release_documentation] to learn more.
-
-RBCli will check your github repo's tags and compare that version number with one specified in your application at `config/version.rb`.
-
-```ruby
-autoupdate github_repo: '<your_user>/<your_repo>', access_token: nil, enterprise_hostname: nil, force_update: false, message: nil
-``` 
-The `github_repo` should point to the repo using the `user/repo` syntax. 
-
-The `access_token` can be overridden by the user via their config file, so it can be left as `nil` if you enable [Userspace Configuration][userspace_configuration]. The token is not needed at all if using a public repo. For instructions on generating a new access token, see [here][github_generate_token]. 
-
-The `enterprise_hostname` setting allows you to point RBCli at a local GitHub Enterprise server.
-
-Setting `force_update: true` will halt execution if an update is available, forcing the user to update.
-
-The `message` parameter allows setting a custom message that will be displayed when an update is available. Leaving it as `nil` will use the default message provided by RBCli.
-
-## Rubygems.org Update Check
-
-The Rubygems update check will check if there is a new published version of the gem on Rubygems.org. The latest published version is compared to the version number you configured RBCli with.
-
-```ruby
-autoupdate gem: '<your_gem>', force_update: false, message: nil
-```
-
-The `gem` parameter should simply state the name of the gem.
- 
-Setting `force_update: true` will halt execution if an update is available, forcing the user to update.
-
-The `message` parameter allows setting a custom message that will be displayed when an update is available. Leaving it as `nil` will use the default message provided by RBCli.
-
-[github_release_documentation]: https://help.github.com/articles/creating-releases/
-[userspace_configuration]: {{< ref "advanced/user_config_files" >}}
-[github_generate_token]: https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/

data/docs-src/content/advanced/command_types.md

@@ -1,148 +0,0 @@
----
-title: "Command Types"
-date: 2019-06-20T15:07:21-04:00
-draft: false
----
-
-RBCli has three different command types:
-
-* __Standard Commands__ (Ruby-based)
-* __Scripted Commands__ (Ruby+Bash based)
-* __External Commands__ (Wrapping a 3rd party application)
-
-
-This document is provided to be a reference. If you would like an in-depth tutorial, please see [Your First Command][your_first_command].
-
-
-## General Command Structure
-
-Commands in RBCli are created by subclassing `Rbcli::Command`. All commands share a certain common structure:
-
-```ruby
-class List < Rbcli::Command                                                           # Declare a new command by subclassing Rbcli::Command
-	description 'TODO: Description goes here'                                           # (Required) Short description for the global help
-	usage <<-EOF
-TODO: Usage text goes here
-EOF                                                                                   # (Required) Long description for the command-specific help
-	parameter :force, 'Force testing', type: :boolean, default: false, required: false  # (Optional, Multiple) Add a command-specific CLI parameter. Can be called multiple times
-
-	config_default :myopt2, description: 'My Option #2', default: 'Default Value Here'  # (Optional, Multiple) Specify an individual configuration parameter and set a default value. These will also be included in generated user config.
-                                                                                      # Alternatively, you can simply create a yaml file in the `default_user_configs` directory in your project that specifies the default values of all options
-end
-```
-
-* `description`
-	* A short description of the command, which will appear in the top-level help (when the user runs `mytool -h`).
-* `usage`
-	* A description of how the command is meant to be used. This description can be as long as you want, and can be as in-depth as you'd like. It will show up as a long, multi-line description when the user runs the command-sepcific help (`mytool list -h`).
-* `parameter`
-	* Command-line tags that the user can enter that are specific to only this command. We will get into these in the next section on [Options, Parameters, and Arguments][parameters_documentation]
-* `config_default`
-	* This sets a single item in the config file that will be made available to the user. More information can be found in the documentation on [User Config Files][user_config_documentation]
-
-## Standard Commands
-
-Standard commands are written as ruby code. To create a standard command called `list`, run:
-
-```bash
-rbcli command --name=list
-#or
-rbcli command -n list
-```
-
-A standard command can be identified by the presence of an `action` block in the definition:
-
-```ruby
-class List < Rbcli::Command
-	action do |params, args, global_opts, config|
-		# Code goes here
-	end
-end
-```
-
-Your application's __parameters__, __arguments__, __options__, and __config__ are available in the variables passed into the block. For more information on these, see [Options, Parameters, and Arguments][parameters_documentation].
-
-
-## Scripted Commands
-
-Scripted commands are part Ruby, part Bash scripting. They are a good choice to use if you feel something might be easier or more performant to script with Bash, or if you already have a Bash script you'd like to use in your project. You can create one with:
-
-```bash
-rbcli script -n list
-```
-
-This will create two files in your RBCli project: a Ruby file with the common command declaration (see [General Command Structure](#general-command-structure)), and a bash script in the folder `application/commands/scripts/`.
-
-You can tell a command is a script by the line:
-
-```ruby
-class List < Rbcli::Command
-	script
-end
-```
-
-RBCli will pass along your applications config and CLI parameters through JSON environment variables. To make things easy, a Bash library is provided that makes retrieving and parsing these variables easy. It is already imported when you generate the command, with the line:
-
-```bash
-source $(echo $(cd "$(dirname $(gem which rbcli))/../lib-sh" && pwd)/lib-rbcli.sh)
-``` 
-
-This will find the library which is stored on the system as part of the RBCli gem.
-
-You can then retrieve the values present in your variables like such:
-
-```bash
-rbcli params
-rbcli args
-rbcli global_opts
-rbcli config
-rbcli myvars
-
-echo "Usage Examples:"
-echo "Log Level:  $(rbcli config .logger.log_level)"
-echo "Log Target: $(rbcli config .logger.log_target)"
-echo "First Argument (if passed): $(rbcli args .[0])"
-```
-
-For your convenience, the script will have all the instructions needed there. For more instructions on how to use JQ syntax to parse values, see the [JQ documentation][jq_documentation].
-
-## External Commands
-
-External Commands are used to wrap 3rd party applications. RBCli accomplishes this by allowing you to set environment variables and command line parameters based on your input variables.
-
-RBCli provides this feature through the `extern` keyword. It provides two modes -- __direct path__ and __variable path__ -- which work similarly.
-
-
-### Direct Path Mode
-
-Direct path mode is the simpler mode of the two External Command modes. It allows you to provide a specific command with environment variables set, though it does not allow using RBCli parameters, arguments, options, and config.
-
- ```ruby
-class List < Rbcli::Command
- 	extern path: 'path/to/application', envvars: {MYVAR: 'some_value'}                               # (Required) Runs a given application, with optional environment variables, when the user runs the command.
-end
- ```
-
-Here, we supply a string to run the command. We can optioanlly provide environment variables which will be set for the external application.
-
-### Variable Path Mode
-
-Variable Path mode works the same as Direct Path Mode, only instead of providing a string we provide a block that returns a string (which will be the command executed). This allows us to generate different commands based on the CLI parameters that the user passed, or pass configuration as CLI parameters to the external application:
-
-```ruby
-class Test < Rbcli::Command
-	extern envvars: {MY_OTHER_VAR: 'another_value'} do |params, args, global_opts, config|          # Alternate usage. Supplying a block instead of a path allows us to modify the command based on the arguments and configuration supplied by the user. This allows passing config settings as command line arguments to external applications. The block must return a string, which is the command to be executed.
-		cmd = '/path/to/application'
-		cmd += ' --test-script foo --ignore-errors' if params[:force]
-		cmd
-	end
-end
-```
-
-__NOTE__: Passing user-supplied data as part of the command string may be a security risk (example: `/path/to/application --name #{params[:name]}`). It is highly recommended to provide the fixed strings yourself, and only select which strings are used based on the variables provided. This is demonstrated in the example above.
-
-
-[your_first_command]: {{< ref "tutorial/30-your_first_command" >}}
-[parameters_documentation]: {{< ref "tutorial/40-options_parameters_and_arguments" >}}
-[user_config_documentation]: {{< ref "advanced/user_config_files" >}}
-[jq_documentation]: https://stedolan.github.io/jq/manual/

data/docs-src/content/advanced/distributed_state_locking.md

@@ -1,37 +0,0 @@
----
-title: "Distributed State and Locking"
-date: 2019-06-20T15:07:21-04:00
-draft: false
----
-
-Distributed Locking allows a [Remote State][state_storage] to be shared among multiple users of the application to make writes appear atomic between sessions. To use it, simply set the  `locking:` parameter to `true` when enabling remote state.
-
-This is how locking works:
-
-1. The application attempts to acquire a lock on the remote state when you first access it
-2. If the backend is locked by a different application, wait and try again
-3. If it succeeds, the lock is held and refreshed periodically
-4. When the application exits, the lock is released
-5. If the application does not refresh its lock, or fails to release it when it exits, the lock will automatically expire within 60 seconds
-6. If another application steals the lock (unlikely but possible), and the application tries to save data, a `StandardError` will be thrown
-7. You can manually attempt to lock/unlock by calling `Rbcli.remote_state.lock` or `Rbcli.remote_state.unlock`, respectively. 
-
-
-## Manual Locking
-
-Remember: all state in Rbcli is lazy-loaded. Therefore, RBCli wll only attempt to lock the data when you first try to access it. If you need to make sure that the data is locked before executing a block of code, use:
-
-```ruby
-Rbcli.remote_state.refresh
-```
-
-to force the lock and retrieve the latest data. You can force an unlock by calling:
-
-```ruby
-Rbcli.remote_state.disconnect
-```
-
-Even if you do not want to store any data, you can leverage manual locking to control access to a different shared resource, such as a stateful API. For example, if you write a cloud deployment toolkit, you can ensure that only one user is attempting to modify a deployment at any given time.
-
-
-[state_storage]: {{< ref "advanced/state_storage" >}}

data/docs-src/content/advanced/hooks.md

@@ -1,69 +0,0 @@
----
-title: "Execution Hooks"
-date: 2019-06-20T15:07:21-04:00
-draft: false
----
-
-RBCli provides you with hooks that can be used to have code execute at certain places in the execution chain. These hooks are optional, and do not have to be defined for your application to run.
-
-All hooks will be created in the `hooks/` folder in your project.
-
-## The Defailt Action Hook
-
-The Default hook is called when a user calls your application without providing a command. If the hook is not provided, the application will automatically display the help text (the same as running it with `-h`).
-
-To create it in your project, run:
-
-```bash
-rbcli hook --default
-# or
-rbcli hook -d
-```
-
-You will then find the hook under `hooks/default_action.rb`.
-
-
-## The Pre-Execution Hook
-
-The Pre-Execution hook is called after the global command line options are parsed and before a command is executed.
-
-To create it in your project, run:
-
-```bash
-rbcli hook --pre
-# or
-rbcli hook -p
-```
-
-You will then find the hook under `hooks/pre_execution.rb`.
-
-## The Post-Execution Hook
-
-The Pre-Execution hook is called after a command is executed.
-
-To create it in your project, run:
-
-```bash
-rbcli hook --post
-# or
-rbcli hook -o
-```
-
-You will then find the hook under `hooks/post_execution.rb`.
-
-## The First-Run Hook
-
-The First-Run hook is called the first time a user executes your application. Using the first-run hook requires enabling [Local State Storage][state_storage] for persistence.
-
-To create it in your project, run:
-
-```bash
-rbcli hook --firstrun
-# or
-rbcli hook -f
-```
-
-You will then find the hook under `hooks/first_run.rb`.
-
-
-[state_storage]: {{< ref "advanced/state_storage" >}}

data/docs-src/content/advanced/interactive_commands.md

@@ -1,41 +0,0 @@
----
-title: "Interactive Commands"
-date: 2019-06-20T15:07:21-04:00
-draft: false
----
-
-## Why interactive commands?
-
-When catering to an audience of users who are not accustomed to scripting, you may want to prompt them for the information directly (the typical CS-101 'puts' and 'gets' pattern). This can be a lot more straightforward than having to read the help texts of your tool, and trying multiple times to enter all of the required data.
-
-Of course, we want to make sure that scripting with the tool still works well (headless interaction). We accomplish this by extending our parameters with a `prompt` option; RBCli will continue to accept the parameter as usual, but if the parameter is omitted then it will prompt the user with the given text.
-
-## How to do it with Rbcli
-
-There is an option when declaring a command's parameters to prompt the user for a value if not entered on the command line. This can be done with the `prompt:` keyword. For example:
-
-```ruby
-class Mycmd < Rbcli::Command
-	parameter :sort, 'Sort output alphabetically', type: :boolean, default: false, prompt: "Sort output alphabetically?"
-	action do |params, args, global_opts, config|
-		puts params[:sort]
-	end
-end
-```
-
-Now, if we run the command while omitting the `--sort` parameter, as such:
-
-```bash
-mytool mycmd
-```
-
-That should give you the prompt:
-
-```
-Sort output alphabetically? (y/N):
-```
-
-Because we set the parameter to default to `false` the default here is `N`, which is used if the user hits enter without entering a letter. If the default was set to `true`, then the `Y` would be capitalized and be the default.
-
-String parameters behave similarly, but default to the string defined instead of a boolean value.
- 

data/docs-src/content/advanced/logging.md

@@ -1,39 +0,0 @@
----
-title: "Logging"
-date: 2019-06-20T15:07:21-04:00
-draft: false
----
-
-Logging with RBCli is straightforward - it looks at the config file for logging settings, and instantiates a single, globally accessible [Logger][ruby_logger] object. You can access it within a standard command like this:
-
-```ruby
-Rbcli::log.info { 'These logs can go to STDERR, STDOUT, or a file' }
-```
-
-## Enabling Logging
-
-To enable logging, simply set the default values in the `config/logging.rb` file:
-
-```ruby
-log_level :info
-log_target 'stderr'
-```
-
-* `log_level`
-	* You can set the default log level using either numeric or standard Ruby logger levels: 0-5, or DEBUG < INFO < WARN < ERROR < FATAL < UNKNOWN
-* `log_target`
-	* This specifies where the logs will be placed. Valid values are nil (disables logging), 'STDOUT', 'STDERR', or a file path (all as strings).
-
-## Userspace Config Overrides
-
-If [Userspace Configuration][userspace_configuration] is enabled, these options will also be present in the user's config file to override defaults: 
-
-```yaml
-# Log Settings
-logger:
-  log_level: warn              # 0-5, or DEBUG < INFO < WARN < ERROR < FATAL < UNKNOWN
-  log_target: stderr           # STDOUT, STDERR, or a file path
-```
-
-[ruby_logger]: https://ruby-doc.org/stdlib-2.4.0/libdoc/logger/rdoc/Logger.html
-[userspace_configuration]: {{< ref "advanced/user_config_files" >}}

data/docs-src/content/advanced/remote_execution.md

@@ -1,60 +0,0 @@
----
-title: "Remote Execution"
-date: 2019-06-20T15:07:21-04:00
-draft: false
----
-
-RBCli can be configured to execute commands on a remote machine via SSH instead of locally.
-
-Currently, only `script` and `extern` commands are supported.
-
-## Configuration
-
-To allow remote execution, go to `config/general.rb` and change the following line to `true`:
-
-```ruby
-remote_execution permitted: false
-```
-
-Then, for each command that you would like to enable remote execution for, add the following directive to the command class declaration:
-
-```ruby
-remote_permitted
-```
-
-## Usage
-
-Your end users can now execute a command remotely by specifying the connection string and credentials on the command line as follows:
-
-```bash
-mytool --remote-exec [user@]host[:port] --identity (/path/to/private/ssh/key or password) <command>
-# or
-mytool -r [user@]host[:port] -i (/path/to/private/ssh/key or password) <command>
-```
-
-Some valid examples are:
-
-```bash
-mytool -r example.com -i myPassword showuserfiles -u MyUser
-mytool -r root@server.local -i ~/.ssh/id_rsa update
-mytool -r admin@172.16.0.1:2202 -i ~/.ssh/mykey cleartemp
-```
-
-If the end user is unsure of which commands can or can not be executed remotely, they can check by running `mytool -h`. Commands that have remote execution enabled will have an asterisk (*) by their name:
-
-```bash
-$ mytool -h
-A simple command line tool.
-For more information on individual commands, run `mytool <command> -h`.
-
-Usage:
-      foo [options] command [parameters]
-
-Commands:
-      bar                  TODO: Description goes here
-   *  baz                  TODO: Description goes here
-
-...
-```
-
-In this example, the command `baz` is available for remote execution