cogy 0.0.3 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0dc60289e97c5f49e30bfd90581fe24743fc04c6
-  data.tar.gz: 422827094a27717584a27c0f2e1812cd7297811f
+  metadata.gz: ef283e5c6e479be874048248d27dcfa5acbc6dea
+  data.tar.gz: e64669954bea500e59b959a9b17071f8ed35ceaf
 SHA512:
-  metadata.gz: a21ad7aa25394ee9eeeb6423f49ad6c122c82a7ed4efce6e81d8704da2bf69850a03ddb69d0bf67b7c6f00b4e042980272c51c4828b754853d27b81a8fc83d7a
-  data.tar.gz: 9c5f3b2626f38622200600577c4f20fc59510414455b5e0db88d32b6e6cccc4f01b4777700fd4673d62e35949d35ce832b305df610056038967cb3e31d430d75
+  metadata.gz: f7214c918cbd28eb24aa93e40ad389fdf2e1adff0ec93ba8322563b74ceea081638592f359d07d56676760f4e661a40e54faab26721ce718850bfb9843a563ea
+  data.tar.gz: 36f69dad0e051b6a5501df3c40dec962847922229911781b229b715e7286f1b128584a0f70b3fbe79bf53a771aca982dc2240857f8f451ce8892ab395fbe3b1e

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright 2016 Skroutz S.A.
+
+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

@@ -1,75 +1,144 @@
 # Cogy
 
+[![Build Status](https://api.travis-ci.org/skroutz/cogy.svg?branch=master)](https://travis-ci.org/skroutz/cogy)
+[![Gem Version](https://badge.fury.io/rb/cogy.svg)](https://badge.fury.io/rb/cogy)
+[![Inline docs](http://inch-ci.org/github/skroutz/cogy.svg)](http://inch-ci.org/github/skroutz/cogy)
+
 Cogy integrates [Cog](https://operable.io/) with Rails
-in a way that managing commands becomes a breeze.
+in a way that writing & deploying commands from your application is a breeze.
+
+See the API documentation [here](http://www.rubydoc.info/github/skroutz/cogy).
 
 ## Status
 
-*DISCLAIMER*: While we use Cogy in production, it's still in public alpha and
-is under heavy development.
+Cogy is still in public alpha.
 
-This means that a few critical bits are missing (the Relay executable and
-RSpec helpers to name a few) and the API is not stable yet.
+While we use it in production, it's still under heavy development.
+This means that there are a few rough edges and some important bits are missing.
 
-However, feel free to test it and gives us your feedback!
+However we'd love any [feedback, suggestions or ideas](https://github.com/skroutz/cogy/issues/new).
 
 ## Why
 
-Creating a Cog command that talks with a Rails app typically involves writing
+Creating a ChatOps command that talks with a Rails app typically involves writing
 a route, maybe a controller, an action and code to handle the command arguments
 and options.
 
-This is a tedious and repetitive task and involves writing a lot of boilerplate
+This is a tedious and repetitive task and involves a lot of boilerplate
 code each time someone wants to add a new command.
 
 Cogy is an opinionated library that provides a way to get rid of all the
-repetitive work and makes writing commands a breeze!
+repetitive work.
 
-Making a new command available for use is as simple as adding the following line
-to a file in your application:
+Writing a new command and deploying it is as simple as:
 
 ```ruby
 # in cogy/my_commands.rb
 
-on "foo", desc: "Echo a foo bar back at you!" do |_args, _opts, user|
-  "@#{user}: foo bar"
+on "foo", desc: "Echo a foo bar back at you!" do
+  "@#{handle}: foo bar"
 end
 ```
 
-...and deploying!
+...and deploying! After a second or so, the command is ready to be used.
 
 ## How it works
 
 Cogy is essentially three things:
 
 1. An opinionated way to write, manage & ship commands: All Cogy commands are
-   defined in your Rails app and end up invoking a single executable within the
-   Relay (see below). Cogy provides versioning and dynamically generates the
-   bundle config, which is also served by your Rails app (via a Rails Engine).
-   This, accompanied with the command [TODO: INSERT LINK HERE] that
-   can install bundles from other bundles, makes it possible to automatically
-   install the newly-written commands by invoking a trigger when you deploy
-   your app.
-2. A Rails Engine that is mounted in your application and routes the incoming
-   requests to their user-defined handlers. It also creates the `/inventory`
+   defined in your Rails app and end up invoking a [single executable](https://github.com/skroutz/cogy-bundle/blob/master/commands/cogy) within the
+   Relay. Cogy also provides bundle versioning and dynamically generates the
+   installable bundle config, which is also served by your Rails application
+   and consumed by the [`cogy:install`](https://github.com/skroutz/cogy-bundle)
+   command that installs the new Cogy-generated bundle when you deploy your
+   application.
+2. A library that provides the API for defining the commands. This library
+   is integrated in your application via a Rails Engine that routes the incoming
+   requests to their respective handlers. It also creates the `/inventory`
    endpoint, which serves the installable bundle configuration in YAML and can be
-   consumed directly by the `cogutils:install` command [TODO: INSERT LINK].
-3. An executable [TODO: INSERT LINK HERE] which all commands point to.
-   This is placed inside the Relays and performs the requests to your application
+   consumed directly by the [`cogy:install`](https://github.com/skroutz/cogy-bundle) command.
+3. A [Cog bundle](https://github.com/skroutz/cogy-bundle) that contains the
+   [executable](https://github.com/skroutz/cogy-bundle/blob/master/commands/cogy)
+   that all the commands end up invoking.
+   It is placed inside the Relays and performs the requests to your application
    when a user invokes a command in the chat. It then posts the result back
-   to the user.
+   to the user. It also contains the `cogy:install` command for automating
+   the task of installing the new bundle when a command is added/modified.
+
+Take a look at the relevant [diagrams](diagrams/) for an illustration of how
+Cogy works.
+
+## Requirements
 
-## Installation
+* [cogy bundle](https://github.com/skroutz/cogy-bundle)
+* Ruby 2.1+
+* Tested with Rails 4.2
 
-Add the following to your Gemfile:
+## Install
+
+Add it to your Gemfile:
 
 ```ruby
 gem "cogy"
 ```
 
+Then run `bundle install`
+
+Next, run the generator:
+
+```shell
+$ bin/rails g cogy:install
+```
+
+This will create a sample command, mount the engine and add a sample
+configuration initializer in your application.
+
+## Usage
+
+Defining a new command:
+
+```ruby
+# in cogy/commands.rb
+
+on "foo", desc: "Echo a bar" do
+  "bar"
+end
+```
+
+This will print "bar" back to the user who calls `!foo` in Slack, for example.
+
+Inside the block there are the following pre-defined helpers available:
+
+* `#args`: an array containing the arguments passed to the command
+* `#opts`: a hash containing the options passed to the command
+* `#handle`: the chat handle of the user who called the command
+* `#env`: a hash containing the Cogy environment, that is, every environment variable
+  starting with 'COGY_' and set in the Relay
+
+For instructions on defining your own helpers, see [Helpers](#helpers).
+
+A more complete example:
+
+```ruby
+# in cogy/commands.rb
+on "calc",
+  args: [:a, :b],
+  opts: { op: { type: "string" } },
+  desc: "Performs a calculation between numbers <a> and <b>",
+  examples: "myapp:calc sum 1 2" do
+  op = opts[:op].to_sym
+  result = args.map(&:to_i).inject(&op)
+  "Hello @#{user}, the result is: #{result}"
+end
+```
+
+For more examples see the [test commands](https://github.com/skroutz/cogy/tree/master/test/dummy/cogy).
+
+
 ## Configuration
 
-The options provided are the following:
+The configuration options provided are the following:
 
 ```ruby
 # in config/initializers/cogy.rb
@@ -86,10 +155,10 @@ Cogy.configure do |config|
   config.bundle_description = "myapp-generated commands from Cogy"
 
   # Can be either a string or an object that responds to `#call` and returns
-  # a string. Must be set explicitly.
+  # a string.
   config.bundle_version = "0.0.1"
 
-  # If you used a callable object, it will be evaluated each time the inventory
+  # if you used a callable object, it will be evaluated each time the inventory
   # is called. This can be useful if you want the version to change dynamically
   # when it's needed.
   #
@@ -101,7 +170,6 @@ Cogy.configure do |config|
   }
 
   # The path in the Relay where the cogy command executable is located at.
-  # Must be set explicitly.
   config.executable_path = "/cogcmd/cogy"
 
   # Paths in your application where the files that define the commands live in.
@@ -114,38 +182,59 @@ end
 
 ```
 
-## Usage
+You can use the generator to quickly create a config initializer in your app:
+
+```shell
+$ bin/rails g cogy:config
+```
+
+### Helpers
 
-Commands are defined like so:
+It is possible to define helpers that can be used throughout commands. They
+can be defined during configuration and can accept a variable number of
+arguments, or no arguments at all.
+
+Let's define a helper that fetches a `Shops` address of the user who called the
+command:
 
 ```ruby
-# in cogy/commands.rb
+Cogy.configure do |c|
+  c.helper(:shop_address) { Shop.find_by(owner: handle).address }
+end
+```
 
-on "foo", desc: "Echo a bar" do
-  "bar"
+*(Note that custom helpers also have access to the default helpers like
+`handle`, `args` etc.)*
+
+Then we could have a command like this:
+
+```ruby
+on "shop_address", desc: "Returns the user's Shop address" do
+  "@#{handle}: Your shop's address is #{shop_address}"
 end
 ```
 
-The last line evaluated is the result of the command.
+We can also define helpers that accept arguments:
 
-A more complete example:
+```ruby
+Cogy.configure do |c|
+  c.helper(:format) { |answer| answer.titleize }
+end
+```
+
+Then in our command we could call it like so:
 
 ```ruby
-# in cogy/commands.rb
-on "calc",
-  args: [:a, :b],
-  opts: { op: { type: "string", required: true, short_flag: "o" } },
-  desc: "Performs a calculation between numbers <a> and <b>",
-  examples: "!myapp:calc sum 1 2" do |req_args, req_opts, user|
-  op = req_opts[:op].to_sym
-  result = req_args.map(&:to_i).inject(&op)
-  "Hello @#{user}, the result is: #{result}"
+on "foo", desc: "Nothing special" do
+  format "hello there, how are you today?"
 end
 ```
 
+Rails' URL helpers are also available inside the commands.
+
 ## Error template
 
-When a command throws an error, the default error template is rendered, which
+When a command throws an error the [default error template](https://github.com/skroutz/cogy/blob/master/app/views/cogy/error.text.erb) is rendered, which
 is the following:
 
     @<%= @user %>: Command '<%= @cmd %>' returned an error.
@@ -154,7 +243,7 @@ is the following:
     <%= @exception.class %>:<%= @exception.message %>
     ```
 
-However it can be overriden in the application by creating a view in
+It can be overriden in the application by creating a view in
 `app/views/cogy/error.text.erb`.
 
 ## Authors
@@ -165,4 +254,3 @@ However it can be overriden in the application by creating a view in
 ## License
 
 Cogy is licensed under MIT. See [LICENSE](LICENSE).
-

data/Rakefile

@@ -4,24 +4,10 @@ rescue LoadError
   puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
 end
 
-require 'rdoc/task'
-
-RDoc::Task.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'Cogy'
-  rdoc.options << '--line-numbers'
-  rdoc.rdoc_files.include('README.rdoc')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
-
 APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
 load 'rails/tasks/engine.rake'
-
-
 load 'rails/tasks/statistics.rake'
 
-
-
 Bundler::GemHelper.install_tasks
 
 require 'rake/testtask'
@@ -33,5 +19,9 @@ Rake::TestTask.new(:test) do |t|
   t.verbose = false
 end
 
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['app/**/*.rb', 'config/**/*.rb', 'lib/**/*.rb']
+end
 
 task default: :test

data/app/controllers/cogy/cogy_controller.rb

@@ -3,26 +3,47 @@ require_dependency "cogy/application_controller"
 module Cogy
   class CogyController < ApplicationController
     # GET <mount_path>/cmd/:cmd/:user
+    #
+    # The command endpoint is the one that the cogy executable (see
+    # https://github.com/skroutz/cogy-bundle hits. It executes the requested
+    # {Command} and responds back the result, which is then printed to the user
+    # by the cogy executable.
+    #
+    # See https://github.com/skroutz/cogy-bundle.
     def command
       cmd = params[:cmd]
-      args = request.query_parameters.select { |k,_| k !~ /\Acog_opt_/ }.values
+      args = request.query_parameters.select { |k,_| k =~ /\Acog_argv_/ }.values
       opts = request.query_parameters.select { |k,_| k =~ /\Acog_opt_/ }
         .transform_keys { |k| k.sub("cog_opt_", "") }
+      cogy_env = request.query_parameters.select { |k,_| k =~ /\Acogy_/ }
       user = params[:user]
 
       begin
-        render text: Cogy.commands[cmd].run!(args, opts, user)
+        if (command = Cogy.commands[cmd])
+          context = Context.new(args, opts, user, cogy_env)
+          render text: context.run!(command)
+        else
+          render status: 404, text: "The command '#{cmd}' does not exist."
+        end
       rescue => e
         @user = user
         @cmd = cmd
         @exception = e
-        render "cogy/error"
+        respond_to do |format|
+          format.any do
+            render "/cogy/error.text.erb", content_type: "text/plain", status: 500
+          end
+        end
       end
     end
 
-    # GET /inventory
+    # GET <mount_path>/inventory
+    #
+    # The inventory endpoint, is essentially the bundle config in YAML format,
+    # which is installable by Cog. It is typically installed by the
+    # `cogy:install` command (see https://github.com/skroutz/cogy-bundle).
     def inventory
-      render text: Cogy.bundle_config.to_yaml
+      render text: Cogy.bundle_config.to_yaml, content_type: "application/x-yaml"
     end
   end
 end

data/app/views/cogy/error.text.erb

@@ -1,5 +1,5 @@
 @<%= @user %>: Command '<%= @cmd %>' returned an error.
 
 ```
-<%= @exception.class %>:<%= @exception.message %>
+<%= @exception.class %>: <%= @exception.message %>
 ```

data/lib/cogy/command.rb

@@ -1,9 +1,26 @@
 module Cogy
+  # {Command} represents a user-defined registered command that can be used
+  # in the chat. It contains the Cog-related stuff (ie. everything that
+  # needs to be in the bundle config) and a block that will run and return
+  # the result (ie. handler).
   class Command
-    attr :name, :args, :opts, :desc, :long_desc, :examples, :rules, :handler
+    # The name of the command. Also used in {Cogy.bundle_config}.
+    #
+    # @return [String]
+    attr :name
+
+    # The code that will run when the command is invoked
+    #
+    # @return [Proc]
+    attr :handler
 
-    def initialize(name, args: [], opts: {}, desc:, long_desc: nil, examples: nil, rules: nil)
-      @name = name
+    # Attributes related to the bundle config in Cog
+    attr :args, :opts, :desc, :long_desc, :examples, :rules
+
+    # See {Cogy.on}
+    def initialize(name, handler, args: [], opts: {}, desc:, long_desc: nil, examples: nil, rules: nil)
+      @name = name.to_s
+      @handler = handler
       @args = [args].flatten.map!(&:to_s)
       @opts = opts.with_indifferent_access
       @desc = desc
@@ -12,31 +29,31 @@ module Cogy
       @rules = rules || ["allow"]
     end
 
-    def register!(handler)
+    # Registers a command.
+    #
+    # @raise [StandardError] if a command with the same name is already
+    #   registered
+    #
+    # @return [self]
+    def register!
       if Cogy.commands[name]
         raise "A command with the name #{name} is already registered"
       end
 
-      @handler = handler
-      @handler.command = self
-
       Cogy.commands[name] = self
     end
 
-    def run!(*args)
-      handler.run(*args)
-    end
-
-    # Suitable for bundle config display
+    # @return [String] the command arguments suitable for conversion to YAML
+    #   for displaying in a bundle config.
     def formatted_args
       args.map { |a| "<#{a}>" }.join(" ")
     end
 
-    # Suitable for bundle config display.
-    #
-    # Get rid of HashWithIndifferentAccess, otherwise the resulting YAML
-    # will contain garbage.
+    # @return [Hash] the command options suitable for conversion to YAML
+    #   for displaying in a bundle config
     def formatted_opts
+      # Convert to Hash in order to get rid of HashWithIndifferentAccess,
+      # otherwise the resulting YAML will contain garbage.
       opts.to_hash
     end
   end

data/lib/cogy/context.rb

@@ -0,0 +1,52 @@
+module Cogy
+  # {Context} represents a particular invocation request of a {Command}
+  # performed by a user. It holds state like the command arguments, options etc.
+  # In other words, it provides the context in which a {Command} should be
+  # invoked.
+  #
+  # A {Context} essentially is an HTTP request performed by the `cogy:cogy`
+  # command (https://github.com/skroutz/cogy-bundle) on behalf of the user.
+  # You can think of it as the equivalent of the ActionPack's `Request` class.
+  class Context
+    # @return [Array] The Cog command arguments as passed by the user who
+    #   invoked the command.
+    #
+    # @see https://cog-book.operable.io/#_arguments
+    attr :args
+
+    # @return [Hash] The Cog command options as provided by the user who
+    #   invoked the command
+    #
+    # @see https://cog-book.operable.io/#_options
+    attr :opts
+
+    # @return [String] The chat handle of the user who invoked the command
+    #
+    # @see https://cog-book.operable.io/#_general_metadata
+    attr :handle
+
+    # @return [Hash] The Cogy environment (ie. all environment variables in
+    # the Relay executable that start with 'COGY_')
+    #
+    # @see https://github.com/skroutz/cogy-bundle/blob/master/commands/cogy
+    attr :env
+
+    def initialize(args, opts, handle, env)
+      @args = args
+      @opts = opts
+      @handle = handle
+      @env = env
+    end
+
+    # Executes a {Command} in the context of {self}.
+    #
+    # @param [Command] cmd the {Command} to be executed
+    #
+    # @return [String] the result of the command. This is what will get printed
+    #   back to the user that invoked the command and is effectively the return
+    #   value of the command body.
+    def run!(cmd)
+      instance_eval(&cmd.handler)
+    end
+  end
+end

data/lib/cogy/engine.rb

@@ -3,18 +3,12 @@ module Cogy
     isolate_namespace Cogy
 
     config.after_initialize do
-      if Cogy.bundle_version.nil?
-        raise "You must set the :bundle_version setting"
-      end
-
-      if Cogy.executable_path.nil?
-        raise "You must set the :executable_path setting"
-      end
-
       Cogy.command_load_paths.each do |path|
         files = Dir[Rails.root.join(path,"*.rb")]
         files.each { |f| Cogy.module_eval(File.read(f)) }
       end
+
+      Context.include(Rails.application.routes.url_helpers)
     end
   end
 end

data/lib/cogy/invocation.rb

@@ -0,0 +1,37 @@
+module Cogy
+  # {Context} represents a particular invocation request of a {Command}
+  # performed by a user. It holds state like the command arguments, options etc.
+  # In other words, it provides the context in which a {Command} should be
+  # invoked.
+  #
+  # A {Context} essentially is an HTTP request performed by the `cogy:cogy`
+  # command (https://github.com/skroutz/cogy-bundle) on behalf of the user.
+  # You can think of it as the equivalent of the ActionPack's `Request` class.
+  class Context
+    # The Cog command arguments as provided by the user who invoked the command.
+    #
+    # See https://cog-book.operable.io/#_arguments
+    attr :args
+
+    # The Cog command options as provided by the user who invoked the command
+    #
+    # See https://cog-book.operable.io/#_options
+    attr :opts
+
+    # The chat handle of the user who invoked the command
+    #
+    # See https://cog-book.operable.io/#_general_metadata
+    attr :user
+
+    # The Cogy environment (ie. all environment variables in the Relay
+    # executable that start with 'COGY_')
+    attr :env
+
+    def initialize(args, opts, user, env)
+      @args = args
+      @opts = opts
+      @user = user
+      @env = env
+    end
+  end
+end

data/lib/cogy/version.rb

@@ -1,3 +1,3 @@
 module Cogy
-  VERSION = "0.0.3"
+  VERSION = "0.1.0"
 end