issue-core/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Issue Facade is a universal CLI for issue tracking that provides a unified interface to multiple issue tracking backends (GitHub, GitLab, Gitea, local SQLite). It implements the Facade Pattern to abstract away differences between various issue tracking systems, providing developers with a consistent CLI experience regardless of the underlying backend.

Development Commands

Installation & Setup

• Install for development: pip install -e ".[dev]"
• Install production: pip install -e .
• Clean build artifacts: make issue-facade-clean

Testing

• Run all tests: pytest tests/
• Run specific test file: pytest tests/test_gitea_backend.py
• Run with coverage: pytest tests/ --cov=issue_tracker --cov-report=html --cov-report=term
• Run integration tests: pytest tests/test_gitea_integration.py -v

Code Quality

• Run linter: make issue-facade-lint
• Format code: black issue_tracker/ tests/ (line length: 100)
• Sort imports: isort issue_tracker/ tests/

CLI Usage

The project provides two entry points: issue and issue-tracker (both execute issue_tracker.cli.main:main)

Common commands:

• issue list - List issues
• issue show <number> - Show issue details
• issue create "Title" - Create new issue
• issue close <number> - Close issue
• issue backend list - List configured backends
• issue sync - Synchronize with remote backend

Architecture

Core Design Pattern: Facade with Plugin Architecture

The codebase implements a plugin-based facade pattern with clear separation of concerns:

┌─────────────────────────────────────────┐
│         CLI Layer (Click)               │
│   issue_tracker/cli/*.py                │
└───────────────┬─────────────────────────┘
                │
┌───────────────▼─────────────────────────┐
│     Core Domain Models                  │
│   issue_tracker/core/models.py          │
│   (Issue, Label, User, etc.)            │
└───────────────┬─────────────────────────┘
                │
┌───────────────▼─────────────────────────┐
│     Backend Interface (ABC)             │
│   issue_tracker/core/interfaces.py      │
│   IssueBackend, LocalBackend,           │
│   RemoteBackend, SyncableBackend        │
└───────────────┬─────────────────────────┘
                │
        ┌───────┴────────┐
        │                │
┌───────▼──────┐  ┌──────▼───────┐
│Local Backend │  │Gitea Backend │
│  (SQLite)    │  │  (REST API)  │
└──────────────┘  └──────────────┘

Key Components

1. Core Domain Models (issue_tracker/core/models.py)

• Issue: Universal issue model with state management, label categorization, and domain logic
• Label: Supports categorization (priority/type/status/other) with cached properties
• User, Milestone, Comment: Supporting models
• IssueState, Priority, IssueType: Enumerations with backend mapping

The Issue model uses @cached_property for performance optimization and includes domain logic methods (close(), reopen(), add_label(), etc.) that enforce business rules.

2. Backend Interface (issue_tracker/core/interfaces.py)

• IssueBackend (ABC): Defines the contract all backends must implement
• LocalBackend, RemoteBackend: Marker interfaces for backend categorization
• SyncableBackend: Interface for backends supporting synchronization
• BackendCapabilities: Describes feature support per backend
• BackendFactory: Registry pattern for backend creation

Critical: All backends MUST implement the full IssueBackend interface. The interface includes:

• Connection management: connect(), disconnect(), test_connection()
• CRUD operations: create_issue(), get_issue(), update_issue(), delete_issue()
• Query operations: list_issues(), search_issues()
• Label, User, Milestone, Comment operations
• Optional: bulk_update_issues() (if capabilities support it)

3. Backend Implementations

Local Backend (issue_tracker/backends/local/backend.py):

• Uses SQLite with schema defined in schema.sql
• Full offline functionality
• Serves as synchronization source of truth
• Implements LocalBackend and SyncableBackend

Gitea Backend (issue_tracker/backends/gitea/backend.py):

• REST API integration with Gitea instances
• Rate limiting and error handling
• ID mapping between local and remote issues
• Implements RemoteBackend and SyncableBackend

4. CLI Layer (issue_tracker/cli/)

• main.py: Entry point, Click group setup, command registration
• commands.py: Core issue operations (list, show, create, close)
• backend_commands.py: Backend management (add, list, switch)
• sync_commands.py: Synchronization operations
• utils.py: Helper functions for formatting and backend access

ID Mapping Strategy

The system uses a dual-ID approach for cross-backend synchronization:

• id: Universal ID (UUID for local, external ID for remote)
• number: Human-readable sequential number (user-facing)
• backend_id: Backend-specific identifier for sync

When syncing, backends maintain mappings between local numbers and remote IDs. The Gitea backend stores this in sync_metadata on the Issue model.

State Management

IssueState enum provides universal states with backend-specific mapping via to_backend_string():

• OPEN, CLOSED, IN_PROGRESS, BLOCKED
• Some backends (like Gitea) only support OPEN/CLOSED, so IN_PROGRESS and BLOCKED map to OPEN

Testing Strategy

Test Organization

• test_gitea_backend.py: Unit tests for Gitea backend with mocked API
• test_gitea_integration.py: Full integration tests with real Gitea instance
• test_cli_commands.py: CLI command testing

Integration Tests

The integration tests (test_gitea_integration.py) expect a Gitea instance at http://localhost:3000 with test credentials. They create a temporary test repository, run full CRUD operations, and clean up afterwards.

Important: Integration tests use pytest markers:

• @pytest.mark.integration - Integration tests (slower)
• @pytest.mark.unit - Unit tests (fast)

Run only unit tests: pytest -m unit Run only integration tests: pytest -m integration

Common Development Tasks

Adding a New Backend

1. Create backend package in issue_tracker/backends/<name>/
2. Implement IssueBackend interface (or extend LocalBackend/RemoteBackend)
3. Implement all abstract methods from the interface
4. Define BackendCapabilities to specify supported features
5. Register backend in BackendFactory (typically in __init__.py)
6. Add configuration handling in CLI backend commands
7. Write unit tests with mocked external dependencies
8. Write integration tests if applicable

Modifying the Issue Model

When changing issue_tracker/core/models.py:

1. Update the Issue dataclass definition
2. Update to_dict() serialization method
3. Invalidate caches if adding/modifying label-dependent properties
4. Update all backend implementations to handle new fields
5. Update database schema in backends/local/schema.sql
6. Write migration logic if modifying existing fields

Adding CLI Commands

1. Add command function in appropriate file (commands.py, backend_commands.py, etc.)
2. Use @click.command() decorator with appropriate options
3. Call get_backend(ctx) to retrieve the active backend
4. Use format_issue() or format_issue_list() from utils.py for consistent output
5. Handle errors with raise click.ClickException(message)
6. Register command in main.py if creating new command group

Configuration

Project Configuration (pyproject.toml)

• Entry points: issue and issue-tracker commands
• Dependencies: click, requests, python-dateutil
• Optional dependencies: dev, docs, gitea, github, jira
• Code style: Black (line-length=100), isort (profile="black")
• Test markers: unit, integration, slow

Makefile Integration

The capability integrates with the parent markitect project via Makefile:

• Prefixed targets: issue-facade-* for development commands
• Unprefixed targets: issue-* for user-facing CLI operations
• Uses pip install -e for editable installation

Important Patterns and Conventions

Error Handling

• Backend-specific errors inherit from base exceptions (e.g., GiteaAPIError)
• CLI commands convert exceptions to click.ClickException with user-friendly messages
• Use specific exception types for rate limiting, authentication, network issues

Type Hints

• Mypy strict mode enabled (disallow_untyped_defs = true)
• All functions must have type annotations
• Use Optional[T] for nullable types
• Use List[T], Dict[K, V] from typing module (Python 3.8 compatibility)

Performance Optimizations

• Use @cached_property for expensive computations (e.g., label categorization)
• Call invalidate_cache() when modifying cached data
• Single-pass algorithms for label categorization in Issue model

Synchronization

When implementing sync:

1. Local backend is source of truth
2. Remote backends track last sync timestamp
3. Use get_issues_modified_since() for incremental sync
4. Handle conflicts via SyncableBackend.resolve_sync_conflict()
5. Store sync metadata in Issue.sync_metadata dict

Dependencies and External Systems

Runtime Dependencies

• click: CLI framework (>=8.0.0)
• requests: HTTP client for remote backends (>=2.25.0)
• python-dateutil: Date/time parsing (>=2.8.0)

Development Dependencies

• pytest: Testing framework with markers support
• pytest-cov: Coverage reporting
• pytest-mock: Mocking utilities
• black, isort, flake8, mypy: Code quality tools

External Systems

• Gitea API: REST API at /api/v1/ endpoints
• SQLite: Local database (no server required)
• Future: GitHub API, GitLab API, JIRA API

Repository Context

This is a capability within the larger markitect project (/capabilities/issue-facade/). The capability:

• Can be installed independently via pip install -e .
• Integrates with parent project via Makefile targets
• Follows markitect capability conventions for structure and naming