For more examples see the [test commands](https://github.com/skroutz/cogy/tree/master/test/dummies/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 is automatically converted to JSON. 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, use 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](https://cog-book.operable.io/#_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

The configuration options provided are the following:

```ruby
# in config/initializers/cogy.rb

Cogy.configure do |config|
# 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: "myapp"
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 endpoint where Cogy is reachable at. This depends on where you've
# mounted the Cogy engine at.
cogy_endpoint: "http://www.example.com/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.
#
# Default: ["cogy"]
config.command_load_paths = "cogy"
end

```

You can use the generator to quickly create a config initializer in your app:

```shell
$ bin/rails g cogy:config
```

### Helpers

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 the `address` of a `Shop` record:
command:

```ruby
Cogy.configure do |c|
c.helper(:shop_address) { Shop.find_by(owner: handle).address }
end
```

*(Note that custom helpers also have access to the default helpers like
`handle`, `args` etc.)*

Then we could have a command that makes use of the helper:

```ruby
on "shop_address", desc: "Returns the user's Shop address" do
"@#{handle}: Your shop's address is #{shop_address}"
end
```

Helpers may also accept arguments:

```ruby
Cogy.configure do |c|
c.helper(:format) { |answer| answer.titleize }
end
```

This helper could be called like so:

```ruby
on "foo", desc: "Nothing special" do
format "hello there, how are you today?"
end
```

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
is the following:

@<%= @user %>: Command '<%= @cmd %>' returned an error.

```
<%= @exception.class %>:<%= @exception.message %>
```

It can be overriden in the application by creating a view in
`app/views/cogy/error.text.erb`.

## Testing commands

We don't yet provide means to write tests for the commands, but you can easily
test them by executing a request to your development server. For example,
if you mounted the engine like so:

```ruby
mount Cogy::Engine, at: "cogy"
```

you can test a `foo` command like this:

```shell
$ curl -XPOST --data "COG_ARGV_0=foo" http://localhost:3000/cogy/cmd/foo
```

In the request body you may pass the complete or any part of the
[Cog environment](https://cog-book.operable.io/#_command_environment_variables) you need.

This is essentially what the [cogy executable](https://github.com/skroutz/cogy-bundle)
also does.

## Deployment

Cogy provides integration with Capistrano 2 & 3.

There is just one task, `cogy:notify_cog`, which 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:

* `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 code of 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, ""
set :cogy_endpoint, ""

after "deploy:restart", "cogy:notify_cog"
```

### Capistrano 3

Add the following in your Capfile:

```ruby
require "cogy/capistrano"
```

Then configure the task and hook it:

```ruby
# in config/deploy.rb

set :cogy_release_trigger_url, ""
set :cogy_endpoint, ""

after "", "cogy:notify_cog"
```

### 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.

## Development

Running the tests and RuboCop for the latest Rails version:

```shell
$ rake
```

Running just the tests:

```shell
$ rake test
```

Running RuboCop:

```shell
$ rake rubocop
```

Generating documentation:

```shell
$ rake yard
```

Running the tests for all the supported Rails versions:

```shell
$ appraisal rake
```

Or for a specific version:

```shell
$ appraisal 4.2 rake test
```

## Authors

* [Agis Anastasopoulos](https://github.com/agis-)
* [Mpampis Kostas](https://github.com/charkost)

## License