npm package: @ignium/builder
Description: AI-powered CLI tool for developers to build software with Anthropic Claude and OpenAI assistant.  Allows you to automate specific tasks/workflows in your development process, driven by AI.
Author: Your Name
Latest version: 1.0.2

# Builder AI 🤖

A powerful command-line interface tool that integrates with Anthropic Claude and OpenAI to help developers build software more efficiently. Unlike other AI assistants, Builder AI focuses on **automated workflows** for specific development tasks, allowing teams to create repeatable, AI-powered processes.

## Features

- 🔄 **Workflow Automation**: Create and run pre-built workflows for common tasks (unit tests, docs, refactoring)
- 🔌 **MCP Integration**: Connect workflows to external services via Model Context Protocol (Jira, GitHub, databases, etc.)
- 🚀 **Interactive Chat**: Have conversations with AI about your code and development tasks
- 📝 **Code Generation**: Generate code based on natural language prompts
- 🔍 **Code Review**: Get AI-powered code reviews and improvement suggestions
- 📚 **Code Explanation**: Understand complex code and concepts
- ⚙️ **Flexible Configuration**: Support for both Anthropic Claude and OpenAI models
- 🎯 **Project Context**: AI understands your project structure and dependencies
- 🔐 **Secure**: API keys are stored securely using system keychain
- 📦 **Team-Ready**: Share workflows across your team by committing `.builder/` directory

## Installation

### Prerequisites

- Node.js 18.0.0 or higher
- npm or yarn

### Install from source

```bash
# Clone the repository
git clone <repository-url>
cd builder-ai

# Install dependencies
npm install

# Build the project
npm run build

# Link globally (optional)
npm link
```

### Install globally

```bash
npm install -g builder-ai
```

## Quick Start

1. **Initialize with API Key**
   ```bash
   builder init --provider anthropic --token "your-api-key"
   ```
   Or for OpenAI:
   ```bash
   builder init --provider openai --token "your-api-key"
   ```

   This will:
   - Create a `.builder/` directory with pre-built workflows
   - Generate a `builder.json` file with your project configuration
   - Auto-detect your framework, language, and styling approach

2. **Run a Workflow**
   ```bash
   builder workflow list              # See available workflows
   builder workflow run unit-tests    # Generate unit tests for your code
   builder workflow run docs          # Generate documentation
   builder workflow run refactor      # Get refactoring suggestions
   ```

3. **Interactive Mode**
   ```bash
   builder workflow                   # Select and run workflows interactively
   ```

4. **Other Commands**
   ```bash
   builder chat                       # Start an AI chat session
   builder generate "prompt"          # Generate code from a prompt
   builder review                     # Get code review
   ```

## Commands

### `builder init`
Initialize Builder AI with your provider and API key. Creates a `.builder/` directory with pre-built workflows.

```bash
builder init --provider anthropic --token "your-api-key"
builder init --provider openai --token "your-api-key" --model "gpt-4"
builder init --provider anthropic --token "your-api-key" --temp 0.5 --max-tokens 2000
```

Options:
- `-p, --provider`: AI provider (anthropic|openai)
- `-t, --token`: API token/key (required)
- `-m, --model`: AI model name
- `--temp`: Temperature setting (0.0-1.0)
- `--max-tokens`: Maximum tokens

### `builder workflow`
Run pre-built workflows for common development tasks.

```bash
# List available workflows
builder workflow list
builder workflow ls

# Run a specific workflow
builder workflow run unit-tests           # Generate unit tests
builder workflow run docs                 # Generate documentation
builder workflow run refactor             # Refactor code

# Run with options
builder workflow run unit-tests --files "src/utils.ts,src/api.ts"
builder workflow run unit-tests --output tests/
builder workflow run unit-tests --dry-run # Preview without making changes

# Get workflow information
builder workflow info unit-tests

# Interactive mode
builder workflow                          # Select workflow interactively
```

#### Pre-built Workflows

**create-component** - Create components from Jira tickets (MCP-powered)
- Fetches ticket information from Jira via MCP
- Generates components based on requirements and acceptance criteria
- Supports custom templates and patterns
- Variables: `ticketId`, `componentPath`
- Requires: Jira MCP server

**unit-tests** - Generate comprehensive unit tests
- Analyzes your code and generates test files
- Uses your project's testing framework (Jest, Mocha, Vitest, etc.)
- Follows existing test patterns in your codebase
- Output: `{filename}.test.{ext}` files

**docs** - Generate documentation
- Creates JSDoc/TSDoc documentation for your code
- Documents APIs, functions, and classes
- Includes usage examples

**refactor** - Refactor code for better quality
- Identifies code smells and improvement opportunities
- Suggests performance optimizations
- Improves readability and maintainability

**sync-with-github** - Sync with GitHub issues (MCP-powered)
- Fetches open issues from GitHub
- Analyzes for automation opportunities
- Requires: GitHub MCP server

### `builder setup`
Configure your AI provider and API keys interactively.

```bash
builder setup
```

### `builder chat`
Start an interactive chat session with the AI.

```bash
builder chat                    # Basic chat
builder chat --context          # Include project context
```

### `builder generate`
Generate code based on a prompt.

```bash
builder generate "Create a REST API endpoint"    # Generate with prompt
builder generate -f src/api.ts                   # Save to specific file
builder generate --no-context                    # Skip project context
```

### `builder review`
Review code for improvements and issues.

```bash
builder review                  # Review current directory
builder review src/main.ts      # Review specific file
```

### `builder explain`
Explain code, concepts, or technologies.

```bash
builder explain "React hooks"                    # Explain concept
builder explain -f src/utils.ts                  # Explain specific file
```

### `builder config`
View or modify configuration.

```bash
builder config                  # Show current config
builder config --show           # Show current config
builder config --edit           # Edit configuration
builder config --reset          # Reset to defaults
```

## Configuration

Builder AI uses two types of configuration:

### Global Configuration (AI Provider)
Stored securely in your system keychain:
- **Provider**: Choose between Anthropic Claude and OpenAI
- **Model**: Select specific AI models (Claude 3.5 Sonnet, GPT-4, etc.)
- **Temperature**: Control creativity vs. focus (0.0 - 1.0)
- **Max Tokens**: Set maximum response length
- **API Key**: Your provider's API key

### Project Configuration (`builder.json`)
Stored in your project root and committed to version control:
```json
{
  "name": "my-project",
  "version": "1.0.0",
  "framework": "nextjs",
  "language": "typescript",
  "styling": "tailwind",
  "testFramework": "jest",
  "paths": {
    "components": "src/components",
    "pages": "src/app",
    "tests": "__tests__"
  }
}
```

This configuration:
- Is auto-detected during `builder init`
- Can be customized for your project
- Is used by workflows to generate appropriate code
- Should be committed to share with your team

## Supported AI Providers

### Anthropic Claude
- Claude 3.5 Sonnet (recommended)
- Claude 3 Opus
- Claude 3 Haiku

### OpenAI
- GPT-4 Turbo (recommended)
- GPT-4
- GPT-3.5 Turbo

## Workflows

### Creating Custom Workflows

Workflows are JSON files stored in `.builder/workflows/`. Each workflow defines a series of steps to automate a task.

Example workflow structure:

```json
{
  "name": "custom-workflow",
  "description": "My custom workflow",
  "version": "1.0.0",
  "mcpServers": {
    "jira": {
      "name": "jira",
      "type": "remote",
      "url": "http://localhost:3000",
      "env": {
        "AUTH_TOKEN": "${JIRA_API_TOKEN}"
      },
      "timeout": 10000
    }
  },
  "variables": {
    "ticketId": "PROJ-123"
  },
  "steps": [
    {
      "type": "mcp",
      "description": "Fetch data from external service",
      "mcp": {
        "server": "jira",
        "tool": "get_issue",
        "params": {
          "issueKey": "${ticketId}"
        },
        "outputVar": "ticket"
      }
    },
    {
      "type": "generate",
      "description": "Generate output",
      "prompt": "Create code based on: ${ticket.fields.summary}"
    }
  ],
  "config": {
    "filePatterns": ["**/*.ts", "**/*.js"],
    "outputPattern": "{filename}.generated.{ext}",
    "temperature": 0.7,
    "maxTokens": 4000
  }
}
```

### Step Types

- **analyze**: Gather information about files and project structure
- **generate**: Use AI to generate new content
- **validate**: Ensure output meets requirements
- **transform**: Modify existing code
- **mcp**: Call tools on MCP servers to fetch/update external data

### MCP Integration

Builder AI supports the Model Context Protocol (MCP) for connecting workflows to external services:

- **Jira**: Fetch tickets, create issues, update statuses
- **GitHub**: Access issues, PRs, repositories
- **Databases**: Query and update data
- **Custom Services**: Any service with an MCP server

#### MCP Server Configuration

Configure MCP servers in your workflow:

```json
{
  "mcpServers": {
    "myserver": {
      "name": "myserver",
      "type": "local|remote",
      "url": "http://localhost:3000",  // for remote servers
      "command": "npx",                 // for local servers
      "args": ["my-mcp-server"],       // for local servers
      "env": {
        "AUTH_TOKEN": "..."
      },
      "timeout": 10000
    }
  }
}
```

#### Using MCP Steps

Call MCP tools in workflow steps:

```json
{
  "type": "mcp",
  "description": "Fetch Jira ticket",
  "mcp": {
    "server": "jira",
    "tool": "get_issue",
    "params": {
      "issueKey": "${ticketId}"
    },
    "outputVar": "ticket"
  }
}
```

#### Variable Interpolation

Use `${varName}` to reference variables in:
- MCP parameters: `"issueKey": "${ticketId}"`
- AI prompts: `"Generate code for: ${ticket.fields.summary}"`
- Output paths: `"outputPattern": "${componentPath}/${filename}.tsx"`

Variables can come from:
- Workflow definition (`variables` section)
- Command line arguments
- MCP tool responses (`outputVar`)

### Sharing Workflows

Commit the `.builder/` directory to your repository to share workflows with your team:

```bash
git add .builder/
git commit -m "Add custom workflows"
git push
```

Team members who run `builder init` will get the shared workflows automatically.

## Development

### Project Structure

```
src/
├── commands/           # CLI command implementations
│   ├── init.ts
│   ├── setup.ts
│   ├── chat.ts
│   ├── generate.ts
│   ├── review.ts
│   ├── explain.ts
│   ├── config.ts
│   └── workflow.ts     # Workflow management
├── services/           # Core services
│   ├── ai-provider.ts  # AI integration
│   ├── config.ts       # Configuration management
│   ├── project-context.ts # Project analysis
│   └── workflow.ts     # Workflow execution
├── types/              # TypeScript type definitions
│   └── index.ts
└── index.ts           # Main entry point
```

### Available Scripts

```bash
npm run build          # Build the project with tsup
npm run dev            # Watch mode with tsup
npm run dev:local      # Build, link, and watch for local testing
npm run start          # Run built version
npm run test           # Run tests
npm run lint           # Lint code
npm run format         # Format code
npm run clean          # Clean build artifacts
```

### Local Development

For local development and testing:

```bash
# Install dependencies
npm install

# Start development mode with local linking
npm run dev:local

# In another terminal, test the CLI
builder --help
builder init --provider anthropic --token "test-token"
```

### Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Support

For issues and questions:
- Create an issue on GitHub
- Check the documentation
- Review the configuration guide

## Examples

### Create Component from Jira Ticket

```bash
# Set up environment variables
export JIRA_MCP_URL="http://localhost:3000"
export JIRA_API_TOKEN="your-jira-token"

# Run the workflow with custom variables
builder workflow run create-component
```

The workflow will:
1. Connect to your Jira MCP server
2. Fetch ticket PROJ-123 (or your specified ticket)
3. Extract requirements and acceptance criteria
4. Generate a React component based on the ticket
5. Save to `src/components/`

### Custom Workflow with Multiple MCP Calls

```json
{
  "name": "feature-from-ticket",
  "mcpServers": {
    "jira": { "type": "remote", "url": "http://localhost:3000" },
    "github": { "type": "remote", "url": "http://localhost:3001" }
  },
  "steps": [
    {
      "type": "mcp",
      "mcp": {
        "server": "jira",
        "tool": "get_issue",
        "params": { "issueKey": "${ticketId}" },
        "outputVar": "ticket"
      }
    },
    {
      "type": "generate",
      "prompt": "Implement: ${ticket.fields.summary}"
    },
    {
      "type": "mcp",
      "mcp": {
        "server": "github",
        "tool": "create_pull_request",
        "params": {
          "title": "${ticket.fields.summary}",
          "body": "Implements ${ticketId}"
        }
      }
    }
  ]
}
```

## Roadmap

- [x] Workflow automation system
- [x] Pre-built workflows (unit-tests, docs, refactor)
- [x] MCP (Model Context Protocol) integration
- [x] Workflow variables and interpolation
- [ ] Support for more AI providers (Google Gemini, etc.)
- [ ] Integration with popular IDEs
- [ ] Workflow marketplace for sharing workflows
- [ ] Workflow conditions and loops
- [ ] Custom prompt templates
- [ ] Team collaboration features
- [ ] CI/CD integration for automated workflows
- [ ] Workflow versioning and dependencies
- [ ] Pre-built MCP server connectors