chaperone 0.0.1

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+coverage
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in chaperone.gemspec
+gem 'rake'
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Matthew Werner
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,119 @@
+# Chaperone
+
+Getting as close to automated as we can.
+
+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
+- `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 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
+
+To see a full guide example, see the [`deploy.rb`](https://github.com/mwerner/chaperone/blob/master/examples/deploy.rb) file in the repository's `examples` dir
+
+## Libraries
+
+The `Guide` class includes the [cocaine](https://github.com/thoughtbot/cocaine)
+and [highline](https://github.com/JEG2/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

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/chaperone.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'chaperone/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "chaperone"
+  gem.version       = Chaperone::VERSION
+  gem.authors       = ["Matthew Werner"]
+  gem.email         = ["mwerner@zendesk.com"]
+  gem.description   = %q{Guides you step by step through the things you can mess up}
+  gem.summary       = %q{Guides you step by step through the things you can mess up}
+  gem.license       = 'MIT'
+  gem.homepage      = "https://github.com/mwerner/chaperone"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'simplecov'
+  gem.add_development_dependency 'mocha'
+
+  gem.add_runtime_dependency 'thor'
+  gem.add_runtime_dependency 'cocaine'
+  gem.add_runtime_dependency 'activesupport'
+  gem.add_runtime_dependency 'highline'
+
+end

data/examples/deploy.rb

@@ -0,0 +1,66 @@
+require 'rubygems'
+require 'chaperone'
+
+class Deploy < Chaperone::Guide
+
+  URL = 'https://github.com/mwerner/chaperone'
+  STEPS = %w[
+    check_ruby_version
+    execute_capistrano
+    tag_release_version
+    notify_flowdock
+  ]
+
+  protected
+
+  def check_ruby_version
+    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.current = version
+      p.code    = 'rvm use 1.9.3'
+    end
+  end
+
+  def execute_capistrano
+    prompt do |p|
+      p.title   = 'Run capistrano task'
+      p.code    = 'bundle exec cap production deploy'
+      p.notes = %{
+        The script can be found in config/deploy/production.rb
+      }
+    end
+  end
+
+  def tag_release_version
+    latest = CommandLine.new('git describe --abbrev=0 --tags').run.gsub("\n",'') rescue 'Unable to determine'
+
+    prompt(question: false) do |p|
+      p.title = 'Tagging the release'
+      p.notes = %{
+        - This should be the next unreleased tag in the current Changelog.md
+        Latest Deployed Version: #{status(latest)}
+      }
+    end
+
+    version = ask(strong('The version youre deploying:')).to_s
+    prompt do |p|
+      p.code = %{
+        git tag -a #{version}
+        git push origin #{version}
+      }
+    end
+  end
+
+  def notify_flowdock
+    prompt do |p|
+      p.title   = 'Notify flowdock chat'
+      p.code    = '@all just deployed master to production'
+    end
+  end
+
+end
+
+Deploy.new.start

data/lib/chaperone/guide.rb

@@ -0,0 +1,88 @@
+module Chaperone
+  class Guide
+    include Cocaine
+    include Output
+    include HighlineConfig
+
+    attr_accessor :steps, :current_step, :iteration, :url
+
+    STEPS = ['no_steps_defined']
+    URL   = 'https://github.com/mwerner/chaperone'
+
+    def initialize(opts={})
+      @steps          = opts[:steps] || self.class::STEPS
+      @url            = self.class::URL
+      @iteration      = 0
+      @current_step   = opts[:step].to_i || 0
+    end
+
+    def start
+      welcome!
+      
+      (0..steps.length-1).each do |step|
+        @iteration = step
+
+        if current_step > iteration
+          skip_step!
+          next
+        end
+
+        break unless execute_step(steps[iteration].to_sym)
+        complete_step!
+      end
+
+      complete!
+    end
+
+    protected
+
+    def no_steps_defined
+      prompt(question: false) do |p|
+        p.title = "No Steps are defined for #{self.class.to_s}"
+      end
+    end
+
+    def execute_step(step, proceed=true)
+      unless self.respond_to?(step)
+        output "WARNING: #{step} is not defined"
+        return
+      end
+
+      loop do
+        case send(step)
+        when 'r'; next
+        when 'x'; proceed = false
+        end
+
+        break
+      end
+
+      proceed
+    end
+
+    private
+
+    def prompt(opts={}, &config)
+      Prompt.new(opts, &config).render
+    end
+
+    def welcome!
+      output '==> Begin'
+      output "==> Reference: #{url}" if url
+    end
+
+    def complete_step!
+      @current_step += 1
+      output notice("==> [#{iteration}] Completed Step")
+    end
+
+    def skip_step!
+      output notice("==> Skipping [#{iteration}] #{steps[iteration].gsub('_',' ')}")
+    end
+
+    def complete!
+      output "==> Finished"
+    end
+
+  end
+end

data/lib/chaperone/prompt.rb

@@ -0,0 +1,44 @@
+module Chaperone
+  class Prompt
+    include Output
+    include HighlineConfig
+
+    attr_accessor :title, :notes, :needs, :current, :code, :question, :config
+
+    def initialize(config={})
+      @config = {padding: true, question: true}.merge(config)
+      yield(self) if block_given?
+    end
+
+    def render
+      output body
+      return unless has_question?
+      ask strong("#{question} [c]ontinue, [r]etry, e[x]it".squeeze(' '))
+    end
+
+    def lines
+      sections = []
+      sections << action( title )                        if title
+      sections << notes                                  if notes
+      sections << "#{requirement('Required:')} #{needs}" if needs
+      sections << "#{status('Current:')} #{current}"     if current
+      sections << direction("\n #{code}")                if code
+      sections
+    end
+
+    def body
+      text = lines.join("\n ")
+      text = "\n#{text}\n\n" if has_padding?
+      text.squeeze(' ')
+    end
+
+    def has_padding?
+      !!config[:padding]
+    end
+
+    def has_question?
+      !!config[:question]
+    end
+
+  end
+end

data/lib/chaperone/version.rb

@@ -0,0 +1,3 @@
+module Chaperone
+  VERSION = "0.0.1"
+end

data/lib/chaperone.rb

@@ -0,0 +1,38 @@
+require 'cocaine'
+require 'chaperone/version'
+require 'highline/import'
+
+module HighlineConfig
+  COLORS = [:status, :notice, :action, :error, :requirement, :strong, :direction]
+
+  HighLine.color_scheme = HighLine::ColorScheme.new do |scheme|
+    scheme[:action]       = [ :bold, :yellow, :on_black ]
+    scheme[:notice]       = [ :green ]
+    scheme[:status]       = [ :bold, :blue ]
+    scheme[:error]        = [ :red ]
+    scheme[:direction]    = [ :bold, :black, :on_gray ]
+    scheme[:strong]       = [ :gray, :bold ]
+    scheme[:requirement]  = [ :bold, :cyan ]
+  end
+
+  COLORS.each do |hue|
+    define_method(hue.to_sym) do |message|
+      "<%= color('#{message}', :#{hue})%>"
+    end
+  end
+end
+
+module Output
+  def output(message)
+    say(message) unless ENV['env'] == 'test'
+  end
+end
+
+module Chaperone
+  autoload :Prompt,    'chaperone/prompt'
+  autoload :Guide,     'chaperone/guide'
+
+  module Guides
+    autoload :Brew,    'chaperone/guides/brew'
+  end
+end

data/spec/models/guide_spec.rb

@@ -0,0 +1,54 @@
+require 'spec_helper'
+
+describe Guide do
+  
+  context '#initialize' do
+    it 'defaults step to 0' do
+      Guide.new.current_step.should eq(0)
+    end
+
+    it 'accepts step param' do
+      guide = Guide.new(step: 2)
+      guide.current_step.should eq(2)
+      guide.start
+    end
+  end
+
+  context '#start' do
+    let(:guide){Guide.new}
+
+    it 'calls welcome and complete' do
+      Guide.any_instance.expects(:welcome!).once
+      Guide.any_instance.expects(:complete!).once
+      guide.start
+    end
+
+    it 'runs no_steps_defined when no steps are defined' do
+      Guide.any_instance.expects(:no_steps_defined).once
+      guide.start
+    end
+
+    it 'provides the chaperone url if none is defined' do
+      guide.url.should eq(Guide::URL)
+    end
+
+    context 'with steps' do
+      let(:guide){Guide.new(steps: ['a','b'])}
+      let(:stubbed_guide){
+        guide.stubs(:a)
+        guide.stubs(:b)
+      }
+
+      it 'warns on an undefined step' do
+        expect{ guide.start }.to_not raise_error
+      end
+      
+      it 'runs each step' do
+        stubbed_guide.expects(:a).once
+        stubbed_guide.expects(:b).once
+        guide.start
+      end
+    end
+
+  end
+end

data/spec/models/prompt_spec.rb

@@ -0,0 +1,46 @@
+require 'spec_helper'
+
+describe Guide do
+  let(:attrs){%w(title notes needs current code)}
+  context '#initialize' do
+    it 'defaults config' do
+      Prompt.new.config.should eq({padding: true, question: true})
+    end
+
+    it 'allows config' do
+      params = {padding: false, question: false}
+      Prompt.new(params).config.should eq(params)
+    end
+
+    it 'executes a block' do
+      prompt = Prompt.new do |p|
+        attrs.each do |attr|
+          p.send("#{attr.to_sym}=", "My #{attr}")
+        end
+      end
+      attrs.each do |attr|
+        prompt.send(attr.to_sym).should eq("My #{attr}")
+      end
+    end
+  end
+
+  context '#lines' do
+    it 'returns an array' do
+      prompt = Prompt.new{|p| p.title = 'My title'}
+      prompt.lines.should be_a_kind_of(Array)
+    end
+
+    it 'accepts a dsl' do
+      prompt = Prompt.new do |p|
+        attrs.each do |attr|
+          p.send("#{attr.to_sym}=", "My #{attr}")
+        end
+      end
+
+      prompt.lines.each_with_index do |line, i|
+        line.should include("My #{attrs[i]}")
+      end
+    end
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,17 @@
+ENV['env'] = 'test'
+
+require 'simplecov'
+SimpleCov.start
+
+require 'chaperone'
+require 'mocha/api'
+
+RSpec.configure do |config|
+  include Mocha::API
+  include Chaperone
+
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+  config.order = 'random'
+end

metadata

@@ -0,0 +1,182 @@
+--- !ruby/object:Gem::Specification
+name: chaperone
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Matthew Werner
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-04-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: cocaine
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: highline
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Guides you step by step through the things you can mess up
+email:
+- mwerner@zendesk.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- chaperone.gemspec
+- examples/deploy.rb
+- lib/chaperone.rb
+- lib/chaperone/guide.rb
+- lib/chaperone/prompt.rb
+- lib/chaperone/version.rb
+- spec/models/guide_spec.rb
+- spec/models/prompt_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/mwerner/chaperone
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -1260887828363319748
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -1260887828363319748
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Guides you step by step through the things you can mess up
+test_files:
+- spec/models/guide_spec.rb
+- spec/models/prompt_spec.rb
+- spec/spec_helper.rb