hexastack 0.0.0__py3-none-any.whl

hexastack/__init__.py

@@ -0,0 +1,64 @@
+import importlib
+import importlib.util
+import sys
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import hexastack_ai as ai
+    import hexastack_auth as auth
+    import hexastack_cli as cli
+    import hexastack_core as core
+    import hexastack_cqrs as cqrs
+    import hexastack_db as db
+    import hexastack_events as events
+    import hexastack_fastapi as fastapi
+    import hexastack_graphql as graphql
+    import hexastack_grpc as grpc
+    import hexastack_logging as logging
+    import hexastack_mcp as mcp
+    import hexastack_otel as otel
+
+__all__ = [
+    "ai",
+    "auth",
+    "cli",
+    "core",
+    "cqrs",
+    "db",
+    "events",
+    "fastapi",
+    "graphql",
+    "grpc",
+    "logging",
+    "mcp",
+    "otel",
+]
+
+_installed_shorthands: list[str] = []
+
+# Dynamically discover and expose only currently installed packages
+for _shorthand in __all__:
+    _module_name = f"hexastack_{_shorthand}"
+    if importlib.util.find_spec(_module_name) is not None:
+        try:
+            _mod = importlib.import_module(_module_name)
+            globals()[_shorthand] = _mod
+            sys.modules[f"hexastack.{_shorthand}"] = _mod
+            _installed_shorthands.append(_shorthand)
+        except (ImportError, AttributeError):
+            pass
+
+
+def __dir__() -> list[str]:
+    """Return only installed package shorthands and module globals."""
+    return sorted(set(list(globals().keys()) + _installed_shorthands))
+
+
+def __getattr__(name: str) -> Any:
+    """Provide clear guidance when an uninstalled optional package is accessed."""
+    if name in __all__:
+        raise AttributeError(
+            f"Package 'hexastack-{name}' is not installed. "
+            f"Install it via 'pip install hexastack[{name}]' or 'pip install hexastack-{name}'."
+        )
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

hexastack/adapters/__init__.py

@@ -0,0 +1,7 @@
+from hexastack.adapters.cli import add_serve_command
+from hexastack.adapters.fastapi import create_demo_app
+
+__all__ = [
+    "add_serve_command",
+    "create_demo_app",
+]

hexastack/adapters/cli/__init__.py

@@ -0,0 +1,28 @@
+"""CLI adapters for Hexastack umbrella package.
+
+Sub-packages:
+    scaffolding: Project creation and initialization commands (`new`, `init`).
+    demo: Showcase, diagnostics, server, and UI commands (`demo`, `ui`, `serve`, `db`, `grpc`, `mcp`).
+"""
+
+from hexastack.adapters.cli.demo.commands import (
+    DemoGroupDocs,
+    InspectGroupDocs,
+    add_db_commands,
+    add_grpc_commands,
+    add_mcp_commands,
+    add_serve_command,
+    add_ui_commands,
+)
+from hexastack.adapters.cli.scaffolding.commands import add_scaffold_commands
+
+__all__ = [
+    "add_db_commands",
+    "add_grpc_commands",
+    "add_mcp_commands",
+    "add_scaffold_commands",
+    "add_serve_command",
+    "add_ui_commands",
+    "DemoGroupDocs",
+    "InspectGroupDocs",
+]

hexastack/adapters/cli/demo/__init__.py

@@ -0,0 +1,21 @@
+"""Demo showcase and diagnostic CLI commands."""
+
+from hexastack.adapters.cli.demo.commands import (
+    DemoGroupDocs,
+    InspectGroupDocs,
+    add_db_commands,
+    add_grpc_commands,
+    add_mcp_commands,
+    add_serve_command,
+    add_ui_commands,
+)
+
+__all__ = [
+    "add_db_commands",
+    "add_grpc_commands",
+    "add_mcp_commands",
+    "add_serve_command",
+    "add_ui_commands",
+    "DemoGroupDocs",
+    "InspectGroupDocs",
+]

hexastack/adapters/cli/demo/commands.py

@@ -0,0 +1,334 @@
+"""CLI command definitions for demo showcase and diagnostics.
+
+Notes/Architectural Intent:
+    Provides subcommands for inspecting registries, running diagnostic queries,
+    and launching interactive developer servers.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+from typing import Any
+
+import typer
+
+from hexastack.domain.diagnostics import (
+    GetSystemInfoQuery,
+    InspectRegistryQuery,
+    PingDemoCommand,
+)
+from hexastack_cli.infra.decorators import (
+    cli_command,
+    cli_group,
+    cli_query,
+)
+from hexastack_core.domain.exceptions import MissingDependencyError
+
+__all__ = [
+    "add_db_commands",
+    "add_grpc_commands",
+    "add_mcp_commands",
+    "add_serve_command",
+    "add_ui_commands",
+    "DemoGroupDocs",
+    "InspectGroupDocs",
+]
+
+
+@cli_group("demo", help="Interactive demonstration commands")
+class DemoGroupDocs:
+    """CLI group documentation container for demo commands."""
+
+    pass
+
+
+@cli_group("inspect", help="Introspect registered CQRS handlers, routes, and config")
+class InspectGroupDocs:
+    """CLI group documentation container for inspect commands."""
+
+    pass
+
+
+# Decorate diagnostics domain models with CLI exposure metadata
+cli_query(
+    "info",
+    aliases=["doctor", "status"],
+    help="Display installed Hexastack packages and optional dependency statuses.",
+)(GetSystemInfoQuery)
+
+cli_query(
+    "registry",
+    group="inspect",
+    aliases=["handlers"],
+    help="Display registered CQRS commands, queries, and configurations.",
+)(InspectRegistryQuery)
+
+cli_command(
+    "ping",
+    group="demo",
+    aliases=["/ping"],
+    help="Send a test ping command through the CQRS execution pipeline.",
+)(PingDemoCommand)
+
+
+def add_db_commands(app: typer.Typer) -> None:
+    """Register 'db' subcommand group with migration management commands."""
+    if importlib.util.find_spec("hexastack_db") is None:
+        return
+
+    db_app = typer.Typer(
+        name="db",
+        help="Database migration management (requires hexastack[db,migrations]).",
+        no_args_is_help=True,
+    )
+    app.add_typer(db_app, name="db")
+
+    def _require_migrations() -> None:
+        if importlib.util.find_spec("alembic") is None:
+            raise MissingDependencyError(
+                "alembic is required for migration commands. "
+                "Install via 'pip install hexastack-db[migrations]'."
+            )
+
+    def _get_config(migrations_dir: str, url: str | None) -> Any:
+        from hexastack_db.infra.migrations import get_alembic_config
+
+        db_url = url or os.environ.get("DATABASE_URL", "sqlite:///hexastack.db")
+        return get_alembic_config(
+            migrations_dir=migrations_dir,
+            db_url=db_url,
+        )
+
+    @db_app.command(name="init", help="Scaffold a new migrations directory.")
+    def db_init(
+        directory: str = typer.Argument(
+            "migrations", help="Path to create the migrations directory."
+        ),
+    ) -> None:
+        _require_migrations()
+        from hexastack_db.infra.migrations import init_migrations
+
+        init_migrations(directory)
+
+    @db_app.command(
+        name="migrate", help="Apply pending database migrations (upgrade to head)."
+    )
+    def db_migrate(
+        directory: str = typer.Option(
+            "migrations", "--dir", help="Migrations directory."
+        ),
+        revision: str = typer.Option("head", "--revision", help="Target revision."),
+        url: str | None = typer.Option(
+            None, "--url", help="Database URL (overrides DATABASE_URL env var)."
+        ),
+    ) -> None:
+        _require_migrations()
+        from hexastack_db.infra.migrations import run_upgrade
+
+        run_upgrade(_get_config(directory, url), revision=revision)
+
+    @db_app.command(name="revision", help="Generate a new migration revision script.")
+    def db_revision(
+        message: str = typer.Argument(..., help="Short description of the migration."),
+        directory: str = typer.Option(
+            "migrations", "--dir", help="Migrations directory."
+        ),
+        no_autogenerate: bool = typer.Option(
+            False, "--no-autogenerate", help="Disable schema autogeneration."
+        ),
+        url: str | None = typer.Option(
+            None, "--url", help="Database URL (overrides DATABASE_URL env var)."
+        ),
+    ) -> None:
+        _require_migrations()
+        from hexastack_db.infra.migrations import run_revision
+
+        run_revision(
+            _get_config(directory, url),
+            message=message,
+            autogenerate=not no_autogenerate,
+        )
+
+    @db_app.command(name="current", help="Show the current applied revision.")
+    def db_current(
+        directory: str = typer.Option(
+            "migrations", "--dir", help="Migrations directory."
+        ),
+        url: str | None = typer.Option(
+            None, "--url", help="Database URL (overrides DATABASE_URL env var)."
+        ),
+    ) -> None:
+        _require_migrations()
+        from hexastack_db.infra.migrations import run_current
+
+        run_current(_get_config(directory, url))
+
+    @db_app.command(name="history", help="Show migration revision history.")
+    def db_history(
+        directory: str = typer.Option(
+            "migrations", "--dir", help="Migrations directory."
+        ),
+        url: str | None = typer.Option(
+            None, "--url", help="Database URL (overrides DATABASE_URL env var)."
+        ),
+    ) -> None:
+        _require_migrations()
+        from hexastack_db.infra.migrations import run_history
+
+        run_history(_get_config(directory, url))
+
+    @db_app.command(
+        name="stamp",
+        help="Stamp the database at a revision without running migrations.",
+    )
+    def db_stamp(
+        revision: str = typer.Argument(
+            "head", help="Revision to stamp (default: head)."
+        ),
+        directory: str = typer.Option(
+            "migrations", "--dir", help="Migrations directory."
+        ),
+        url: str | None = typer.Option(
+            None, "--url", help="Database URL (overrides DATABASE_URL env var)."
+        ),
+    ) -> None:
+        _require_migrations()
+        from hexastack_db.infra.migrations import stamp
+
+        stamp(_get_config(directory, url), revision)
+
+
+def add_grpc_commands(app: typer.Typer) -> None:
+    """Register 'grpc' subcommand group for RPC services."""
+    if importlib.util.find_spec("hexastack_grpc") is None:
+        return
+
+    grpc_app = typer.Typer(
+        name="grpc",
+        help="High-performance gRPC server management.",
+        no_args_is_help=True,
+    )
+    app.add_typer(grpc_app, name="grpc")
+
+    @grpc_app.command(
+        name="serve",
+        help="Launch the gRPC server daemon.",
+    )
+    def grpc_serve(
+        host: str = typer.Option("0.0.0.0", "--host", "-h", help="Bind host."),
+        port: int = typer.Option(50051, "--port", "-p", help="Bind port."),
+    ) -> None:
+        import grpc
+
+        import hexastack.application.diagnostics
+        from hexastack_core.infra.bootstrap import bootstrap
+        from hexastack_grpc.adapters.server import run_grpc_server
+
+        runtime = bootstrap(packages_to_scan=[hexastack.application.diagnostics])
+        server = runtime.container.resolve(grpc.Server)
+        typer.echo(f"Starting gRPC server on {host}:{port}...")
+        run_grpc_server(server, block=True)
+
+
+def add_mcp_commands(app: typer.Typer) -> None:
+    """Register 'mcp' subcommand group for AI agent integration."""
+    if importlib.util.find_spec("hexastack_mcp") is None:
+        return
+
+    mcp_app = typer.Typer(
+        name="mcp",
+        help="Model Context Protocol (MCP) AI agent tools and server.",
+        no_args_is_help=True,
+    )
+    app.add_typer(mcp_app, name="mcp")
+
+    @mcp_app.command(
+        name="run",
+        help="Launch the MCP server in stdio mode (for Claude, Cursor, Antigravity).",
+    )
+    def mcp_run() -> None:
+        from mcp.server.fastmcp import FastMCP as McpServer
+
+        import hexastack.application.diagnostics
+        from hexastack_core.infra.bootstrap import bootstrap
+        from hexastack_mcp.adapters.stdio import run_stdio_server
+
+        runtime = bootstrap(packages_to_scan=[hexastack.application.diagnostics])
+        server = runtime.container.resolve(McpServer)
+        run_stdio_server(server)
+
+
+def add_ui_commands(app: typer.Typer) -> None:
+    """Register 'ui' command to launch the interactive DevTools web dashboard."""
+
+    @app.command(
+        name="ui",
+        help="Launch the Hexastack DevTools interactive web UI (requires hexastack[ui]).",
+    )
+    def ui_command(
+        host: str = typer.Option("127.0.0.1", "--host", "-h", help="Bind host."),
+        port: int = typer.Option(8000, "--port", "-p", help="Bind port."),
+        reload: bool = typer.Option(
+            False, "--reload/--no-reload", help="Enable auto-reloading."
+        ),
+    ) -> None:
+        if importlib.util.find_spec("nicegui") is None:
+            raise MissingDependencyError(
+                "NiceGUI is required to launch the interactive UI. "
+                "Install via 'pip install hexastack[ui]' or 'pip install hexastack-fastapi[ui]'."
+            )
+
+        if importlib.util.find_spec("uvicorn") is None:
+            raise MissingDependencyError(
+                "uvicorn is required to run the web server. "
+                "Install via 'pip install hexastack[web]' or 'pip install uvicorn[standard]'."
+            )
+
+        import uvicorn
+
+        from hexastack.adapters.fastapi import create_demo_app
+
+        typer.echo(f"Starting Hexastack DevTools at http://{host}:{port}/_devtools ...")
+        demo_app = create_demo_app()
+        uvicorn.run(demo_app, host=host, port=port, reload=reload)
+
+
+def add_serve_command(app: typer.Typer) -> None:
+    """Register 'serve' command to launch the local FastAPI dev server using Uvicorn.
+
+    Args:
+        app: Target Typer application instance.
+    """
+
+    @app.command(
+        name="serve",
+        help="Launch the Hexastack local development server (requires hexastack[web]).",
+    )
+    def serve(
+        host: str = typer.Option(
+            "127.0.0.1", "--host", "-h", help="Bind host address."
+        ),
+        port: int = typer.Option(8000, "--port", "-p", help="Bind port number."),
+        reload: bool = typer.Option(
+            True, "--reload/--no-reload", help="Enable live reloading."
+        ),
+    ) -> None:
+        if importlib.util.find_spec("uvicorn") is None:
+            raise MissingDependencyError(
+                "uvicorn is required to run the local server. "
+                "Install via 'pip install hexastack[web]' or 'pip install uvicorn[standard]'."
+            )
+
+        if importlib.util.find_spec("fastapi") is None:
+            raise MissingDependencyError(
+                "fastapi is required to run the local server. "
+                "Install via 'pip install hexastack[fastapi]'."
+            )
+
+        import uvicorn
+
+        from hexastack.adapters.fastapi import create_demo_app
+
+        demo_app = create_demo_app()
+        uvicorn.run(demo_app, host=host, port=port, reload=reload)

hexastack/adapters/cli/scaffolding/__init__.py

@@ -0,0 +1,7 @@
+"""CLI adapter for project scaffolding."""
+
+from hexastack.adapters.cli.scaffolding.commands import add_scaffold_commands
+
+__all__ = [
+    "add_scaffold_commands",
+]

hexastack/adapters/cli/scaffolding/commands.py

@@ -0,0 +1,156 @@
+"""CLI command definitions for project scaffolding and template subcommands.
+
+Notes/Architectural Intent:
+    Supports both `hexastack new <name> --template <template>` and template subcommands
+    like `hexastack new web-api <name>` or `hexastack new event-driven <name>`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import cast
+
+import typer
+
+from hexastack.application.scaffolding.generator import (
+    TemplateType,
+    scaffold_project,
+)
+
+__all__ = [
+    "add_scaffold_commands",
+]
+
+
+def add_scaffold_commands(app: typer.Typer) -> None:
+    """Register 'new' and 'init' project scaffolding commands with template subcommands.
+
+    Args:
+        app: Target Typer application instance.
+    """
+    new_app = typer.Typer(
+        name="new",
+        help="Scaffold a new Hexagonal microservice project.",
+        no_args_is_help=True,
+        invoke_without_command=True,
+    )
+    app.add_typer(new_app, name="new")
+
+    @new_app.command(
+        name="web-api",
+        help="Scaffold a RESTful Web API microservice (FastAPI + UoW + DevTools UI).",
+    )
+    def new_web_api(
+        name: str = typer.Argument(..., help="Name of the new microservice project."),
+        description: str = typer.Option(
+            "A modern RESTful microservice powered by Hexastack.",
+            "--description",
+            "-d",
+            help="Project description.",
+        ),
+        db: str = typer.Option(
+            "in-memory",
+            "--db",
+            help="Database driver: in-memory, sqlite, postgres.",
+        ),
+    ) -> None:
+        target_path = scaffold_project(
+            name=name,
+            template="web-api",
+            description=description,
+            db_type=db,
+        )
+        typer.echo(f"🎉 Created new Hexastack Web API project at '{target_path}'")
+        typer.echo(f"   Next steps:\n     cd {name}\n     uv sync\n     uv run pytest")
+
+    @new_app.command(
+        name="minimal",
+        help="Scaffold a lightweight CLI or worker service (Core + CQRS + Logging).",
+    )
+    def new_minimal(
+        name: str = typer.Argument(..., help="Name of the new microservice project."),
+        description: str = typer.Option(
+            "A lightweight Hexastack service.",
+            "--description",
+            "-d",
+            help="Project description.",
+        ),
+    ) -> None:
+        target_path = scaffold_project(
+            name=name,
+            template="minimal",
+            description=description,
+        )
+        typer.echo(f"🎉 Created new Minimal Hexastack project at '{target_path}'")
+        typer.echo(f"   Next steps:\n     cd {name}\n     uv sync\n     uv run pytest")
+
+    @new_app.command(
+        name="event-driven",
+        help="Scaffold an Event-Driven service with CloudEvents and Transactional Outbox.",
+    )
+    def new_event_driven(
+        name: str = typer.Argument(..., help="Name of the new microservice project."),
+        description: str = typer.Option(
+            "An event-driven Hexastack service.",
+            "--description",
+            "-d",
+            help="Project description.",
+        ),
+    ) -> None:
+        target_path = scaffold_project(
+            name=name,
+            template="event-driven",
+            description=description,
+            include_events=True,
+        )
+        typer.echo(f"🎉 Created new Event-Driven Hexastack project at '{target_path}'")
+        typer.echo(f"   Next steps:\n     cd {name}\n     uv sync\n     uv run pytest")
+
+    @new_app.command(
+        name="mcp-agent",
+        help="Scaffold an AI Model Context Protocol (MCP) server & agent tools service.",
+    )
+    def new_mcp_agent(
+        name: str = typer.Argument(..., help="Name of the new microservice project."),
+        description: str = typer.Option(
+            "An MCP AI agent tools service powered by Hexastack.",
+            "--description",
+            "-d",
+            help="Project description.",
+        ),
+    ) -> None:
+        target_path = scaffold_project(
+            name=name,
+            template="mcp-agent",
+            description=description,
+            include_mcp=True,
+        )
+        typer.echo(f"🎉 Created new MCP Agent Hexastack project at '{target_path}'")
+        typer.echo(f"   Next steps:\n     cd {name}\n     uv sync\n     uv run pytest")
+
+    @app.command(
+        name="init",
+        help="Initialize a new Hexastack microservice in the current working directory.",
+    )
+    def init(
+        name: str = typer.Option(
+            None,
+            "--name",
+            "-n",
+            help="Project name (defaults to current directory name).",
+        ),
+        template: str = typer.Option(
+            "web-api",
+            "--template",
+            "-t",
+            help="Project template: minimal, web-api, event-driven, mcp-agent, enterprise.",
+        ),
+    ) -> None:
+        current_dir = Path.cwd()
+        proj_name = name or current_dir.name
+        target_path = scaffold_project(
+            name=proj_name,
+            template=cast("TemplateType", template),
+            output_dir=current_dir.parent,
+        )
+        typer.echo(f"🎉 Initialized Hexastack project in '{target_path}'")

hexastack/adapters/cli.py

@@ -0,0 +1,27 @@
+"""Compatibility module for CLI adapter commands.
+
+Notes/Architectural Intent:
+    Re-exports commands from hexastack.adapters.cli.demo and hexastack.adapters.cli.scaffolding.
+"""
+
+from hexastack.adapters.cli.demo.commands import (
+    DemoGroupDocs,
+    InspectGroupDocs,
+    add_db_commands,
+    add_grpc_commands,
+    add_mcp_commands,
+    add_serve_command,
+    add_ui_commands,
+)
+from hexastack.adapters.cli.scaffolding.commands import add_scaffold_commands
+
+__all__ = [
+    "add_db_commands",
+    "add_grpc_commands",
+    "add_mcp_commands",
+    "add_scaffold_commands",
+    "add_serve_command",
+    "add_ui_commands",
+    "DemoGroupDocs",
+    "InspectGroupDocs",
+]