npm package: @mockingmagician/assistant-runner
Description: 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.
Latest version: 0.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

```bash
# 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:
```bash
cp .env.example .env
```

2. Edit the `.env` file and fill in your environment variables:
```env
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:

```bash
# 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:

```bash
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`:
```typescript
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:
```typescript
// 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:
```bash
docker build -t cli-assistant .
```

2. Run the container with your environment file:
```bash
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](https://semver.org/) (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.