Merge pull request hubotio#387 from github/v3-external-scripts

External Scripts from npm for V3

README.md

@@ -46,6 +46,43 @@ individual scripts.
 [hubot-scripts]: https://github.com/github/hubot-scripts
 [hubot-scripts-readme]: https://github.com/github/hubot-scripts#readme
 
+## external-scripts
+
+This functionality allows users to enable scripts from `npm` packages which
+don't have to be included in the `hubot-scripts` repository.
+
+To enable to functionality you can follow the following steps.
+
+1. Add the packages as dependencies into your `package.json`
+2. `npm install` to make sure those packages are installed
+
+To enable third-party scripts that you've added you will need to add the package
+name as a double quoted string to the `external-scripts.json` file for your
+hubot.
+
+### Creating a script package
+
+Creating a script package for hubot is very simple. Start by creating a normal
+`npm` package. Make sure you add a main file for the entry point (e.g.
+`index.js` or `index.coffee`).
+
+In this entry point file you're going to have to export a function that hubot
+will use to load the scripts in your package. Below is a simple example for
+loading each script in a `./scripts` directory in your package.
+
+```coffeescript
+Fs   = require 'fs'
+Path = require 'path'
+
+module.exports = (robot) ->
+  path = Path.resolve __dirname, 'scripts'
+  Fs.exists path, (exists) ->
+    if exists
+      robot.loadFile path, file for file in Fs.readdirSync(path)
+```
+
+After you've built your `npm` package you can publish it to [npmjs][npmjs].
+
 ## HTTP Listener
 
 Hubot has a HTTP listener which listens on the port specified by the `PORT`

bin/hubot

@@ -99,6 +99,13 @@ else
           scriptsPath = Path.join __dirname, "node_modules", "hubot-scripts", "src", "scripts"
           robot.loadHubotScripts scriptsPath, scripts
 
+    scriptsFile = Path.join __dirname, "..", "external-scripts.json"
+    Fs.exists scriptsFile, (exists) =>
+      if exists
+        Fs.readFile scriptsFile, (err, data) ->
+          scripts = JSON.parse data
+          robot.loadExternalScripts scripts
+
     for path in Options.scripts
       if path[0] == '/'
         scriptsPath = path

src/creator.coffee

@@ -64,7 +64,8 @@ class Creator
       "README.md",
       ".gitignore",
       "bin/hubot",
-      "hubot-scripts.json"
+      "hubot-scripts.json",
+      "external-scripts.json"
     ]
 
     @copy "#{@templateDir}/#{file}", "#{@path}/#{file}" for file in files

src/robot.coffee

@@ -165,6 +165,20 @@ class Robot
     for script in scripts
       @loadFile path, script
 
+  # Public: Load scripts from packages specfied in the
+  # `external-scripts.json` file.
+  #
+  # packages - An Array of packages containing hubot scripts to load.
+  #
+  # Returns nothing.
+  loadExternalScripts: (packages) ->
+    @logger.debug "Loading external-scripts from npm packages"
+    for pkg in packages
+      try
+        require(pkg) @
+      catch error
+        @logger.error "Error loading scripts from npm package - #{error}"
+
   # Setup the Connect server's defaults.
   #
   # Returns nothing.

src/templates/README.md

@@ -99,11 +99,26 @@ of adding it to hubot itself, you can submit pull requests to
 [hubot-scripts][hubot-scripts].
 
 To enable scripts from the hubot-scripts package, add the script name with
-extension as a double quoted string to the hubot-scripts.json file in this
+extension as a double quoted string to the `hubot-scripts.json` file in this
 repo.
 
 [hubot-scripts]: https://github.com/github/hubot-scripts
 
+## external-scripts
+
+Tired of waiting for your script to be merged into `hubot-scripts`? Want to
+maintain the repository and package yourself? Then this added functionality
+maybe for you!
+
+Hubot is now able to load scripts from third-party `npm` packages! To enable
+this functionality you can follow the following steps.
+
+1. Add the packages as dependencies into your `package.json`
+2. `npm install` to make sure those packages are installed
+
+To enable third-party scripts that you've added you will need to add the package
+name as a double quoted string to the `external-scripts.json` file in this repo.
+
 ## Deployment
 
     % heroku create --stack cedar

src/templates/external-scripts.json

@@ -0,0 +1 @@
+[]