Metadata-Version: 2.5
Name: bug-lifecycle-engine
Version: 1.0.0
Summary: QA capability package — full bug lifecycle management against the existing worky bugs table
License: Proprietary
Requires-Python: >=3.11
Requires-Dist: alembic==1.13.1
Requires-Dist: fastapi==0.111.0
Requires-Dist: psycopg2-binary>=2.9.9
Requires-Dist: pydantic-settings==2.2.1
Requires-Dist: pydantic==2.7.1
Requires-Dist: pyyaml==6.0.1
Requires-Dist: sqlalchemy==2.0.30
Requires-Dist: uvicorn==0.30.1
Provides-Extra: dev
Requires-Dist: factory-boy==3.3.0; extra == 'dev'
Requires-Dist: pytest-asyncio==0.23.6; extra == 'dev'
Requires-Dist: pytest==8.2.0; extra == 'dev'
Description-Content-Type: text/markdown

# bug-lifecycle-engine

QA capability package for full **bug lifecycle management** against the existing
`worky` database.

## QA-DB-Only Constraint

This package **does not create or own a database**. It maps directly onto the
pre-existing `bugs` table in the `worky` Postgres instance.

**Table access:**

| Table | Access | Notes |
|---|---|---|
| `bugs` | read/write | Core table — all lifecycle transitions |
| `test_runs` | read-only FK target | |
| `test_cases` | read-only FK target | |
| `users` | read-only FK target | |
| `projects`, `usecases`, `user_stories`, `tasks`, `subtasks` | read-only FK targets | Hierarchy |
| `clients`, `programs` | read-only FK targets | Top-level hierarchy |

**Migration policy:**
- This package ships additive-only migrations in `migrations/versions/`.
- No existing column is dropped, renamed, or type-changed.
- Every migration file includes a `downgrade()` function that fully reverses the change.
- No migration recreates the `bugs` table or any other pre-existing table.

## Installation

```bash
# From source
pip install -e .

# From a tagged GitHub release
pip install git+https://github.com/<org>/bug-lifecycle-engine@v1.0.0
```

## Running migrations

```bash
# Apply all pending additive migrations
cd packages/bug-lifecycle-engine
alembic upgrade head

# Roll back the most recent migration
alembic downgrade -1
```

Set `DATABASE_URL` in the environment before running Alembic, or configure
`alembic.ini`'s `sqlalchemy.url`. The recommended approach is env-var-driven:

```bash
export DATABASE_URL="postgresql+psycopg2://user:pass@host:5432/worky"
alembic upgrade head
```

## Usage

```python
from bug_lifecycle_engine import get_engine, get_session
from bug_lifecycle_engine.crud import BugCRUD

engine = get_engine()
with get_session(engine) as session:
    crud = BugCRUD(session)
    bug = crud.create(payload)
    crud.transition(bug.id, "Open", by="USR-000001")
```

## Environment Variables

| Variable | Description |
|---|---|
| `DATABASE_HOST` | Postgres host |
| `DATABASE_PORT` | Postgres port (default `5432`) |
| `DATABASE_NAME` | Database name |
| `DATABASE_USER` | Postgres user |
| `DATABASE_PASSWORD` | Postgres password |
| `DATABASE_POOL_SIZE` | Connection pool size (default `5`) |
| `DATABASE_MAX_OVERFLOW` | Pool max overflow (default `10`) |
