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

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

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: qx-cli
-Version: 0.2.0
+Version: 1.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: nats-py>=2.9.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: qx-core
 Requires-Dist: rich>=13.0.0

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

@@ -1,6 +1,6 @@
 [project]
 name = "qx-cli"
-version = "0.2.0"
+version = "1.1.0"
 description = "Qx CLI: scaffolding, code generation, local dev orchestration"
 readme = "README.md"
 requires-python = ">=3.14"
@@ -11,6 +11,7 @@ dependencies = [
     "typer>=0.12.0",
     "rich>=13.0.0",
     "jinja2>=3.1.0",
+    "nats-py>=2.9.0",
     "pyyaml>=6.0",
 ]
 

qx_cli-1.1.0/src/qx/cli/commands/dlq.py

@@ -0,0 +1,231 @@
+"""``qx dlq`` — inspect and replay dead-letter queue messages.
+
+Commands::
+
+    qx dlq list                        # show recent dead letters
+    qx dlq replay <id>                 # re-publish a dead letter to its original NATS subject
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+app = typer.Typer(no_args_is_help=True)
+console = Console()
+
+
+def _get_db_url() -> str:
+    url = os.getenv("DATABASE_URL")
+    if not url:
+        console.print("[red]DATABASE_URL is not set.[/red]")
+        raise typer.Exit(code=1)
+    return url
+
+
+def _get_nats_url() -> str:
+    return os.getenv("NATS_URL", "nats://localhost:4222")
+
+
+@app.command("list")
+def list_dead_letters(
+    db_url: str = typer.Option(
+        None,
+        "--db-url",
+        envvar="DATABASE_URL",
+        help="Postgres connection URL.",
+    ),
+    limit: int = typer.Option(50, "--limit", "-n", help="Maximum rows to display."),
+    event_name: str = typer.Option(
+        None,
+        "--event-name",
+        "-e",
+        help="Filter by event name (substring match).",
+    ),
+) -> None:
+    """List recent dead-letter messages."""
+
+    async def _run() -> None:
+        from sqlalchemy import text  # noqa: PLC0415
+        from sqlalchemy.ext.asyncio import create_async_engine  # noqa: PLC0415
+
+        url = (db_url or _get_db_url()).replace("postgresql://", "postgresql+asyncpg://", 1)
+        engine = create_async_engine(url, echo=False)
+
+        try:
+            async with engine.connect() as conn:
+                exists = (
+                    await conn.execute(
+                        text(
+                            "SELECT 1 FROM information_schema.tables"
+                            " WHERE table_name = 'qx_dead_letters'"
+                        )
+                    )
+                ).first()
+                if not exists:
+                    console.print(
+                        "[yellow]qx_dead_letters table not found."
+                        " Run migrations or configure DeadLetterStore first.[/yellow]"
+                    )
+                    return
+
+                filters = ""
+                params: dict[str, object] = {"limit": limit}
+                if event_name:
+                    filters = "WHERE event_name ILIKE :event_name"
+                    params["event_name"] = f"%{event_name}%"
+
+                rows = (
+                    (
+                        await conn.execute(
+                            text(
+                                f"""
+                            SELECT id, event_name, delivered_count,
+                                   last_error, failed_at, subject
+                            FROM qx_dead_letters
+                            {filters}
+                            ORDER BY failed_at DESC
+                            LIMIT :limit
+                            """
+                            ),
+                            params,
+                        )
+                    )
+                    .mappings()
+                    .all()
+                )
+        finally:
+            await engine.dispose()
+
+        if not rows:
+            console.print("[dim]No dead letters found.[/dim]")
+            return
+
+        table = Table(show_header=True, header_style="bold", box=None, padding=(0, 2))
+        table.add_column("ID", style="dim")
+        table.add_column("Event Name")
+        table.add_column("Deliveries", justify="right")
+        table.add_column("Failed At")
+        table.add_column("Last Error")
+
+        for r in rows:
+            failed_str = r["failed_at"].strftime("%Y-%m-%d %H:%M:%S") if r["failed_at"] else "—"
+            error = (r["last_error"] or "")[:60]
+            if len(r["last_error"] or "") > 60:
+                error += "…"
+            table.add_row(
+                str(r["id"])[:8] + "…",
+                r["event_name"],
+                str(r["delivered_count"]),
+                failed_str,
+                error,
+            )
+
+        console.print(table)
+        console.print(f"\n[dim]{len(rows)} row(s) shown (limit {limit})[/dim]")
+
+    asyncio.run(_run())
+
+
+@app.command()
+def replay(
+    id: str = typer.Argument(..., help="UUID of the dead letter row to replay."),
+    db_url: str = typer.Option(
+        None,
+        "--db-url",
+        envvar="DATABASE_URL",
+        help="Postgres connection URL.",
+    ),
+    nats_url: str = typer.Option(
+        None,
+        "--nats-url",
+        envvar="NATS_URL",
+        help="NATS server URL (falls back to NATS_URL or nats://localhost:4222).",
+    ),
+    subject_override: str = typer.Option(
+        None,
+        "--subject",
+        help="Override the NATS subject (default: use the original subject from the DB row).",
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt."),
+) -> None:
+    """Re-publish a dead letter to its original NATS subject.
+
+    Fetches the stored payload from ``qx_dead_letters`` by ID and
+    republishes it to the original NATS subject so the worker can
+    attempt processing again.
+    """
+
+    async def _run() -> None:
+        import json  # noqa: PLC0415
+
+        import nats  # noqa: PLC0415
+        from sqlalchemy import text  # noqa: PLC0415
+        from sqlalchemy.ext.asyncio import create_async_engine  # noqa: PLC0415
+
+        url = (db_url or _get_db_url()).replace("postgresql://", "postgresql+asyncpg://", 1)
+        engine = create_async_engine(url, echo=False)
+
+        try:
+            async with engine.connect() as conn:
+                row = (
+                    (
+                        await conn.execute(
+                            text(
+                                "SELECT id, event_name, payload, headers, subject"
+                                " FROM qx_dead_letters WHERE id = :id"
+                            ),
+                            {"id": id},
+                        )
+                    )
+                    .mappings()
+                    .first()
+                )
+        finally:
+            await engine.dispose()
+
+        if row is None:
+            console.print(f"[red]Dead letter [bold]{id}[/bold] not found.[/red]")
+            raise typer.Exit(code=1)
+
+        target_subject = subject_override or row["subject"]
+        if not target_subject:
+            console.print("[red]Row has no stored subject. Use --subject to specify one.[/red]")
+            raise typer.Exit(code=1)
+
+        if not yes:
+            confirmed = typer.confirm(
+                f"Replay [bold]{row['event_name']}[/bold] → [bold]{target_subject}[/bold]?"
+            )
+            if not confirmed:
+                raise typer.Abort()
+
+        payload_bytes = (
+            row["payload"].encode()
+            if isinstance(row["payload"], str)
+            else json.dumps(row["payload"]).encode()
+        )
+
+        # Reconstruct headers from stored headers dict, dropping None values.
+        stored_headers: dict[str, str] = {}
+        if row["headers"]:
+            raw = row["headers"] if isinstance(row["headers"], dict) else json.loads(row["headers"])
+            stored_headers = {k: v for k, v in raw.items() if v is not None}
+
+        nc = await nats.connect(nats_url or _get_nats_url())
+        try:
+            js = nc.jetstream()
+            await js.publish(target_subject, payload_bytes, headers=stored_headers or None)
+        finally:
+            await nc.drain()
+
+        console.print(
+            f"[green]✓[/green]  Replayed [bold]{row['event_name']}[/bold]"
+            f" → [bold]{target_subject}[/bold]"
+        )
+
+    asyncio.run(_run())

{qx_cli-0.2.0 → qx_cli-1.1.0}/src/qx/cli/commands/doctor.py

@@ -178,10 +178,45 @@ def _check_connectivity() -> None:
             )
 
 
+_MIN_VERSIONS: dict[str, str] = {
+    "qx-core": "0.2.0",
+    "qx-cqrs": "0.2.0",
+    "qx-db": "0.2.0",
+    "qx-http": "0.2.0",
+    "qx-events": "0.2.0",
+    "qx-worker": "0.2.0",
+    "qx-cli": "0.2.0",
+}
+
+
+def _check_version_mismatches() -> None:
+    from importlib.metadata import PackageNotFoundError, version  # noqa: PLC0415
+
+    from packaging.version import Version  # noqa: PLC0415
+
+    console.print("\n[bold]Version requirements[/bold]")
+    found_mismatch = False
+    for pkg, min_ver in _MIN_VERSIONS.items():
+        try:
+            installed = version(pkg)
+            if Version(installed) < Version(min_ver):
+                console.print(_fail(f"{pkg} {installed} < {min_ver} (minimum required)"))
+                found_mismatch = True
+            else:
+                console.print(_ok(f"{pkg} {installed} >= {min_ver}"))
+        except PackageNotFoundError:
+            pass  # already reported in _check_packages
+
+    if not found_mismatch:
+        console.print(_ok("All installed qx packages meet minimum version requirements"))
+
+
 @app.callback(invoke_without_command=True)
 def doctor(
-    connectivity: bool = typer.Option(
-        False, "--connectivity", "-c", help="Also probe Postgres / Redis / NATS TCP ports."
+    no_connectivity: bool = typer.Option(
+        False,
+        "--no-connectivity",
+        help="Skip Postgres / Redis / NATS TCP reachability probes.",
     ),
     fix: bool = typer.Option(
         False, "--fix", help="Print shell commands to resolve detected issues."
@@ -196,8 +231,9 @@ def doctor(
     _check_tools(failures, fix_commands)
     _check_packages()
     _check_env()
+    _check_version_mismatches()
 
-    if connectivity:
+    if not no_connectivity:
         _check_connectivity()
 
     console.print()

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

@@ -3,6 +3,12 @@
 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``.
+
+Vertical-slice services support a ``<slice>/<Name>`` syntax:
+
+    qx generate command user/CreateUser    # → user/commands/create_user.py
+    qx generate query   user/GetUser       # → user/queries/get_user.py
+    qx generate slice   payment            # → payment/ skeleton
 """
 
 from __future__ import annotations
@@ -33,7 +39,6 @@ def _service_package(start: Path | None = None) -> tuple[Path, str]:
             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():
@@ -68,46 +73,79 @@ def aggregate(
 
 @app.command()
 def command(
-    name: str = typer.Argument(..., help="Command name (e.g. 'CreateUser')."),
+    name: str = typer.Argument(
+        ..., help="Command name. Use 'slice/Name' for vertical-slice services."
+    ),
     aggregate_for: str = typer.Option(
         "",
         "--aggregate",
         "-a",
-        help="Target aggregate (for layout hints).",
+        help="Target aggregate (for layout hints, layered mode only).",
     ),
     force: bool = typer.Option(False, "--force", "-f"),
 ) -> None:
-    """Generate a Command class and its handler."""
+    """Generate a Command class and its handler.
+
+    Layered:  qx generate command CreateUser
+    VS:       qx generate command user/CreateUser
+    """
     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,
-    )
+    if "/" in name:
+        slice_name, artifact_name = _parse_slice(name)
+        context = _names(artifact_name, pkg)
+        context.update(_slice_names(slice_name))
+        files = render_tree("qx.cli.scaffolds", "command_vs", root, context, overwrite=force)
+    else:
+        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')."),
+    name: str = typer.Argument(
+        ..., help="Query name. Use 'slice/Name' for vertical-slice services."
+    ),
+    force: bool = typer.Option(False, "--force", "-f"),
+) -> None:
+    """Generate a Query class and its handler.
+
+    Layered:  qx generate query GetUser
+    VS:       qx generate query user/GetUser
+    """
+    root, pkg = _service_package()
+    if "/" in name:
+        slice_name, artifact_name = _parse_slice(name)
+        context = _names(artifact_name, pkg)
+        context.update(_slice_names(slice_name))
+        files = render_tree("qx.cli.scaffolds", "query_vs", root, context, overwrite=force)
+    else:
+        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 esaggregate(
+    name: str = typer.Argument(..., help="Aggregate name (PascalCase, e.g. 'Shipment')."),
     force: bool = typer.Option(False, "--force", "-f"),
 ) -> None:
-    """Generate a Query class and its handler."""
+    """Generate an event-sourced aggregate (EventSourcedAggregate subclass, no ORM mapping)."""
     root, pkg = _service_package()
     context = _names(name, pkg)
     files = render_tree(
         "qx.cli.scaffolds",
-        "query",
+        "esaggregate",
         root,
         context,
         overwrite=force,
     )
-    console.rule(f"[bold green]query {context['name_pascal']} generated[/bold green]")
+    console.rule(
+        f"[bold green]event-sourced aggregate {context['name_pascal']} generated[/bold green]"
+    )
     preview_tree(files, root)
 
 
@@ -158,19 +196,67 @@ def endpoint(
     preview_tree(files, root)
 
 
+@app.command(name="slice")
+def generate_slice(
+    name: str = typer.Argument(..., help="Slice name (e.g. 'payment', 'user')."),
+    force: bool = typer.Option(False, "--force", "-f"),
+) -> None:
+    """Generate a new vertical slice (application/<slice>/commands/, queries/, presentation/<slice>.py).
+
+    After generating, mount the new router in main.py:
+
+        from <service>.presentation.payment import router as payment_router
+        app.include_router(payment_router, prefix="/v1")
+    """
+    root, pkg = _service_package()
+    context = _slice_names(name)
+    context["service_pkg"] = pkg
+    files = render_tree("qx.cli.scaffolds", "slice", root, context, overwrite=force)
+    console.rule(f"[bold green]slice {context['slice_name_pascal']} generated[/bold green]")
+    preview_tree(files, root)
+    console.print(
+        "\n[bold]Wire the router in main.py:[/bold]\n"
+        f"  from {pkg}.presentation.{context['slice_name_snake']} import router as "
+        f"{context['slice_name_snake']}_router\n"
+        f'  app.include_router({context["slice_name_snake"]}_router, prefix="/v1")\n'
+    )
+
+
 # ---- helpers ----
 
 
 def _names(name: str, pkg: str) -> dict[str, Any]:
     """Build the standard naming variants for a generated artifact."""
+    snake = _snake(name)
     return {
         "name_pascal": _pascal(name),
-        "name_snake": _snake(name),
+        "name_snake": snake,
         "name_kebab": _kebab(name),
+        "name_upper": snake.upper(),
         "service_pkg": pkg,
     }
 
 
+def _slice_names(slice_name: str) -> dict[str, Any]:
+    """Build naming variants for a slice."""
+    snake = _snake(slice_name)
+    return {
+        "slice_name_snake": snake,
+        "slice_name_pascal": _pascal(slice_name),
+        "slice_name_kebab": _kebab(slice_name),
+    }
+
+
+def _parse_slice(name: str) -> tuple[str, str]:
+    """Split 'user/CreateUser' → ('user', 'CreateUser')."""
+    parts = name.split("/", 1)
+    if len(parts) != 2 or not parts[0] or not parts[1]:
+        raise typer.BadParameter(
+            f"Invalid format '{name}'. Use '<slice>/<Name>' (e.g. 'user/CreateUser')."
+        )
+    return parts[0], parts[1]
+
+
 def _snake(s: str) -> str:
     import re  # noqa: PLC0415
 

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

@@ -22,11 +22,23 @@ def service(
         help="Directory to create the project in.",
     ),
     force: bool = typer.Option(False, "--force", "-f", help="Overwrite existing files."),
+    slices: bool = typer.Option(
+        False,
+        "--slices/--no-slices",
+        help="Use vertical-slice layout (feature-first) instead of layered.",
+    ),
+    domain: str = typer.Option(
+        "",
+        "--domain",
+        "-d",
+        help="Starter slice name for --slices (defaults to service name).",
+    ),
 ) -> 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.
+    By default generates a layered service (application/domain/infrastructure/
+    presentation). With --slices, generates a vertical-slice layout where each
+    feature is self-contained under its own directory.
     """
     pkg_name = _snake(name)
     context = {
@@ -36,6 +48,16 @@ def service(
         "service_kebab": _kebab(name),
         "service_pkg_path": pkg_name.replace("_", "/"),
     }
+
+    if slices:
+        domain_snake = _snake(domain) if domain else pkg_name
+        context["domain_snake"] = domain_snake
+        context["domain_pascal"] = _pascal(domain_snake)
+        context["domain_kebab"] = _kebab(domain_snake)
+        template = "service_vs"
+    else:
+        template = "service"
+
     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)")
@@ -44,21 +66,30 @@ def service(
 
     files = render_tree(
         "qx.cli.scaffolds",
-        "service",
+        template,
         dest,
         context,
         overwrite=force,
     )
     console.rule("[bold green]Service scaffolded[/bold green]")
     preview_tree(files, dest)
-    console.print(
+
+    next_steps = (
         "\n[bold]Next steps:[/bold]\n"
         f"  cd {context['service_kebab']}\n"
         "  uv sync\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"
+        f"  uv run uvicorn {pkg_name}.main:app --reload\n"
     )
+    if slices:
+        next_steps += (
+            "\n[bold]Add more slices:[/bold]\n"
+            "  qx generate slice <slice_name>\n"
+            "  qx generate command <slice_name>/<CommandName>\n"
+            "  qx generate query <slice_name>/<QueryName>\n"
+        )
+    console.print(next_steps)
 
 
 def _snake(s: str) -> str: