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

# 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

# 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

# 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

# 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

pip install issue-facade

2. Automatic Configuration

The facade auto-detects your repository's issue tracker:

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

3. Manual Configuration (if needed)

# 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

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

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

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:

{
  "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:

{
  "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

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

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

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:

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:

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

# .git/hooks/pre-commit
issue list --assignee=me --state=open > ISSUES.md
git add ISSUES.md

CI/CD Integration

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

IDE Integration

# 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)

• Core facade architecture
• GitHub/GitLab/Gitea backend support
• Local SQLite backend
• Automatic repository detection
• 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.