tessl/npm-hubot

A comprehensive chat bot framework modeled after GitHub's Campfire bot for building extensible chat bots across multiple platforms

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Command Line Interface

Name: tessl/npm-hubot
Author: tessl

Complete CLI for creating, configuring, and running hubot instances with various adapter and configuration options.

Capabilities

Basic CLI Usage

The hubot command provides a complete interface for managing bot instances.

# Basic usage
hubot [options]

# Create new bot deployment
hubot --create <directory> [options]

# Run existing bot
hubot --adapter <adapter> [options]

# Configuration testing
hubot --config-check

Command Line Options

# Adapter options
-a, --adapter ADAPTER        # Specify chat adapter (default: Shell)
-f, --file FILE              # Path to adapter file

# Bot configuration
-n, --name NAME              # Set robot name (default: Hubot)
-l, --alias ALIAS            # Set robot alias for mentions
-d, --disable-httpd          # Disable HTTP server (default: enabled)

# Script loading
-r, --require PATH           # Additional scripts path to load

# Deployment
-c, --create DIR             # Create new hubot deployment in directory

# Utility options
-t, --config-check           # Test configuration and exit
-e, --execute                # Execute command directly
-v, --version                # Show version information
-h, --help                   # Show help message

Creating New Bot Deployments

Generate complete bot project structure with configuration and example scripts.

# Create basic bot
hubot --create mybot

# Create bot with specific adapter
hubot --create mybot --adapter @hubot-friends/hubot-slack

# Create bot with custom name and alias
hubot --create mybot --name "CompanyBot" --alias "!"

Generated Structure:

mybot/
├── package.json           # Dependencies and scripts
├── .env                  # Environment variables template
├── scripts/              # Local scripts directory
│   └── example.js        # Example script
├── external-scripts.json # External script configuration
└── README.md             # Setup instructions

Running Bots

Start bot instances with various configurations.

# Run with Shell adapter (development)
hubot --adapter Shell --name DevBot

# Run with external adapter
hubot --adapter @hubot-friends/hubot-slack --name SlackBot

# Run with custom adapter file
hubot --file ./adapters/my-adapter.js --name CustomBot

# Run with alias for mentions
hubot --adapter Shell --alias "!" --name AliasBot

# Run without HTTP server
hubot --adapter Shell --disable-httpd --name SimpleBot

# Run with additional script paths
hubot --adapter Shell --require ./custom-scripts --name ExtendedBot

Configuration Testing

Validate bot configuration before deployment.

# Test current configuration
hubot --config-check

# Test specific adapter configuration
hubot --config-check --adapter @hubot-friends/hubot-slack

# Test with environment variables
HUBOT_SLACK_TOKEN=xoxb-test hubot --config-check --adapter @hubot-friends/hubot-slack

Environment Variables

Common environment variables used by hubot and adapters.

# Core hubot variables
HUBOT_NAME=MyBot                    # Robot name
HUBOT_ALIAS="!"                     # Robot alias
HUBOT_DESCRIPTION="My helpful bot"  # Robot description
HUBOT_LOG_LEVEL=info               # Logging level (debug, info, warn, error)

# HTTP server configuration
PORT=8080                          # HTTP server port
BIND_ADDRESS=0.0.0.0              # HTTP server bind address
EXPRESS_USER=admin                 # HTTP basic auth username
EXPRESS_PASSWORD=secret            # HTTP basic auth password

# Adapter-specific variables (examples)
HUBOT_SLACK_TOKEN=xoxb-your-token  # Slack bot token
HUBOT_DISCORD_TOKEN=your-token     # Discord bot token
HUBOT_CAMPFIRE_TOKEN=your-token    # Campfire API token
HUBOT_CAMPFIRE_ROOMS=12345,67890   # Campfire room IDs

Programmatic Usage

Using the CLI functionality programmatically in Node.js applications.

import { parseOptions, main } from "hubot/bin/hubot";

// Parse command line arguments
const options = parseOptions([
  '--adapter', 'Shell',
  '--name', 'ProgrammaticBot'
]);

// Run bot with options
await main(options);

Generator Functionality

The CLI includes bot generation capabilities for creating new deployments.

/**
 * Create new hubot deployment
 * @param hubotDirectory - Target directory for new bot
 * @param options - Generation options
 */
function create(hubotDirectory: string, options: GeneratorOptions): Promise<void>;

interface GeneratorOptions {
  adapter?: string;    // Default adapter to configure
  name?: string;       // Bot name
  description?: string; // Bot description
}

Usage Example:

import { create } from "hubot/src/GenHubot.mjs";

await create("./my-new-bot", {
  adapter: "@hubot-friends/hubot-slack",
  name: "CompanyBot",
  description: "Our company's helpful chat bot"
});

Development Workflow

Common CLI patterns for bot development.

# Development setup
mkdir my-hubot
cd my-hubot
hubot --create . --adapter Shell

# Install additional dependencies
npm install hubot-help hubot-diagnostics

# Start development server
npm start
# or
hubot --adapter Shell --name DevBot

# Test configuration
hubot --config-check

# Run with debug logging
HUBOT_LOG_LEVEL=debug hubot --adapter Shell

# Production deployment
NODE_ENV=production hubot --adapter @hubot-friends/hubot-slack

Error Handling and Debugging

CLI provides detailed error messages and debugging options.

# Enable debug logging
HUBOT_LOG_LEVEL=debug hubot --adapter Shell

# Validate adapter configuration
hubot --config-check --adapter problematic-adapter

# Test with minimal configuration
hubot --adapter Shell --disable-httpd --name TestBot

# Check version and dependencies
hubot --version
npm list

Integration with Process Managers

Running hubot with process managers like PM2, systemd, or Docker.

# PM2 configuration
pm2 start hubot --name "my-bot" -- --adapter @hubot-friends/hubot-slack

# Systemd service
[Unit]
Description=Hubot Chat Bot
After=network.target

[Service]
Type=simple
User=hubot
WorkingDirectory=/opt/hubot
ExecStart=/usr/bin/node /usr/bin/hubot --adapter @hubot-friends/hubot-slack
Restart=always
Environment=NODE_ENV=production
Environment=HUBOT_SLACK_TOKEN=xoxb-your-token

[Install]
WantedBy=multi-user.target

# Docker usage
docker run -d \
  --name my-hubot \
  -e HUBOT_SLACK_TOKEN=xoxb-your-token \
  -e HUBOT_NAME=DockerBot \
  hubot:latest \
  hubot --adapter @hubot-friends/hubot-slack

Configuration Files

Hubot supports configuration through various file formats.

// package.json configuration
{
  "name": "my-hubot",
  "scripts": {
    "start": "hubot --adapter Shell",
    "slack": "hubot --adapter @hubot-friends/hubot-slack"
  },
  "hubot": {
    "external-scripts": [
      "hubot-help",
      "hubot-diagnostics"
    ]
  }
}

// .env file
HUBOT_NAME=CompanyBot
HUBOT_ALIAS=!
HUBOT_SLACK_TOKEN=xoxb-your-token
HUBOT_LOG_LEVEL=info
PORT=8080

Types

interface CLIOptions {
  adapter?: string;        # Adapter name or path
  file?: string;          # Adapter file path
  name?: string;          # Robot name
  alias?: string;         # Robot alias
  create?: string;        # Directory to create bot in
  require?: string;       # Additional scripts path
  'disable-httpd'?: boolean; # Disable HTTP server
  'config-check'?: boolean;  # Test configuration
  execute?: boolean;      # Execute command directly
  version?: boolean;      # Show version
  help?: boolean;         # Show help
}