Metadata-Version: 2.4
Name: qx-cli
Version: 0.2.0
Summary: Qx CLI: scaffolding, code generation, local dev orchestration
Author: Qx Engineering
License: MIT
Requires-Python: >=3.14
Requires-Dist: jinja2>=3.1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: qx-core
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

# qx-cli

Scaffolding, code generation, and local-dev orchestration for the Qx framework. Invoked as `qx` once installed, or `uv run qx` during development.

## What lives here

- **`qx new service NAME`** — scaffold a complete new Qx service: directory structure, pyproject.toml, DI bootstrap, FastAPI app factory, Alembic config, Docker Compose overrides, and a `README.md`.
- **`qx generate aggregate NAME`** — add a domain aggregate with `Entity`, events, and a stub repository to an existing service.
- **`qx generate command NAME`** — add a `Command` and handler class with the standard boilerplate.
- **`qx generate query NAME`** — add a `Query` and handler class.
- **`qx generate endpoint`** — add a FastAPI route file wired to the Mediator.
- **`qx generate event NAME`** — add an `IntegrationEvent` and its handler skeleton.
- **`qx dev up`** — start the local Docker Compose stack (Postgres, Redis, NATS, Prometheus, Tempo, Grafana, MailHog, MinIO).
- **`qx dev down`** — stop and remove the local stack.
- **`qx version`** — print the framework version.

## Usage

```bash
# Install (or use via uv in the workspace)
pip install qx-cli

# Scaffold a new service
qx new service payments-service
cd payments-service

# Add domain objects
qx generate aggregate Payment
qx generate command ProcessPayment
qx generate query GetPayment
qx generate event PaymentProcessed

# Start local infra
qx dev up

# Run
uv run uvicorn payments_service.main:app --reload
```

## Generated structure

`qx new service` produces:

```
my-service/
├── src/my_service/
│   ├── domain/aggregates/        # domain model
│   ├── application/
│   │   ├── commands/             # command handlers
│   │   └── queries/              # query handlers
│   ├── infrastructure/
│   │   └── persistence/          # repositories, SA mapping
│   └── presentation/routes/      # FastAPI routes
├── tests/
│   ├── unit/
│   └── integration/
├── alembic/
├── pyproject.toml
└── README.md
```

## Design rules

- Generated code follows the same conventions as `examples/identity-service` — it is the canonical reference for what the generator should produce.
- `qx dev up/down` is a thin wrapper around `docker compose` pointing at `deploy/docker-compose.yaml` in the workspace root. It does not manage application containers, only infrastructure.
