Chaperone

Holding your hand when Automation can't take the wheel.

Sometimes there are processes that just can't be automated. Chaperone is a CLI for watching over someone as they go through a process that has human-driven components. These are processes such as deployment or software installation. The gem does not actually execute the commands, but rather leaves it to the person following the guide to do so.

Automation > Chaperone

Bear in mind that you should prefer automation to chaperone whenever possible. If you find the steps you're writing for chaperone could be safely executed within a script, chaperone is probably not the appropriate place for that process.

Usage

Chaperone includes a Guide class which you inherit from. This guide provides a DSL that allows you to easily produce multi-step functionality with common informational displays as the user progresses through a given guide.

After you have defined your guide, you simply call MyGuide.new.start to begin

Providing reference info

A defined URL constant is displayed at the start of the guide which points to a more thorough explanation of what's happening. It's rare that a chaperone guide can give all the backstory needed, so it's handy to let the guidee know where they can get more info.

Defining steps

The STEPS constant is an array of strings that defines the names of the step methods and their order. Each step string must correspond to a method on the class.

Initialization Options

step will let you specify the number of the step you want to start on. Useful when you are continuing a previously exited guide.

steps lets you define the array of steps your guide will use. This list is normally defined in the STEPS constant, but if you have a specific case where you only want to run through a subset of steps, this is the best way to accomplish that.

Prompt

Each step is rendered using a prompt block. The prompt accepts a few types of calls that vary depending on what type of information you want to display on the screen. These calls vary the visual presentation of the content as well as it's order

Options

  • padding - Specifies if there should be any extra spaces in the prompt (Boolean, default: true)
  • question - Specifies if there should be a blocking actions prompt (Boolean, default: true)

Prompt DSL

  • title A brief message explaining this step
  • needs The requirement to continue
  • current What the guidee is currently using related to the needs
  • notes A plain block of text
  • code Highlighted block of exact syntax that they can copy and paste
  • debug Text that is displayed when a user selects the debug option.
  • question The text displayed on the action prompt

Actions

Each prompt is blocked by a command line input:

[C]ontinue, e[x]it, [r]etry

If the user has assigned a string to the debug attribute, the prompt will look like: 

[C]ontinue, [d]ebug, e[x]it, [r]etry

If you passed a question into the prompt block, you'll see it before the actions:

Ready to continue? [C]ontinue, e[x]it, [r]etry

The default is to continue, retry is handy for things like git branch checks which a user can update in another terminal and confirm the change is recognized.

Example

version = CommandLine.new('ruby', '-v').run.gsub("\n",'')
prompt do |p|
  p.title    = 'Ruby Version Check'
  p.needs    = 'ruby 1.9.3[Any Patch Level]'
  p.notes    = '1.8.7 is not supported, sorry.'
  p.current  = version
  p.code     = 'rvm use 1.9.3'
  p.question = 'Using the right version?'
end

# Output:
Ruby Version Check
Required: ruby 1.9.3[Any Patch Level]
Current: ruby 1.9.3p194 (2012-04-20 revision 35410) [x86_64-darwin12.2.0]

rvm use 1.9.3

Using the right version? [c]ontinue, [r]etry, e[x]it

To see a full guide example, see the deploy.rb file in the repository's examples dir

Libraries

The Guide class includes the cocaine and highline libraries. Go nuts.

Future

There are a few things I'm hoping to include as a part of this gem

  • Delivering guide execution reports to a remote server
  • Error reporting to catch failed guide execution in disparate locations
  • A central source for guide distribution

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request