357 Tool Development Guide Cc64ee04

IoTHackBot Tool Development Guide

This guide documents the standard project structure and development patterns used for iothackbot tools.

Project Structure Overview

All iothackbot tools follow a consistent architecture separating CLI, core functionality, and shared interfaces.

Directory Structure

tools/iothackbot/
├── __init__.py                 # Package initialization
├── tool_name.py               # CLI entry point with argparse and colorama
├── core/
│   ├── tool_name_core.py      # Core tool logic implementing ToolInterface
│   └── interfaces.py          # Shared interfaces (ToolInterface, ToolConfig, etc.)
└── bin/
    └── tool_name             # Executable binary (imports from tools/iothackbot/)

Development Patterns

1. Core Tool Implementation (core/tool_name_core.py)

"""
Core tool_name functionality - Description.
Separated from CLI logic for automation and chaining.
"""

from .interfaces import ToolInterface, ToolConfig, ToolResult

class ToolNameTool(ToolInterface):
    """Tool implementation."""

    @property
    def name(self) -> str:
        return "tool_name"

    @property
    def description(self) -> str:
        return "What the tool does"

    def run(self, config: ToolConfig) -> ToolResult:
        """Execute the tool."""
        # Implementation here
        pass

2. CLI Implementation (tool_name.py)

#!/usr/bin/env python3
import argparse
from colorama import init, Fore, Style
from .core.tool_name_core import ToolNameTool
from .core.interfaces import ConfigBuilder, OutputFormatter

class ToolNameOutputFormatter(OutputFormatter):
    """Custom output formatter for tool results."""

    def _format_text(self, result: 'ToolResult') -> str:
        """Format results as human-readable text."""
        if not result.success:
            return "\n".join(result.errors)
        # Custom formatting logic
        return formatted_output

def tool_name():
    """Main CLI entry point."""
    parser = argparse.ArgumentParser(description="Tool description")
    parser.add_argument("input", help="Input description")
    parser.add_argument("-o", "--output", help="Output option")
    parser.add_argument("--format", choices=['text', 'json', 'quiet'], default='text')
    parser.add_argument("-v", "--verbose", action="store_true")

    args = parser.parse_args()
    init()  # Initialize colorama

    config = ConfigBuilder.from_args(args, 'tool_name')
    tool = ToolNameTool()
    result = tool.run(config)

    formatter = ToolNameOutputFormatter()
    output = formatter.format_result(result, config.output_format)
    if output:
        print(output)

    return 0 if result.success else 1

3. Binary Executable (bin/tool_name)

#!/usr/bin/python
# -*- coding: utf-8 -*-
import sys
from iothackbot.tool_name import tool_name
if __name__ == "__main__":
    sys.exit(tool_name())

4. ConfigBuilder Integration

Add custom argument handling to interfaces.py:

# In ConfigBuilder.from_args()
if hasattr(args, 'custom_arg'):
    custom_args['custom_arg'] = args.custom_arg

Output Formatting Standards

Color Scheme

• Green: Success messages, found items
• Yellow: Warnings, directory paths
• Cyan: Detailed information, file listings
• Red: Errors, failures

Emoji Usage

• NO EMOJIS in tool output - use text labels instead
• Use descriptive text like [HIGH RISK], FAILED, SUCCESS instead of emoji symbols
• Maintain professional, parseable output that works in all environments

Format Support

All tools must support:

• text: Human-readable colored output (default)
• json: Structured JSON output
• quiet: Minimal/no output

Development Workflow

1. Create core functionality in core/tool_name_core.py
2. Implement CLI wrapper in tool_name.py
3. Create binary in bin/tool_name
4. Update ConfigBuilder for custom arguments
5. Test integration with existing tools
6. Add to registry if needed for chaining

Key Interfaces

ToolInterface

• name: Tool identifier
• description: Tool purpose
• run(config: ToolConfig) -> ToolResult: Main execution

ToolConfig

• input_path: Primary input file/directory
• output_format: text/json/quiet
• verbose: Enable verbose output
• custom_args: Tool-specific arguments

ToolResult

• success: Boolean success indicator
• data: Tool-specific results
• errors: List of error messages
• metadata: Additional execution info
• execution_time: Performance metric

Testing

• Test with various input types
• Verify all output formats work
• Check error handling
• Validate color output
• Test binary execution
• Ensure chaining compatibility

Example Tool Template

Use this as a starting point for new tools:

# Create files
touch tools/iothackbot/new_tool.py
touch tools/iothackbot/core/new_tool_core.py
touch bin/new_tool
chmod +x bin/new_tool

# Implement following the patterns above
# Test integration with existing tools

Chaining Support

Tools should be designed for chaining:

• Accept ToolResult from previous tools
• Return standardized ToolResult
• Support pipeline operations
• Maintain compatibility with iothackbot workflow