generated from coulomb/repo-seed
feat: rename to issue-core and add task ingestion endpoint
Renames the package, distribution, CLI alias, Makefile targets, and working directory from issue-facade to issue-core, signalling its role as the authoritative task lifecycle manager for the Coulomb org (peer to activity-core, rules-core, project-core). Adds POST /issues/ ingestion endpoint for activity-core's IssueSink, under a new optional [api] extra. The endpoint is served by `issue serve`, authenticates via the ISSUE_CORE_API_KEY env var (Bearer or X-API-Key header), and routes the TaskSpec payload to the configured default backend with full traceability metadata embedded in sync_metadata. - T01: Python package issue_tracker -> issue_core, dir rename - T02: registered in state hub under custodian domain - T03: INTENT.md (what it is, what it isn't, how it fits) - T04: SCOPE.md (in/out-of-scope, integration boundaries) - T05: POST /issues/ via FastAPI + Uvicorn, 9 unit tests - T06: docs/nats-task-ingestion.md design stub Closes ISSC-WP-0001. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
46
CLAUDE.md
46
CLAUDE.md
@@ -4,28 +4,28 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
||||
|
||||
## 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.
|
||||
Issue Core 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`
|
||||
- Clean build artifacts: `make issue-core-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 with coverage: `pytest tests/ --cov=issue_core --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/`
|
||||
- Run linter: `make issue-core-lint`
|
||||
- Format code: `black issue_core/ tests/` (line length: 100)
|
||||
- Sort imports: `isort issue_core/ tests/`
|
||||
|
||||
### CLI Usage
|
||||
The project provides two entry points: `issue` and `issue-tracker` (both execute `issue_tracker.cli.main:main`)
|
||||
The project provides two entry points: `issue` and `issue-core` (both execute `issue_core.cli.main:main`)
|
||||
|
||||
Common commands:
|
||||
- `issue list` - List issues
|
||||
@@ -44,18 +44,18 @@ The codebase implements a **plugin-based facade pattern** with clear separation
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ CLI Layer (Click) │
|
||||
│ issue_tracker/cli/*.py │
|
||||
│ issue_core/cli/*.py │
|
||||
└───────────────┬─────────────────────────┘
|
||||
│
|
||||
┌───────────────▼─────────────────────────┐
|
||||
│ Core Domain Models │
|
||||
│ issue_tracker/core/models.py │
|
||||
│ issue_core/core/models.py │
|
||||
│ (Issue, Label, User, etc.) │
|
||||
└───────────────┬─────────────────────────┘
|
||||
│
|
||||
┌───────────────▼─────────────────────────┐
|
||||
│ Backend Interface (ABC) │
|
||||
│ issue_tracker/core/interfaces.py │
|
||||
│ issue_core/core/interfaces.py │
|
||||
│ IssueBackend, LocalBackend, │
|
||||
│ RemoteBackend, SyncableBackend │
|
||||
└───────────────┬─────────────────────────┘
|
||||
@@ -70,7 +70,7 @@ The codebase implements a **plugin-based facade pattern** with clear separation
|
||||
|
||||
### Key Components
|
||||
|
||||
#### 1. Core Domain Models (`issue_tracker/core/models.py`)
|
||||
#### 1. Core Domain Models (`issue_core/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
|
||||
@@ -78,7 +78,7 @@ The codebase implements a **plugin-based facade pattern** with clear separation
|
||||
|
||||
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`)
|
||||
#### 2. Backend Interface (`issue_core/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
|
||||
@@ -94,19 +94,19 @@ The Issue model uses `@cached_property` for performance optimization and include
|
||||
|
||||
#### 3. Backend Implementations
|
||||
|
||||
**Local Backend** (`issue_tracker/backends/local/backend.py`):
|
||||
**Local Backend** (`issue_core/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`):
|
||||
**Gitea Backend** (`issue_core/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/`)
|
||||
#### 4. CLI Layer (`issue_core/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)
|
||||
@@ -150,7 +150,7 @@ Run only integration tests: `pytest -m integration`
|
||||
|
||||
### Adding a New Backend
|
||||
|
||||
1. Create backend package in `issue_tracker/backends/<name>/`
|
||||
1. Create backend package in `issue_core/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
|
||||
@@ -161,7 +161,7 @@ Run only integration tests: `pytest -m integration`
|
||||
|
||||
### Modifying the Issue Model
|
||||
|
||||
When changing `issue_tracker/core/models.py`:
|
||||
When changing `issue_core/core/models.py`:
|
||||
1. Update the `Issue` dataclass definition
|
||||
2. Update `to_dict()` serialization method
|
||||
3. Invalidate caches if adding/modifying label-dependent properties
|
||||
@@ -181,7 +181,7 @@ When changing `issue_tracker/core/models.py`:
|
||||
## Configuration
|
||||
|
||||
### Project Configuration (`pyproject.toml`)
|
||||
- Entry points: `issue` and `issue-tracker` commands
|
||||
- Entry points: `issue` and `issue-core` commands
|
||||
- Dependencies: click, requests, python-dateutil
|
||||
- Optional dependencies: dev, docs, gitea, github, jira
|
||||
- Code style: Black (line-length=100), isort (profile="black")
|
||||
@@ -189,7 +189,7 @@ When changing `issue_tracker/core/models.py`:
|
||||
|
||||
### Makefile Integration
|
||||
The capability integrates with the parent markitect project via `Makefile`:
|
||||
- Prefixed targets: `issue-facade-*` for development commands
|
||||
- Prefixed targets: `issue-core-*` for development commands
|
||||
- Unprefixed targets: `issue-*` for user-facing CLI operations
|
||||
- Uses `pip install -e` for editable installation
|
||||
|
||||
@@ -239,7 +239,7 @@ When implementing sync:
|
||||
|
||||
## Repository Context
|
||||
|
||||
This is a capability within the larger markitect project (`/capabilities/issue-facade/`). The capability:
|
||||
This is a capability within the larger markitect project (`/capabilities/issue-core/`). 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
|
||||
@@ -268,7 +268,7 @@ feedback/
|
||||
|
||||
### For Users: Submitting Feedback
|
||||
|
||||
Users of issue-facade (master projects integrating it) can submit feedback in multiple ways:
|
||||
Users of issue-core (master projects integrating it) can submit feedback in multiple ways:
|
||||
|
||||
**Option 1: Using feedback CLI**
|
||||
```bash
|
||||
@@ -294,8 +294,8 @@ EOF
|
||||
**Option 3: From master project**
|
||||
```bash
|
||||
cd my-master-project
|
||||
echo "Feedback about issue-facade..." > feedback.md
|
||||
cp feedback.md capabilities/issue-facade/feedback/inbound/$(date +%Y%m%d)-feedback.md
|
||||
echo "Feedback about issue-core..." > feedback.md
|
||||
cp feedback.md capabilities/issue-core/feedback/inbound/$(date +%Y%m%d)-feedback.md
|
||||
```
|
||||
|
||||
### For Maintainers: Processing Feedback
|
||||
|
||||
Reference in New Issue
Block a user