jossh 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 89bbdbdf3826fe36d90cb9c883b272dc2a61b480
-  data.tar.gz: 8f3ee16da118802914ec86221606a4abf99cdb89
+  metadata.gz: ae6b17ea42779bad1f8ba891969a8ff6aba3b4a3
+  data.tar.gz: 5550c9b4bb4a1b26396befaddb9baab2aaecfb31
 SHA512:
-  metadata.gz: 474aa547a0e00146e1a0bc0b477e358e2d210939639f58f8e854b42c530c8a24d20f04d711de205a6eb2fa538e7a2793dcc9dfa2eb186ee2634627c9db0be2c2
-  data.tar.gz: 28e579729179e79b391eb2ce7e443d3dd5087bba59d98e67269f7f18c0ee85ca310f49fec4cb50f2b9c571b6bfa1316898cbc0b3936d8188e3b16471d6bcfdc1
+  metadata.gz: 7aca02debcfdf336894b3efe1c1178aea44ec455ebce3332208018ea7fdde7be8d9445cf0159c7c9457d006fac51acccc680f9d057a1d2235c554d414de5a371
+  data.tar.gz: 98dd31bb03b543c68368a64f740855ab74e3988d0210e163d4de7bd214107ed6348cb2bb09d49bbe3dfa2bfa3b0cf3c92f3bbe858b98b0a64a180100bf54c069

data/README.md

@@ -1,6 +1,11 @@
 Jossh - Your SSH Buddy
 ======================
 
+[![Gem Version](https://badge.fury.io/rb/jossh.svg)](http://badge.fury.io/rb/jossh)
+[![Code Climate](https://codeclimate.com/github/DannyBen/jossh/badges/gpa.svg)](https://codeclimate.com/github/DannyBen/jossh)
+[![Dependency Status](https://gemnasium.com/DannyBen/jossh.svg)](https://gemnasium.com/DannyBen/jossh)
+
+
 Ruby SSH functions for easier and prettier remote deployment and automation.
 
 ## Install
@@ -24,8 +29,29 @@ Or install manually
 6. Allows storing host specifications in a YAML file.
 7. Supports all options available in `Net::SSH#start`.
 8. Prints output Heroku-style.
+9. Provides a command line interface - `jossh <host> <script>` 
+
+## Command Line Usage
 
-## Usage
+After installing, you can call `jossh` from the command line to run arbitrary
+commands or a local script over SSH.
+
+```
+$ jossh
+
+Usage: jossh <host> <script>
+
+ <host>   - any key available in ./ssh_hosts.yml
+ <script> - can be either a filename or one or more direct command
+            quotes are only needed if you include multiple commands
+            with && or semicolor (;)
+
+Examples: jossh localhost git status
+          jossh localhost "cd ~ && ls -l"
+          jossh localhost deploy
+```
+
+## Library Usage
 
 ### Example 1: Host specifications in a YAML file
 
@@ -78,4 +104,17 @@ touch 'tmp/restart.txt'
 echo "-> Done"
 ```
 
-See also: The examples folder
+See also: The [examples folder](https://github.com/DannyBen/jossh/tree/master/examples)
+
+## Host specification file
+
+Host specifications should be configured in `ssh_hosts.yml` by default.
+
+If you wish to use a different location, use the `ssh_hostfile` method:
+
+```ruby
+ssh_hostfile "my_hosts.yml"
+ssh! :myhost, 'ls'
+```
+
+See [ssh_hosts.example.yml](https://github.com/DannyBen/jossh/blob/master/ssh_hosts.example.yml) as an example.

data/bin/jossh

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby
+
+require 'jossh'
+
+# for dev (not needed in most cases)
+# require File.dirname(__FILE__) + "/../lib/jossh"
+
+trap(:INT) { abort "\r\nGoodbye" }
+
+def usage
+  "\nUsage: jossh <host> <script>\n\n" +
+  " <host>   - any key available in ./ssh_hosts.yml\n" +
+  " <script> - can be either a filename or one or more direct command\n" + 
+  "            quotes are only needed if you include multiple commands\n" + 
+  "            with && or semicolor (;)\n\n" +
+  "Examples: jossh localhost git status\n" +
+  "          jossh localhost \"cd ~ && ls -l\"\n" +
+  "          jossh localhost deploy"
+end
+
+def run
+  host = ARGV.shift
+  script = ARGV.join ' '
+  host and script or abort usage
+  if File.exist? script
+    ssh_script! host.to_sym, script
+  else
+    ssh host.to_sym, script
+  end
+end
+
+run

data/lib/jossh/api.rb

@@ -1,21 +1,81 @@
+# = API Methods
+# These are all the exposed commands. 
+
 module Jossh
 
-  def ssh_script!(hostspec, script)
-    CommandRunner.new.ssh_script! hostspec, script
+  # Execute one or more commands via SSH
+  #
+  # ==== Params:
+  #
+  # +hostspec+:: 
+  #   A hash of SSH host parameters or a symbol pointing to a record in 
+  #   +ssh_hosts.yml+. If a hash is provided, it must include at 
+  #   least +:host+ and +:user+. It can also include any or the options 
+  #   supported by Net::SSH#start.
+  #
+  # +script+::   
+  #   A string or array of commands
+  #
+  # +callback+:: 
+  #   (optional) A method to be called on each block of data received from 
+  #   the SSH execution. If none provided, we will simply use `puts`.
+  #
+  # ==== Examples:
+  #
+  #   ssh :localhost, ["cd /opt/app", "git pull"]
+  #
+  #   ssh { host: 'localhost', user: 'vagrant' }, "ls -l"
+  #
+  #   def my_puts(data)
+  #     puts "> #{data}"
+  #   end
+  #   ssh :localhost, "ls -l", method: my_puts
+  #
+  def ssh(hostspec, script, callback: nil)
+    CommandRunner.instance.ssh hostspec, script, callback: callback
   end
 
-  def ssh_script(hostspec, script, callback: nil)
-    CommandRunner.new.ssh_script hostspec, script, callback: callback
+  # Same as +ssh+, only this will print a pretty output. 
+  #
+  # This method accepts only +hostspec+ and +script+ (no +callback+).
+  #
+  def ssh!(hostspec, script)
+    CommandRunner.instance.ssh! hostspec, script
   end
 
-  def ssh!(hostspec, script)
-    CommandRunner.new.ssh! hostspec, script
+  # Same as +ssh+, only load commands from a file.
+  #
+  # ==== Params:
+  #
+  # +hostspec+:: 
+  #   See +ssh+
+  #
+  # +script+:: 
+  #   A path to the script to run. The script file should be a file with a
+  #   list of shell commands.
+  #
+  # +callback+:: 
+  #   (optional) See +ssh+
+  #
+  # ==== Examples:
+  #
+  #   ssh_script :localhost, "deploy"
+  #
+  def ssh_script(hostspec, script, callback: nil)
+    CommandRunner.instance.ssh_script hostspec, script, callback: callback
   end
 
-  def ssh(hostspec, script, callback: nil)
-    CommandRunner.new.ssh hostspec, script, callback: callback
+  # Same as +ssh_script+, only this will print a pretty output. 
+  #
+  # This method accepts only +hostspec+ and +script+ (no +callback+).
+  #
+  def ssh_script!(hostspec, script)
+    CommandRunner.instance.ssh_script! hostspec, script
   end
 
+  def ssh_hostfile(file)
+    CommandRunner.instance.ssh_hostfile file
+  end
 
 end
 

data/lib/jossh/command_runner.rb

@@ -3,8 +3,15 @@ require "yaml"
 
 module Jossh
 
+  # CommandRunner is the primary class in the Jossh module. It is responsible
+  # for providing the backend for all api methods.
+  #
   class CommandRunner
 
+    def self.instance
+      @@instance ||= self.new
+    end
+
     def ssh!(hostspec, script)
       ssh hostspec, script, callback: OutputHandler.new.method(:pretty_puts)
     end
@@ -17,7 +24,7 @@ module Jossh
       user     = hostspec.delete :user
 
       Net::SSH.start( host, user, hostspec ) do |ssh| 
-        ssh.exec! script do |ch, stream, data|
+        ssh.exec! script do |_ch, _stream, data|
           callback.call data
         end
       end
@@ -31,6 +38,10 @@ module Jossh
       ssh hostspec, load_script(script), callback: callback
     end
 
+    def ssh_hostfile(file)
+      @hostfile = file
+    end
+
     private
 
     def load_spec(key)

data/lib/jossh/output_handler.rb

@@ -1,17 +1,31 @@
 require 'colsole'
 
-# Print functions inspired by Heroku and based on code from Mina
-# https://github.com/mina-deploy/mina/blob/master/lib/mina/output_helpers.rb
-
 module Jossh
 
+  # OutputHandler is responsible for generating the pretty output created by
+  # +ssh!+ and +ssh_script!+ commands.
+  #
   class OutputHandler
 
     include Colsole
 
+    # Print indented output while giving special treatment to strings that 
+    # start with certain markers.
+    #
+    # This method is used as the callback function by +ssh!+ and +ssh_script!+
+    #
+    # ==== Params:
+    # +lines+::
+    #   A newline delimited string or array to pretty-print
+    #
+    #
+    # ==== Credits:
+    # This function was inspired by Heroku and based on code from Mina[https://github.com/mina-deploy/mina/blob/master/lib/mina/output_helpers.rb]
+    #
     def pretty_puts(lines)
       lines = lines.split("\n") if lines.is_a? String
       lines.each do |line|
+        line = line.rstrip.gsub /\t/, "        "
         if line =~ /^\-+> (.*?)$/
           puts_status $1
         elsif line =~ /^! (.*?)$/
@@ -43,7 +57,7 @@ module Jossh
     end
 
     def puts_stdout(msg)
-      say "       #{msg}"
+      puts "       #{msg}"
     end
 
   end

data/lib/jossh/version.rb

@@ -1,3 +1,3 @@
 module Jossh
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jossh
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Danny Ben Shitrit
@@ -83,11 +83,13 @@ dependencies:
 description: Jossh is a wrapper around Ruby Net::SSH with a simpler interface and
   prettier output
 email: db@dannyben.com
-executables: []
+executables:
+- jossh
 extensions: []
 extra_rdoc_files: []
 files:
 - README.md
+- bin/jossh
 - lib/jossh.rb
 - lib/jossh/api.rb
 - lib/jossh/command_runner.rb