xcorecli 1.0.0__py3-none-any.whl

xcli/migrations/cli.py

@@ -0,0 +1,292 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from alembic import command
+from rich.console import Console
+from typer import Typer
+
+from xcli.migrations.runtime import (
+    create_alembic_config,
+    discover_models,
+    get_database_url,
+    plugins_root,
+    project_root,
+    render_discovery_summary,
+)
+
+_CTX = {"help_option_names": ["-h", "--help"]}
+app = Typer(help="Alembic migrations for xcore plugins.", context_settings=_CTX)
+console = Console()
+
+_ENV_TEMPLATE = """from __future__ import annotations
+
+from logging.config import fileConfig
+from pathlib import Path
+import sys
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+
+config = context.config
+ROOT = Path(config.config_file_name).resolve().parent if config.config_file_name else Path.cwd()
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from xcli.migrations.runtime import discover_models, get_database_url
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+config.set_main_option("sqlalchemy.url", get_database_url())
+discovery = discover_models()
+target_metadata = discovery.target_metadata
+
+
+def run_migrations_offline() -> None:
+    context.configure(
+        url=get_database_url(),
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+        compare_type=True,
+        compare_server_default=True,
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    configuration = config.get_section(config.config_ini_section, {})
+    configuration["sqlalchemy.url"] = get_database_url()
+
+    connectable = engine_from_config(
+        configuration,
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            compare_type=True,
+            compare_server_default=True,
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()
+"""
+
+_SCRIPT_TEMPLATE = """\"\"\"${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+\"\"\"
+from __future__ import annotations
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+
+# revision identifiers, used by Alembic.
+revision = ${repr(up_revision)}
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}
+"""
+
+_INI_TEMPLATE = """[alembic]
+script_location = {script_location}
+sqlalchemy.url = {database_url}
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S
+"""
+
+
+def _alembic_dir(directory: str) -> Path:
+    return (project_root() / directory).resolve()
+
+
+def _ensure_initialized(directory: str) -> None:
+    if not _alembic_dir(directory).exists():
+        console.print(
+            "[red]Alembic is not initialized yet.[/red] Run [cyan]xcli migration init[/cyan] first."
+        )
+        raise typer.Exit(1)
+
+
+@app.command("init")
+def init(
+    directory: str = typer.Option("alembic", "--dir", help="Alembic directory to create."),
+    force: bool = typer.Option(False, "--force", help="Overwrite generated files if they already exist."),
+) -> None:
+    """Create an Alembic workspace wired to integration.yaml and plugin models."""
+    root = project_root()
+    alembic_dir = _alembic_dir(directory)
+    versions_dir = alembic_dir / "versions"
+    ini_path = root / "alembic.ini"
+
+    if alembic_dir.exists() and not force:
+        console.print(
+            f"[yellow]Alembic directory already exists:[/yellow] [cyan]{alembic_dir}[/cyan] "
+            "[dim](use --force to overwrite generated files)[/dim]"
+        )
+        raise typer.Exit(1)
+
+    discovery = discover_models()
+
+    alembic_dir.mkdir(parents=True, exist_ok=True)
+    versions_dir.mkdir(parents=True, exist_ok=True)
+
+    (alembic_dir / "README").write_text(
+        "Auto-generated by xcli migration init. Revision files live in versions/.\n",
+        encoding="utf-8",
+    )
+    (alembic_dir / "env.py").write_text(_ENV_TEMPLATE, encoding="utf-8")
+    (alembic_dir / "script.py.mako").write_text(_SCRIPT_TEMPLATE, encoding="utf-8")
+    (alembic_dir / "__init__.py").write_text("", encoding="utf-8")
+    ini_path.write_text(
+        _INI_TEMPLATE.format(script_location=directory, database_url=get_database_url()),
+        encoding="utf-8",
+    )
+
+    console.print(f"[green]✓[/green] Alembic initialized in [cyan]{alembic_dir}[/cyan]")
+    console.print(f"[green]✓[/green] Config written to [cyan]{ini_path}[/cyan]")
+    console.print(f"[dim]Plugins root:[/dim] {plugins_root()}")
+    console.print(f"[dim]Discovery:[/dim] {render_discovery_summary(discovery)}")
+
+    if discovery.modules:
+        console.print("[dim]Modules scanned:[/dim]")
+        for module in discovery.modules:
+            console.print(f"  - {module}")
+
+    if discovery.warnings:
+        console.print("[yellow]Warnings while scanning models:[/yellow]")
+        for warning in discovery.warnings:
+            console.print(f"  - {warning}")
+
+
+@app.command("revision")
+def revision(
+    message: str = typer.Option(..., "--message", "-m", help="Revision message."),
+    autogenerate: bool = typer.Option(
+        True,
+        "--autogenerate/--empty",
+        help="Generate migration operations from discovered SQLAlchemy metadata.",
+    ),
+    directory: str = typer.Option("alembic", "--dir", help="Alembic directory."),
+) -> None:
+    """Create a new Alembic revision."""
+    _ensure_initialized(directory)
+    cfg = create_alembic_config(directory)
+    command.revision(cfg, message=message, autogenerate=autogenerate)
+
+
+@app.command("upgrade")
+def upgrade(
+    revision: str = typer.Argument("head", help="Target revision, for example head or +1."),
+    directory: str = typer.Option("alembic", "--dir", help="Alembic directory."),
+) -> None:
+    """Apply migrations."""
+    _ensure_initialized(directory)
+    command.upgrade(create_alembic_config(directory), revision)
+
+
+@app.command("downgrade")
+def downgrade(
+    revision: str = typer.Argument(..., help="Target revision, for example -1 or base."),
+    directory: str = typer.Option("alembic", "--dir", help="Alembic directory."),
+) -> None:
+    """Rollback migrations."""
+    _ensure_initialized(directory)
+    command.downgrade(create_alembic_config(directory), revision)
+
+
+@app.command("current")
+def current(
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed revision info."),
+    directory: str = typer.Option("alembic", "--dir", help="Alembic directory."),
+) -> None:
+    """Show the current database revision."""
+    _ensure_initialized(directory)
+    command.current(create_alembic_config(directory), verbose=verbose)
+
+
+@app.command("history")
+def history(
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed history."),
+    directory: str = typer.Option("alembic", "--dir", help="Alembic directory."),
+) -> None:
+    """Show migration history."""
+    _ensure_initialized(directory)
+    command.history(create_alembic_config(directory), verbose=verbose)
+
+
+@app.command("heads")
+def heads(
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed head info."),
+    directory: str = typer.Option("alembic", "--dir", help="Alembic directory."),
+) -> None:
+    """Show migration heads."""
+    _ensure_initialized(directory)
+    command.heads(create_alembic_config(directory), verbose=verbose)
+
+
+@app.command("stamp")
+def stamp(
+    revision: str = typer.Argument(..., help="Revision to stamp without applying migrations."),
+    directory: str = typer.Option("alembic", "--dir", help="Alembic directory."),
+) -> None:
+    """Stamp the database with a revision without running upgrade/downgrade."""
+    _ensure_initialized(directory)
+    command.stamp(create_alembic_config(directory), revision)

xcli/migrations/runtime.py

@@ -0,0 +1,198 @@
+from __future__ import annotations
+
+import importlib.util
+import inspect
+import sys
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from types import ModuleType
+from typing import Iterator
+
+import yaml
+from alembic.config import Config
+from rich.console import Console
+from sqlalchemy import MetaData
+from sqlalchemy.orm import DeclarativeBase
+
+console = Console()
+
+_CONFIG_CANDIDATES = (
+    "integration.yaml",
+    "integration.json",
+    "config/integration.yaml",
+    "config/integration.json",
+)
+_IGNORED_PARTS = {
+    ".git",
+    ".hg",
+    ".svn",
+    ".venv",
+    "__pycache__",
+    "node_modules",
+    "dist",
+    "build",
+    "data",
+    "alembic",
+    "migrations",
+}
+
+
+@dataclass(slots=True)
+class DiscoveryResult:
+    target_metadata: list[MetaData]
+    modules: list[str]
+    warnings: list[str]
+
+
+def require_config_path() -> Path:
+    for candidate in _CONFIG_CANDIDATES:
+        path = Path(candidate)
+        if path.exists():
+            return path.resolve()
+    console.print("[yellow]⚠[/yellow] No integration.yaml — run [cyan]xcli init[/cyan] first.")
+    raise SystemExit(1)
+
+
+def load_config() -> dict:
+    path = require_config_path()
+    return yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+
+
+def project_root() -> Path:
+    return require_config_path().parent.resolve()
+
+
+def plugins_root() -> Path:
+    cfg = load_config()
+    raw = cfg.get("plugins", {}).get("directory", "./app")
+    root = Path(raw)
+    if not root.is_absolute():
+        root = project_root() / root
+    return root.resolve()
+
+
+def get_database_url() -> str:
+    cfg = load_config()
+    databases = cfg.get("services", {}).get("databases", {})
+    default = databases.get("default", {})
+    url = default.get("url")
+    if not url:
+        console.print(
+            "[red]No database URL found in services.databases.default.url inside integration.yaml[/red]"
+        )
+        raise SystemExit(1)
+    return str(url)
+
+
+def create_alembic_config(directory: str = "alembic") -> Config:
+    root = project_root()
+    alembic_dir = root / directory
+    cfg = Config()
+    cfg.set_main_option("script_location", str(alembic_dir))
+    cfg.set_main_option("sqlalchemy.url", get_database_url())
+    cfg.config_file_name = str(root / "alembic.ini")
+    return cfg
+
+
+def discover_models() -> DiscoveryResult:
+    root = plugins_root()
+    if not root.exists():
+        console.print(f"[red]Plugins directory not found: [cyan]{root}[/cyan][/red]")
+        raise SystemExit(1)
+
+    metadata_by_id: dict[int, MetaData] = {}
+    loaded_modules: list[str] = []
+    warnings: list[str] = []
+
+    for plugin_dir in sorted(p for p in root.iterdir() if p.is_dir() and not p.name.startswith('.')):
+        for py_file in _iter_python_files(plugin_dir):
+            try:
+                module = _load_module(py_file, plugin_dir)
+            except Exception as exc:
+                warnings.append(f"{py_file}: {exc}")
+                continue
+
+            loaded_modules.append(str(py_file.relative_to(project_root())))
+            for metadata in _extract_metadata(module):
+                metadata_by_id.setdefault(id(metadata), metadata)
+
+    return DiscoveryResult(
+        target_metadata=list(metadata_by_id.values()),
+        modules=loaded_modules,
+        warnings=warnings,
+    )
+
+
+def render_discovery_summary(result: DiscoveryResult) -> str:
+    parts = [
+        f"loaded={len(result.modules)} module(s)",
+        f"metadata={len(result.target_metadata)}",
+        f"warnings={len(result.warnings)}",
+    ]
+    return ", ".join(parts)
+
+
+def _iter_python_files(plugin_dir: Path) -> Iterator[Path]:
+    for path in plugin_dir.rglob("*.py"):
+        if any(part in _IGNORED_PARTS for part in path.parts):
+            continue
+        yield path
+
+
+@contextmanager
+def _sys_path(*paths: Path) -> Iterator[None]:
+    original = list(sys.path)
+    inserts = [str(path.resolve()) for path in paths if path.exists()]
+    for entry in reversed(inserts):
+        if entry not in sys.path:
+            sys.path.insert(0, entry)
+    try:
+        yield
+    finally:
+        sys.path[:] = original
+
+
+def _load_module(py_file: Path, plugin_dir: Path) -> ModuleType:
+    module_name = "xcli_migrations_" + "_".join(py_file.with_suffix("").parts)
+    spec = importlib.util.spec_from_file_location(module_name, py_file)
+    if spec is None or spec.loader is None:
+        raise ImportError("unable to build module spec")
+
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    try:
+        with _sys_path(project_root(), plugin_dir, plugin_dir / "src"):
+            spec.loader.exec_module(module)
+    finally:
+        sys.modules.pop(module_name, None)
+    return module
+
+
+def _extract_metadata(module: ModuleType) -> list[MetaData]:
+    found: dict[int, MetaData] = {}
+    for obj in vars(module).values():
+        metadata = _metadata_from_object(obj)
+        if metadata is not None:
+            found.setdefault(id(metadata), metadata)
+    return list(found.values())
+
+
+def _metadata_from_object(obj: object) -> MetaData | None:
+    if isinstance(obj, MetaData):
+        return obj
+
+    if inspect.isclass(obj):
+        if obj is not DeclarativeBase and issubclass(obj, DeclarativeBase):
+            return getattr(obj, "metadata", None)
+
+        metadata = getattr(obj, "metadata", None)
+        registry = getattr(obj, "registry", None)
+        if isinstance(metadata, MetaData) and registry is not None:
+            return metadata
+
+    metadata = getattr(obj, "metadata", None)
+    if isinstance(metadata, MetaData) and getattr(obj, "__table__", None) is not None:
+        return metadata
+
+    return None