hubot 3.4.0 → 3.5.0

package/.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: Release
+on:
+  push:
+    branches:
+      - master
+permissions:
+  contents: read
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: "lts/*"
+      - name: Install Dependencies
+        run: npm clean-install
+      - name: Verify the integrity of provenance attestations and registry signatures for installed dependencies
+        run: npm audit signatures
+      - name: Run Tests
+        run: npm test
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npx semantic-release

package/.node-version

@@ -0,0 +1 @@
+18.16.0

package/README.md

@@ -1,4 +1,6 @@
-[![Build Status](https://travis-ci.org/hubotio/hubot.svg?branch=master)](https://travis-ci.org/hubotio/hubot) [![Coverage Status](https://coveralls.io/repos/github/hubotio/hubot/badge.svg?branch=master)](https://coveralls.io/github/hubotio/hubot?branch=master)
+![Build Status: MacOS](https://github.com/hubotio/hubot/actions/workflows/nodejs-macos.yml/badge.svg)
+![Build Status: Ubuntu](https://github.com/hubotio/hubot/actions/workflows/nodejs-ubuntu.yml/badge.svg)
+![Build Status: Window](https://github.com/hubotio/hubot/actions/workflows/nodejs-windows.yml/badge.svg)
 
 # Hubot
 
@@ -16,3 +18,4 @@ are building your own bot. But if you do, check out [CONTRIBUTING.md](CONTRIBUTI
 ## License
 
 See the [LICENSE](LICENSE.md) file for license rights and limitations (MIT).
+`

package/bin/hubot

@@ -3,7 +3,7 @@
 # While all other files have been converted to JavaScript via https://github.com/github/hubot/pull/1347,
 # we left the `bin/hubot` file to remain in CoffeeScript in order prevent
 # breaking existing 3rd party adapters of which some are still written in
-# CoffeeScript themselves. We will depracate and eventually remove this file
+# CoffeeScript themselves. We will deprecate and eventually remove this file
 # in a future version of hubot
 
 require './hubot.js'

package/docs/adapters/development.md

@@ -6,43 +6,40 @@ permalink: /docs/adapters/development/
 
 ## Adapter Basics
 
-All adapters inherit from the Adapter class in the `src/adapter.coffee` file.  If you're writing your adapter in CoffeeScript, require the primary version of the adapter:
-
-```coffee
-Adapter = require('hubot').Adapter
-```
+All adapters inherit from the Adapter class in the `src/adapter.js` file.
 
 If you're writing your adapter in ES2015, you must require the ES2015 entrypoint instead:
 
-```js
+```javascript
 const Adapter = require('hubot/es2015').Adapter;
 ```
 
 There are certain methods that you will want to override.  Here is a basic stub of what an extended Adapter class would look like:
 
-```coffee
-class Sample extends Adapter
-
-  constructor: ->
-    super
-    @robot.logger.info "Constructor"
-
-  send: (envelope, strings...) ->
-    @robot.logger.info "Send"
-
-  reply: (envelope, strings...) ->
-    @robot.logger.info "Reply"
-
-  run: ->
-    @robot.logger.info "Run"
-    @emit "connected"
-    user = new User 1001, name: 'Sample User'
-    message = new TextMessage user, 'Some Sample Message', 'MSG-001'
-    @robot.receive message
-
-
-exports.use = (robot) ->
-  new Sample robot
+```javascript
+const Adapter = require('../adapter')
+const User = require('../user')
+const TextMessage = require('../message').TextMessage
+class Sample extends Adapter {
+    constructor(robot) {
+        super(robot)
+        this.robot.logger.info('Constructor')
+    }
+    send(envelope, ...strings) {
+        this.robot.logger.info('Send')
+    }
+    reply(envelope, ...strings) {
+        this.robot.logger.info('Reply')
+    }
+    run() {
+        this.robot.logger.info('Run')
+        this.emit('connected')
+        const user = new User(1001, 'Sample User')
+        const message = new TextMessage(user, 'Some Sample Message', 'MSG-001')
+        this.robot.receive(message)
+    }
+}
+exports.use = (robot) => new Sample(robot)
 ```
 
 ## Setting Up Your Development Environment
@@ -76,16 +73,18 @@ exports.use = (robot) ->
 
 ## Gotchas
 
-There is a an open issue in the node community around [npm linked peer dependencies not working](https://github.com/npm/npm/issues/5875).  To get this working for our project you will need to do some minor changes to your code.
+There is a an open issue in the node community around [npm linked peer dependencies not working](https://github.com/npm/npm/issues/5875). To get this working for our project you will need to do some minor changes to your code.
 
 1. For the import in your `hubot-sample` adapter, add the following code
 
-  ```coffee
-  try
-    {Robot,Adapter,TextMessage,User} = require 'hubot'
-  catch
-    prequire = require('parent-require')
-    {Robot,Adapter,TextMessage,User} = prequire 'hubot'
+  ```javascript
+  let  {Robot,Adapter,TextMessage,User} = {}
+  try {
+    {Robot,Adapter,TextMessage,User} = require('hubot')
+  } catch {
+    const prequire = require('parent-require')
+    {Robot,Adapter,TextMessage,User} = prequire('hubot')
+  }
   ```
 2. In your `hubot-sample` folder, modify the `package.json` to include the following dependency so this custom import mechanism will work
 

package/docs/implementation.md

@@ -43,9 +43,7 @@ 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.
+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
 

package/docs/index.md

@@ -44,15 +44,12 @@ 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.
 
-Hubot needs Redis to persist data, so before you can start hubot on your own computer, you should have Redis installed on your localhost. If just want to test Hubot without Redis, then you can remove `hubot-redis-brain` from `external-scripts.json`.
+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>`
+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:
 
@@ -107,7 +104,7 @@ To use a script from an NPM package:
 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 placed there are automatically loaded and ready to use with your hubot. Read more about customizing hubot by [writing your own scripts](scripting.md).
+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
 
@@ -115,9 +112,7 @@ Hubot uses the adapter pattern to support multiple chat-backends. Here is a [lis
 
 ## 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.
+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)
@@ -127,4 +122,4 @@ Please note the support for deploying to Windows isn't officially supported.
 
 ## 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.
+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

@@ -15,23 +15,23 @@ When you rename Hubot, he will no longer respond to his former name. In order to
 
 Setting this up is very easy:
 
-1. Create a [bundled script](scripting.md) in the `scripts/` directory of your Hubot instance called `rename-hubot.coffee`
+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:
 
-```coffeescript
-# Description:
-#   Tell people hubot's new name if they use the old one
-#
-# Commands:
-#   None
-#
-module.exports = (robot) ->
-  robot.hear /^hubot:? (.+)/i, (res) ->
-    response = "Sorry, I'm a diva and only respond to #{robot.name}"
-    response += " or #{robot.alias}" if robot.alias
-    res.reply response
-    return
+```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.
@@ -49,70 +49,72 @@ This pattern is similar to the Renaming the Hubot Instance pattern above:
 
 Here is the setup:
 
-1. Create a [bundled script](scripting.md) in the `scripts/` directory of your Hubot instance called `deprecations.coffee`
+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:
 
-```coffeescript
-# Description:
-#   Tell users when they have used commands that are deprecated or renamed
-#
-# Commands:
-#   None
-#
-module.exports = (robot) ->
-  robot.respond /help\s*(.*)?$/i, (res) ->
-    res.reply "That means nothing to me anymore. Perhaps you meant `docs` instead?"
-    return
+```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.
+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.
+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:
 
-```coffeescript
-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.
+```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) ->
-    lock = robot.brain.get('yourLockName')
-
-    if lock?
-      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}."
-      return
+  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
+    robot.brain.set('yourLockName', msg.message)  // includes user, room, etc about who locked
 
-    yourLongClobberingAsyncThing (err, response) ->
-      # Clear the lock
+    yourLongClobberingAsyncThing(err, res).then(
+      // Clear the lock
       robot.brain.remove('yourLockName')
-      msg.reply "Finally Done"
+      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.
+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.coffee`
+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:
 
-```coffeescript
-proxy = require 'proxy-agent'
-module.exports = (robot) ->
+```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
@@ -123,27 +125,40 @@ In a simple robot, this isn't much different from just putting the conditions in
 
 For example, the [factoid lookup command](https://github.com/github/hubot-scripts/blob/bd810f99f9394818a9dcc2ea3729427e4101b96d/src/scripts/factoid.coffee#L95-L99) could be reimplemented as:
 
-```coffeescript
-module.exports = (robot) ->
-  # Dynamically populated list of factoids
-  facts =
-    fact1: 'stuff'
-    fact2: 'other stuff'
-
-  robot.listen(
-    # Matcher
-    (message) ->
-      match = message.match(/^~(.*)$/)
-      # Only match if there is a matching factoid
-      if match and match[1] in facts
-        match[1]
-      else
-        false
-    # Callback
-    (response) ->
-      fact = response.match
-      res.reply "#{fact} is #{facts[fact]}"
-  )
+```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
@@ -152,54 +167,69 @@ One of the awesome features of Hubot is its ability to make changes to a product
 
 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 whitelist/blacklist
+* Two buckets of access: full and restricted with include/exclude list
 * Specific access rules for every command (Role-based Access Control)
-* Blacklisting/whitelisting commands in specific rooms
+* 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 whitelisting/blacklisting users and listeners.
+Once you have segregated the listeners, you need to make some tradeoff decisions around include/exclude users and listeners.
 
-The key deciding factors for whitelisting vs blacklisting 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.
-* Whitelisting 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 "approved" list).
-* Blacklisting 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 blacklist), but has a much lower maintenance overhead if the blacklist is small/rarely updated.
+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 scary here), but has a lower maintenance overhead (no need to modify/enumerate all the fun/culture scripts in your access policy).
+* 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: whitelist of users given access to selectively restricted power commands
-```coffeescript
-POWER_COMMANDS = [
-  'deploy.web' # String that matches the listener ID
-]
+Example: inclusion list of users given access to selectively restricted power commands
 
-POWER_USERS = [
-  'jdoe' # String that matches the user ID set by the adapter
+```javascript
+const POWER_COMMANDS = [
+    'deploy.web' // String that matches the listener ID
 ]
 
-module.exports = (robot) ->
-  robot.listenerMiddleware (context, next, done) ->
-    if context.listener.options.id in POWER_COMMANDS
-      if context.response.message.user.id in POWER_USERS
-        # 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()
+// 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.
+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
 
@@ -210,13 +240,13 @@ Example access policy:
 * 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, though there is [ongoing work](https://github.com/michaelansel/hubot-rbac) to build a generalized framework for access management.
+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 blacklist solution is [ongoing](https://github.com/kristenmills/hubot-command-blacklist). A whitelist soultion could take a similar approach.
+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
 
@@ -227,6 +257,7 @@ 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