@mockingmagician/assistant-runner v0.4.0

CLI Assistant

An intelligent command-line interface assistant powered by TypeScript and AI. This tool helps automate common CLI tasks through natural language processing and a modular tool system.

Features

• 🤖 Advanced natural language command processing using OpenAI agnostic models
• 🔄 Interactive CLI interface with spinners and prompts

• 🛠️ Modular tool system for easy extensibility
• 📦 Built with TypeScript for type safety and better developer experience
• 🧪 Comprehensive test coverage with Jest

• 📧 Email integration capabilities
• 🌐 Web scraping functionality with Puppeteer
• 🗃️ Local data storage with SQLite

• 🐳 Docker support for containerized deployment

Prerequisites

• Node.js (v16 or higher)
• npm or yarn
• Docker (optional, for containerized usage)

Installation

# Clone the repository
git clone git@github.com:MockingMagician/cli-assistant.git
cd cli-assistant

# Install dependencies
npm install

Project Structure

• src/ - Source code
  • tools/ - CLI tool implementations
  • misc/ - Miscellaneous utilities and helpers
  • __tests__/ - Test files
• .env.example - Example environment configuration
• Dockerfile - Docker configuration
• tsconfig.json - TypeScript configuration
• jest.config.ts - Jest test configuration

Environment Setup

1. Copy the example environment file:

cp .env.example .env

2. Edit the .env file and fill in your environment variables:

SMTP_USER=change@me.com
SMTP_PASS=some_password
SMTP_HOST=some_host
SMTP_PORT=some_port

FISH_AUDIO_API_KEY=some_api_key

OPEN_WEATHER_API_KEY=some_api_key

GITHUB_TOKEN=some_token

OPENAI_AGNOSTIC_API_KEY=
OPENAI_AGNOSTIC_BASE_URL=http://localhost:1234/v1
OPENAI_AGNOSTIC_MODEL=qwen2.5-7b-instruct-1m

Development

Available scripts:

# Build the project
npm run build

# Run in development mode with hot-reload
npm run dev

# Run tests
npm run test

Testing

The project uses Jest for testing. Run the test suite with:

npm run test

Adding New Tools

To add a new tool to the CLI assistant:

1. Create a new file in src/tools/ with the naming convention your-tool.tool.ts
2. Implement the ToolInterface from tool.interface.ts:

import { ToolInterface } from './tool.interface';
import OpenAI from 'openai';

interface YourToolParameters {
    // Define your tool's input parameters
    param1: string;
    param2: number;
}

interface YourToolReturn {
    // Define your tool's return value structure
    result: string;
}

export class YourTool implements ToolInterface<YourToolParameters, YourToolReturn> {
    definition: OpenAI.ChatCompletionTool = {
        type: 'function',
        function: {
            name: 'your_tool_name',
            description: 'What your tool does',
            parameters: {
                type: 'object',
                properties: {
                    param1: {
                        type: 'string',
                        description: 'Description of param1'
                    },
                    param2: {
                        type: 'number',
                        description: 'Description of param2'
                    }
                },
                required: ['param1', 'param2']
            }
        }
    };

    async perform(parameters: YourToolParameters): Promise<YourToolReturn> {
        // Your tool logic here
        return {
            result: 'Tool execution result'
        };
    }
}

3. Add corresponding test file in src/tools/__tests__/your-tool.tool.test.ts
4. Register your tool in the main file with the tools registry:

// In cli.ts
import { YourTool } from "./tools/your-tool.tool";

toolRegistry.register(new YourTool());

Docker

Build and run the application in a Docker container:

1. Build the image:

docker build -t cli-assistant .

2. Run the container with your environment file:

docker run -it --rm --env-file .env cli-assistant

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Versioning

This project uses Semantic Versioning (SemVer) for versioning. For the versions available, see the tags on this repository.

Given a version number MAJOR.MINOR.PATCH, increment the:

• MAJOR version when you make incompatible API changes,
• MINOR version when you add functionality in a backwards-compatible manner, and
• PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.