qx-cli 0.1.0__tar.gz

qx_cli-0.1.0/.gitignore

@@ -0,0 +1,51 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+eggs/
+.eggs/
+sdist/
+wheels/
+*.egg-link
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# uv
+.uv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Type checking
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Docker
+*.env.local
+
+# Dist artifacts
+dist/

qx_cli-0.1.0/PKG-INFO

@@ -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.

qx_cli-0.1.0/README.md

@@ -0,0 +1,65 @@
+# 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.

qx_cli-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "qx-cli"
+version = "0.1.0"
+description = "Qx CLI: scaffolding, code generation, local dev orchestration"
+readme = "README.md"
+requires-python = ">=3.14"
+license = { text = "MIT" }
+authors = [{ name = "Qx Engineering" }]
+dependencies = [
+    "qx-core",
+    "typer>=0.12.0",
+    "rich>=13.0.0",
+    "jinja2>=3.1.0",
+    "pyyaml>=6.0",
+]
+
+[project.scripts]
+qx = "qx.cli.main:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qx"]

qx_cli-0.1.0/src/qx/cli/__init__.py

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

qx_cli-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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