qx-cli 0.1.0__py3-none-any.whl

qx/cli/scaffolds/service/README.md.j2

@@ -0,0 +1,59 @@
+# {{ service_name }}
+
+A [Qx](https://qx.dev) service.
+
+## Quickstart
+
+```bash
+uv sync
+docker compose -f ../deploy/docker-compose.yaml up -d  # local Postgres + Redis + NATS
+uv run alembic upgrade head
+uv run uvicorn {{ service_pkg }}.main:app --reload
+```
+
+The service listens on `http://localhost:8000`. Health checks live at
+`/healthz` and `/readyz`; metrics at `/metrics`; OpenAPI docs at `/docs`.
+
+## Project layout
+
+```
+src/{{ service_pkg }}/
+  domain/         # aggregates, entities, value objects, domain events
+  application/    # command/query handlers, DTOs, application services
+  infrastructure/ # SQLAlchemy mappings, repositories, NATS adapters
+  presentation/   # FastAPI routers, gRPC servicers
+  main.py         # composition root
+```
+
+## Generating code
+
+```bash
+qx generate aggregate Invoice
+qx generate command CreateInvoice --aggregate Invoice
+qx generate query GetInvoice
+qx generate endpoint --method POST --handler CreateInvoice /invoices
+qx generate event InvoiceCreated
+```
+
+## Testing
+
+```bash
+uv run pytest
+```
+
+Integration tests use testcontainers — they require Docker running locally.
+
+## Configuration
+
+All settings come from environment variables with the prefix `QX_`.
+The most common:
+
+| Env var | Purpose |
+|---|---|
+| `QX_DB__URL` | Postgres connection URL |
+| `QX_CACHE__URL` | Redis URL |
+| `QX_NATS__SERVERS` | NATS servers (JSON array) |
+| `QX_LOGGING__JSON_OUTPUT` | `true` in prod, `false` for human-readable |
+| `QX_LOGGING__LEVEL` | `INFO`/`DEBUG`/etc. |
+
+See the framework docs for the full list.

qx/cli/scaffolds/service/alembic/env.py.j2

@@ -0,0 +1,13 @@
+"""Alembic env — defers to the framework helper.
+
+Service-specific MetaData comes from the infrastructure layer; the framework
+handles async engine wiring and naming conventions.
+"""
+
+from __future__ import annotations
+
+from qx.db.migrations import run_async_migrations
+
+from {{ service_pkg }}.infrastructure import metadata
+
+run_async_migrations(metadata)

qx/cli/scaffolds/service/alembic/script.py.mako

@@ -0,0 +1,26 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+"""
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

qx/cli/scaffolds/service/alembic.ini.j2

@@ -0,0 +1,38 @@
+[alembic]
+script_location = alembic
+sqlalchemy.url = postgresql+asyncpg://postgres:postgres@localhost:5432/{{ service_pkg }}
+file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

qx/cli/scaffolds/service/pyproject.toml.j2

@@ -0,0 +1,47 @@
+[project]
+name = "{{ service_kebab }}"
+version = "0.1.0"
+description = "{{ service_name }} — a Qx service."
+requires-python = ">=3.12"
+dependencies = [
+    "qx-core",
+    "qx-di",
+    "qx-cqrs",
+    "qx-db",
+    "qx-cache",
+    "qx-events",
+    "qx-http",
+    "qx-observability",
+    "qx-worker",
+    "uvicorn[standard]>=0.32.0",
+    "alembic>=1.13.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "qx-testing",
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "ruff>=0.6.0",
+    "mypy>=1.11.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/{{ service_pkg }}"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+plugins = ["pydantic.mypy"]

qx/cli/scaffolds/service/src/__service_pkg__/__init__.py.j2

@@ -0,0 +1,3 @@
+"""{{ service_name }} service package."""
+
+__version__ = "0.1.0"

qx/cli/scaffolds/service/src/__service_pkg__/application/__init__.py.j2

@@ -0,0 +1,22 @@
+"""Application layer.
+
+Command/query handlers, application services, and DTOs.
+
+When you add a command via ``qx generate command Foo``, the handler
+is registered automatically by walking the ``application`` module here.
+"""
+
+from __future__ import annotations
+
+from qx.cqrs import Mediator
+from qx.di import Container
+
+
+def register_handlers(mediator: Mediator, _container: Container) -> int:
+    """Discover and register every CQRS handler in this package.
+
+    Returns the number of handlers registered.
+    """
+    from {{ service_pkg }} import application as app_pkg
+
+    return mediator.register_decorated(app_pkg)

qx/cli/scaffolds/service/src/__service_pkg__/domain/__init__.py.j2

@@ -0,0 +1,22 @@
+"""Domain layer.
+
+Aggregates, entities, value objects, and domain events live here. This layer
+has no dependencies on infrastructure (no SQLAlchemy, no HTTP, no NATS).
+
+When you add an aggregate via ``qx generate aggregate Foo``, it
+appears under ``aggregates/``. Register your integration event types in
+``register_events`` so the worker knows how to decode them off the broker.
+"""
+
+from __future__ import annotations
+
+from qx.events import EventRegistry
+
+
+def register_events(registry: EventRegistry) -> None:
+    """Register every IntegrationEvent class this service publishes or consumes.
+
+    The registry is used by the worker to deserialize incoming NATS messages.
+    """
+    # registry.register(SomeIntegrationEvent)
+    pass

qx/cli/scaffolds/service/src/__service_pkg__/infrastructure/__init__.py.j2

@@ -0,0 +1,22 @@
+"""Infrastructure layer.
+
+Concrete adapters: SQLAlchemy mappings, repositories, NATS adapters,
+external HTTP clients. This layer depends on everything; domain and
+application depend on nothing here directly — only on the interfaces
+they declare.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy import MetaData
+
+from qx.db import make_metadata
+from qx.db.outbox import include_outbox_table
+
+# Single metadata for the service. Add Table() definitions in the same
+# module that defines the aggregate (under domain/aggregates/<name>/mapping.py)
+# and they will all share this MetaData.
+metadata: MetaData = make_metadata()
+
+# The outbox table is always present; aggregates plug in alongside.
+include_outbox_table(metadata)

qx/cli/scaffolds/service/src/__service_pkg__/main.py.j2

@@ -0,0 +1,88 @@
+"""{{ service_name }} entrypoint.
+
+Wires the DI container, mediator, database, observability, and FastAPI app
+together. ``uvicorn {{ service_pkg }}.main:app`` boots the service.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+
+from qx.core import QxSettings
+from qx.cqrs import ExceptionTranslationBehavior, LoggingBehavior, Mediator
+from qx.db import (
+    DatabaseSettings,
+    SessionFactory,
+    UnitOfWork,
+    create_engine,
+    make_session_factory,
+)
+from qx.di import Container
+from qx.events import EventRegistry, MediatorEventDispatcher
+from qx.http import setup_qx_app
+from qx.observability import setup_observability
+
+from {{ service_pkg }}.application import register_handlers
+from {{ service_pkg }}.domain import register_events
+from {{ service_pkg }}.presentation import register_routes
+
+
+def build_app() -> FastAPI:
+    settings = QxSettings(app={"name": "{{ service_kebab }}"})
+    metrics, health = setup_observability(settings)
+    container = Container()
+
+    # ---- Settings + infrastructure singletons ----
+    db_settings = DatabaseSettings()
+    engine = create_engine(db_settings)
+    session_factory = make_session_factory(engine)
+    container.register_instance(SessionFactory, session_factory)
+
+    # ---- Mediator ----
+    mediator = Mediator(
+        container,
+        command_behaviors=(LoggingBehavior(), ExceptionTranslationBehavior()),
+        query_behaviors=(LoggingBehavior(), ExceptionTranslationBehavior()),
+    )
+    container.register_instance(Mediator, mediator)
+
+    # ---- Event registry (integration event types this service knows about) ----
+    event_registry = EventRegistry()
+    register_events(event_registry)
+    container.register_instance(EventRegistry, event_registry)
+
+    # ---- UnitOfWork — scoped (per-request) ----
+    def _uow_factory() -> UnitOfWork:
+        from qx.db.outbox import DefaultOutboxRecorder
+        return UnitOfWork(
+            session_factory=session_factory,
+            dispatcher=MediatorEventDispatcher(mediator),
+            outbox=DefaultOutboxRecorder(),
+        )
+    container.register_scoped(UnitOfWork, _uow_factory)
+
+    # ---- Handlers (commands, queries, integration handlers) ----
+    register_handlers(mediator, container)
+
+    @asynccontextmanager
+    async def lifespan(_app: FastAPI) -> AsyncIterator[None]:
+        try:
+            yield
+        finally:
+            await engine.dispose()
+
+    app = setup_qx_app(
+        container,
+        settings,
+        metrics=metrics,
+        health=health,
+        extra_lifespan=lifespan,
+    )
+    register_routes(app)
+    return app
+
+
+app = build_app()

qx/cli/scaffolds/service/src/__service_pkg__/presentation/__init__.py.j2

@@ -0,0 +1,21 @@
+"""Presentation layer.
+
+FastAPI routers, gRPC servicers, CLI commands. This is where wire-format
+concerns live: serialization, deserialization, HTTP status mapping. No
+business logic — that's in the application/domain layers.
+"""
+
+from __future__ import annotations
+
+from fastapi import FastAPI
+
+
+def register_routes(app: FastAPI) -> None:
+    """Mount every router this service exposes.
+
+    Generated endpoints register themselves here. Wire your routers as the
+    CLI generates them.
+    """
+    # Example: from {{ service_pkg }}.presentation.routes.users import router as users_router
+    #          app.include_router(users_router, prefix="/v1")
+    pass

qx/cli/scaffolds/service/tests/test_smoke.py.j2

@@ -0,0 +1,33 @@
+"""Smoke test for the {{ service_name }} service.
+
+Exercises the FastAPI app boot and the framework probe endpoints. Doesn't
+require any external infrastructure.
+"""
+
+from __future__ import annotations
+
+import pytest
+from fastapi.testclient import TestClient
+
+from {{ service_pkg }}.main import build_app
+
+
+@pytest.fixture
+def client() -> TestClient:
+    return TestClient(build_app())
+
+
+def test_healthz(client: TestClient) -> None:
+    r = client.get("/healthz")
+    assert r.status_code == 200
+
+
+def test_readyz(client: TestClient) -> None:
+    r = client.get("/readyz")
+    assert r.status_code == 200
+
+
+def test_metrics(client: TestClient) -> None:
+    r = client.get("/metrics")
+    assert r.status_code == 200
+    assert b"qx_command_total" in r.content

qx/cli/templates/__init__.py

@@ -0,0 +1,162 @@
+"""Jinja2 template rendering helpers.
+
+Templates live in ``qx.cli.scaffolds`` as text files and get rendered
+with a small context. The conventions:
+
+- A template file's path under ``scaffolds/`` (with ``.j2`` stripped from the
+  end) becomes its output path under the target directory.
+- ``__name__`` substitutions are done in path components for paths that
+  vary per generation (e.g., command name, aggregate name).
+- The Jinja2 environment is sandboxed (no filesystem loaders into arbitrary
+  paths, no exec filters).
+
+The rendering loop intentionally keeps it boring: walk a template tree,
+render each file, write to disk. No conditional file inclusion based on
+template flags — if a scaffold needs variations, split it into multiple
+templates and have the command pick one.
+"""
+
+from __future__ import annotations
+
+import shutil
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+from jinja2 import Environment, StrictUndefined
+from rich.console import Console
+from rich.tree import Tree
+
+__all__ = ["preview_tree", "render_tree"]
+
+console = Console()
+
+
+def _make_env() -> Environment:
+    env = Environment(
+        autoescape=False,
+        undefined=StrictUndefined,
+        keep_trailing_newline=True,
+        block_start_string="{%",
+        block_end_string="%}",
+        variable_start_string="{{",
+        variable_end_string="}}",
+    )
+    env.filters["snake"] = _snake_case
+    env.filters["pascal"] = _pascal_case
+    env.filters["kebab"] = _kebab_case
+    return env
+
+
+def _snake_case(s: str) -> str:
+    import re  # noqa: PLC0415
+
+    s = re.sub(r"[\s\-]+", "_", s.strip())
+    s = re.sub(r"(.)([A-Z][a-z]+)", r"\1_\2", s)
+    s = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", s)
+    return s.lower()
+
+
+def _pascal_case(s: str) -> str:
+    return "".join(p.capitalize() for p in _snake_case(s).split("_"))
+
+
+def _kebab_case(s: str) -> str:
+    return _snake_case(s).replace("_", "-")
+
+
+def render_tree(
+    template_pkg: str,
+    template_root: str,
+    dest: Path,
+    context: dict[str, Any],
+    *,
+    overwrite: bool = False,
+) -> list[Path]:
+    """Render every template under ``template_pkg/template_root`` into ``dest``.
+
+    ``template_pkg`` is a dotted Python package containing the templates
+    (e.g., ``qx.cli.scaffolds.service``). Templates are discovered via
+    ``importlib.resources`` so they work after install (no filesystem
+    assumptions).
+
+    Returns the list of files written.
+    """
+    env = _make_env()
+    written: list[Path] = []
+
+    source_root = resources.files(template_pkg)
+    if template_root:
+        source_root = source_root / template_root
+
+    for entry in _walk(source_root):
+        rel = entry["rel"]
+        # Skip the empty __init__.py markers we use to make scaffold trees
+        # importable via importlib.resources — they're package metadata, not content.
+        basename = rel.rsplit("/", 1)[-1]
+        if basename == "__init__.py" and not entry["text"].strip():
+            continue
+        text = entry["text"]
+        # Substitute path components: __thing__ in filenames → context["thing"].
+        out_rel = _substitute_path(rel, context)
+        # Drop trailing .j2 from file names so output looks natural.
+        if out_rel.endswith(".j2"):
+            out_rel = out_rel[:-3]
+        out_path = dest / out_rel
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        if out_path.exists() and not overwrite:
+            console.print(f"[yellow]skip[/yellow]   {out_path}")
+            continue
+        template = env.from_string(text)
+        rendered = template.render(**context)
+        out_path.write_text(rendered, encoding="utf-8")
+        written.append(out_path)
+        console.print(f"[green]write[/green]  {out_path}")
+    return written
+
+
+def _walk(source_root: Any) -> list[dict[str, Any]]:
+    """Recursively gather template files from a resources Traversable."""
+    out: list[dict[str, Any]] = []
+
+    def visit(node: Any, rel: str) -> None:
+        if node.is_file():
+            out.append({"rel": rel, "text": node.read_text(encoding="utf-8")})
+            return
+        for child in node.iterdir():
+            visit(child, f"{rel}/{child.name}" if rel else child.name)
+
+    visit(source_root, "")
+    return out
+
+
+def _substitute_path(path: str, context: dict[str, Any]) -> str:
+    """Replace ``__key__`` occurrences in path with ``context[key]``."""
+    import re  # noqa: PLC0415
+
+    def repl(m: re.Match[str]) -> str:
+        key = m.group(1)
+        if key not in context:
+            return m.group(0)
+        return str(context[key])
+
+    return re.sub(r"__([a-zA-Z_][a-zA-Z0-9_]*)__", repl, path)
+
+
+def preview_tree(files: list[Path], dest: Path) -> None:
+    """Render a Rich tree showing what was generated."""
+    tree = Tree(f"[bold]{dest}[/bold]")
+    rels = sorted(p.relative_to(dest) for p in files)
+    nodes: dict[Path, Any] = {Path(): tree}
+    for rel in rels:
+        accumulated = Path()
+        parent_node = tree
+        for part in rel.parts:
+            accumulated = accumulated / part
+            if accumulated in nodes:
+                parent_node = nodes[accumulated]
+                continue
+            node = parent_node.add(part)
+            nodes[accumulated] = node
+            parent_node = node
+    console.print(tree)

qx_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: qx-cli
+Version: 0.1.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.