cogy 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 594980685522210c3c12429b0ff4aeff0011e103
-  data.tar.gz: 006c7df96512ee2ee362102782d8fa68430546b2
+  metadata.gz: 0d68c05583565f05400bafb31ec6487ed3ed72d2
+  data.tar.gz: a693a5479f2ea5c0a74ebcca4d17a1ea5ac7e5b5
 SHA512:
-  metadata.gz: 1aab5e7578c675ae57209331e27c1dfedc67f7144feca18aed40be622d4c8a4eb46a7d27426058e36012464428fb155a20c1a67a270255be6151e89ebe0ab2fe
-  data.tar.gz: 0474fc729b3405ee55754ad7cbf1b5e36902e64fb2fe4f74c588ee6033af37f1f4e960c0c30fdd51efb03f661799938a638be825a9f74536e3dbe9a08d856867
+  metadata.gz: 115ffd20c179abbdf00324759778b7ad5945213c91f6724b5e41e0f3f0f860ebd0c1c9412b5380d7bdbebd3f47876f3c22468cc52ae75f4abad235a4b55786c5
+  data.tar.gz: 02c5c9aec2d01c167a6b29e027b787988d627e27692ea24370c45491b7a0f8b0583631d0b4955eb143d6dea9ceca3c0b1a9a30359f7f9b091508ee492c710c33

data/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## master (unreleased)
 
+## 0.4.0 (2016-12-05)
+
+This release requires the [cogy-bundle](https://github.com/skroutz/cogy-bundle)
+to be at version 0.4.0 or later.
+
+### Changed
+
+- The 'user' parameter no longer exists in the incoming request path ([#60](https://github.com/skroutz/cogy/issues/60))
+
 ## 0.3.0 (2016-11-29)
 
 This release requires the [cogy-bundle](https://github.com/skroutz/cogy-bundle)

data/README.md

@@ -11,18 +11,19 @@ See the API documentation [here](http://www.rubydoc.info/github/skroutz/cogy).
 
 Refer to the [Changelog](CHANGELOG.md) to see what's changed between releases.
 
-## Status
-
-Cogy is still in public alpha.
+## Features
 
-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.
+- Write commands inside your Rails app, using Ruby (see [_Usage_](#usage))
+- The bundle config is generated automatically
+- Commands are installed _automatically_ when you deploy (see [_Deployment_](#deployment))
+- Support for JSON responses and Templates (see [_Returning JSON to COG_](#returning-json-to-cog))
+- Customizable error templates (see [_Error template_](#error-template))
 
-However we'd love any [feedback, suggestions or ideas](https://github.com/skroutz/cogy/issues/new).
+...and more on the way!
 
 ## Why
 
-Creating a ChatOps command that talks with a Rails app typically involves writing
+Creating ChatOps commands that talk with a Rails app typically involves writing
 a route, maybe a controller, an action and code to handle the command arguments
 and options.
 
@@ -30,9 +31,9 @@ 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.
+boilerplate stuff so you can focus on just the actual commands.
 
-Writing a new command and deploying it is as simple as:
+Deploying a new command is as simple as writing:
 
 ```ruby
 # in cogy/my_commands.rb
@@ -42,15 +43,15 @@ on "foo", desc: "Echo a foo bar back at you!" do
 end
 ```
 
-...and deploying! After a second or so, the command is ready to be used.
+...and deploying!
 
 ## 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](https://github.com/skroutz/cogy-bundle/blob/master/commands/cogy) within the
-   Relay. Cogy also provides bundle versioning and dynamically generates the
+   defined in your Rails app and end up invoking a single executable within the
+   Relay (see below). 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
@@ -68,14 +69,22 @@ Cogy is essentially three things:
    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.
+Take a look at the relevant [diagrams](diagrams/) for a detailed illustration.
 
 ## Requirements
 
-* [cogy bundle](https://github.com/skroutz/cogy-bundle)
+* [cogy bundle v0.3.0+](https://github.com/skroutz/cogy-bundle)
 * Ruby 2.1+
-* Tested with Rails 4.2
+* Rails 4.2 (support for Rails 5 is on the way)
+
+## Status
+
+Cogy is still in public alpha.
+
+While we use it in production, it's still under heavy development.
+This means that there are a few rough edges and things change fast.
+
+However we'd love any [feedback, suggestions or ideas](https://github.com/skroutz/cogy/issues/new).
 
 ## Install
 
@@ -120,14 +129,14 @@ on "add", args: [:a, :b], desc: "Add two numbers" do
 end
 ```
 
-Inside the block there are the following pre-defined helpers available:
+Inside the block there are the following helpers available:
 
 * `args`: an array containing the arguments passed to the command
   * arguments can also be accessed by their names as local variables
 * `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
+* `env`: a hash containing the Relay environment as available in the cogy
+  bundle
 
 For instructions on defining your own helpers, see [Helpers](#helpers).
 
@@ -158,7 +167,8 @@ on "foo", desc: "Just a JSON" do
 end
 ```
 
-The hash automatically gets converted to JSON by Cogy. The above command would return the following response to Cog:
+The hash is automatically converted to JSON. The above command would return
+the following response to Cog:
 
 ```
 COG_TEMPLATE: foo
@@ -166,7 +176,8 @@ JSON
 {"a":3}
 ```
 
-To customize the Cog [template](#Templates) to be used, pass the `template` option:
+To customize the Cog [template](#Templates) to be used, use the `template`
+option:
 
 ```ruby
 on "foo", desc: "Just a JSON", template: "bar" do
@@ -232,7 +243,7 @@ Cogy.configure do |config|
   config.bundle = {
     # The bundle name.
     #
-    # Default: "cogy"
+    # Default: "myapp"
     name: "myapp",
 
     # The bundle description
@@ -281,11 +292,12 @@ $ bin/rails g cogy:config
 
 ### Helpers
 
-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.
+It is possible to define helpers that can be used throughout commands. This is
+useful for DRYing repetitive code.
+
+They are defined during configuration and may also accept arguments.
 
-Let's define a helper that fetches a `Shops` address of the user who called the
+Let's define a helper that fetches the `address` of a `Shop` record:
 command:
 
 ```ruby
@@ -297,7 +309,7 @@ end
 *(Note that custom helpers also have access to the default helpers like
 `handle`, `args` etc.)*
 
-Then we could have a command like this:
+Then we could have a command that makes use of the helper:
 
 ```ruby
 on "shop_address", desc: "Returns the user's Shop address" do
@@ -305,7 +317,7 @@ on "shop_address", desc: "Returns the user's Shop address" do
 end
 ```
 
-We can also define helpers that accept arguments:
+Helpers may also accept arguments:
 
 ```ruby
 Cogy.configure do |c|
@@ -313,7 +325,7 @@ Cogy.configure do |c|
 end
 ```
 
-Then in our command we could call it like so:
+This helper could be called like so:
 
 ```ruby
 on "foo", desc: "Nothing special" do
@@ -321,11 +333,12 @@ on "foo", desc: "Nothing special" do
 end
 ```
 
-Rails' URL helpers are also available inside the commands.
+Rails URL helpers (ie. `foo_url`) are also available inside the commands.
 
 ## Error template
 
-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
+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.
@@ -337,12 +350,39 @@ is the following:
 It can be overriden in the application by creating a view in
 `app/views/cogy/error.text.erb`.
 
+## Installation Trigger
+
+In order to automate the process of installing the new bundle versions
+(eg. after a new command is added), you must create a [Cog Trigger](https://cog-book.operable.io/#_developing_a_trigger)
+that will perform the installation, which will be called when you deploy your
+app.
+
+The trigger will look this:
+
+```shell
+$ cogctl triggers
+Name               ID                                    Enabled  Pipeline
+ReleaseUrlTrigger  d10df83b-a737-4fc4-8d9b-bf9627412d0a  true     cogy:install --url $body.url > chat://#general
+```
+
+It essentially uses the [cogy bundle](https://github.com/skroutz/cogy-bundle)
+and installs the bundle config which is served by your application
+(ie. http://your-app.com/cogy/inventory).
+
+See [_Deployment_](#deployment) on information about how this trigger is
+invoked.
+
 ## Deployment
 
-Cogy provides the `cogy:notify_cog` task for Capistrano. This task should run
-*after* the application server is respawned/restarted, so that the new commands
-are picked up. In Capistrano 2 for example, it should run after
-`deploy:restart`.
+Cogy provides integration with Capistrano 2 and 3.
+
+There is the just one task, `cogy:notify_cog`, which just executes the
+[installation Trigger](#installation-trigger).
+
+The task should run
+*after* the application server is restarted, so that the new commands
+are picked up and served by the Inventory endpoint. In Capistrano 2 for
+example, it should run after the built-in `deploy:restart` task.
 
 The following options need to be set:
 
@@ -354,7 +394,7 @@ The following options need to be set:
 You can also configure the timeout value for the request to the Trigger by
 setting the `cogy_trigger_timeout` option (default: 7).
 
-The task can be found [here](https://github.com/skroutz/cogy/blob/master/lib/cogy/capistrano/cogy.rake).
+The code of the task can be found [here](https://github.com/skroutz/cogy/blob/master/lib/cogy/capistrano/cogy.rake).
 
 ### Capistrano 2
 

data/app/controllers/cogy/cogy_controller.rb

@@ -1,22 +1,21 @@
 require_dependency "cogy/application_controller"
 
 module Cogy
+  # This is the entry point to the host application.
+  #
+  # All Cogy-command invocations of the users end up being served by this
+  # controller ({#command}).
   class CogyController < ApplicationController
-    # POST <mount_path>/cmd/:cmd/:user
+    # POST /<mount_path>/cmd/:cmd
     #
-    # 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.
+    # Executes the requested {Command} and returns the result.
     def command
       cmd = params[:cmd]
       args = params.select { |k, _| k.start_with?("COG_ARGV_") }
                    .sort_by { |k, _| k.match(/\d+\z/)[0] }.to_h.values
       opts = params.select { |k, _| k.start_with?("COG_OPT_") }
                    .transform_keys { |k| k.sub("COG_OPT_", "").downcase }
-      user = params[:user]
+      user = params["COG_CHAT_HANDLE"]
       cog_env = request.request_parameters
 
       begin
@@ -43,11 +42,10 @@ module Cogy
       end
     end
 
-    # GET <mount_path>/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).
+    # Returns the bundle config in YAML format, which is installable by Cog.
+    # It is typically hit by `cogy:install` (https://github.com/skroutz/cogy-bundle).
     def inventory
       render text: Cogy.bundle_config.to_yaml, content_type: "application/x-yaml"
     end

data/config/routes.rb

@@ -1,4 +1,4 @@
 Cogy::Engine.routes.draw do
-  post "cmd/:cmd/:user" => "cogy#command"
+  post "cmd/:cmd" => "cogy#command"
   get "inventory" => "cogy#inventory"
 end

data/lib/cogy/command.rb

@@ -1,27 +1,59 @@
 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).
+  # {Command} represents a user-defined, registered command that can be used
+  # in the chat. It contains information about Cog-related stuff (ie. everything that
+  # needs to be in the bundle config like args & opts) and the block that will
+  # return the result ({Command#handler}).
   class Command
-    # The name of the command. Also used in {Cogy.bundle_config}.
-    #
     # @return [String]
     attr_reader :name
 
-    # The code that will run when the command is invoked
-    #
     # @return [Proc]
     attr_reader :handler
 
-    # Attributes related to the bundle config in Cog
-    attr_reader :args, :opts, :desc, :long_desc, :examples, :rules
+    # @return [Array]
+    attr_reader :args
+
+    # @return [Hash{Symbol=>Hash}]
+    attr_reader :opts
+
+    # @return [String]
+    attr_reader :desc
+
+    # @return [String]
+    attr_reader :long_desc
+
+    # @return [String]
+    attr_reader :examples
 
-    # The Cog template that the command should use
+    # @return [Array]
+    attr_reader :rules
+
+    # @return [String]
     attr_reader :template
 
-    # See {Cogy.on}
-    def initialize(name, handler, args: [], opts: {}, desc:, long_desc: nil, examples: nil, rules: nil, template: nil)
+    # This is typically used via {Cogy.on} which also registers the newly
+    # created {Command}.
+    #
+    # @param name      [String, Symbol] the name of the command. This is how the
+    #   command will be invoked in the chat.
+    #
+    # @param handler   [Proc] the code that will run when the command is invoked
+    #
+    # @param args      [Array<Symbol, String>, Symbol, String] the arguments
+    #   accepted by the command
+    #
+    # @param opts      [Hash{Symbol=>Hash}] the options accepted by the command
+    # @param desc      [String] the description
+    # @param long_desc [String] the long description
+    # @param examples  [String] usage examples of the command
+    # @param rules     [Array] the command rules
+    # @param template  [String] the name of the template to use
+    #
+    # @raise [ArgumentError] if {#opts} are invalid
+    #
+    # @see Cogy.on
+    def initialize(name, handler, args: [], opts: {}, desc:, long_desc: nil,
+                   examples: nil, rules: nil, template: nil)
       @name = name.to_s
       @handler = handler
       @args = [args].flatten.map!(&:to_s)

data/lib/cogy/context.rb

@@ -1,39 +1,39 @@
 module Cogy
   # {Context} represents a particular invocation request of a {Command}
-  # performed by a user. It holds state like the command arguments, options etc.
+  # performed by a user. It holds state like the given 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.
+  # A {Context} essentially is an HTTP request performed by `cogy:cogy`
+  # (https://github.com/skroutz/cogy-bundle) on behalf of the user.
+  # You can think of it as the equivalent of the ActionPack's `Request` object.
   class Context
-    # @return [Command] the {Command} to be invoked by {Context#invoke}
+    # @return [Command]
     attr_reader :command
 
-    # @return [Array] The Cog command arguments as passed by the user who
-    #   invoked the command.
-    #
-    # @see https://cog-book.operable.io/#_arguments
+    # @return [Array]
     attr_reader :args
 
-    # @return [Hash] The Cog command options as provided by the user who
-    #   invoked the command
-    #
-    # @see https://cog-book.operable.io/#_options
+    # @return [Hash]
     attr_reader :opts
 
-    # @return [String] The chat handle of the user who invoked the command
-    #
-    # @see https://cog-book.operable.io/#_general_metadata
+    # @return [String]
     attr_reader :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
+    # @return [Hash]
     attr_reader :env
 
+    # @param command [Command] the {Command} to be invoked
+    # @param args [Array] the arguments as provided by the user
+    # @param opts [Hash] the options as provided by the user
+    # @param handle [String] the chat handle of the user
+    # @param env [Hash] the Cog Relay environment
+    #
+    # @see https://cog-book.operable.io/#_arguments
+    # @see https://cog-book.operable.io/#_options
+    # @see https://cog-book.operable.io/#_command_environment_variables
+    #
+    # @note By 'user' we refer to the user who invoked the command in chat.
     def initialize(command, args, opts, handle, env)
       @command = command
       @args = args
@@ -44,7 +44,7 @@ module Cogy
       define_arg_helpers
     end
 
-    # Invokes the {Command}
+    # Invokes the command pointed by {#command}.
     #
     # @return [Object] the result of the command. This is what will get printed
     #   back to the user that invoked the command and is effectively the return

data/lib/cogy/version.rb

@@ -1,3 +1,3 @@
 module Cogy
-  VERSION = "0.3.0".freeze
+  VERSION = "0.4.0".freeze
 end

data/lib/cogy.rb

@@ -4,21 +4,18 @@ require "cogy/context"
 
 module Cogy
   # The supported Cog bundle config version.
-  #
-  # @see http://docs.operable.io/docs/bundle-configs
   COG_BUNDLE_VERSION = 4
 
   # Holds all the registered {Command} objects. Not to be messed with.
   @@commands = {}
   mattr_accessor :commands
 
-  # Configuration related to the Cog bundle. Used in {Cogy.bundle_config}
-  # in order to generate the bundle config YAML.
+  # Configuration related to the Cog bundle. Used in {Cogy.bundle_config}.
   #
   # @see https://cog-book.operable.io/#_the_config_file
   @@bundle = {
     # The bundle name
-    name: "cogy",
+    name: "myapp",
 
     # The bundle description
     description: "Cog commands generated from Cogy",
@@ -40,8 +37,6 @@ module Cogy
   mattr_accessor :bundle
 
   # The Cog templates. Used in {Cogy.bundle_config}.
-  #
-  # @see https://cog-book.operable.io/#_templates
   @@templates = {}
   mattr_accessor :templates
 
@@ -50,29 +45,23 @@ module Cogy
   @@command_load_paths = ["cogy"]
   mattr_accessor :command_load_paths
 
-  # Registers a command to Cogy. All the options passed are used solely for
-  # generating the bundle config (ie. {Cogy.bundle_config}). The passed block
-  # is the code that will get executed when the command is invoked.
+  # Initializes a new {Command} and registers it. All the options passed are
+  # used when generating the bundle config in {Cogy.bundle_config}.
   #
-  # The last value of the block is what will get printed as the result of the
-  # command. It should be a string. If you want to return early in a point
-  # inside the block, use `next` instead of `return`.
+  # The given block is the code that will execute when the command is invoked.
+  # The return value of that block is what will get returned as a result
+  # back to Cog.
   #
-  # Inside the command block, there are the public attributes of {Context}
-  # available.
+  # Inside the command block the public attributes of {Context} are
+  # available in addition to any user-defined handlers.
   #
   # @param cmd_name [String, Symbol] the name of the command. This is how the
   #   command will be invoked in the chat.
-  # @param [Hash] opts the options to create the command with. All these options
+  # @param opts [Hash] the options to create the command with. All these options
   #   are used solely for generating the bundle config for Cog, thus they map
   #   directly to Cog's bundle config format.
   #   See https://cog-book.operable.io/#_the_config_file for more information.
-  # @option opts [Array<Symbol, String>, Symbol, String] :args ([])
-  # @option opts [Hash{Symbol=>Hash}] :opts ({})
-  # @option opts [String] :desc required
-  # @option opts [String] :long_desc (nil)
-  # @option opts [String] :examples (nil)
-  # @option opts [Array] :rules (["allow"])
+  #   For documentation on what's supported right now see {Command#initialize}.
   #
   # @example
   #   Cogy.on "calc",
@@ -90,11 +79,10 @@ module Cogy
   #     "Hello #{user}, the answer is: #{result}"
   #   end
   #
-  # @return [void]
+  # @return [Command] the created command
   #
-  # @note If you want to return early in a point inside a command block,
-  #   `next` should be used instead of `return`, due to the way Proc objects
-  #   work in Ruby.
+  # @note to return early inside a command block, `next` should be used instead
+  #   of `return` due to the way Proc objects work in Ruby.
   def self.on(cmd_name, opts = {}, &handler)
     cmd = Command.new(cmd_name, handler, opts)
     cmd.register!
@@ -102,7 +90,7 @@ module Cogy
 
   # Generates the bundle config
   #
-  # @return [Hash]
+  # @return [Hash] the bundle config
   def self.bundle_config
     version = if bundle[:version].respond_to?(:call)
                 bundle[:version].call
@@ -161,14 +149,11 @@ module Cogy
 
   # Defines a user helper method that can be used throughout commands.
   #
-  # @param [Symbol] name the name of the helper
-  # @param [Proc] blk the helper body
+  # @param name [Symbol] the name of the helper
+  # @param blk [Proc] the helper body
   #
   # @return [void]
   #
-  # @note User helpers also have access to the default helpers like `user`, `env`
-  #   etc.
-  #
   # @example
   #   Cogy.configure do |c|
   #     helper(:user) { User.find_by(slack_handle: handle) }
@@ -176,6 +161,9 @@ module Cogy
   #     # a helper that accepts an argument
   #     helper(:format) { |answer| answer.titleize }
   #   end
+  #
+  # @note User helpers also have access to the default helpers like `user`, `env`
+  #   etc.
   def self.helper(name, &blk)
     Context.class_eval { define_method(name, blk) }
   end