🚀 AI Workflow Utils

The Ultimate AI-Powered Development Workflow Automation Platform

Streamline your development process with intelligent Jira ticket creation, AI-powered code reviews & pull request creation with custom template support, featuring a beautiful dark/light theme interface

🎉 NEW IN v1.x.x - Game-Changing Features!

🎯 Feature #1: AI-Powered Jira Ticket Creation

Create professional Jira tickets (Tasks, Bugs, Stories) using AI with multiple provider support:

• 🤖 OpenAI Compatible APIs: GPT-4, Claude, and other cloud providers
• 🏠 Local AI with Ollama LLaVA: Complete privacy with local image analysis
• 📸 Smart Image Analysis: Upload screenshots and get detailed issue descriptions
• ⚡ Real-time Streaming: Watch AI generate content live
• 🎨 Professional Templates: Auto-formatted with proper sections and acceptance criteria
• 🔗 Direct Jira Integration: Creates tickets instantly with your access token

🚀 Feature #2: AI-Powered Pull Request Creation

Revolutionary AI-powered pull request creation for Atlassian Bitbucket:

• 🤖 Intelligent PR Generation: AI analyzes commit messages to create professional PR titles and descriptions
• 📝 Smart Commit Analysis: Automatically determines PR type (feat/fix/chore) based on commit patterns
• ⚡ Real-time Streaming: Watch AI generate PR content live with streaming updates
• 🔄 Multi-Model Support: Uses Ollama for local AI processing with privacy
• ✏️ Editable Previews: Review and edit AI-generated content before creating the PR
• 💾 Smart Persistence: Remembers project and repository settings for faster workflow

🔍 Feature #3: AI-Powered Code Review

Revolutionary AI-powered pull request reviews for Atlassian Bitbucket:

• 🧠 Intelligent Code Analysis: AI reviews your code changes
• 💡 Smart Suggestions: Get actionable improvement recommendations
• 🔄 Multi-Model Support: OpenAI Compatible APIs + Ollama for flexibility
• ⚡ Coming Soon: AI adds review comments directly to your PRs
• ⚡ Coming Soon: Direct comment integration

📊 Feature #4: Real-time Logs & Monitoring

Comprehensive logging and monitoring system for troubleshooting and system insights:

• 📋 Real-time Log Streaming: Live view of application logs with automatic updates
• 🔍 Advanced Filtering: Filter logs by level (Error, Warn, Info, Debug) and search by content
• 📅 Log History: Access historical logs with pagination and date filtering
• 🎨 Syntax Highlighting: Color-coded log levels for easy identification
• 💾 Log Management: Automatic log rotation and size management
• 🔧 Debug Mode: Enable detailed debug logging for troubleshooting
• 📱 Responsive Design: Access logs from any device with mobile-friendly interface

🧩 Feature #5: Universal API Client (NEW!)

The new API Client module provides a flexible, general-purpose interface for making API requests to any service (Jira, Bitbucket, email, or custom endpoints).

• 🔗 Universal API Requests: Send requests to any configured endpoint
• ⚡ CLI & Server Support: Use via CLI or /api/api-client endpoint
• 🛠️ Modular Architecture: Easily extend for new APIs
• 🔒 Secure & Configurable: Manage endpoints in ~/.ai-workflow-utils/environment.json
• 📋 Error Handling & Logging: Built-in reliability

Coming Soon: AI-powered automation, script generation, and smart workflow integration will be added in future releases.

🌙 Feature #6: Intelligent Dark Theme System

Beautiful, adaptive interface that automatically adjusts to your preferences:

• 🌓 Auto Theme Detection: Automatically follows your system's dark/light mode preference
• 🎨 Manual Theme Control: Switch between Light, Dark, and Auto modes with a single click
• 🎭 Persistent Preferences: Your theme choice is remembered across sessions
• 🌈 Gradient Design System: Stunning gradient backgrounds and glass-morphism effects
• 📱 Consistent Theming: Dark theme support across all components and pages
• 👁️ Eye-friendly: Carefully crafted colors that reduce eye strain during long sessions
• 🔄 Smooth Transitions: Elegant animations when switching between themes

🔗 Feature #6: MCP Client Configuration

Advanced Model Context Protocol (MCP) client management for seamless AI tool integration:

• 🛠️ Comprehensive Client Management: Create, configure, and manage multiple MCP clients
• 🌐 Flexible Connection Types: Support for both remote URL-based and local command-based MCP servers
• 🔐 Secure Authentication: Token-based authentication with secure credential storage
• ⚡ Real-time Testing: Test MCP client connections instantly to ensure proper configuration
• 📝 Client Documentation: Add descriptions and metadata for organized client management
• 🔄 Enable/Disable Toggle: Easily activate or deactivate clients without deletion
• 🏗️ LangChain Integration: Seamless integration with LangChain MCP adapters for AI workflows

🚀 Quick Start Guide

Step 1: Recommended - Ollama Setup (For Local AI)

# Install Ollama (if you want local AI processing)
# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# Windows - Download from https://ollama.com/

# Download the LLaVA model for image analysis
ollama pull llava

# Start Ollama service
ollama serve

Then configure Ollama as your AI provider in the web interface.

Step 2: Installation

npm install -g ai-workflow-utils

Step 3: Permission Setup (Important!)

The application includes file upload functionality that requires proper permissions. Check if your setup is ready:

# Check if the application has necessary permissions
ai-workflow-utils check-permissions

If you see permission warnings:

# Option 1: Fix project directory permissions
sudo chown -R $USER:$USER ~/.npm
mkdir -p ~/ai-workflow-utils && cd ~/ai-workflow-utils

# Option 2: Use a custom upload directory
export UPLOAD_DIR=~/ai-workflow-utils/uploads

📖 For detailed setup instructions, see DEPLOYMENT.md

Step 4: Launch the Application

# Start the application directly
ai-workflow-utils

The application will start immediately and be available at http://localhost:3000

Step 5: (Optional) Install as Startup Service

For production use or to run automatically on system boot:

ai-workflow-utils startup install

The service will now start automatically on boot. Access at http://localhost:3000

Startup Service Management:

ai-workflow-utils startup status    # Check service status
ai-workflow-utils startup start     # Start the service
ai-workflow-utils startup stop      # Stop the service
ai-workflow-utils startup uninstall # Remove startup service

Step 6: (Optional) PWA Installation (Progressive Web App)

**Supported Platforms:**

- **macOS**: Uses LaunchAgents (user-level service)
- **Windows**: Uses Windows Service Manager
- **Linux**: Uses systemd

For detailed startup service documentation, see [STARTUP.md](STARTUP.md)

### **Step 5: Configure Using the Settings Page**

All configuration is managed through the web-based settings page:

- Visit
  [`http://localhost:3000/settings/environment`](http://localhost:3000/settings/environment)
- Configure your AI provider (Anthropic Claude, OpenAI GPT, Google Gemini,
  Ollama)
- Set up Jira integration (URL, API token)
- Configure repository provider (Bitbucket)
- Set up issue tracking (Jira, etc.)
- Configure MCP clients for Model Context Protocol integration

All changes are saved to `~/.ai-workflow-utils/environment.json` and persist
across upgrades.

**No manual .env setup required!**

### **Step 6: (Optional) PWA Installation (Progressive Web App)**

**AI Workflow Utils is a fully-featured PWA!** Install it as a native app for
the best experience:

**🖥️ Desktop Installation:**

1. Open `http://localhost:3000` in Chrome, Edge
2. Look for the "Install" button in the address bar
3. Click "Install" to add AI Workflow Utils to your desktop
4. Launch directly from your desktop/dock - no browser needed!

**✨ PWA Benefits:**

- **🚀 Faster Loading**: Cached resources for instant startup
- **📱 Native Feel**: Works like a desktop
- **🔄 Auto Updates**: Always get the latest features
- **💾 Offline Ready**: Basic functionality works without internet
- **🎯 Focused Experience**: No browser distractions

---

<details>
     
<summary><strong>🎯 Feature Deep Dive</strong></summary>

### **🎫 AI Jira Ticket Creation**

**What makes it special:**

- **Dual AI System**: Primary cloud AI with local Ollama fallback
- **Image Intelligence**: Upload screenshots and get detailed bug reports
- **Smart Templates**: Automatically formats content based on issue type
- **Real-time Generation**: Watch AI create your tickets live

**Example Usage:**

1. Navigate to "Create Jira"
2. Describe your issue: _"Login button doesn't work on mobile"_
3. Upload a screenshot (optional)
4. Select issue type (Bug/Task/Story)
5. Watch AI generate professional content
6. Review and create ticket directly in Jira

**AI Providers Supported:**

- **OpenAI GPT-4** (with vision)
- **Anthropic Claude** (with vision)
- **Any OpenAI-compatible API**
- **Ollama LLaVA** (local, private)

### **🚀 AI-Powered Pull Request Creation**

**Revolutionary PR Generation:**

- **Smart Commit Analysis**: AI analyzes your commit messages to understand the
  changes
- **Automatic Type Detection**: Determines if changes are features, fixes, or
  chores
- **Professional Formatting**: Generates conventional commit-style titles
  (feat/fix/chore)
- **Streaming Generation**: Watch AI create content in real-time with live
  updates
- **Local AI Processing**: Uses Ollama for complete privacy and offline
  capability

**How it works:**

1. Navigate to "Create PR"
2. Enter project key, repository slug, ticket number, and branch name
3. Click "Preview" to start AI generation
4. Watch AI analyze commits and generate title/description in real-time
5. Edit the generated content if needed
6. Click "Create Pull Request" to submit to Bitbucket

**AI Features:**

- **Commit Message Analysis**: Extracts meaningful information from commit
  history
- **Smart Categorization**: Automatically prefixes with feat/fix/chore based on
  content
- **Ticket Integration**: Includes ticket numbers in standardized format
- **Editable Previews**: Full control over final content before submission
- **Persistent Settings**: Remembers project and repo settings for faster
  workflow

### **🔍 AI Code Review**

**Revolutionary Code Review:**

- **Context-Aware Analysis**: AI understands your codebase
- **Security Scanning**: Identifies potential vulnerabilities
- **Performance Optimization**: Suggests efficiency improvements
- **Best Practices**: Enforces coding standards

**How it works:**

1. Open a pull request in Bitbucket
2. Navigate to "GitStash Review"
3. Enter PR details
4. AI analyzes code changes
5. Get detailed review with suggestions
6. _Coming Soon_: Direct comment integration

### **📊 Real-time Logs & Monitoring**

**Comprehensive System Monitoring:**

- **Live Log Streaming**: Real-time log updates without page refresh
- **Multi-level Filtering**: Filter by Error, Warn, Info, Debug levels
- **Smart Search**: Full-text search across all log entries
- **Historical Access**: Browse past logs with pagination
- **Performance Insights**: Monitor API calls, response times, and system health

**How it works:**

1. Navigate to "Logs" in the web interface
2. Select log level filters (All, Error, Warn, Info, Debug)
3. Use search to find specific entries or error messages
4. View real-time updates as the system operates
5. Access historical logs for troubleshooting past issues

**Monitoring Features:**

- **Error Tracking**: Immediate visibility into system errors
- **API Monitoring**: Track AI provider calls and response times
- **User Activity**: Monitor feature usage and workflow patterns
- **System Health**: Resource usage and performance metrics
- **Debug Support**: Detailed logging for development and troubleshooting

</details>

<!-- Manual environment setup is deprecated. All configuration should be done via the web-based settings page. -->

---

</details>

---

<details>
<summary><strong>🏗️ Technical Architecture & Development</strong></summary>

### **🧩 Functional Programming Architecture**

AI Workflow Utils follows **functional programming principles** throughout the
codebase:

- **Pure Functions**: Side-effect free functions with predictable outputs
- **Immutable State Management**: State updates create new objects instead of
  mutations
- **Function Composition**: Small, composable functions that work together
- **No Classes**: Functional approach instead of object-oriented programming
- **Separation of Concerns**: Each module has a specific, well-defined
  responsibility

**Benefits:**

- **Easier Testing**: Pure functions are simple to test and reason about
- **Better Maintainability**: Predictable code flow and reduced complexity
- **Improved Reliability**: Immutable state prevents many common bugs
- **Enhanced Debugging**: Clear data flow makes debugging straightforward

### **🎭 Mock-First Development**

**Comprehensive Jira Mocking Service** for development and testing:

```bash
# Enable mock mode (no real API calls)
JIRA_MOCK_MODE=true

# Use real Jira API
JIRA_MOCK_MODE=false

Mock Service Features:

• Realistic API Responses: Mock data that matches real Jira API structure
• Stateful Operations: Created issues, comments, and attachments persist in memory
• Complete CRUD Support: Create, read, update, delete operations
• Advanced Features: JQL search, issue transitions, field validation
• Error Simulation: Test error handling with realistic error responses
• Fast Development: No external dependencies for development/testing

Functional Mock Architecture:

// Pure state management
const getMockState = () => ({ ...mockState });
const updateMockState = updates => ({ ...mockState, ...updates });

// Functional API operations
export const createIssue = async issueData => {
  /* pure function */
};
export const getIssue = async issueKey => {
  /* pure function */
};
export const searchIssues = async jql => {
  /* pure function */
};

📁 Modular Architecture

server/
├── controllers/           # Feature-based controllers
│   ├── jira/             # Jira integration
│   │   ├── services/     # Business logic services
│   │   ├── models/       # Data models
│   │   ├── utils/        # Utility functions
│   │   └── README.md     # Module documentation
│   ├── pull-request/     # PR creation & review
│   ├── email/            # Email generation
│   ├── chat/             # AI chat integration
│   └── mcp/              # Model Context Protocol client management
├── mocks/                # Mock services (excluded from npm package)
│   └── jira/             # Comprehensive Jira mocking
└── services/             # Shared services

Each module follows the same structure:

• Services: Core business logic (functional)
• Models: Data transformation and validation
• Utils: Pure utility functions
• README.md: Complete module documentation

🔧 Development Best Practices

• ESLint Integration: Enforces functional programming patterns
• Modular Design: Each feature is self-contained
• Comprehensive Documentation: Every module has detailed README
• Mock-First Testing: Develop without external dependencies
• Environment Variables: Configuration through environment
• Type Safety: JSDoc annotations for better IDE support