issue-core/README.md

# Issue Facade - Universal CLI for Issue Tracking

A convenient command-line facade that provides a unified interface to the repository's main issue tracker, regardless of which backend system is actually being used.

## Purpose

The **Issue Facade** acts as a convenient CLI wrapper that automatically detects and interfaces with whatever issue tracking system is configured for the current repository. This means you get a consistent, intuitive command-line experience whether your project uses:

- GitHub Issues
- GitLab Issues
- Gitea Issues
- JIRA
- Local SQLite storage
- Any other supported backend

## Philosophy

Rather than learning different commands and workflows for each issue tracking system, the Issue Facade provides:

- **One CLI to rule them all**: Same commands work across all backends
- **Repository-aware**: Automatically detects the relevant issue tracker for your repo
- **Offline capability**: Local SQLite fallback when remote systems are unavailable
- **Seamless sync**: Keep local and remote issue trackers synchronized

## How It Works

```bash
# The facade automatically detects your repository's issue tracker
cd /path/to/my-project
issue list                    # Lists issues from the repo's configured tracker

cd /path/to/another-project
issue list                    # Lists issues from THIS repo's tracker

# Same commands, different backends - transparent to the user
```

## Key Features

### 🎯 **Repository Context Awareness**
The facade automatically detects:
- Git remotes (GitHub, GitLab, Gitea URLs)
- Configuration files (`.issue-config`, `pyproject.toml`, etc.)
- Environment variables
- Default fallbacks

### 🖥️ **Unified CLI Experience**
```bash
# Core issue operations (same across all backends)
issue list                          # List issues
issue show 42                       # Show issue details
issue create "Bug in parser"        # Create new issue
issue edit 42 --add-label bug       # Edit existing issue
issue close 42 --comment "Fixed"    # Close with comment
issue comment 42 "Still broken"     # Add comment

# Advanced operations
issue list --assignee=me --state=open
issue search "memory leak"
issue stats                         # Show issue statistics
```

### 🔄 **Automatic Backend Detection**
```bash
# GitHub repository
cd my-github-project
issue list  # → Automatically uses GitHub Issues API

# Gitea repository
cd my-gitea-project
issue list  # → Automatically uses Gitea Issues API

# Offline/local work
cd any-project
issue backend set local
issue list  # → Uses local SQLite storage
```

### 🌐 **Seamless Synchronization**
```bash
# Work offline, sync later
issue create "Bug found offline" --local
issue sync                          # Pushes to remote when online

# Keep backups
issue sync pull                     # Download all remote issues locally
issue export backup.json            # Export for archival
```

## Installation & Setup

### 1. Install the Facade
```bash
pip install issue-facade
```

### 2. Automatic Configuration
The facade auto-detects your repository's issue tracker:

```bash
cd your-repository
issue config detect                 # Auto-configure based on git remotes
issue list                          # Ready to use!
```

### 3. Manual Configuration (if needed)
```bash
# Configure specific backends
issue backend add github my-repo
issue backend add gitea company-repo
issue backend add local offline

# Set repository-specific backend
issue config set-backend github     # For current repository
```

## Repository Integration Examples

### GitHub Repository
```bash
cd my-github-project
issue config detect
# → Automatically configures GitHub Issues via API
# → Uses .github/ISSUE_TEMPLATE/ for templates
# → Respects repository labels and milestones

issue create "Security vulnerability" --template security
```

### Corporate Gitea
```bash
cd company-project
issue config detect
# → Detects Gitea instance from git remote
# → Prompts for access token (one-time setup)
# → Uses corporate labels and workflows

issue list --milestone "Q4 Release"
```

### Offline Development
```bash
cd any-project
issue backend set local
# → Creates local SQLite database in .issue-facade/
# → Full offline functionality
# → Sync to remote when connection available

issue create "Performance issue" --offline
issue sync when-online
```

## Configuration

### Per-Repository Configuration
Each repository can have its own configuration in `.issue-facade/config.json`:

```json
{
  "backend": "github",
  "github": {
    "owner": "myorg",
    "repo": "myproject",
    "token_env": "GITHUB_TOKEN"
  },
  "local": {
    "db_path": ".issue-facade/issues.db",
    "sync_enabled": true
  },
  "templates": {
    "bug": ".github/ISSUE_TEMPLATE/bug_report.md",
    "feature": ".github/ISSUE_TEMPLATE/feature_request.md"
  }
}
```

### Global Configuration
User-wide settings in `~/.config/issue-facade/config.json`:

```json
{
  "default_backend": "local",
  "github_token": "env:GITHUB_TOKEN",
  "gitea_instances": {
    "company": {
      "url": "https://git.company.com",
      "token": "env:GITEA_TOKEN"
    }
  },
  "offline_mode": false,
  "sync_interval": "1h"
}
```

## Architecture

### Facade Pattern Implementation
```
Repository Working Directory
├── .git/                           # Git repository
├── .issue-facade/                  # Facade configuration
│   ├── config.json                # Repository-specific config
│   ├── issues.db                  # Local SQLite cache/backup
│   └── templates/                 # Issue templates
├── your-project-files...
└── issue                          # CLI command (context-aware)
```

### Backend Detection Logic
1. **Check repository configuration**: `.issue-facade/config.json`
2. **Analyze git remotes**: Detect GitHub/GitLab/Gitea URLs
3. **Look for platform files**: `.github/`, `.gitlab/`, etc.
4. **Check environment**: `GITHUB_TOKEN`, `GITLAB_TOKEN`, etc.
5. **Fall back to local**: SQLite storage if no remote detected

### Multi-Repository Support
```bash
# Each repository maintains its own context
/projects/web-app/     → GitHub Issues
/projects/api-server/  → GitLab Issues
/projects/cli-tool/    → Gitea Issues
/projects/experiment/  → Local SQLite

# Same commands work in all contexts
cd web-app && issue list      # GitHub
cd api-server && issue list   # GitLab
cd cli-tool && issue list     # Gitea
cd experiment && issue list   # Local
```

## Use Cases

### 1. **Multi-Platform Developer**
You work with repositories across GitHub, GitLab, and company Gitea:
```bash
# Learn one CLI, use everywhere
issue list --assignee=me        # Works on all platforms
issue create "Cross-platform bug" --label bug
```

### 2. **Offline Developer**
You need to track issues without constant internet:
```bash
issue create "Found while flying" --offline
issue list --local             # View offline issues
issue sync                      # Upload when back online
```

### 3. **Repository Migration**
Moving from GitHub to GitLab:
```bash
issue export github-backup.json    # Backup from GitHub
issue backend set gitlab            # Switch to GitLab
issue import github-backup.json     # Import to GitLab
```

### 4. **Cross-Repository Analytics**
Track issues across multiple repositories:
```bash
issue stats --all-repos            # Statistics across all configured repos
issue search "security" --global   # Search across all issue trackers
```

## Integration with Development Workflow

### Git Hooks Integration
```bash
# .git/hooks/pre-commit
issue list --assignee=me --state=open > ISSUES.md
git add ISSUES.md
```

### CI/CD Integration
```bash
# In your CI pipeline
issue create "Build failed on commit $SHA" --label ci-failure
issue close-if-fixed $ISSUE_NUMBER
```

### IDE Integration
```bash
# VS Code, Vim, Emacs plugins can use the CLI
:IssueList                          # List issues in editor
:IssueCreate "Typo in function"     # Create issue from editor
```

## Comparison with Native Tools

| Feature | issue-facade | gh (GitHub CLI) | glab (GitLab CLI) | Platform Web UI |
|---------|--------------|-----------------|-------------------|-----------------|
| **Multi-platform** | ✅ All backends | ❌ GitHub only | ❌ GitLab only | ❌ Single platform |
| **Offline support** | ✅ Local SQLite | ❌ Online only | ❌ Online only | ❌ Online only |
| **Consistent CLI** | ✅ Same commands | ❌ GitHub-specific | ❌ GitLab-specific | ❌ Web interface |
| **Repository context** | ✅ Auto-detect | ✅ Git-aware | ✅ Git-aware | ❌ Manual navigation |
| **Cross-repo search** | ✅ Global search | ❌ Single repo | ❌ Single repo | ❌ Single repo |
| **Data portability** | ✅ Export/import | ❌ Platform-locked | ❌ Platform-locked | ❌ Platform-locked |

## Future Roadmap

### Version 1.0 (Current)
- [x] Core facade architecture
- [x] GitHub/GitLab/Gitea backend support
- [x] Local SQLite backend
- [x] Automatic repository detection
- [x] Basic synchronization

### Version 1.1
- [ ] Advanced sync (conflict resolution)
- [ ] Issue templates support
- [ ] Workflow automation hooks
- [ ] Plugin system for custom backends

### Version 2.0
- [ ] Web dashboard for multi-repo overview
- [ ] Advanced analytics and reporting
- [ ] Team collaboration features
- [ ] Integration with project management tools

## Contributing

The Issue Facade is designed to be:
- **Backend-agnostic**: Easy to add new issue tracking systems
- **Repository-aware**: Respects the conventions of each platform
- **Developer-friendly**: Consistent CLI across all environments

To add a new backend:
1. Implement the `IssueBackend` interface
2. Add detection logic for the platform
3. Register the backend in the factory
4. Add CLI configuration support

## Why "Facade"?

The **Facade Pattern** perfectly describes this tool's purpose:

> *"Provide a unified interface to a set of interfaces in a subsystem. Facade defines a higher-level interface that makes the subsystem easier to use."*

Instead of learning different CLIs for GitHub (`gh`), GitLab (`glab`), JIRA, etc., the Issue Facade provides one consistent interface that works with all of them. It's the universal remote control for issue tracking systems.

The facade doesn't replace the underlying issue trackers - it makes them easier to use consistently across different platforms and repositories.