qx-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{qx_cli-0.1.0 → qx_cli-0.2.0}/.gitignore

@@ -49,3 +49,8 @@ Thumbs.db
 
 # Dist artifacts
 dist/
+
+# VS Code extension build artifacts
+extensions/vscode/node_modules/
+extensions/vscode/dist/
+extensions/vscode/*.vsix

{qx_cli-0.1.0 → qx_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qx-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: Qx CLI: scaffolding, code generation, local dev orchestration
 Author: Qx Engineering
 License: MIT

{qx_cli-0.1.0 → qx_cli-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "qx-cli"
-version = "0.1.0"
+version = "0.2.0"
 description = "Qx CLI: scaffolding, code generation, local dev orchestration"
 readme = "README.md"
 requires-python = ">=3.14"

qx_cli-0.2.0/src/qx/cli/commands/dev.py

@@ -0,0 +1,134 @@
+"""``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_files() -> list[Path]:
+    """Locate the base compose file and any service-level override.
+
+    Returns a list of ``-f <path>`` values — base first, override second
+    (if present). Docker Compose merges them in order.
+
+    Search order for the base file:
+      1. ``./deploy/docker-compose.yaml``
+      2. ``./docker-compose.yaml``
+      3. Walk up looking for ``deploy/docker-compose.yaml``
+
+    A ``docker-compose.override.yaml`` in CWD is automatically appended when
+    found, allowing per-service extensions of the shared stack.
+    """
+    cwd = Path.cwd()
+    base: Path | None = None
+
+    candidates = [
+        cwd / "deploy" / "docker-compose.yaml",
+        cwd / "docker-compose.yaml",
+    ]
+    for c in candidates:
+        if c.exists():
+            base = c
+            break
+
+    if base is None:
+        for parent in cwd.parents:
+            c = parent / "deploy" / "docker-compose.yaml"
+            if c.exists():
+                base = c
+                break
+
+    if base is None:
+        raise typer.BadParameter(
+            "Could not find a docker-compose.yaml. Run from a qx project tree."
+        )
+
+    files = [base]
+    override = cwd / "docker-compose.override.yaml"
+    if override.exists():
+        files.append(override)
+        console.print(f"[dim]using override: {override}[/dim]")
+
+    return files
+
+
+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.")
+
+
+def _compose_file_flags() -> list[str]:
+    """Build the ``-f file [-f override]`` flags for all compose subcommands."""
+    flags: list[str] = []
+    for f in _find_compose_files():
+        flags += ["-f", str(f)]
+    return flags
+
+
+@app.command()
+def up(
+    detach: bool = typer.Option(True, "--detach/--no-detach", "-d/-n"),
+    service: str = typer.Argument("", help="Bring up a specific service only (omit for all)."),
+) -> None:
+    """Start the local infrastructure stack (+ service override if present)."""
+    cmd = [*_docker_compose_cmd(), *_compose_file_flags(), "up"]
+    if detach:
+        cmd.append("-d")
+    if service:
+        cmd.append(service)
+    console.print(f"[dim]$ {' '.join(cmd)}[/dim]")
+    subprocess.run(cmd, check=False)
+
+
+@app.command()
+def down(
+    volumes: bool = typer.Option(False, "--volumes", "-v", help="Also remove volumes."),
+) -> None:
+    """Stop the local infrastructure stack."""
+    cmd = [*_docker_compose_cmd(), *_compose_file_flags(), "down"]
+    if volumes:
+        cmd.append("-v")
+    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)."),
+    tail: int = typer.Option(100, "--tail", "-n", help="Number of lines to show from the end."),
+) -> None:
+    """Tail logs from the local stack."""
+    cmd = [*_docker_compose_cmd(), *_compose_file_flags(), "logs", "-f", "--tail", str(tail)]
+    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."""
+    cmd = [*_docker_compose_cmd(), *_compose_file_flags(), "ps"]
+    subprocess.run(cmd, check=False)
+
+
+@app.command()
+def restart(
+    service: str = typer.Argument(..., help="Service name to restart."),
+) -> None:
+    """Restart a specific container in the stack."""
+    cmd = [*_docker_compose_cmd(), *_compose_file_flags(), "restart", service]
+    console.print(f"[dim]$ {' '.join(cmd)}[/dim]")
+    subprocess.run(cmd, check=False)

qx_cli-0.2.0/src/qx/cli/commands/doctor.py

@@ -0,0 +1,216 @@
+"""``qx doctor`` — environment health check.
+
+Validates that all tools and services required to develop with qx are
+reachable. Exits non-zero if any required component is missing.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import shutil
+import socket
+import subprocess
+import sys
+from urllib.parse import urlparse
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+app = typer.Typer()
+console = Console()
+
+_QX_PACKAGES = [
+    "qx-core",
+    "qx-di",
+    "qx-cqrs",
+    "qx-db",
+    "qx-http",
+    "qx-observability",
+    "qx-events",
+    "qx-worker",
+    "qx-cache",
+    "qx-auth",
+    "qx-grpc",
+    "qx-search",
+    "qx-testing",
+    "qx-cli",
+    "qx-devtools",
+]
+
+_TOOL_FIXES: dict[str, str] = {
+    "uv": "curl -LsSf https://astral.sh/uv/install.sh | sh",
+    "git": "brew install git  # macOS\n# or: apt install git",
+    "docker": "# Install Docker Desktop:\nhttps://www.docker.com/products/docker-desktop/",
+}
+
+
+def _ok(msg: str) -> str:
+    return f"[green]✓[/green]  {msg}"
+
+
+def _fail(msg: str) -> str:
+    return f"[red]✗[/red]  {msg}"
+
+
+def _warn(msg: str) -> str:
+    return f"[yellow]![/yellow]  {msg}"
+
+
+def _tcp_reachable(host: str, port: int, timeout: float = 2.0) -> bool:
+    try:
+        with socket.create_connection((host, port), timeout=timeout):
+            return True
+    except OSError:
+        return False
+
+
+def _check_python(failures: list[str], fix_commands: list[str]) -> None:
+    major, minor, micro = sys.version_info[:3]
+    ver_str = f"{major}.{minor}.{micro}"
+    console.print("\n[bold]Python[/bold]")
+    if (major, minor) >= (3, 14):
+        console.print(_ok(f"Python {ver_str}"))
+    else:
+        msg = f"Python {ver_str} — need ≥ 3.14"
+        console.print(_fail(msg))
+        failures.append(msg)
+        fix_commands.append("# Install Python 3.14 via uv:\nuv python install 3.14")
+
+
+def _check_tools(failures: list[str], fix_commands: list[str]) -> None:
+    console.print("\n[bold]Tools[/bold]")
+    for tool in ("uv", "git", "docker", "ruff", "mypy"):
+        path = shutil.which(tool)
+        if path:
+            try:
+                out = subprocess.run(
+                    [tool, "--version"], capture_output=True, text=True, timeout=5, check=False
+                )
+                ver = (out.stdout or out.stderr).strip().splitlines()[0]
+                console.print(_ok(f"{tool}  [dim]{ver}[/dim]"))
+            except Exception:
+                console.print(_ok(f"{tool}  [dim]{path}[/dim]"))
+        elif tool in _TOOL_FIXES:
+            msg = f"{tool} not found on PATH"
+            console.print(_fail(msg))
+            failures.append(msg)
+            fix_commands.append(f"# Install {tool}:\n{_TOOL_FIXES[tool]}")
+        else:
+            console.print(_warn(f"{tool} not found (optional for dev)"))
+
+    if shutil.which("docker"):
+        try:
+            result = subprocess.run(
+                ["docker", "info"], capture_output=True, text=True, timeout=5, check=False
+            )
+            if result.returncode == 0:
+                console.print(_ok("Docker daemon running"))
+            else:
+                console.print(_warn("Docker daemon not running (run: docker desktop start)"))
+        except Exception:
+            console.print(_warn("Docker daemon check timed out"))
+
+
+def _check_packages() -> None:
+    console.print("\n[bold]qx packages[/bold]")
+    table = Table(show_header=True, header_style="bold", box=None, padding=(0, 2))
+    table.add_column("Package")
+    table.add_column("Version")
+    table.add_column("Status")
+    for pkg in _QX_PACKAGES:
+        try:
+            ver = importlib.metadata.version(pkg)
+            table.add_row(pkg, ver, "[green]installed[/green]")
+        except importlib.metadata.PackageNotFoundError:
+            table.add_row(pkg, "—", "[yellow]not installed[/yellow]")
+    console.print(table)
+
+
+def _check_env() -> None:
+    import os  # noqa: PLC0415
+
+    console.print("\n[bold]Environment variables[/bold]")
+    env_vars = {
+        "DATABASE_URL": True,
+        "REDIS_URL": False,
+        "NATS_URL": False,
+        "SECRET_KEY": False,
+        "OTEL_EXPORTER_OTLP_ENDPOINT": False,
+    }
+    for var, required in env_vars.items():
+        val = os.getenv(var)
+        if val:
+            display = "***" if "SECRET" in var else val
+            console.print(_ok(f"{var}  [dim]{display}[/dim]"))
+        elif required:
+            console.print(_warn(f"{var} not set"))
+        else:
+            console.print(f"   [dim]{var} not set (optional)[/dim]")
+
+
+def _check_connectivity() -> None:
+    import os  # noqa: PLC0415
+
+    console.print("\n[bold]Connectivity[/bold]")
+    defaults = {
+        "DATABASE_URL": "postgresql://localhost:5432",
+        "REDIS_URL": "redis://localhost:6379",
+        "NATS_URL": "nats://localhost:4222",
+    }
+    default_ports = {"postgres": 5432, "redis": 6379, "nats": 4222}
+    labels = {"DATABASE_URL": "Postgres", "REDIS_URL": "Redis", "NATS_URL": "NATS"}
+
+    for env_var, label in labels.items():
+        raw = os.getenv(env_var, defaults[env_var])
+        try:
+            parsed = urlparse(raw)
+            host = parsed.hostname or "localhost"
+            key = label.lower()
+            port = parsed.port or next(v for k, v in default_ports.items() if k in key)
+        except Exception:
+            continue
+        if _tcp_reachable(host, port):
+            console.print(_ok(f"{label}  {host}:{port}"))
+        else:
+            console.print(
+                _warn(f"{label}  {host}:{port} unreachable (is the stack running? qx dev up)")
+            )
+
+
+@app.callback(invoke_without_command=True)
+def doctor(
+    connectivity: bool = typer.Option(
+        False, "--connectivity", "-c", help="Also probe Postgres / Redis / NATS TCP ports."
+    ),
+    fix: bool = typer.Option(
+        False, "--fix", help="Print shell commands to resolve detected issues."
+    ),
+) -> None:
+    """Check that your development environment is correctly set up."""
+    failures: list[str] = []
+    fix_commands: list[str] = []
+
+    console.rule("[bold]qx doctor[/bold]")
+    _check_python(failures, fix_commands)
+    _check_tools(failures, fix_commands)
+    _check_packages()
+    _check_env()
+
+    if connectivity:
+        _check_connectivity()
+
+    console.print()
+    if failures:
+        console.rule(f"[red]{len(failures)} issue(s) found[/red]")
+        if fix and fix_commands:
+            console.print("\n[bold]Suggested fixes:[/bold]\n")
+            for cmd in fix_commands:
+                console.print(f"[dim]{cmd}[/dim]\n")
+        else:
+            console.print(
+                "[dim]Run [bold]qx doctor --fix[/bold] for suggested remediation commands.[/dim]"
+            )
+        raise typer.Exit(code=1)
+    else:
+        console.rule("[green]All checks passed[/green]")

{qx_cli-0.1.0 → qx_cli-0.2.0}/src/qx/cli/commands/generate.py

@@ -46,9 +46,15 @@ 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)."""
+    """Generate a new aggregate (domain entity + table mapping + repository + migration stub)."""
+    import secrets  # noqa: PLC0415
+    from datetime import UTC, datetime  # noqa: PLC0415
+
     root, pkg = _service_package()
     context = _names(name, pkg)
+    context["revision_id"] = secrets.token_hex(6)
+    context["create_date"] = datetime.now(UTC).strftime("%Y-%m-%d %H:%M:%S.%f")[:-3]
+    context["migration_name"] = f"create_{context['name_snake']}"
     files = render_tree(
         "qx.cli.scaffolds",
         "aggregate",

{qx_cli-0.1.0 → qx_cli-0.2.0}/src/qx/cli/commands/new.py

@@ -55,7 +55,7 @@ def service(
         "\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"
+        "  qx dev up          # start Postgres · Redis · NATS · Grafana\n"
         "  uv run alembic upgrade head\n"
         "  uv run uvicorn " + f"{pkg_name}.main:app --reload\n"
     )

{qx_cli-0.1.0 → qx_cli-0.2.0}/src/qx/cli/main.py

@@ -10,6 +10,7 @@ Subcommands::
     qx generate event NAME         # add an integration event
     qx dev up                      # start docker-compose stack
     qx dev down                    # stop the stack
+    qx doctor                      # check dev environment health
     qx version                     # print framework version
 
 Invoke as ``qx`` once the package is installed; ``uv run qx ...``
@@ -19,7 +20,7 @@ during development.
 from __future__ import annotations
 
 import typer
-from qx.cli.commands import dev, generate, new
+from qx.cli.commands import dev, doctor, generate, new
 from rich.console import Console
 
 console = Console()
@@ -38,6 +39,7 @@ app.add_typer(
     help="Generate code into an existing service (aggregate, command, query, ...).",
 )
 app.add_typer(dev.app, name="dev", help="Local development orchestration.")
+app.add_typer(doctor.app, name="doctor", help="Check development environment health.")
 
 
 @app.command()

qx_cli-0.2.0/src/qx/cli/scaffolds/aggregate/alembic/versions/__migration_name__.py.j2

@@ -0,0 +1,49 @@
+"""create {{ name_snake }} table
+
+Revision ID: {{ revision_id }}
+Revises:
+Create Date: {{ create_date }}
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "{{ revision_id }}"
+down_revision = None  # set to previous revision ID when chaining
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "{{ name_snake }}",
+        sa.Column("id", sa.Uuid(), nullable=False),
+        # Add columns matching the aggregate's fields here:
+        # sa.Column("name", sa.String(255), nullable=False),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column("version", sa.Integer(), nullable=False, server_default="0"),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_{{ name_snake }}")),
+    )
+    op.create_index(
+        op.f("ix_{{ name_snake }}_created_at"),
+        "{{ name_snake }}",
+        ["created_at"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(op.f("ix_{{ name_snake }}_created_at"), table_name="{{ name_snake }}")
+    op.drop_table("{{ name_snake }}")

qx_cli-0.2.0/src/qx/cli/scaffolds/service/docker-compose.override.yaml.j2

@@ -0,0 +1,17 @@
+# Per-service Docker Compose override.
+#
+# Merged on top of the shared stack (deploy/docker-compose.yaml) when you run
+# ``qx dev up`` from this directory. Use it to add service-specific containers
+# (e.g., seed jobs, mocks, secondary databases) without modifying the shared file.
+#
+# Example — add a local HTTP mock:
+#
+#   services:
+#     payment-mock:
+#       image: mockserver/mockserver:latest
+#       ports:
+#         - "1080:1080"
+
+name: {{ service_kebab }}-dev
+
+services: {}

{qx_cli-0.1.0 → qx_cli-0.2.0}/src/qx/cli/scaffolds/service/pyproject.toml.j2

@@ -2,7 +2,7 @@
 name = "{{ service_kebab }}"
 version = "0.1.0"
 description = "{{ service_name }} — a Qx service."
-requires-python = ">=3.12"
+requires-python = ">=3.14"
 dependencies = [
     "qx-core",
     "qx-di",
@@ -39,9 +39,9 @@ testpaths = ["tests"]
 
 [tool.ruff]
 line-length = 100
-target-version = "py312"
+target-version = "py314"
 
 [tool.mypy]
-python_version = "3.12"
+python_version = "3.14"
 strict = true
 plugins = ["pydantic.mypy"]

{qx_cli-0.1.0 → qx_cli-0.2.0}/src/qx/cli/scaffolds/service/src/__service_pkg__/main.py.j2

@@ -10,7 +10,6 @@ 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 (
@@ -20,6 +19,7 @@ from qx.db import (
     create_engine,
     make_session_factory,
 )
+from qx.db.outbox import DefaultOutboxRecorder
 from qx.di import Container
 from qx.events import EventRegistry, MediatorEventDispatcher
 from qx.http import setup_qx_app
@@ -35,7 +35,7 @@ def build_app() -> FastAPI:
     metrics, health = setup_observability(settings)
     container = Container()
 
-    # ---- Settings + infrastructure singletons ----
+    # ---- Infrastructure singletons ----
     db_settings = DatabaseSettings()
     engine = create_engine(db_settings)
     session_factory = make_session_factory(engine)
@@ -49,19 +49,18 @@ def build_app() -> FastAPI:
     )
     container.register_instance(Mediator, mediator)
 
-    # ---- Event registry (integration event types this service knows about) ----
+    # ---- Event registry ----
     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(),
-        )
+    # ---- UnitOfWork (scoped per request) ----
+    dispatcher = MediatorEventDispatcher(mediator)
+    outbox = DefaultOutboxRecorder()
+
+    def _uow_factory(sf: SessionFactory) -> UnitOfWork:
+        return UnitOfWork(session_factory=sf, dispatcher=dispatcher, outbox=outbox)
+
     container.register_scoped(UnitOfWork, _uow_factory)
 
     # ---- Handlers (commands, queries, integration handlers) ----

{qx_cli-0.1.0 → qx_cli-0.2.0}/tests/test_cli.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import ast
+import os
 import subprocess
 import sys
 from typing import TYPE_CHECKING
@@ -37,7 +38,6 @@ def test_new_service_renders_valid_python(tmp_path: Path) -> None:
     assert (project / "Dockerfile").exists()
     assert (project / "tests" / "test_smoke.py").exists()
 
-    # Every generated .py must parse cleanly.
     for py_file in project.rglob("*.py"):
         text = py_file.read_text()
         try:
@@ -66,7 +66,7 @@ def test_new_service_generates_lint_clean_python(tmp_path: Path) -> None:
 # ---- qx generate ----
 
 
-def _scaffold_service(tmp_path: Path, name: str = "my-service") -> "Path":
+def _scaffold_service(tmp_path: Path, name: str = "my-service") -> Path:
     result = runner.invoke(app, ["new", "service", name, "--target", str(tmp_path)])
     assert result.exit_code == 0, result.stdout
     return tmp_path / name
@@ -74,14 +74,6 @@ def _scaffold_service(tmp_path: Path, name: str = "my-service") -> "Path":
 
 def test_generate_command_renders_valid_python(tmp_path: Path) -> None:
     project = _scaffold_service(tmp_path)
-    result = runner.invoke(
-        app,
-        ["generate", "command", "CreateOrder", "--aggregate", "Order"],
-        catch_exceptions=False,
-    )
-    # generate resolves from cwd; we need to cd into the service dir
-    import os
-
     old = os.getcwd()
     try:
         os.chdir(project)
@@ -96,8 +88,6 @@ def test_generate_command_renders_valid_python(tmp_path: Path) -> None:
 
 def test_generate_query_renders_valid_python(tmp_path: Path) -> None:
     project = _scaffold_service(tmp_path)
-    import os
-
     old = os.getcwd()
     try:
         os.chdir(project)
@@ -112,8 +102,6 @@ def test_generate_query_renders_valid_python(tmp_path: Path) -> None:
 
 def test_generate_event_renders_valid_python(tmp_path: Path) -> None:
     project = _scaffold_service(tmp_path)
-    import os
-
     old = os.getcwd()
     try:
         os.chdir(project)
@@ -128,18 +116,12 @@ def test_generate_event_renders_valid_python(tmp_path: Path) -> None:
 
 def test_generate_endpoint_renders_valid_python(tmp_path: Path) -> None:
     project = _scaffold_service(tmp_path)
-    import os
-
     old = os.getcwd()
     try:
         os.chdir(project)
-        result = runner.invoke(
-            app, ["generate", "endpoint", "/orders", "--handler", "CreateOrder"]
-        )
+        result = runner.invoke(app, ["generate", "endpoint", "/orders", "--handler", "CreateOrder"])
         assert result.exit_code == 0, result.stdout
-        generated = (
-            project / "src" / "my_service" / "presentation" / "routes" / "create_order.py"
-        )
+        generated = project / "src" / "my_service" / "presentation" / "routes" / "create_order.py"
         assert generated.exists()
         ast.parse(generated.read_text())
     finally:
@@ -155,3 +137,39 @@ def test_new_service_refuses_nonempty_dir_without_force(tmp_path: Path) -> None:
         ["new", "service", "demo", "--target", str(tmp_path)],
     )
     assert result.exit_code != 0
+
+
+def test_doctor_runs_without_error(tmp_path: Path) -> None:
+    result = runner.invoke(app, ["doctor"])
+    assert result.exception is None or isinstance(result.exception, SystemExit)
+    assert "qx doctor" in result.stdout
+
+
+def test_generate_aggregate_renders_valid_python(tmp_path: Path) -> None:
+    project = _scaffold_service(tmp_path)
+    old = os.getcwd()
+    try:
+        os.chdir(project)
+        result = runner.invoke(app, ["generate", "aggregate", "Invoice"])
+        assert result.exit_code == 0, result.stdout
+
+        agg = project / "src" / "my_service" / "domain" / "aggregates" / "invoice" / "__init__.py"
+        repo = (
+            project
+            / "src"
+            / "my_service"
+            / "infrastructure"
+            / "persistence"
+            / "invoice"
+            / "repository.py"
+        )
+        migration = project / "alembic" / "versions" / "create_invoice.py"
+
+        assert agg.exists(), "aggregate __init__.py missing"
+        assert repo.exists(), "repository.py missing"
+        assert migration.exists(), "migration stub missing"
+
+        for f in (agg, repo, migration):
+            ast.parse(f.read_text())
+    finally:
+        os.chdir(old)

qx_cli-0.1.0/src/qx/cli/commands/dev.py

@@ -1,86 +0,0 @@
-"""``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)