qx-cli 0.1.0__py3-none-any.whl

qx/cli/__init__.py

@@ -0,0 +1 @@
+"""Qx cli package."""

qx/cli/commands/dev.py

@@ -0,0 +1,86 @@
+"""``qx dev`` — local development orchestration."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+app = typer.Typer(no_args_is_help=True)
+console = Console()
+
+
+def _find_compose_file() -> Path:
+    """Locate the framework's docker-compose.yaml.
+
+    Searches: CWD, then walks up looking for ``deploy/docker-compose.yaml``.
+    """
+    cwd = Path.cwd()
+    candidates = [
+        cwd / "deploy" / "docker-compose.yaml",
+        cwd / "docker-compose.yaml",
+    ]
+    for c in candidates:
+        if c.exists():
+            return c
+    # Walk up
+    for parent in cwd.parents:
+        c = parent / "deploy" / "docker-compose.yaml"
+        if c.exists():
+            return c
+    raise typer.BadParameter("Could not find a docker-compose.yaml. Run from a qx project tree.")
+
+
+def _docker_compose_cmd() -> list[str]:
+    """Pick whichever compose flavor is available."""
+    if shutil.which("docker"):
+        return ["docker", "compose"]
+    if shutil.which("podman"):
+        return ["podman-compose"]
+    raise typer.BadParameter("Neither docker nor podman found on PATH.")
+
+
+@app.command()
+def up(
+    detach: bool = typer.Option(True, "--detach/--no-detach", "-d/-n"),
+) -> None:
+    """Start the local infrastructure stack."""
+    compose = _find_compose_file()
+    cmd = [*_docker_compose_cmd(), "-f", str(compose), "up"]
+    if detach:
+        cmd.append("-d")
+    console.print(f"[dim]$ {' '.join(cmd)}[/dim]")
+    subprocess.run(cmd, check=False)
+
+
+@app.command()
+def down() -> None:
+    """Stop the local infrastructure stack."""
+    compose = _find_compose_file()
+    cmd = [*_docker_compose_cmd(), "-f", str(compose), "down"]
+    console.print(f"[dim]$ {' '.join(cmd)}[/dim]")
+    subprocess.run(cmd, check=False)
+
+
+@app.command()
+def logs(
+    service: str = typer.Argument("", help="Specific service to tail (omit for all)."),
+) -> None:
+    """Tail logs from the local stack."""
+    compose = _find_compose_file()
+    cmd = [*_docker_compose_cmd(), "-f", str(compose), "logs", "-f"]
+    if service:
+        cmd.append(service)
+    console.print(f"[dim]$ {' '.join(cmd)}[/dim]")
+    subprocess.run(cmd, check=False)
+
+
+@app.command()
+def status() -> None:
+    """Show the running containers."""
+    compose = _find_compose_file()
+    cmd = [*_docker_compose_cmd(), "-f", str(compose), "ps"]
+    subprocess.run(cmd, check=False)

qx/cli/commands/generate.py

@@ -0,0 +1,182 @@
+"""``qx generate`` — code generation into an existing service.
+
+Each subcommand expects the cwd to be a qx service directory
+(containing a ``pyproject.toml`` and a Python package matching the service
+name). The CLI infers the service package from ``pyproject.toml``.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import Any
+
+import typer
+from qx.cli.templates import preview_tree, render_tree
+from rich.console import Console
+
+app = typer.Typer(no_args_is_help=True)
+console = Console()
+
+
+def _service_package(start: Path | None = None) -> tuple[Path, str]:
+    """Walk up to find ``pyproject.toml`` and infer the service package."""
+    p = (start or Path.cwd()).resolve()
+    for candidate in (p, *p.parents):
+        pp = candidate / "pyproject.toml"
+        if pp.exists():
+            try:
+                data = tomllib.loads(pp.read_text())
+            except Exception:
+                continue
+            name = data.get("project", {}).get("name", "")
+            if not name:
+                continue
+            pkg = name.replace("-", "_")
+            # Validate the package directory actually exists
+            if (candidate / "src" / pkg).exists():
+                return candidate, pkg
+            if (candidate / pkg).exists():
+                return candidate, pkg
+    raise typer.BadParameter("Could not locate a qx service from current directory.")
+
+
+@app.command()
+def aggregate(
+    name: str = typer.Argument(..., help="Aggregate name (PascalCase, e.g. 'Invoice')."),
+    force: bool = typer.Option(False, "--force", "-f"),
+) -> None:
+    """Generate a new aggregate (domain entity + table mapping + repository)."""
+    root, pkg = _service_package()
+    context = _names(name, pkg)
+    files = render_tree(
+        "qx.cli.scaffolds",
+        "aggregate",
+        root,
+        context,
+        overwrite=force,
+    )
+    console.rule(f"[bold green]aggregate {context['name_pascal']} generated[/bold green]")
+    preview_tree(files, root)
+
+
+@app.command()
+def command(
+    name: str = typer.Argument(..., help="Command name (e.g. 'CreateUser')."),
+    aggregate_for: str = typer.Option(
+        "",
+        "--aggregate",
+        "-a",
+        help="Target aggregate (for layout hints).",
+    ),
+    force: bool = typer.Option(False, "--force", "-f"),
+) -> None:
+    """Generate a Command class and its handler."""
+    root, pkg = _service_package()
+    context = _names(name, pkg)
+    context["aggregate"] = _names(aggregate_for, pkg) if aggregate_for else None
+    files = render_tree(
+        "qx.cli.scaffolds",
+        "command",
+        root,
+        context,
+        overwrite=force,
+    )
+    console.rule(f"[bold green]command {context['name_pascal']} generated[/bold green]")
+    preview_tree(files, root)
+
+
+@app.command()
+def query(
+    name: str = typer.Argument(..., help="Query name (e.g. 'GetUser')."),
+    force: bool = typer.Option(False, "--force", "-f"),
+) -> None:
+    """Generate a Query class and its handler."""
+    root, pkg = _service_package()
+    context = _names(name, pkg)
+    files = render_tree(
+        "qx.cli.scaffolds",
+        "query",
+        root,
+        context,
+        overwrite=force,
+    )
+    console.rule(f"[bold green]query {context['name_pascal']} generated[/bold green]")
+    preview_tree(files, root)
+
+
+@app.command()
+def event(
+    name: str = typer.Argument(..., help="Event name (e.g. 'UserRegistered')."),
+    force: bool = typer.Option(False, "--force", "-f"),
+) -> None:
+    """Generate an IntegrationEvent class."""
+    root, pkg = _service_package()
+    context = _names(name, pkg)
+    files = render_tree(
+        "qx.cli.scaffolds",
+        "event",
+        root,
+        context,
+        overwrite=force,
+    )
+    console.rule(f"[bold green]event {context['name_pascal']} generated[/bold green]")
+    preview_tree(files, root)
+
+
+@app.command()
+def endpoint(
+    path: str = typer.Argument(..., help="Route path (e.g. '/users')."),
+    method: str = typer.Option("POST", "--method", "-m"),
+    handler: str = typer.Option(..., "--handler", "-h", help="Command or Query name to dispatch."),
+    force: bool = typer.Option(False, "--force", "-f"),
+) -> None:
+    """Generate an HTTP endpoint that dispatches a command/query."""
+    root, pkg = _service_package()
+    context = _names(handler, pkg)
+    context.update(
+        {
+            "endpoint_path": path,
+            "endpoint_method": method.upper(),
+            "endpoint_method_lower": method.lower(),
+        }
+    )
+    files = render_tree(
+        "qx.cli.scaffolds",
+        "endpoint",
+        root,
+        context,
+        overwrite=force,
+    )
+    console.rule(f"[bold green]endpoint {method.upper()} {path} generated[/bold green]")
+    preview_tree(files, root)
+
+
+# ---- helpers ----
+
+
+def _names(name: str, pkg: str) -> dict[str, Any]:
+    """Build the standard naming variants for a generated artifact."""
+    return {
+        "name_pascal": _pascal(name),
+        "name_snake": _snake(name),
+        "name_kebab": _kebab(name),
+        "service_pkg": pkg,
+    }
+
+
+def _snake(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(s: str) -> str:
+    return "".join(p.capitalize() for p in _snake(s).split("_"))
+
+
+def _kebab(s: str) -> str:
+    return _snake(s).replace("_", "-")

qx/cli/commands/new.py

@@ -0,0 +1,76 @@
+"""``qx new`` — scaffold new projects."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from qx.cli.templates import preview_tree, render_tree
+from rich.console import Console
+
+app = typer.Typer(no_args_is_help=True)
+console = Console()
+
+
+@app.command()
+def service(
+    name: str = typer.Argument(..., help="Service name (kebab-case)."),
+    target: Path = typer.Option(  # noqa: B008
+        Path.cwd(),  # noqa: B008
+        "--target",
+        "-t",
+        help="Directory to create the project in.",
+    ),
+    force: bool = typer.Option(False, "--force", "-f", help="Overwrite existing files."),
+) -> None:
+    """Scaffold a new qx service.
+
+    Generates a fully wired service with application/domain/infrastructure/
+    presentation layers, a Dockerfile, alembic config, and a passing test.
+    """
+    pkg_name = _snake(name)
+    context = {
+        "service_name": name,
+        "service_pkg": pkg_name,
+        "service_pascal": _pascal(name),
+        "service_kebab": _kebab(name),
+        "service_pkg_path": pkg_name.replace("_", "/"),
+    }
+    dest = target / context["service_kebab"]
+    if dest.exists() and not force and any(dest.iterdir()):
+        console.print(f"[red]error[/red] {dest} exists and is not empty (use --force to overwrite)")
+        raise typer.Exit(1)
+    dest.mkdir(parents=True, exist_ok=True)
+
+    files = render_tree(
+        "qx.cli.scaffolds",
+        "service",
+        dest,
+        context,
+        overwrite=force,
+    )
+    console.rule("[bold green]Service scaffolded[/bold green]")
+    preview_tree(files, dest)
+    console.print(
+        "\n[bold]Next steps:[/bold]\n"
+        f"  cd {context['service_kebab']}\n"
+        "  uv sync\n"
+        "  docker compose -f ../deploy/docker-compose.yaml up -d  # local Postgres/Redis/NATS\n"
+        "  uv run alembic upgrade head\n"
+        "  uv run uvicorn " + f"{pkg_name}.main:app --reload\n"
+    )
+
+
+def _snake(s: str) -> str:
+    import re  # noqa: PLC0415
+
+    s = re.sub(r"[\s\-]+", "_", s.strip())
+    return re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", s).lower()
+
+
+def _pascal(s: str) -> str:
+    return "".join(p.capitalize() for p in _snake(s).split("_"))
+
+
+def _kebab(s: str) -> str:
+    return _snake(s).replace("_", "-")

qx/cli/main.py

@@ -0,0 +1,52 @@
+"""Qx CLI — scaffolding and developer tooling.
+
+Subcommands::
+
+    qx new service NAME            # scaffold a new service
+    qx generate aggregate NAME     # add an aggregate to current service
+    qx generate command NAME       # add a command + handler
+    qx generate query NAME         # add a query + handler
+    qx generate endpoint           # add an HTTP endpoint
+    qx generate event NAME         # add an integration event
+    qx dev up                      # start docker-compose stack
+    qx dev down                    # stop the stack
+    qx version                     # print framework version
+
+Invoke as ``qx`` once the package is installed; ``uv run qx ...``
+during development.
+"""
+
+from __future__ import annotations
+
+import typer
+from qx.cli.commands import dev, generate, new
+from rich.console import Console
+
+console = Console()
+
+app = typer.Typer(
+    name="qx",
+    help="Qx framework CLI — scaffolding, code generation, and dev orchestration.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+app.add_typer(new.app, name="new", help="Scaffold a new project from a template.")
+app.add_typer(
+    generate.app,
+    name="generate",
+    help="Generate code into an existing service (aggregate, command, query, ...).",
+)
+app.add_typer(dev.app, name="dev", help="Local development orchestration.")
+
+
+@app.command()
+def version() -> None:
+    """Print the framework version."""
+    from qx.core import __version__ as core_version  # noqa: PLC0415
+
+    console.print(f"[bold]qx-python[/bold] [cyan]{core_version}[/cyan]")
+
+
+if __name__ == "__main__":
+    app()

qx/cli/scaffolds/aggregate/src/__service_pkg__/domain/aggregates/__name_snake__/__init__.py.j2

@@ -0,0 +1,60 @@
+"""{{ name_pascal }} aggregate.
+
+Domain object. Encapsulates the invariants and emits domain events when
+state changes. Knows nothing about HOW it's stored.
+"""
+
+from __future__ import annotations
+
+from dataclasses import field
+from typing import ClassVar
+from uuid import UUID, uuid4
+
+from qx.core import (
+    AggregateRoot,
+    DomainEvent,
+    Identifier,
+    IntegrationEvent,
+    aggregate,
+)
+
+
+# ---- Domain events ----
+
+
+class {{ name_pascal }}Created(DomainEvent):
+    """In-process event recorded when a {{ name_pascal }} is created."""
+
+    event_name: ClassVar[str] = "{{ service_pkg }}.{{ name_snake }}.created"
+
+    {{ name_snake }}_id: UUID
+
+
+class {{ name_pascal }}CreatedIntegrationEvent(IntegrationEvent):
+    """Cross-process event published via the outbox."""
+
+    event_name: ClassVar[str] = "{{ service_pkg }}.{{ name_snake }}.created"
+    event_version: ClassVar[int] = 1
+
+    {{ name_snake }}_id: UUID
+
+
+# ---- Aggregate ----
+
+
+@aggregate
+class {{ name_pascal }}(AggregateRoot[Identifier]):
+    """The {{ name_pascal }} aggregate root."""
+
+    # Add your fields here. Example:
+    # name: str = ""
+
+    @classmethod
+    def create(cls) -> "{{ name_pascal }}":
+        """Factory: construct a new {{ name_pascal }} and record creation events."""
+        new = cls(id=Identifier(value=uuid4()))
+        new.record_event({{ name_pascal }}Created({{ name_snake }}_id=new.id.value))
+        new.record_event(
+            {{ name_pascal }}CreatedIntegrationEvent({{ name_snake }}_id=new.id.value)
+        )
+        return new

qx/cli/scaffolds/aggregate/src/__service_pkg__/infrastructure/persistence/__name_snake__/mapping.py.j2

@@ -0,0 +1,27 @@
+"""Persistence mapping for {{ name_pascal }}.
+
+Imperative-mapped via the framework's registry. Keep the table definition
+*here* (in infrastructure) and the domain object pure of any ORM dependency.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy import Column, String, Table
+
+from qx.db import make_registry, standard_audit_columns, uuid_column
+
+from {{ service_pkg }}.domain.aggregates.{{ name_snake }} import {{ name_pascal }}
+from {{ service_pkg }}.infrastructure import metadata
+
+registry = make_registry(metadata=metadata)
+
+{{ name_snake }}_table = Table(
+    "{{ name_snake }}",
+    metadata,
+    uuid_column("id", primary_key=True),
+    # Add columns matching the aggregate's fields here.
+    *standard_audit_columns(),
+)
+
+
+registry.map_imperatively({{ name_pascal }}, {{ name_snake }}_table)

qx/cli/scaffolds/aggregate/src/__service_pkg__/infrastructure/persistence/__name_snake__/repository.py.j2

@@ -0,0 +1,21 @@
+"""Repository for {{ name_pascal }}.
+
+Subclass of the framework's generic Repository. Add domain-flavored finders
+here (``find_by_email`` etc.) rather than letting controllers compose
+ad-hoc queries.
+"""
+
+from __future__ import annotations
+
+from qx.db import Repository
+
+from {{ service_pkg }}.domain.aggregates.{{ name_snake }} import {{ name_pascal }}
+from {{ service_pkg }}.infrastructure.persistence.{{ name_snake }}.mapping import {{ name_snake }}_table
+
+
+class {{ name_pascal }}Repository(Repository[{{ name_pascal }}]):
+    entity_cls = {{ name_pascal }}
+    table = {{ name_snake }}_table
+    # Permit filtering only on these fields; everything else is rejected at the boundary.
+    filterable_fields: set[str] = set()
+    sortable_fields: set[str] = {"created_at"}

qx/cli/scaffolds/command/src/__service_pkg__/application/commands/__name_snake__.py.j2

@@ -0,0 +1,32 @@
+"""{{ name_pascal }} command + handler."""
+
+from __future__ import annotations
+
+from qx.core import Result
+from qx.cqrs import Command, command_handler
+from qx.db import UnitOfWork
+
+
+class {{ name_pascal }}Command(Command[None]):
+    """TODO: describe what {{ name_pascal }} does."""
+
+    # Fill in command fields here. Example:
+    # name: str
+
+
+@command_handler({{ name_pascal }}Command)
+class {{ name_pascal }}Handler:
+    """Handler for {{ name_pascal }}Command.
+
+    Constructor-injected dependencies. The DI container resolves these per
+    dispatch — repos, unit-of-work, domain services.
+    """
+
+    def __init__(self, uow: UnitOfWork) -> None:
+        self._uow = uow
+
+    async def handle(self, command: {{ name_pascal }}Command) -> Result[None]:
+        async with self._uow:
+            # TODO: implement the use case
+            await self._uow.commit()
+        return Result.success(None)

qx/cli/scaffolds/endpoint/src/__service_pkg__/presentation/routes/__name_snake__.py.j2

@@ -0,0 +1,24 @@
+"""HTTP endpoint dispatching {{ name_pascal }}."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from qx.cqrs import Mediator
+from qx.http import Inject, envelope_success, unwrap
+
+# Adjust the import path to match where the command/query lives in your project.
+# from {{ service_pkg }}.application.commands.{{ name_snake }} import {{ name_pascal }}Command
+
+router = APIRouter()
+
+
+@router.{{ endpoint_method_lower }}("{{ endpoint_path }}")
+async def {{ name_snake }}_endpoint(
+    # cmd: {{ name_pascal }}Command,
+    mediator: Mediator = Inject(Mediator),
+):
+    """{{ endpoint_method }} {{ endpoint_path }} → dispatches {{ name_pascal }}."""
+    # result = await mediator.send(cmd)
+    # return envelope_success(unwrap(result))
+    return envelope_success({"todo": "wire {{ name_pascal }}Command"})

qx/cli/scaffolds/event/src/__service_pkg__/domain/events/__name_snake__.py.j2

@@ -0,0 +1,18 @@
+"""{{ name_pascal }} integration event."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from qx.core import IntegrationEvent
+
+
+class {{ name_pascal }}(IntegrationEvent):
+    """TODO: document the meaning + downstream contract for this event."""
+
+    event_name: ClassVar[str] = "{{ service_pkg }}.{{ name_snake }}"
+    event_version: ClassVar[int] = 1
+
+    # Payload fields. Keep this minimal — events are a contract, breaking
+    # consumers is painful. Add a new event version rather than rename fields.
+    # example_id: UUID

qx/cli/scaffolds/query/src/__service_pkg__/application/queries/__name_snake__.py.j2

@@ -0,0 +1,21 @@
+"""{{ name_pascal }} query + handler."""
+
+from __future__ import annotations
+
+from qx.core import Result
+from qx.cqrs import Query, query_handler
+
+
+class {{ name_pascal }}Query(Query[None]):
+    """TODO: describe what {{ name_pascal }} returns."""
+
+    # id: UUID
+
+
+@query_handler({{ name_pascal }}Query)
+class {{ name_pascal }}Handler:
+    """Handler for {{ name_pascal }}Query."""
+
+    async def handle(self, query: {{ name_pascal }}Query) -> Result[None]:
+        # TODO: read state, return DTO
+        return Result.success(None)

qx/cli/scaffolds/service/.env.example.j2

@@ -0,0 +1,16 @@
+QX_APP__NAME={{ service_kebab }}
+QX_ENVIRONMENT=development
+
+# Database
+QX_DB__URL=postgresql+asyncpg://postgres:postgres@localhost:5432/{{ service_pkg }}
+QX_DB__ECHO=false
+
+# Cache
+QX_CACHE__URL=redis://localhost:6379/0
+
+# NATS
+QX_NATS__SERVERS=["nats://localhost:4222"]
+
+# Logging
+QX_LOGGING__JSON_OUTPUT=false
+QX_LOGGING__LEVEL=INFO

qx/cli/scaffolds/service/Dockerfile.j2

@@ -0,0 +1,19 @@
+# syntax=docker/dockerfile:1.7
+FROM python:3.12-slim AS build
+WORKDIR /app
+RUN pip install --no-cache-dir uv
+COPY pyproject.toml uv.lock* ./
+RUN uv venv .venv
+COPY src ./src
+RUN uv pip install --python .venv -e .
+
+FROM python:3.12-slim
+WORKDIR /app
+RUN groupadd -r app && useradd -r -g app app
+COPY --from=build --chown=app:app /app /app
+ENV PATH="/app/.venv/bin:$PATH"
+USER app
+EXPOSE 8000
+HEALTHCHECK --interval=10s --timeout=3s --start-period=10s \
+    CMD curl -fsS http://localhost:8000/healthz || exit 1
+CMD ["uvicorn", "{{ service_pkg }}.main:app", "--host", "0.0.0.0", "--port", "8000"]