cogy 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0a52f4ba6969e9d477a270249cb0bea0b02f10b2
-  data.tar.gz: 22c80dd1dfdd7bb81dce01cac652af4143e9d438
+  metadata.gz: 18759faae517b4afcb5f2f133defd44078b37139
+  data.tar.gz: 23245b995cabda4b944844f5bbac83c4101ceafc
 SHA512:
-  metadata.gz: 7ec4ba0dc2ae8713c5c89176e8a78318347a365a1629d986372f8c8b4779b3501f33e6f0d36090e4ae9c869f5516663c773acb5e1387feb8294357406cf5770d
-  data.tar.gz: f4f50c25f2cf2f2a122728487bf8cbe31f9c3a67f821e84685e2e0c1624136382411c47f90294bad90d75977dd6b85ca7129fe9808112bdbc89405084f44f292
+  metadata.gz: 1934850a9fd090ca2f5917b1528b3e8f7b81274c80e5f05d71835af8f77a74993a45a2d9327f8b49ed737911fbfb38c0de4e5c791306bf49e6f6126cdbed6be7
+  data.tar.gz: 04fedae28608564a6983d5e869d98d38d5c1cabd7e1cb91c131d3ea4c0512c180d481374aaadf1abd3f66cd7bc0e562d210bd7bcc47e1f5a0584bb4e099c3fae

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## master (unreleased)
+
+## 0.2.0 (2016-11-28)
+
+### Added
+
+- Add Capistrano 2 & 3 integration ([#13](https://github.com/skroutz/cogy/issues/13))
+- Add support for defining Cog Templates ([#3](https://github.com/skroutz/cogy/issues/3))
+- Add support for returning JSON to Cog ([#3](https://github.com/skroutz/cogy/issues/3))
+- Arguments can also be accessed by their names ([#53](https://github.com/skroutz/cogy/issues/53))
+
+### Changed
+
+- Bundle-related configuration is now grouped together ([#41](https://github.com/skroutz/cogy/issues/41))
+
+### Fixed
+
+- Cog arguments are now ordered properly ([8a550](https://github.com/skroutz/cogy/commit/8a55004ef80822a816a7c0e3fdd6202d968f8926))
+
+## 0.1.1 (2016-11-25)
+
+### Changed
+
+- Everything in the Rails 4.2 series is now supported ([#47](https://github.com/skroutz/cogy/issues/47))
+- Command options are now validated when initializing a command ([#48](https://github.com/skroutz/cogy/issues/48))

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright 2016 Skroutz S.A.
+Copyright 2016 Agis Anastasopoulos
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -101,21 +101,32 @@ configuration initializer in your application.
 Defining a new command:
 
 ```ruby
-# in cogy/commands.rb
+# in cogy/my_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.
+This will print "bar" back to the user who calls `!foo` in Slack.
+
+Let's define a command that simply adds the numbers passed as arguments:
+
+```ruby
+# in cogy/calculations.rb
+
+on "add", args: [:a, :b], desc: "Add two numbers" do
+  a.to_i + b.to_i
+end
+```
 
 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
+* `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
 
 For instructions on defining your own helpers, see [Helpers](#helpers).
@@ -137,6 +148,76 @@ end
 
 For more examples see the [test commands](https://github.com/skroutz/cogy/tree/master/test/dummy/cogy).
 
+### Returning JSON to Cog
+
+You can return JSON to Cog by just returning a `Hash`:
+
+```ruby
+on "foo", desc: "Just a JSON" do
+  { a: 3 }
+end
+```
+
+The hash automatically gets converted to JSON by Cogy. The above command would return the following response to Cog:
+
+```
+COG_TEMPLATE: foo
+JSON
+{"a":3}
+```
+
+To customize the Cog [template](#Templates) to be used, pass the `template` option:
+
+```ruby
+on "foo", desc: "Just a JSON", template: "bar" do
+  { a: 3 }
+end
+```
+
+Info on how Cog handles JSON can be found in the [official documentation](https://cog-book.operable.io/#_returning_data_from_cog).
+
+### Templates
+
+Templates are defined in their own files under `templates/` inside any of
+the [command load paths](#Configuration). For example:
+
+```
+$ tree
+.
+├── README.rdoc
+├── <..>
+├── cogy
+│   ├── some_commands.rb
+│   └── templates
+│       └── foo # <--- a template named 'foo'
+|── <...>
+```
+
+Given the following template:
+
+```
+# in cogy/templates/foo
+~ hello world ~
+```
+
+the resulting bundle config would look like this:
+
+```yaml
+---
+cog_bundle_version: 4
+name: foo
+description: The bundle you really need
+version: 0.0.1
+commands:
+  <...>
+templates:
+  foo:
+    body: |-
+      ~ hello world ~
+```
+
+Refer to the [Cog book](https://cog-book.operable.io/#_templates) for more on
+templates.
 
 ## Configuration
 
@@ -146,34 +227,42 @@ The configuration options provided are the following:
 # in config/initializers/cogy.rb
 
 Cogy.configure do |config|
-  # Used in the generated bundle config YAML.
-  #
-  # Default: "cogy"
-  config.bundle_name = "myapp"
-
-  # Used in the generated bundle config YAML.
-  #
-  # Default: "Cogy-generated commands"
-  config.bundle_description = "myapp-generated commands from Cogy"
-
-  # Can be either a string or an object that responds to `#call` and returns
-  # a string.
-  config.bundle_version = "0.0.1"
-
-  # 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.
-  #
-  # For example, this will change the version only when a command is
-  # added or is modified (uses the 'grit' gem).
-  config.bundle_version = -> {
-    repo = Grit::Repo.new(Rails.root.to_s)
-    repo.log("HEAD", "cogy/", max_count: 1).first.date.strftime("%y%m%d.%H%M%S")
+  # Configuration related to the generated Cog bundle. Will be used when
+  # generating the bundle config YAML to be installed.
+  config.bundle = {
+    # The bundle name.
+    #
+    # Default: "cogy"
+    name: "myapp",
+
+    # The bundle description
+    #
+    # Default: "Cog commands generated from Cogy"
+    description: "myapp-generated commands from Cogy",
+
+    # The bundle version.
+    #
+    # Can be either a string or an object that responds to `#call` and returns
+    # a string.
+    #
+    # Default: "0.0.1"
+    version: "0.0.1",
+
+    # 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
+    # automatically.
+    #
+    # For example, this will change the version only when a command is
+    # added or is modified (uses the 'grit' gem).
+    version: -> {
+      repo = Grit::Repo.new(Rails.root.to_s)
+      repo.log("HEAD", "cogy/", max_count: 1).first.date.strftime("%y%m%d.%H%M%S")
+    },
+
+    # The path in the Relay where the cogy command executable is located.
+    cogy_executable: "/cogcmd/cogy"
   }
 
-  # The path in the Relay where the cogy command executable is located at.
-  config.executable_path = "/cogcmd/cogy"
-
   # Paths in your application where the files that define the commands live in.
   # For example the default value will search for all `*.rb` files in the `cogy/`
   # directory relative to the root of your application.
@@ -248,6 +337,51 @@ is the following:
 It can be overriden in the application by creating a view in
 `app/views/cogy/error.text.erb`.
 
+## Deployment
+
+Cogy provides the `cogy:notify_cog` task for Capistrano. The following options
+need to be set:
+
+* `cogy_release_trigger_url`: This is the URL of the Cog Trigger that will
+  install the newly deployed bundle (ie. `!cogy:install`).
+* `cogy_endpoint`: Where the Cogy Engine is mounted at.
+  For example `http://myapp.com/cogy`.
+
+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).
+
+### Capistrano 2
+
+Add the following in `config/deploy.rb`:
+
+```ruby
+# in config/deploy.rb
+require "cogy/capistrano"
+
+set :cogy_release_trigger_url, "<TRIGGER-INVOCATION-URL>"
+set :cogy_endpoint, "<COGY-MOUNT-POINT>"
+```
+
+The `cogy:notify_cog` task is automatically hooked after `deploy:restart`.
+
+### Capistrano 3
+
+Add the following in your Capfile:
+
+```ruby
+require "cogy/capistrano"
+```
+
+The `cogy:notify_cog` task should be manually hooked after the task that
+restarts the application. For example:
+
+```ruby
+# in config/deploy.rb
+after "deploy:restart_app", "cogy:notify_cog"
+```
+
 ## Development
 
 Running the tests and RuboCop:

data/app/controllers/cogy/cogy_controller.rb

@@ -12,7 +12,9 @@ module Cogy
     # See https://github.com/skroutz/cogy-bundle.
     def command
       cmd = params[:cmd]
-      args = request.query_parameters.select { |k, _| k.start_with?("cog_argv_") }.values
+      args = request.query_parameters.select { |k, _| k.start_with?("cog_argv_") }
+                    .sort_by { |k, _| k.match(/\d+\z/)[0] }.to_h.values
+
       opts = request.query_parameters.select { |k, _| k.start_with?("cog_opt_") }
                     .transform_keys { |k| k.sub("cog_opt_", "") }
       cogy_env = request.query_parameters.select { |k, _| k.start_with?("cogy_") }
@@ -20,8 +22,13 @@ module Cogy
 
       begin
         if (command = Cogy.commands[cmd])
-          context = Context.new(args, opts, user, cogy_env)
-          render text: context.run!(command)
+          result = Context.new(command, args, opts, user, cogy_env).invoke
+          if result.is_a?(Hash)
+            result = "COG_TEMPLATE: #{command.template || command.name}\n" \
+                     "JSON\n" \
+                     "#{result.to_json}"
+          end
+          render text: result
         else
           render status: 404, text: "The command '#{cmd}' does not exist."
         end

data/lib/cogy/capistrano/cogy.rake

@@ -0,0 +1,30 @@
+namespace :cogy do
+  desc "Invoke the Cog Trigger that will install the Cogy-generated bundle"
+  task :notify_cog do
+    require "net/http"
+    require "timeout"
+    require "json"
+
+    trigger_url = fetch(:cogy_release_trigger_url)
+    cogy_endpoint = fetch(:cogy_endpoint)
+
+    begin
+      raise ":cogy_release_trigger_url must be set" if trigger_url.nil?
+      raise ":cogy_endpoint must be set" if cogy_endpoint.nil?
+
+      Timeout.timeout(fetch(:cogy_trigger_timeout) || 7) do
+        url = URI(trigger_url)
+        res = Net::HTTP.post_form(url, url: cogy_endpoint)
+
+        if !res.is_a?(Net::HTTPSuccess)
+          error = JSON.parse(res.body)["errors"]["error_message"]
+          if error !~ /version has already been taken/
+            puts "Error response (#{res.code}) from Cog trigger: #{error}"
+          end
+        end
+      end
+    rescue => e
+      puts "Error invoking Cog trigger: #{e.class} #{e.message}"
+    end
+  end
+end

data/lib/cogy/capistrano.rb

@@ -1 +1,15 @@
-require "cogy/capistrano/v2/tasks"
+require "capistrano/version"
+
+if defined?(Capistrano::VERSION) && Gem::Version.new(Capistrano::VERSION).release >= Gem::Version.new("3.0.0")
+  load File.expand_path("../capistrano/cogy.rake", __FILE__)
+else
+  Capistrano::Configuration.instance(:must_exist).load do
+    _cset(:cogy_release_trigger_url) { nil }
+    _cset(:cogy_endpoint)            { nil }
+    _cset(:cogy_trigger_timeout)     { nil }
+
+    load File.expand_path("../capistrano/cogy.rake", __FILE__)
+
+    after "deploy:restart", "cogy:notify_cog"
+  end
+end

data/lib/cogy/command.rb

@@ -17,8 +17,11 @@ module Cogy
     # Attributes related to the bundle config in Cog
     attr_reader :args, :opts, :desc, :long_desc, :examples, :rules
 
+    # The Cog template that the command should use
+    attr_reader :template
+
     # See {Cogy.on}
-    def initialize(name, handler, args: [], opts: {}, desc:, long_desc: nil, examples: nil, rules: nil)
+    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)
@@ -27,6 +30,7 @@ module Cogy
       @long_desc = long_desc
       @examples = examples
       @rules = rules || ["allow"]
+      @template = template
 
       validate_opts
     end

data/lib/cogy/context.rb

@@ -8,6 +8,9 @@ module 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 [Command] the {Command} to be invoked by {Context#invoke}
+    attr_reader :command
+
     # @return [Array] The Cog command arguments as passed by the user who
     #   invoked the command.
     #
@@ -31,22 +34,49 @@ module Cogy
     # @see https://github.com/skroutz/cogy-bundle/blob/master/commands/cogy
     attr_reader :env
 
-    def initialize(args, opts, handle, env)
+    def initialize(command, args, opts, handle, env)
+      @command = command
       @args = args
       @opts = opts
       @handle = handle
       @env = env
+
+      define_arg_helpers
     end
 
-    # Executes a {Command} in the context of {self}.
-    #
-    # @param [Command] cmd the {Command} to be executed
+    # Invokes the {Command}
     #
-    # @return [String] the result of the command. This is what will get printed
+    # @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
     #   value of the command body.
-    def run!(cmd)
-      instance_eval(&cmd.handler)
+    def invoke
+      instance_eval(&command.handler)
+    end
+
+    private
+
+    # Defines helpers for accessing the arguments of the respective {Command}
+    # by their name.
+    #
+    # For example, assuming a command:
+    #
+    #     on "foo", args: [:a, :b] do
+    #       a + b
+    #     end
+    #
+    # If this was called with the arguments "foo" and "bar", it would return
+    # "foobar".
+    #
+    # @note Keep in mind that these helpers override the attribute readers
+    #   of {Context}, so you're advised to avoid naming arguments with words
+    #   like "args", "opts" etc.
+    #
+    # @todo We may want to implement a protection against overriding reserved
+    #   words
+    def define_arg_helpers
+      command.args.each_with_index do |arg, i|
+        define_singleton_method(arg) { args[i] }
+      end
     end
   end
 end

data/lib/cogy/engine.rb

@@ -1,11 +1,23 @@
+require "pathname"
+
 module Cogy
   class Engine < ::Rails::Engine
     isolate_namespace Cogy
 
     config.after_initialize do
       Cogy.command_load_paths.each do |path|
+        # Add commands
         files = Dir[Rails.root.join(path, "*.rb")]
         files.each { |f| Cogy.module_eval(File.read(f)) }
+
+        # Add templates
+        templates = Dir[Rails.root.join(path, "templates", "*")]
+                    .select { |f| File.file?(f) }
+
+        templates.each do |t|
+          fname = Pathname(t).basename.to_s
+          Cogy.templates[fname] = { "body" => File.read(t).strip }
+        end
       end
 
       Context.include(Rails.application.routes.url_helpers)

data/lib/cogy/version.rb

@@ -1,3 +1,3 @@
 module Cogy
-  VERSION = "0.1.1".freeze
+  VERSION = "0.2.0".freeze
 end

data/lib/cogy.rb

@@ -12,35 +12,38 @@ module Cogy
   @@commands = {}
   mattr_accessor :commands
 
-  # The Cog bundle name.
-  #
-  # Used by {Cogy.bundle_config}.
-  @@bundle_name = "cogy"
-  mattr_accessor :bundle_name
-
-  # The Cog bundle description.
-  #
-  # Used by {Cogy.bundle_config}.
-  @@bundle_description = "Cogy-generated commands"
-  mattr_accessor :bundle_description
-
-  # The Cog bundle version. Can be either a string or an object that responds
-  # to `#call` and returns a string. Used by {Cogy.bundle_config}.
-  #
-  # Used by {Cogy.bundle_config}.
-  #
-  # @example
-  #   bundle_version = -> { rand(2).to_s }
-  @@bundle_version = "0.0.1"
-  mattr_accessor :bundle_version
-
-  # The path in the Cog Relay where the cogy executable
-  # (ie. https://github.com/skroutz/cogy-bundle/blob/master/commands/cogy) is
-  # located.
-  #
-  # Used by {Cogy.bundle_config}.
-  @@executable_path = "/usr/bin/cogy"
-  mattr_accessor :executable_path
+  # Configuration related to the Cog bundle. Used in {Cogy.bundle_config}
+  # in order to generate the bundle config YAML.
+  #
+  # @see https://cog-book.operable.io/#_the_config_file
+  @@bundle = {
+    # The bundle name
+    name: "cogy",
+
+    # The bundle description
+    description: "Cog commands generated from Cogy",
+
+    # The bundle version.
+    #
+    # Can also be an object that responds to `#call` and returns a string. For
+    # example:
+    #
+    #   -> { rand(1).to_s }
+    #
+    version: "0.0.1",
+
+    # The path in the Cog Relay where the cogy executable
+    # (ie. https://github.com/skroutz/cogy-bundle/blob/master/commands/cogy) is
+    # located.
+    cogy_executable: "/usr/bin/cogy"
+  }
+  mattr_accessor :bundle
+
+  # The Cog templates. Used in {Cogy.bundle_config}.
+  #
+  # @see https://cog-book.operable.io/#_templates
+  @@templates = {}
+  mattr_accessor :templates
 
   # Paths where the files that define the commands will be searched in the
   # host application.
@@ -101,16 +104,16 @@ module Cogy
   #
   # @return [Hash]
   def self.bundle_config
-    version = if bundle_version.respond_to?(:call)
-                bundle_version.call
+    version = if bundle[:version].respond_to?(:call)
+                bundle[:version].call
               else
-                bundle_version
+                bundle[:version]
               end
 
     config = {
       "cog_bundle_version" => COG_BUNDLE_VERSION,
-      "name" => bundle_name,
-      "description" => bundle_description,
+      "name" => bundle[:name],
+      "description" => bundle[:description],
       "version" => version
     }
 
@@ -118,7 +121,7 @@ module Cogy
 
     commands.each do |name, cmd|
       config["commands"][name] = {
-        "executable" => executable_path,
+        "executable" => bundle[:cogy_executable],
         "description" => cmd.desc,
         "rules" => cmd.rules
       }
@@ -140,18 +143,18 @@ module Cogy
       end
     end
 
+    config["templates"] = templates if !templates.empty?
+
     config
   end
 
   # Configures Cogy according to the passed block.
   #
-  # @example
-  #   Cogy.configure do |c|
-  #     c.bundle_name = "foo"
-  #   end
-  #
   # @yield [self] yields {Cogy}
+  #
   # @return [void]
+  #
+  # @see https://github.com/skroutz/cogy#configuration
   def self.configure
     yield self
   end

data/lib/generators/cogy/templates/cogy_config.rb

@@ -1,8 +1,11 @@
 # See https://github.com/skroutz/cogy#configuration
 Cogy.configure do |config|
-  #config.bundle_name = "myapp"
-  #config.bundle_description = "Cog commands generated from myapp"
-  #config.bundle_version = "0.0.1"
-  #config.executable_path = "/usr/bin/cogy"
+  #config.bundle = {
+  #  name: "myapp",
+  #  description: "Cog commands generated from myapp",
+  #  version: "0.0.1",
+  #  cogy_executable: "/usr/bin/cogy"
+  #}
+  #
   #config.command_load_paths = ["cogy"]
 end

data/test/dummy/cogy/builtin_helpers.rb

@@ -0,0 +1,11 @@
+on "args_overrides", args: [:handle, :bar], desc: "" do
+  handle + bar
+end
+
+on "empty_args", args: [:a, :b], desc: "" do
+  "#{a.nil? && b.nil?}"
+end
+
+on "add", args: [:a, :b], desc: "Add two numbers" do
+  a.to_i + b.to_i
+end

data/test/dummy/cogy/foo.rb

@@ -22,3 +22,6 @@ on "titleize", desc: "" do
   bar "this should be titleized"
 end
 
+on "args_order", args: [:a, :b, :c], desc: "" do
+  args.join
+end

data/test/dummy/cogy/json_response.rb

@@ -0,0 +1,7 @@
+on "simple_json", desc: "" do
+  { a: 3, b: 4 }
+end
+
+on "custom_template", desc: "", template: "foo" do
+  { a: 3 }
+end

data/test/dummy/cogy/templates/pretty-command

@@ -0,0 +1,5 @@
+**foo:** ~$results[0].name~
+
+~br~
+
+foo

data/test/dummy/config/initializers/cogy.rb

@@ -1,8 +1,11 @@
 Cogy.configure do |c|
-  c.bundle_name = "foo"
-  c.bundle_description = "The bundle you really need"
-  c.bundle_version = "0.0.1"
-  c.executable_path = "/usr/bin/foo"
+  c.bundle = {
+    name: "foo",
+    description: "The bundle you really need",
+    version: "0.0.1",
+    cogy_executable: "/usr/bin/foo"
+  }
+
   c.command_load_paths = ["cogy"]
 
   c.helper(:foo) { env["cogy_foo"] }