hubot 5.0.5 → 5.0.6

package/docs/deploying/heroku.md

@@ -1,66 +0,0 @@
----
-permalink: /docs/deploying/heroku/
----
-
-# Deploying to Heroku
-
-If you've been following along with [Getting Started](../index.md), it's time to deploy so you can use it beyond just your local machine.
-[Heroku](http://www.heroku.com/) is an easy and supported way to deploy hubot.
-
-Install the [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) to start, then follow their '[Getting Started](https://devcenter.heroku.com/articles/heroku-cli#getting-started)' instructions, including logging in the first time:
-
-    % heroku login
-    Enter your Heroku credentials.
-    Email: youremail@example.com
-    Password:
-    Could not find an existing public key.
-    Would you like to generate one? [Yn]
-    Generating new SSH public key.
-    Uploading ssh public key /Users/you/.ssh/id_rsa.pub
-
-Inside your new hubot directory, make sure you've created a git repository, and that your work is committed:
-
-    % git init
-    % git add .
-    % git commit -m "Initial commit"
-
-Then create a Heroku application:
-
-    % heroku create
-    Creating rosemary-britches-123... done, stack is cedar
-    http://rosemary-britches-123.herokuapp.com/ | git@heroku.com:rosemary-britches-123.git
-    Git remote heroku added
-
-Before you deploy the application, you'll need to configure some environment
-variables for hubot to use. The specific variables you'll need depends on which
-[adapter](../adapters.md) and scripts you are using. For Campfire, with no other
-scripts, you'd need to set the following environment variables:
-
-    % heroku config:set HUBOT_CAMPFIRE_ACCOUNT=yourcampfireaccount
-    % heroku config:set HUBOT_CAMPFIRE_TOKEN=yourcampfiretoken
-    % heroku config:set HUBOT_CAMPFIRE_ROOMS=comma,separated,list,of,rooms,to,join
-
-At this point, you are ready to deploy and start chatting. With Heroku, that's a
-git push away:
-
-    % git push heroku main
-
-You'll see some text flying, and eventually some success. You should be able to
-see your bot in your configured chat rooms at this point. If not, you can peek
-at the logs to try to debug:
-
-    % heroku logs
-
-If you make any changes to your hubot, just commit and push them as
-before:
-
-    % git commit -am "Awesome scripts OMG"
-    % git push heroku main
-
-Some scripts needs Redis to work, Heroku offers an addon called [Redis Cloud](https://addons.heroku.com/rediscloud), which has a free plan. To use it:
-
-    % heroku addons:create rediscloud
-
-Note: the free redis plans don't offer any persistence so your hubot will lose all the information when it goes to sleep.
-
-Free dynos on Heroku will [sleep after 30 minutes of inactivity](https://devcenter.heroku.com/articles/dyno-sleeping). That means your hubot would leave the chat room and only rejoin when it does get traffic. This is extremely inconvenient since most interaction is done through chat, and hubot has to be online and in the room to respond to messages. To get around this, you can use the [hubot-heroku-keepalive](https://github.com/hubot-scripts/hubot-heroku-keepalive) script, which will keep your free dyno alive for up to 18 hours/day. If you never want Hubot to sleep, you will need to [upgrade to Heroku's hobby plan](https://www.heroku.com/pricing).

package/docs/deploying/unix.md

@@ -1,72 +0,0 @@
----
-permalink: /docs/deploying/unix/
----
-
-# Deploying to Unix
-
-Because there are so many variations of Linux, and more generally UNIX, it's
-difficult for the hubot team to have canonical documentation for installing and
-deploying it to every version out there. So, this is an attempt to give an
-overview of what's needed to get deploying.
-
-There are 3 primary things to deploying and running hubot:
-
-  * node and npm
-  * a way to get source code updated on the server
-  * a way to start hubot, start it up if it crashes, and restart it when code
-    updates
-
-## node and npm
-
-To start, your UNIX server will need node and npm. Check out the node.js wiki
-for [installing Node.js via package manager](https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager), [Building on GNU/Linux and other UNIX](https://github.com/joyent/node/wiki/Installation#building-on-gnulinux-and-other-unix).
-
-## Updating code on the server
-
-The simplest way to update your hubot's code is going to be to have a git
-checkout of your hubot's source code (that you've created during [Getting Started](../index.md), not the [github/hubot repository](http://github.com/github/hubot), and just git pull to get change. This may
-feel a dirty hack, but it works when you are starting out.
-
-If you have a Ruby background, you might be more comfortable using
-[capistrano](https://github.com/capistrano/capistrano).
-
-If you have a [Chef](http://www.chef.io/chef/) background, there's a
-[deploy](https://docs.chef.io/resource_deploy.html) resource for managing
-deployments.
-
-## Starting, stopping, and restarting hubot
-
-Every hubot install has a `bin/hubot` script to handle starting up the hubot.
-You can run this command from your git checkout on the server, but there are some problems you can encounter:
-
-* you disconnect, and hubot dies
-* hubot dies, for any reason, and doesn't start again
-* it doesn't start up at boot automatically
-
-For handling you disconnecting, you can start with running `bin/hubot` in
-[screen session](http://www.gnu.org/software/screen/) or with
-[nohup](http://linux.die.net/man/1/nohup).
-
-For handling hubot dying, and restarting it automatically, you can imagine
-running `bin/hubot` in a
-[bash while loop](http://tldp.org/HOWTO/Bash-Prog-Intro-HOWTO-7.html#ss7.3). But
-really, you probably want some process monitoring using tools like
-[monit](http://mmonit.com/monit/),
-[god](http://godrb.com/),
-[bluepill](https://github.com/arya/bluepill),
-[upstart](http://upstart.ubuntu.com/),
-[runit](http://smarden.org/runit/),
-[systemd](http://freedesktop.org/wiki/Software/systemd/).
-
-For starting at boot, you can create an init script appropriate for your UNIX
-distribution. If you are using one of the process monitoring tools above, make
-sure it boots at startup. See the [examples](https://github.com/github/hubot/tree/main/examples)
-for configuration examples.
-
-## Recommendations
-
-This document has been deliberately light on strong recommendations. At a high
-level though, it's strongly recommended to avoid anything that is overly manual
-and non-repeatable. That would mean using your OS's packages and tools whenever
-possible, and having a proper deploy tool to update hubot, and process
-management to keep hubot running.

package/docs/deploying/windows.md

@@ -1,66 +0,0 @@
----
-permalink: /docs/deploying/windows/
----
-
-# Deploying to Windows
-
-Hasn't been fully tested - YMMV
-
-There are 4 primary steps to deploying and running hubot on a Windows machine:
-
-* node and npm
-* a way to get source code updated on the server
-* setting up environment variables for hubot
-* a way to start hubot, start it up if it crashes, and restart it when code updates
-
-## node and npm
-
-To start, your windows server will need node and npm.
-The best way to do this is with [chocolatey](http://chocolatey.org) using the [nodejs.install](http://chocolatey.org/packages/nodejs.install) package.
-I've found that sometimes the system path variable is not correctly set; ensure you can run node/npm from the command line. If needed set the PATH variable with `set PATH=%PATH%;\"C:\Program Files\nodejs\"`
-
-Your other option is to install directly from [NodeJS](https://nodejs.org/) and run the current download (v0.12.4 as of this documentation). This should set your PATH variables for you.
-
-## Updating code on the server
-
-To get the code on your server, you can follow the instructions at [Getting Started](../index.md) on your local development machine or directly on the server. If you are building locally, push your hubot to GitHub and clone the repo onto your server. Don't clone the normal [github/hubot repository](http://github.com/github/hubot), make sure you're using the Yo Generator to build your own hubot.
-
-## Setting up environment vars
-
-You will want to set up your hubot environment variables on the server where it will run. You can do this by opening an administrative PowerShell and typing the following:
-
-    [Environment]::SetEnvironmentVariable("HUBOT_ADAPTER", "Campfire", "Machine")
-
-This is equivalent to going into the system menu -> selecting advanced system settings -> environment vars and adding a new system variable called HUBOT_ADAPTER with the value of Campfire.
-
-## Starting, stopping, and restarting hubot
-
-Every hubot install has a `bin/hubot` script to handle starting up the hubot.
-You can run this command directly from your hubot folder by typing the following:
-
-    .\bin\hubot –adapter campfire
-
-There are a few issues if you call it manually, though.
-
-* you disconnect, and hubot dies
-* hubot dies, for any reason, and doesn't start again
-* it doesn't start up at boot automatically
-
-To fix this, you will want to create a .ps1 file with whatever name makes you happy that you will call from your hubot directory. There is a copy of this file in the `examples` directory [here](../../examples/hubot-start.ps1). It should contain the following:
-
-    Write-Host "Starting Hubot Watcher"
-    While (1)
-    {
-        Write-Host "Starting Hubot"
-        Start-Process powershell -ArgumentList ".\bin\hubot –adapter slack" -wait
-    }
-
-Remember to allow local unsigned PowerShell scripts if you are using the .ps1 file to run hubot. Run this command in an Administrator PowerShell window.
-
-    Set-ExecutionPolicy RemoteSigned
-
-You can set this .ps1 as scheduled task on boot if you like or some other way to start your process.
-
-## Expanding the documentation
-
-Not yet fleshed out. [Help contribute by submitting a pull request, please?](https://github.com/github/hubot/pull/new/main)

package/docs/deploying.md

@@ -1,11 +0,0 @@
----
-permalink: /docs/deploying/
----
-
-# Deploying
-
-- [Azure](./deploying/azure.md)
-- [Bluemix](./deploying/bluemix.md)
-- [Heroku](./deploying/heroku.md)
-- [Unix](./deploying/unix.md)
-- [Windows](./deploying/windows.md)

package/docs/implementation.md

@@ -1,55 +0,0 @@
----
-title: Implementation Notes
-permalink: /docs/implementation/
----
-
-# Implementation
-
-For the purpose of maintainability, several internal flows are documented here.
-
-## Message Processing
-
-When a new message is received by an adapter, a new Message object is constructed and passed to `robot.receive` (async). `robot.receive` then attempts to execute each Listener in order of registration by calling `listener.call` (async), passing in the Listener Middleware stack. `listener.call` first checks to see if the listener matches (`match` method, sync), and if so, calls `middleware.execute` (async) on the provided middleware.
-
-`middleware.execute` calls each middleware in order of registration. Middleware can either continue forward (call `next`) or abort (call `done`). If all middleware continues, `middleware.execute` calls `next` (the `listener.call` callback). If any middleware aborts, `middleware.execute` calls `done` (which eventually returns to the `robot.receive` callback).
-
-`middleware.execute` `next` returns to `listener.call`, which executes the matched Listener's callback and then calls the `robot.receive` callback.
-
-Inside the `robot.receive` processing loop, `message.done` is checked after each `listener.call`. If the message has been marked as done, `robot.receive` returns. This correctly handles asynchronous middleware, but will not catch an asynchronous set of `message.done` inside the listener callback (which is expected to be synchronous).
-
-If no listener matches the message (distinct from setting `message.done`), a CatchAllMessage is created which wraps the original message. This new message is run through all listeners again testing for a match. `robot.catchAll` creates a special listener that only matches CatchAllMessages.
-
-## Listeners
-
-Listeners are registered using several functions on the `robot` object: `hear`, `respond`, `enter`, `leave`, `topic`, and `catchAll`.
-
-A listener is used via its `call` method, which is responsible for testing to see if a message matches (`match` is an abstract method) and if so, executes the listener's callback.
-
-Listener callbacks are assumed to be synchronous.
-
-## Middleware
-
-There are two primary entry points for middleware:
-
-1. `robot.listenerMiddleware` - registers a new piece of middleware in a global array
-2. `middleware.execute` - executes all registered middleware in order
-
-## Persistence
-
-### Brain
-
-Hubot has a memory exposed as the `robot.brain` object that can be used to store and retrieve data.
-Furthermore, Hubot scripts exist to enable persistence across Hubot restarts.
-`hubot-redis-brain` is such a script and uses a backend Redis server.
-
-By default, the brain contains a list of all users seen by Hubot.
-Therefore, without persistence across restarts, the brain will contain the list of users encountered so far, during the current run of Hubot. On the other hand, with persistence across restarts, the brain will contain all users encountered by Hubot during all of its runs. This list of users can be accessed through `hubot.brain.users()` and other utility methods.
-
-### Datastore
-
-Hubot's optional datastore, exposed as the `robot.datastore` object, provides a more robust persistence model. Compared to the brain, the datastore:
-
-1. Is always (instead of optionally) backed by a database
-2. Fetches data from the database and stores data in the database on every request, instead of periodically persisting the entire in-memory brain.
-
-The datastore is useful in cases where there's a need for greater reassurances of data integrity or in cases where multiple Hubot instances need to access the same database.

package/docs/index.md

@@ -1,125 +0,0 @@
----
-permalink: /docs/
----
-
-## Getting Started With Hubot
-
-You will need [node.js and npm](https://docs.npmjs.com/getting-started/installing-node). Once those are installed, we can install the hubot generator:
-
-    %  npm install -g yo generator-hubot
-
-This will give us the `hubot` [yeoman](http://yeoman.io/) generator. Now we
-can make a new directory, and generate a new instance of hubot in it. For example, if
-we wanted to make a bot called myhubot:
-
-
-    % mkdir myhubot
-    % cd myhubot
-    % yo hubot
-
-At this point, you'll be asked a few questions about who is creating the bot,
-and which [adapter](adapters.md) you'll be using. Adapters are hubot's
-way of integrating with different chat providers.
-
-If you are using git, the generated directory includes a .gitignore, so you can
-initialize and add everything:
-
-    % git init
-    % git add .
-    % git commit -m "Initial commit"
-
-If you'd prefer to automate your hubot build without being interactively
-prompted for its configuration, you can add the following options
-to the `yo hubot` command to do so:
-
-| Option                                      | Description                                            |
-|:--------------------------------------------|:-------------------------------------------------------|
-| `--owner="Bot Wrangler <bw@example.com>"`   | Bot owner, e.g. "Bot Wrangler <bw@example.com>"        |
-| `--name="Hubot"`                            | Bot name, e.g. "Hubot"                                 |
-| `--description="Delightfully aware robutt"` | Bot description, e.g. "Delightfully aware robutt"      |
-| `--adapter=campfire`                        | Bot adapter, e.g. "campfire"                           |
-| `--defaults`                                | Declare all defaults are set and no prompting required |
-
-You now have your own functional hubot! There's a `bin/hubot`
-command for convenience, to handle installing npm dependencies, loading scripts,
-and then launching your hubot.
-
-Note: Hubot can use Redis to persist data, so before you can start hubot on your own computer, if you want to persist data, then you should have Redis running on your machine accessible via `localhost`. Then, ensure that `hubot-redis-brain` is listed in `external-scripts.json` as an `Array` of module names (e.g. `['hubot-redis-brain']`) or an `object` where the key is the name of the module (e.g. `{'hubot-redis-brain': 'some arbitrary value'}`) where the value of the property in the object is passed to the module function as the second argument. The first argument being the hubot Robot instance.
-
-    % bin/hubot
-    Hubot>
-
-This starts hubot using the [shell adapter](./adapters/shell.md), which is mostly useful for development. Make note of the name in the `hubot>` prompt; this is the name your hubot will respond to with commands. If the prompt reads `myhubot>` then your commands must start with `myhubot <command>`.
-
-For example, to list available commands:
-
-    % bin/hubot
-    myhubot> myhubot help
-    myhubot> Shell: myhubot adapter - Reply with the adapter
-    myhubot animate me <query> - The same thing as `image me`, except adds a few parameters to try to return an animated GIF instead.
-    myhubot echo <text> - Reply back with <text>
-    myhubot help - Displays all of the help commands that Hubot knows about.
-    myhubot help <query> - Displays all help commands that match <query>.
-    myhubot image me <query> - The Original. Queries Google Images for <query> and returns a random top result.
-    myhubot map me <query> - Returns a map view of the area returned by `query`.
-    myhubot mustache me <url|query> - Adds a mustache to the specified URL or query result.
-    myhubot ping - Reply with pong
-    myhubot pug bomb N - get N pugs
-    myhubot pug me - Receive a pug
-    myhubot the rules - Make sure hubot still knows the rules.
-    myhubot time - Reply with current time
-    myhubot translate me <phrase> - Searches for a translation for the <phrase> and then prints that bad boy out.
-    myhubot translate me from <source> into <target> <phrase> - Translates <phrase> from <source> into <target>. Both <source> and <target> are optional
-    ship it - Display a motivation squirrel
-
-You almost definitely will want to change your hubot's name to add character. bin/hubot takes a `--name`:
-
-    % bin/hubot --name sam
-    sam>
-
-Your hubot will now respond as `sam`. This is
-case-insensitive, and can be prefixed with `@` or suffixed with `:`. These are equivalent:
-
-    SAM help
-    sam help
-    @sam help
-    sam: help
-
-## Scripts
-
-Hubot's power comes through scripts. There are hundreds of scripts written and maintained by the community. Find them by searching the [NPM registry](https://www.npmjs.com/browse/keyword/hubot-scripts) for `hubot-scripts <your-search-term>`. For example:
-
-```
-$ npm search hubot-scripts github
-NAME                  DESCRIPTION
-hubot-deployer        Giving Hubot the ability to deploy GitHub repos to PaaS providers hubot hubot-scripts hubot-gith
-hubot-gh-release-pr   A hubot script to create GitHub's PR for release
-hubot-github          Giving Hubot the ability to be a vital member of your github organization
-…
-```
-
-To use a script from an NPM package:
-
-1. Run `npm install --save <package-name>` to add the package as a dependency and install it.
-2. Add the package to `external-scripts.json`.
-3. Run `npm home <package-name>` to open a browser window for the homepage of the script, where you can find more information about configuring and installing the script.
-
-You can also put your own scripts under the `scripts/` directory. All scripts (files ending with either `.js` or `.mjs`) placed there are automatically loaded and ready to use with your hubot. Read more about customizing hubot by [writing your own scripts](scripting.md).
-
-## Adapters
-
-Hubot uses the adapter pattern to support multiple chat-backends. Here is a [list of available adapters](adapters.md), along with details on how to configure them.
-
-## Deploying
-
-You can deploy hubot to Heroku, which is the officially supported method. Additionally you are able to deploy hubot to a UNIX-like system or Windows. Please note the support for deploying to Windows isn't officially supported.
-
-* [Deploying Hubot onto Azure](./deploying/azure.md)
-* [Deploying Hubot onto Bluemix](./deploying/bluemix.md)
-* [Deploying Hubot onto Heroku](./deploying/heroku.md)
-* [Deploying Hubot onto Unix](./deploying/unix.md)
-* [Deploying Hubot onto Windows](./deploying/windows.md)
-
-## Patterns
-
-Using custom scripts, you can quickly customize Hubot to be the most life embettering robot he or she can be. Read [docs/patterns.md](patterns.md) for some nifty tricks that may come in handy as you teach your hubot new skills.

package/docs/patterns.md

@@ -1,265 +0,0 @@
----
-permalink: /docs/patterns/
----
-
-# Patterns
-
-Shared patterns for dealing with common Hubot scenarios.
-
-## Renaming the Hubot instance
-
-When you rename Hubot, he will no longer respond to his former name. In order to train your users on the new name, you may choose to add a deprecation notice when they try to say the old name. The pattern logic is:
-
-* listen to all messages that start with the old name
-* reply to the user letting them know about the new name
-
-Setting this up is very easy:
-
-1. Create a [bundled script](scripting.md) in the `scripts/` directory of your Hubot instance called `rename-hubot.js`
-2. Add the following code, modified for your needs:
-
-```javascript
-//  Description:
-//    Tell people hubot's new name if they use the old one
-
-//  Commands:
-//    None
-
-module.exports = (robot) => {
-  robot.hear(/^hubot:? (.+)/i, (res) => {
-    let response = `Sorry, I'm a diva and only respond to ${robot.name}`
-    response += robot.alias ? ` or ${robot.alias}` : ''
-    return res.reply(response)
-  })
-}
-```
-
-In the above pattern, modify both the hubot listener and the response message to suit your needs.
-
-Also, it's important to note that the listener should be based on what hubot actually hears, instead of what is typed into the chat program before the Hubot Adapter has processed it. For example, the [HipChat Adapter](https://github.com/hipchat/hubot-hipchat) converts `@hubot` into `hubot:` before passing it to Hubot.
-
-## Deprecating or Renaming Listeners
-
-If you remove a script or change the commands for a script, it can be useful to let your users know about the change. One way is to just tell them in chat or let them discover the change by attempting to use a command that no longer exists. Another way is to have Hubot let people know when they've used a command that no longer works.
-
-This pattern is similar to the Renaming the Hubot Instance pattern above:
-
-* listen to all messages that match the old command
-* reply to the user letting them know that it's been deprecated
-
-Here is the setup:
-
-1. Create a [bundled script](scripting.md) in the `scripts/` directory of your Hubot instance called `deprecations.js`
-2. Copy any old command listeners and add them to that file. For example, if you were to rename the help command for some silly reason:
-
-```javascript
-// Description:
-//   Tell users when they have used commands that are deprecated or renamed
-//
-// Commands:
-//   None
-//
-module.exports = (robot) => {
-  robot.respond(/help\s*(.*)?$/i, (res) => {
-    return res.reply('That means nothing to me anymore. Perhaps you meant "docs" instead?')
-  })
-}
-
-```
-
-## Preventing Hubot from Running Scripts Concurrently
-
-Sometimes you have scripts that take several minutes to execute. If these scripts are doing something that could be interfered with by running subsequent commands, you may wish to code your scripts to prevent concurrent access.
-
-To do this, you can set up a lock in the Hubot [brain](scripting.md#persistence) object. The lock is set up here so that different scripts can share the same lock if necessary.
-
-Setting up the lock looks something like this:
-
-```javascript
-module.exports = (robot) => {
-  robot.brain.on('loaded', ()=>{
-    // Clear the lock on startup in case Hubot has restarted and Hubot's brain has persistence (e.g. redis).
-    // We don't want any orphaned locks preventing us from running commands.
-    robot.brain.remove('yourLockName')
-  }
-
-  robot.respond(/longrunningthing/i, (msg) => {
-    const lock = robot.brain.get('yourLockName')
-    if (lock) {
-      return msg.send(`I'm sorry, ${msg.message.user.name}, I'm afraid I can't do that. I'm busy doing something for ${lock.user.name}.`)
-    }
-
-    robot.brain.set('yourLockName', msg.message)  // includes user, room, etc about who locked
-
-    yourLongClobberingAsyncThing(err, res).then(
-      // Clear the lock
-      robot.brain.remove('yourLockName')
-      msg.reply('Finally Done')
-    )).catch(e => console.error(e))
-}
-```
-
-## Forwarding all HTTP requests through a proxy
-
-In many corporate environments, a web proxy is required to access the Internet and/or protected resources. For one-off control, use can specify an [Agent](https://nodejs.org/api/http.html) to use with `robot.http`. However, this would require modifying every script your robot uses to point at the proxy. Instead, you can specify the agent at the global level and have all HTTP requests use the agent by default.
-
-Due to the way Node.js handles HTTP and HTTPS requests, you need to specify a different Agent for each protocol. ScopedHTTPClient will then automatically choose the right ProxyAgent for each request.
-
-1. Install ProxyAgent. `npm install proxy-agent`
-2. Create a [bundled script](scripting.md) in the `scripts/` directory of your Hubot instance called `proxy.js`
-3. Add the following code, modified for your needs:
-
-```javascript
-const proxy = require('proxy-agent')
-module.exports = (robot) => {
-  robot.globalHttpOptions.httpAgent  = proxy('http://my-proxy-server.internal', false)
-  robot.globalHttpOptions.httpsAgent = proxy('http://my-proxy-server.internal', true)
-}
-```
-
-## Dynamic matching of messages
-
-In some situations, you want to dynamically match different messages (e.g. factoids, JIRA projects). Rather than defining an overly broad regular expression that always matches, you can tell Hubot to only match when certain conditions are met.
-
-In a simple robot, this isn't much different from just putting the conditions in the Listener callback, but it makes a big difference when you are dealing with middleware: with the basic model, middleware will be executed for every match of the generic regex. With the dynamic matching model, middleware will only be executed when the dynamic conditions are matched.
-
-For example, the [factoid lookup command](https://github.com/github/hubot-scripts/blob/bd810f99f9394818a9dcc2ea3729427e4101b96d/src/scripts/factoid.coffee#L95-L99) could be reimplemented as:
-
-```javascript
-// use case: Hubot>fact1
-// This listener doesn't require you to type the bot's name first
-
-const {TextMessage} = require('../src/message')
-module.exports = (robot) => {
-    // Dynamically populated list of factoids
-    const facts = {
-        fact1: 'stuff',
-        fact2: 'other stuff'
-    }
-    robot.listen(
-        // Matcher
-        (message) => {
-            // Check that message is a TextMessage type because
-            // if there is no match, this matcher function will 
-            // be called again but the message type will be CatchAllMessage
-            // which doesn't have a `match` method.
-            if(!(message instanceof TextMessage)) return false
-            const match = message.match(/^(.*)$/)
-            // Only match if there is a matching factoid
-            if (match && match[1] in facts) {
-                return match[1]
-            } else {
-                return false 
-            }
-        },
-        // Callback
-        (res) => {
-            const fact = res.match
-            res.reply(`${fact} is ${facts[fact]}`)
-        }
-    )
-}
-```
-
-## Restricting access to commands
-
-One of the awesome features of Hubot is its ability to make changes to a production environment with a single chat message. However, not everyone with access to your chat service should be able to trigger production changes.
-
-There are a variety of different patterns for restricting access that you can follow depending on your specific needs:
-
-* Two buckets of access: full and restricted with include/exclude list
-* Specific access rules for every command (Role-based Access Control)
-* Include/exclude listing commands in specific rooms
-
-### Simple per-listener access
-
-In some organizations, almost all employees are given the same level of access and only a select few need to be restricted (e.g. new hires, contractors, etc.). In this model, you partition the set of all listeners to separate the "power commands" from the "normal commands".
-
-Once you have segregated the listeners, you need to make some tradeoff decisions around include/exclude users and listeners.
-
-The key deciding factors for inclusion vs exclusion of users are the number of users in each category, the frequency of change in either category, and the level of security risk your organization is willing to accept.
-
-* Including users (users X, Y, Z have access to power commands; all other users only get access to normal commands) is a more secure method of access (new users have no default access to power commands), but has higher maintenance overhead (you need to add each new user to the "include" list).
-* Excluding users (all users get access to power commands, except for users X, Y, Z, who only get access to normal commands) is a less secure method (new users have default access to power commands until they are added to the exclusion list), but has a much lower maintenance overhead if the exclusion list is small/rarely updated.
-
-The key deciding factors for selectively allowing vs restricting listeners are the number of listeners in each category, the ratio of internal to external scripts, and the level of security risk your organization is willing to accept.
-
-* Selectively allowing listeners (all listeners are power commands, except for listeners A, B, C, which are considered normal commands) is a more secure method (new listeners are restricted by default), but has a much higher maintenance overhead (every silly/fun listener needs to be explicity downgraded to "normal" status).
-* Selectively restricting listeners (listeners A, B, C are power commands, everything else is a normal command) is a less secure method (new listeners are put into the normal category by default, which could give unexpected access; external scripts are particularly risky here), but has a lower maintenance overhead (no need to modify/enumerate all the fun/culture scripts in your access policy).
-
-As an additional consideration, most scripts do not currently have listener IDs, so you will likely need to open PRs (or fork) any external scripts you use to add listener IDs. The actual modification is easy, but coordinating with lots of maintainers can be time consuming.
-
-Once you have decided which of the four possible models to follow, you need to build the appropriate lists of users and listeners to plug into your authorization middleware.
-
-Example: inclusion list of users given access to selectively restricted power commands
-
-```javascript
-const POWER_COMMANDS = [
-    'deploy.web' // String that matches the listener ID
-]
-
-// Change name to something else to see it reject the command.
-const POWER_USERS = [
-    'Shell' // String that matches the user ID set by the adapter
-]
-  
-module.exports = (robot) => {
-  robot.listenerMiddleware((context, next, done) => {
-      if (POWER_COMMANDS.indexOf(context.listener.options.id) > -1) {
-          if (POWER_USERS.indexOf(context.response.message.user.name) > -1){
-              // User is allowed access to this command
-              next()
-          } else {
-              // Restricted command, but user isn't in whitelist
-              context.response.reply(`I'm sorry, @${context.response.message.user.name}, but you don't have access to do that.`)
-              done()
-          }
-      } else {
-          // This is not a restricted command; allow everyone
-          next()
-      }
-  })
-
-  robot.listen(message => {
-      return true
-  }, {id: 'deploy.web'},
-  res => {
-      res.reply('Deploying web...')
-  })
-}
-```
-
-Remember that middleware executes for ALL listeners that match a given message (including `robot.hear(/.+/)`), so make sure you include them when categorizing your listeners.
-
-### Specific access rules per listener
-
-For larger organizations, a binary categorization of access is usually insufficient and more complex access rules are required.
-
-Example access policy:
-* Each development team has access to cut releases and deploy their service
-* The Operations group has access to deploy all services (but not cut releases)
-* The front desk cannot cut releases nor deploy services
-
-Complex policies like this are currently best implemented in code directly.
-
-### Specific access rules per room
-
-Organizations that have a number of chat rooms that serve different purposes often want to be able to use the same instance of hubot but have a different set of commands allowed in each room.
-
-Work on generalized exlusion list solution is [ongoing](https://github.com/kristenmills/hubot-command-blacklist). An inclusive list soultion could take a similar approach.
-
-## Use scoped npm packages as adapter
-
-It is possible to [install](https://docs.npmjs.com/cli/v7/commands/npm-install) package under a custom alias:
-
-```bash
-npm install <alias>@npm:<name>
-```
-
-So for example to use `@foo/hubot-adapter` package as the adapter, you can:
-
-```bash
-npm install hubot-foo@npm:@foo/hubot-adapter
-
-bin/hubot --adapter foo
-```