microforge 2.0.1
AI-enhanced Python microservice platform with intelligent code generation
License: MIT
Requires Python: >=3.11
Keywords: microservices, ai, code-generation, cli, development, automation

<div align="center">

# 🔨⚡ Microforge

</div>

<p align="center">
  <strong>AI-enhanced microservice platform for Python development</strong>
</p>

<p align="center">
  <a href="https://www.python.org/downloads/release/python-3110/"><img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
  <a href="#"><img src="https://img.shields.io/badge/tests-49%20passing-green.svg" alt="Tests"></a>
  <a href="#"><img src="https://img.shields.io/badge/coverage-80%2B%25-green.svg" alt="Coverage"></a>
  <a href="#"><img src="https://img.shields.io/badge/FastAPI-ready-009688.svg" alt="FastAPI Ready"></a>
  <a href="#"><img src="https://img.shields.io/badge/CLI-Rich%20%2B%20Click-brightgreen.svg" alt="CLI Rich + Click"></a>
</p>

<p align="center">
  <em>Generate, manage, and maintain consistent microservices with a single CLI command</em>
</p>

Microforge standardizes Python microservice creation across multiple repositories with intelligent AI orchestration and graceful template-based fallbacks. Generate, manage, and maintain consistent microservices with a single CLI command.

## ✨ Features

### Single Repository Features
- **🏠 Local Setup**: `microforge setup` initializes everything in your current project
- **📚 Smart Documentation**: Generates comprehensive docs with CLAUDE.md instructions
- **🔄 Intelligent Updates**: Preserves custom content when updating CLAUDE.md
- **🎯 No Auto-commit**: Review all changes before committing

### Multi-Repository Features  
- **📊 Service Registry**: Centralized management of multiple microservice repositories
- **🌐 Batch Operations**: Generate docs across all services with one command
- **🔀 Automated PRs**: Creates branches and PR links for each repository
- **📈 Scale Management**: Track and update dozens of services efficiently

### Core Features
- **🧠 AI-Enhanced Development**: Claude Code integration for intelligent code generation
- **🎯 Standards Enforcement**: Consistent coding patterns and quality checks
- **🔧 Graceful Degradation**: Works with or without AI assistance
- **⚡ Agent-Based**: Uses AI agents for complex analysis and generation
- **🎨 Beautiful Web UI**: Modern dashboard with real-time visualizations
- **📥 GitHub Integration**: Fetch and save issues locally with attachments

## 🛠️ Core Technologies

- **Framework**: FastAPI with async/await patterns
- **Databases**: PostgreSQL, MongoDB, Redis support
- **Code Quality**: flake8, mypy, pytest, black
- **AI Integration**: Claude Code (optional)
- **CLI**: Click + Rich for beautiful terminal experience

## 🚀 Quick Start

### Installation

```bash
# Install Microforge from dev branch (default - you need access to the private repo)
pip install git+https://github.com/inviz-search/microforge-ai.git

# Or install from a specific branch
pip install git+https://github.com/inviz-search/microforge-ai.git@feature/ai-hooks-system

# That's it! Microforge is now available in your current environment
# No env-setup needed - Microforge auto-detects its location!

# Keep Microforge up to date
microforge update                            # Update to latest version
# Microforge auto-checks for updates daily and notifies you

# Multiple conda environments? No problem!
# Each environment has its own independent Microforge installation
```

### Project Setup (Recommended)

After installing Microforge, run setup in your project:

```bash
# In your project directory
microforge setup

# This creates:
# - CLAUDE.md (Project-specific AI instructions)
# - docs/service/ (Comprehensive documentation)
# - MICROFORGE_CLAUDE.md (Microforge hooks)
# - .microforge/hooks/ (Hook definitions)
# - .microforge/config.yaml (Configuration)
```

**Important**: Review the generated files and commit when ready. All changes are local - no auto-commit.

### Basic Usage

#### For Single Repository (Current Project)
```bash
# One-time setup in your project
cd your-project/
microforge setup

# This creates comprehensive documentation and AI instructions
# Review changes and commit when ready
```

#### For Multi-Repository Management
```bash
# Create application groups for better organization
microforge app add search --description "Search and discovery platform"
microforge app add auth --description "Authentication and authorization"

# Register services within applications
microforge service add search-api https://github.com/company/search-api --app search
microforge service add query-parser https://github.com/company/query-parser --app search
microforge service add auth-service https://github.com/company/auth-service --app auth
microforge service add user-service https://github.com/company/user-service --app auth

# View organized structure
microforge app list                          # Shows all applications
microforge app show search                   # Shows search app with its services
microforge service list --app search         # List only search services

# Generate documentation across all services
microforge analyze --all                     # Creates PRs in each repo

# Or update a specific service
microforge analyze search-api
```

## 📋 Available Commands

### 🚀 Single Repository Setup (Working in your project)
```bash
# Quick setup - Initialize everything in current project
microforge setup                             # Docs + Hooks + CLAUDE.md
microforge setup --docs-only                 # Only generate documentation
microforge setup --hooks-only                # Only initialize hooks
microforge setup --force                     # Regenerate all files

# Analyze and document current project
microforge analyze .                         # Generate docs and dependencies
microforge audit .                           # Code quality and security audit
```

### 🌐 Multi-Repository Management (Managing multiple services)
```bash
# Application Management - Group related services together
microforge app add <name> --description <desc>  # Create application group
microforge app list                             # List all applications
microforge app show <name>                      # Show app with its services
microforge app remove <name>                    # Remove app and all services
microforge app status                           # Overview of apps and services

# Service Registry - Track multiple repositories
microforge service add <name> <repo-url>        # Register standalone service
microforge service add <name> <repo-url> --app <app>  # Add to application
microforge service list                         # List all registered services
microforge service list --app <app>             # List services in an app
microforge service show <name>                  # Show service details
microforge service update <name> --repo-url <url>
microforge service remove <name>

# Documentation and analysis across multiple repos
microforge analyze <service-name>               # Analyze specific service
microforge analyze --all                        # Analyze all services
microforge audit <service-name>                 # Audit specific service
microforge audit --all                          # Audit all services
# Note: Multi-repo operations create branches and PRs in each repository
```

### 🔄 Version Management (Keep Microforge up to date)
```bash
microforge update                            # Update to latest version
microforge update --check                    # Check for updates without installing
microforge update --force                    # Force reinstall current version
# Auto-checks for updates once per day when you run any command
```

### 🔍 Code Audit (Quality and security analysis)
```bash
microforge audit .                           # Full audit of current directory
microforge audit . --security-only           # Security vulnerabilities only
microforge audit . --debt-only               # Technical debt analysis only
microforge audit . --quick                   # Quick essential checks
microforge audit . --format json             # Output in JSON format
```

### 📥 GitHub Issues Management (Fetch and create issues)
```bash
# Prerequisites: Install and authenticate GitHub CLI
brew install gh                              # Install GitHub CLI (macOS)
gh auth login                                # Authenticate with GitHub

# Fetch issues from current repository
microforge issues fetch                      # Interactive selection of open issues
microforge issues fetch --state all          # Show all issues (open and closed)
microforge issues fetch --state closed       # Show only closed issues
microforge issues fetch --label bug          # Filter by label
microforge issues fetch --assignee @me       # Filter by assignee
microforge issues fetch --number 123         # Fetch specific issue directly

# Batch operations
microforge issues fetch --all                # Download all issues without selection
microforge issues fetch --limit 10           # Limit number of issues to fetch
microforge issues fetch --output-dir ./my-issues  # Custom output directory

# Advanced options
microforge issues fetch --no-attachments     # Skip downloading images/files

# Create issues from local files
microforge issues create ./issues/issue_123  # Create from downloaded issue
microforge issues create ./my-template       # Create from custom template
microforge issues create ./issue-folder --labels bug,urgent    # Add labels
microforge issues create ./issue-folder --assignees @username  # Add assignees

# Submit issues to Claude for analysis (requires Claude CLI)
microforge issues submit --issue-id 123 --agent implementation.md  # Analyze with implementation agent
microforge issues submit --issue-id 123 --agent security.md        # Security analysis
microforge issues submit --issue-id 123 --agent audit_report       # Code audit perspective
microforge issues submit --issue-id 123 --agent /path/to/custom.md  # Custom agent file
microforge issues submit --issue-id 123 --agent implementation --batch  # Non-interactive mode

# Output structure (for fetch):
# issues/
# ├── issue_123/
# │   ├── issue.md        # Complete issue with description and comments
# │   ├── metadata.yaml   # Structured data (labels, assignees, dates)
# │   └── attachments/    # Downloaded images and files

# Input structure (for create):
# issue-folder/
# ├── metadata.yaml       # Required: title, labels, assignees, milestone
# ├── issue.md           # Required: issue body content
# └── attachments/       # Optional: files to reference (manual upload needed)
```

### 🎯 AI Hooks Management (Code quality enforcement)
```bash
microforge hooks init                        # Initialize hooks
microforge hooks status                      # Check status and version
microforge hooks update                      # Update to latest version
microforge hooks list                        # List available hooks
microforge hooks show <hook_name>            # Show hook details
microforge hooks view <hook_name>            # View hook instructions
microforge hooks toggle <name> --enable      # Enable a hook
microforge hooks toggle <name> --disable     # Disable a hook
microforge hooks refresh                      # Refresh hook registry
microforge hooks validate                     # Validate hook configurations
```

### 🎨 Web Dashboard (Beautiful UI for visual management)
```bash
microforge ui                                # Launch web dashboard (opens browser)
microforge ui --port 8080                    # Use custom port
microforge ui --no-browser                   # Don't open browser automatically
microforge ui --reload                       # Enable auto-reload for development
```

## 🏗️ Architecture

```
┌─────────────────────────────────────────┐
│        AI Enhancement Layer            │ ← Optional, graceful degradation
├─────────────────────────────────────────┤
│        Core Platform & Templates        │ ← Always available
├─────────────────────────────────────────┤
│    Standard Config & Conventions        │ ← Industry standards
└─────────────────────────────────────────┘
```

**Core Principles:**
- **Standard-First**: Industry-standard tools and patterns
- **AI-Enhanced**: Intelligent orchestration when Claude Code is available
- **Single Package**: No complex setup or separate extensions
- **Portable**: No vendor lock-in

## 🤖 Claude Integration

Microforge integrates with Claude CLI for AI-powered analysis:

```bash
# Install Claude CLI (if not already installed)
npm install -g @anthropic-ai/claude

# Now commands automatically use Claude
microforge setup          # Claude assists with project setup
microforge analyze .      # Claude analyzes your codebase
microforge audit .        # Claude audits code quality
```

### Command Options
All commands support Claude integration:
- `--use-claude` (default): Use Claude CLI for analysis
- `--no-claude`: Use Python fallback implementation
- `--batch`: Run Claude in non-interactive batch mode

## 📖 AI Agents & Hooks

Microforge uses specialized AI agents to analyze and document your code:

### Agents
- **[Base Orchestrator](docs/agents/base-orchestrator.md)** - Coordinates all analysis operations
- **[Documentation Agent](docs/agents/documentation.md)** - Generates comprehensive service documentation
- **[Dependency Graph Agent](docs/agents/dependency-graph.md)** - Maps service, endpoint, and function dependencies
- **[Audit Report Agent](docs/agents/audit-report.md)** - Performs code quality and security audits

### Hooks
- **[Planning Hook](docs/hooks/planning-pre-hook.md)** - Creates implementation plans before code changes
- **[Code Quality Hook](docs/hooks/code-quality.md)** - Enforces standards for AI assistants

### Hook Version Management
Microforge tracks hook versions to ensure consistency across projects:
- **Automatic Updates**: Check for updates with `microforge hooks status`
- **Version Tracking**: Each hook has its own version number
- **Safe Updates**: Configuration is preserved when updating hooks
- **Compliance Checking**: Validate your project against hook requirements

**[📚 Full Agents Documentation](docs/agents/index.md)** | **[🔧 Full Hooks Documentation](docs/hooks/index.md)**

## 🧪 Development & Testing

```bash
# Run all tests
make test

# Specific test categories
make test-unit                # Unit tests
make test-integration         # Integration tests
make test-core               # Core module tests
make test-cli                # CLI tests

# Code quality
make lint                    # Linting
make format                  # Code formatting
make type-check             # Type checking
make quality                # All quality checks

# Development workflow
make dev                    # Setup + test + quality
make ci                     # CI simulation
```

## 📁 Project Structure

```
src/microforge/
├── cli/                    # Click-based CLI interface
│   ├── main.py            # CLI entry point
│   └── commands/          # Command implementations
├── core/                  # Core platform logic
│   ├── service_registry.py    # Service management
│   ├── config_manager.py     # Configuration handling
│   └── template_engine.py    # Template system
├── ai/                    # AI integration components
│   ├── agents/            # Specialized AI agents
│   └── workflows/         # AI-driven workflows
└── utils/                 # Shared utilities
```

## 🔧 Configuration

Service registry data is stored in `~/.microforge/services.json` and created automatically on first use.

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Run tests (`make test`)
4. Check code quality (`make quality`)
5. Commit changes (`git commit -m 'Add amazing feature'`)
6. Push to branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

## 📄 Requirements

- Python 3.11+
- Git (for repository operations)
- Click 8.1+ and Rich 13.0+ (automatically installed)

## 📜 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

**Built with ❤️ for modern Python microservice development**