dblift 4.0.2__tar.gz → 4.2.0__tar.gz

{dblift-4.0.2 → dblift-4.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dblift
-Version: 4.0.2
+Version: 4.2.0
 Summary: Flyway-style raw-SQL migrations for Python teams. No JVM, and you see the exact SQL before it runs.
 Keywords: flyway,migrations,python,sql,postgresql,mysql
 Classifier: Development Status :: 5 - Production/Stable
@@ -103,6 +103,8 @@ Provides-Extra: django
 Requires-Dist: Django>=4.2; extra == "django"
 Provides-Extra: otel
 Requires-Dist: opentelemetry-api>=1.20; extra == "otel"
+Provides-Extra: mcp
+Requires-Dist: mcp>=2.2; extra == "mcp"
 Provides-Extra: all
 Requires-Dist: dblift[cosmosdb,db2,duckdb,mariadb,mongodb,mysql,oracle,postgresql,sqlserver]; extra == "all"
 Requires-Dist: dblift[redshift,snowflake]; extra == "all"

{dblift-4.0.2 → dblift-4.2.0}/dblift/__init__.py

@@ -2,4 +2,4 @@
 DBLift - A flexible database migration tool
 """
 
-__version__ = "4.0.2"
+__version__ = "4.2.0"

{dblift-4.0.2 → dblift-4.2.0}/dblift/cli/_command_handlers.py

@@ -19,6 +19,7 @@ from dblift.cli.handlers.baseline import _handle_baseline
 from dblift.cli.handlers.clean import _handle_clean
 from dblift.cli.handlers.import_flyway import _handle_import_flyway
 from dblift.cli.handlers.info import _handle_info, _info_result_to_dict  # noqa: F401
+from dblift.cli.handlers.mcp import _handle_mcp
 from dblift.cli.handlers.migrate import _handle_migrate
 from dblift.cli.handlers.repair import _handle_repair
 from dblift.cli.handlers.undo import _handle_undo
@@ -36,6 +37,7 @@ _COMMAND_HANDLERS: Dict[str, Callable[[CliCommandContext], Tuple[bool, Any]]] =
     "baseline": _handle_baseline,
     "repair": _handle_repair,
     "import-flyway": _handle_import_flyway,
+    "mcp": _handle_mcp,
 }
 
 _extension_handlers = load_command_handlers()

{dblift-4.0.2 → dblift-4.2.0}/dblift/cli/_parser_setup.py

@@ -560,6 +560,14 @@ def create_parser(
         default="table",
         help="Output format (default: table)",
     )
+    # validate / migrate --format option (JSON output for scripting and agents)
+    for _machine_parser in (validate_parser, migrate_parser):
+        _machine_parser.add_argument(
+            "--format",
+            choices=["console", "json"],
+            default="console",
+            help="Output format (default: console)",
+        )
     # DB utility commands
     db_parser = subparsers.add_parser("db", help="Database utility commands")
     db_subparsers = db_parser.add_subparsers(dest="db_command", required=True)
@@ -574,6 +582,12 @@ def create_parser(
         action="store_true",
         help="List all properties and how to set them (config key / env var / CLI flag)",
     )
+    # `dblift mcp` serves the read-only commands as MCP tools over stdio. It is a
+    # zero-config command: the server loads the project config per tool call.
+    subparsers.add_parser(
+        "mcp",
+        help="Serve dblift commands as MCP tools over stdio (requires dblift[mcp])",
+    )
     import_module("dblift.cli.extensions").load_command_extensions(parser)
     # Stubs fill whatever gaps the extensions left — never the reverse.
     _register_premium_stub_parsers(parser)

{dblift-4.0.2 → dblift-4.2.0}/dblift/cli/handlers/_shared.py

@@ -7,10 +7,12 @@ per-command files stay focused on their own behaviour.
 
 from __future__ import annotations
 
+import contextlib
+import io
 import re
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Any, Callable, Dict, List, Optional, Tuple
 
 # Flyway-compatible migration filename patterns — used by SQL-file validation to
 # skip non-migration SQL files when scanning a directory (e.g. leftover
@@ -131,3 +133,87 @@ def _extract_version_filters(args: Any) -> tuple[Any, Any, Any, Any, Any]:
         getattr(args, "tags", None),
         getattr(args, "exclude_tags", None),
     )
+
+
+def _enum_name(value: Any) -> Any:
+    """Return an enum member's ``name`` (``MigrationType.SQL`` → ``"SQL"``), else *value*.
+
+    ``MigrationInfo.type`` / ``.status`` can be enum members; ``json.dumps``
+    cannot serialise those, so the machine payload carries the name.
+    """
+    if value is None or isinstance(value, str):
+        return value
+    name = getattr(value, "name", None)
+    if isinstance(name, str):
+        return name
+    return str(value)
+
+
+def _migration_info_to_dict(m: Any) -> Dict[str, Any]:
+    """Serialise one ``MigrationInfo`` row for ``--format json`` payloads.
+
+    Shared by ``info``, ``validate`` and ``migrate`` so the row shape is one
+    contract, not three.
+    """
+    installed_on = getattr(m, "installed_on", None)
+    return {
+        "script": m.script,
+        "version": str(m.version) if m.version else None,
+        "description": m.description,
+        "type": _enum_name(m.type),
+        "status": _enum_name(m.status),
+        "checksum": m.checksum,
+        "installed_on": (
+            (installed_on.isoformat() if hasattr(installed_on, "isoformat") else installed_on)
+            if installed_on
+            else None
+        ),
+        "installed_by": m.installed_by,
+        "execution_time": m.execution_time,
+        "error": getattr(m, "error", None),
+    }
+
+
+def run_json_guarded(
+    ctx: "CliCommandContext",
+    command_type: str,
+    call: Callable[[], Any],
+    serialize: Callable[[Any], Dict[str, Any]],
+) -> Tuple[bool, Any]:
+    """Run *call* honouring the ``--format`` contract of ``ctx.args``.
+
+    Human mode: run, report completion, return ``(result.success, result)``;
+    exceptions propagate so the outer runner formats them. Machine mode:
+    stdout is redirected while *call* runs (banners and headers printed by
+    the command must not contaminate the JSON payload), an exception becomes
+    ``{"success": false, "error": "<Type>: <msg>"}`` on stdout, and the
+    serialised result is the only thing written. ``SystemExit`` and
+    ``KeyboardInterrupt`` are not ``Exception`` and always propagate.
+    """
+    from dblift.cli._output import from_args
+
+    command_output = from_args(ctx.args)
+    result: Any = None
+    if not command_output.is_machine_format:
+        result = call()
+        if result is None:
+            return (False, None)
+        _set_command_completed(ctx.log, result, command_type)
+        return (result.success, result)
+
+    error: Optional[Exception] = None
+    try:
+        with contextlib.redirect_stdout(io.StringIO()):
+            result = call()
+    except Exception as exc:
+        error = exc
+    if error is not None or result is None:
+        text = (
+            f"{type(error).__name__}: {error}"
+            if error is not None
+            else f"{command_type.lower()}() returned no result"
+        )
+        command_output.machine({"success": False, "error": text})
+        return (False, None)
+    command_output.machine(serialize(result))
+    return (result.success, result)

dblift-4.2.0/dblift/cli/handlers/info.py

@@ -0,0 +1,56 @@
+"""Handler for the ``info`` command + InfoResult JSON serialization."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Tuple
+
+from dblift.cli.handlers._shared import (
+    CliCommandContext,
+    _extract_version_filters,
+    _migration_info_to_dict,
+    run_json_guarded,
+)
+
+
+def _info_result_to_dict(result: Any) -> Dict[str, Any]:
+    """Serialize an InfoResult to a JSON-compatible dict."""
+    migrations = [_migration_info_to_dict(m) for m in getattr(result, "migrations", [])]
+    return {
+        # ``success`` mirrors the error-path payload (``{"success": False, ...}``)
+        # so downstream consumers can do ``result["success"]`` on both happy and
+        # error paths without a KeyError on the happy path.
+        "success": bool(getattr(result, "success", True)),
+        # Same reason ``OutputFormatter.format_info`` prints as ``Error: ...``.
+        # Without it a JSON consumer saw ``success: false`` and nothing else,
+        # while the key was already populated on the handler's exception payload.
+        "error": getattr(result, "error_message", None),
+        "current_schema_version": getattr(result, "current_schema_version", None),
+        "target_schema": getattr(result, "target_schema", ""),
+        "db_version": getattr(result, "db_version", None),
+        "database_url_masked": getattr(result, "database_url_masked", None),
+        "native_driver": getattr(result, "native_driver", None),
+        "migrations": migrations,
+    }
+
+
+def _handle_info(ctx: CliCommandContext) -> Tuple[bool, Any]:
+    target_version, versions, exclude_versions, tags, exclude_tags = _extract_version_filters(
+        ctx.args
+    )
+
+    from dblift.cli._output import from_args as _output_from_args
+
+    use_json = _output_from_args(ctx.args).is_machine_format
+    info_kwargs = {
+        "target_version": target_version,
+        "tags": tags,
+        "exclude_tags": exclude_tags,
+        "versions": versions,
+        "exclude_versions": exclude_versions,
+        "recursive": ctx.recursive,
+        "additional_dirs": ctx.additional_scripts_dirs if ctx.additional_scripts_dirs else None,
+        "display_human": not use_json,
+    }
+    return run_json_guarded(
+        ctx, "INFO", lambda: ctx.client.info(**info_kwargs), _info_result_to_dict
+    )

dblift-4.2.0/dblift/cli/handlers/mcp.py

@@ -0,0 +1,36 @@
+"""Handler for the ``mcp`` command: serve dblift tools over stdio."""
+
+from __future__ import annotations
+
+from typing import Any, List, Tuple
+
+from dblift.cli._output import CommandOutput
+from dblift.cli.handlers._shared import CliCommandContext
+
+
+def _handle_mcp(ctx: CliCommandContext) -> Tuple[bool, Any]:
+    """Build the MCP server and block on stdin/stdout until the client disconnects.
+
+    Zero-config: no project config or database is touched at start. Each tool
+    call loads the config the way the CLI would, prefixed with the root flags
+    this process was started with (``ctx.args.global_arguments``).
+    """
+    from dblift.cli.mcp.server import MissingMcpSdkError, build_server
+
+    global_argv: List[str] = list(getattr(ctx.args, "global_arguments", None) or [])
+    try:
+        server = build_server(global_argv)
+    except MissingMcpSdkError as exc:
+        CommandOutput("console").error(str(exc))
+        return (False, None)
+    except Exception as exc:
+        # A registrar contributed by an installed add-on package can fail the
+        # build — a duplicate tool name, a signature the SDK rejects. Report
+        # it as a CLI error; a traceback is not something the user can act on.
+        CommandOutput("console").error(f"dblift mcp: could not start the server: {exc}")
+        return (False, None)
+    server.run_stdio()
+    return (True, None)
+
+
+_handle_mcp._dblift_zero_config_command = True  # type: ignore[attr-defined]

dblift-4.2.0/dblift/cli/handlers/migrate.py

@@ -0,0 +1,72 @@
+"""Handler for the ``migrate`` command + MigrateResult JSON serialization."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Tuple
+
+from dblift.cli.handlers._shared import (
+    CliCommandContext,
+    _extract_version_filters,
+    _migration_info_to_dict,
+    run_json_guarded,
+)
+from dblift.cli.handlers.validate import _validate_result_to_dict
+
+
+def _migrate_result_to_dict(result: Any, dry_run: bool) -> Dict[str, Any]:
+    """Serialize a MigrateResult to a JSON-compatible dict."""
+    return {
+        "success": bool(getattr(result, "success", True)),
+        "error": getattr(result, "error_message", None),
+        "dry_run": bool(dry_run),
+        "target_schema": getattr(result, "target_schema", ""),
+        "current_schema_version": getattr(result, "current_schema_version", None),
+        "dry_run_count": getattr(result, "dry_run_count", 0),
+        "migrations": [_migration_info_to_dict(m) for m in getattr(result, "migrations", [])],
+        "migrations_applied": list(getattr(result, "migrations_applied", [])),
+    }
+
+
+def _handle_migrate(ctx: CliCommandContext) -> Tuple[bool, Any]:
+    target_version, versions, exclude_versions, tags, exclude_tags = _extract_version_filters(
+        ctx.args
+    )
+    additional_dirs = ctx.additional_scripts_dirs if ctx.additional_scripts_dirs else None
+
+    # Handle --validate-only by calling validate instead of migrate
+    if getattr(ctx.args, "validate_only", False):
+
+        def _validate_call() -> Any:
+            return ctx.client.validate(
+                target_version=target_version,
+                tags=tags,
+                exclude_tags=exclude_tags,
+                versions=versions,
+                exclude_versions=exclude_versions,
+                recursive=ctx.recursive,
+                additional_dirs=additional_dirs,
+            )
+
+        return run_json_guarded(ctx, "VALIDATE", _validate_call, _validate_result_to_dict)
+
+    dry_run = bool(getattr(ctx.args, "dry_run", False))
+
+    def migrate_call() -> Any:
+        return ctx.client.migrate(
+            target_version=target_version,
+            dry_run=dry_run,
+            tags=tags,
+            exclude_tags=exclude_tags,
+            versions=versions,
+            exclude_versions=exclude_versions,
+            mark_as_executed=getattr(ctx.args, "mark_as_executed", False),
+            show_sql=getattr(ctx.args, "show_sql", False),
+            show_query_results=getattr(ctx.args, "show_query_results", False),
+            placeholders=ctx.placeholders,
+            recursive=ctx.recursive,
+            additional_dirs=additional_dirs,
+        )
+
+    return run_json_guarded(
+        ctx, "MIGRATE", migrate_call, lambda r: _migrate_result_to_dict(r, dry_run)
+    )

dblift-4.2.0/dblift/cli/handlers/validate.py

@@ -0,0 +1,47 @@
+"""Handler for the ``validate`` command + ValidateResult JSON serialization."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Tuple
+
+from dblift.cli.handlers._shared import (
+    CliCommandContext,
+    _extract_version_filters,
+    _migration_info_to_dict,
+    run_json_guarded,
+)
+
+
+def _validate_result_to_dict(result: Any) -> Dict[str, Any]:
+    """Serialize a ValidateResult to a JSON-compatible dict."""
+    return {
+        "success": bool(getattr(result, "success", True)),
+        "error": getattr(result, "error_message", None),
+        "target_schema": getattr(result, "target_schema", ""),
+        "error_count": getattr(result, "error_count", 0),
+        "validated_migrations": [
+            _migration_info_to_dict(m) for m in getattr(result, "validated_migrations", [])
+        ],
+        "failed_migrations": [
+            _migration_info_to_dict(m) for m in getattr(result, "failed_migrations", [])
+        ],
+    }
+
+
+def _handle_validate(ctx: CliCommandContext) -> Tuple[bool, Any]:
+    target_version, versions, exclude_versions, tags, exclude_tags = _extract_version_filters(
+        ctx.args
+    )
+
+    def call() -> Any:
+        return ctx.client.validate(
+            target_version=target_version,
+            tags=tags,
+            exclude_tags=exclude_tags,
+            versions=versions,
+            exclude_versions=exclude_versions,
+            recursive=ctx.recursive,
+            additional_dirs=ctx.additional_scripts_dirs if ctx.additional_scripts_dirs else None,
+        )
+
+    return run_json_guarded(ctx, "VALIDATE", call, _validate_result_to_dict)

{dblift-4.0.2 → dblift-4.2.0}/dblift/cli/main.py

@@ -473,6 +473,8 @@ def _parse_argv_and_load_config(argv: List[str]) -> _CliContext:
         commands[0], "_dblift_zero_config_command", False
     ):
         handler = _COMMAND_HANDLERS[commands[0]]
+        # Terminal-style commands (e.g. `mcp`) replay these root flags per call.
+        args.global_arguments = global_arguments
         success, _payload = handler(CliCommandContext(args=args))
         sys.exit(0 if success else 1)
 

dblift-4.2.0/dblift/cli/mcp/__init__.py

@@ -0,0 +1 @@
+"""``dblift mcp`` — a stdio MCP server exposing read-only dblift commands as tools."""

dblift-4.2.0/dblift/cli/mcp/registry.py

@@ -0,0 +1,34 @@
+"""Discover MCP tool registrars contributed by installed add-on packages.
+
+Each ``dblift.mcp_tools`` entry point resolves to ``register(server) -> None``,
+which receives the :class:`dblift.cli.mcp.server.DbliftMcpServer` and calls
+``server.command_tool(...)`` for every tool it contributes. OSS declares the
+group empty; the built-in tools are registered by :mod:`dblift.cli.mcp.tools`.
+"""
+
+from __future__ import annotations
+
+import os
+from importlib.metadata import entry_points
+from typing import Any, Callable, Dict, List
+
+MCP_TOOLS_ENTRY_POINT_GROUP = "dblift.mcp_tools"
+
+ToolRegistrar = Callable[[Any], None]
+
+
+def load_mcp_tool_registrars() -> List[ToolRegistrar]:
+    """Load every ``dblift.mcp_tools`` registrar, sorted by entry-point name.
+
+    Honours ``DBLIFT_DISABLE_CLI_EXTENSIONS=1`` like the other CLI seams and
+    rejects two entry points sharing a name — silently keeping one would make
+    the tool list depend on install order.
+    """
+    if os.environ.get("DBLIFT_DISABLE_CLI_EXTENSIONS") == "1":
+        return []
+    by_name: Dict[str, ToolRegistrar] = {}
+    for entry_point in entry_points(group=MCP_TOOLS_ENTRY_POINT_GROUP):
+        if entry_point.name in by_name:
+            raise ValueError(f"Duplicate MCP tool registrar: {entry_point.name}")
+        by_name[entry_point.name] = entry_point.load()
+    return [by_name[name] for name in sorted(by_name)]

dblift-4.2.0/dblift/cli/mcp/runner.py

@@ -0,0 +1,214 @@
+"""Run one CLI command in-process and hand back its ``--format json`` payload.
+
+This is the seam every MCP tool goes through. It replays the four phases of
+:func:`dblift.cli.main.main` for a single command — argv split, config load,
+logging, client, handler — but never :func:`execute_single_command`, whose
+``SystemExit`` on a capability denial would terminate the stdio server on the
+first unlicensed call. Everything that would exit the CLI process becomes a
+:class:`CommandInvocationError` carrying the exit code, and stdout is
+redirected for the whole call: the JSON-RPC transport owns the real stream.
+
+Stderr is captured too: a command's content may render through the stdout
+console or through the console logger, which writes to stderr, and a
+text-mode call joins both so the logger's lines are not lost. Capture also
+lets a failed command's detail be quoted in the raised error. It is
+*mirrored* rather than swallowed: the command's log lines still reach the
+real stderr, which is where a stdio MCP server's own diagnostics belong —
+only stdout is reserved outright for the JSON-RPC channel.
+
+Any exception the handler raises — not just :class:`SystemExit` and
+:class:`~dblift.core.seams.capabilities.CapabilityDeniedError` — becomes a
+:class:`CommandInvocationError`; only :class:`KeyboardInterrupt` and other
+non-:class:`Exception` signals still propagate. The client built for the
+call is closed afterward when it exposes a callable ``close`` (some
+handlers get a config-only stand-in with none), so a long-lived server
+making many calls does not leak one connection per call.
+
+Calls are serialised by a module-level lock. A client may issue several
+tool calls at once and the SDK runs synchronous tool bodies in worker
+threads, but everything a call reaches for is process-global: ``sys.argv``
+(rewritten while the argv is parsed), ``sys.stdout`` and ``sys.stderr``
+(redirected here), the ``LogFactory`` class attributes and the console
+header flag. Concurrent calls therefore dismantle each other's redirects
+and namespaces — one command's payload can be returned for another, and
+bytes meant for a tool result escape to the real stdout, which is the
+JSON-RPC channel. One command at a time is the only safe reading of that
+shared state.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import sys
+import threading
+from typing import Any, Dict, Optional, Sequence
+
+from dblift.cli._constants import EXIT_LICENSE_REQUIRED
+from dblift.cli.handlers._shared import CliCommandContext
+from dblift.core.seams.capabilities import CapabilityDeniedError
+from dblift.core.seams.tier_resolver import resolve_tier
+
+JSON_FORMAT_ARGV: tuple[str, ...] = ("--format", "json")
+_LICENSE_FALLBACK = "This command requires a license that is not available."
+_TAIL = 2000
+_CALL_LOCK = threading.Lock()
+
+
+class CommandInvocationError(Exception):
+    """A command did not produce a payload; ``exit_code`` is what the CLI would have returned."""
+
+    def __init__(self, message: str, exit_code: int) -> None:
+        """Store *message* as the exception text and *exit_code* for the caller."""
+        super().__init__(message)
+        self.exit_code = exit_code
+
+
+class _TeeStream(io.TextIOBase):
+    """A write target that both records text and mirrors it to another stream.
+
+    Used for stderr: :func:`run_command` needs the text to build a detailed
+    :class:`CommandInvocationError`, but the lines themselves must still
+    reach the real stderr rather than vanish, unlike stdout.
+
+    Subclasses :class:`io.TextIOBase` so a command reaching past ``write`` —
+    ``writelines``, ``isatty``, ``fileno`` — meets a real text stream rather
+    than an :class:`AttributeError`.
+    """
+
+    def __init__(self, buffer: io.StringIO, mirror: Optional[Any]) -> None:
+        """Record writes into *buffer* and, when *mirror* is set, forward them to it too."""
+        self._buffer = buffer
+        self._mirror = mirror
+
+    def write(self, text: str) -> int:
+        """Append *text* to the buffer and forward it to the mirror stream."""
+        self._buffer.write(text)
+        if self._mirror is not None:
+            self._mirror.write(text)
+        return len(text)
+
+    def writable(self) -> bool:
+        """Report the stream as writable — that is the only thing it is for."""
+        return True
+
+    def flush(self) -> None:
+        """Flush the mirror stream, if any."""
+        if self._mirror is not None:
+            self._mirror.flush()
+
+
+def run_command(
+    global_argv: Sequence[str],
+    command: str,
+    argv: Sequence[str],
+    *,
+    json_argv: Optional[Sequence[str]] = JSON_FORMAT_ARGV,
+) -> Dict[str, Any]:
+    """Run ``dblift <global_argv> <command> <argv> [json_argv]`` and return its payload.
+
+    With *json_argv* (default ``--format json``) the return value is the parsed
+    stdout document. With ``json_argv=None`` the command has no machine format;
+    the return value is ``{"success": <handler result>, "output": <text>}``,
+    where *text* is the captured stdout followed by the captured stderr (each
+    stripped, joined with a newline, empty parts omitted). A command's content
+    may land on either console — some commands render through the stdout
+    console, others through the console logger, which writes to stderr — so
+    both are joined rather than risk losing whichever one carried it.
+
+    One call at a time: the module docstring lists the process-global state a
+    call rewrites. A second caller waits rather than corrupting the first.
+    """
+    with _CALL_LOCK:
+        return _run_command_locked(global_argv, command, argv, json_argv=json_argv)
+
+
+def _run_command_locked(
+    global_argv: Sequence[str],
+    command: str,
+    argv: Sequence[str],
+    *,
+    json_argv: Optional[Sequence[str]],
+) -> Dict[str, Any]:
+    """Body of :func:`run_command`; the caller must hold :data:`_CALL_LOCK`."""
+    from dblift.cli import main as cli_main
+    from dblift.cli._command_handlers import _COMMAND_HANDLERS, _validate_migrate_options
+
+    full_argv = [*global_argv, command, *argv, *(json_argv or ())]
+    stdout_buf, stderr_buf = io.StringIO(), io.StringIO()
+    stderr_tee = _TeeStream(stderr_buf, sys.stderr)
+    log: Any = None
+    client: Any = None
+    success = False
+    try:
+        with contextlib.redirect_stdout(stdout_buf), contextlib.redirect_stderr(stderr_tee):
+            ctx = cli_main._parse_argv_and_load_config(full_argv)
+            cli_main._setup_logging_and_output(ctx)
+            log = ctx.log
+            scripts_dir, additional_dirs, recursive, dir_map = (
+                cli_main._resolve_scripts_directories(
+                    ctx.args, ctx.config, ctx.parser, ctx.commands
+                )
+            )
+            client = cli_main._build_command_client(ctx)
+            placeholders = cli_main._collect_placeholders(ctx.args, ctx.config)
+            if command == "migrate":
+                _validate_migrate_options(ctx.args, ctx.parser)
+            cli_main._ensure_connection(client, ctx.log, command)
+            handler = _COMMAND_HANDLERS[command]
+            success, _result = handler(
+                CliCommandContext(
+                    client=client,
+                    args=ctx.args,
+                    log=ctx.log,
+                    scripts_dir=scripts_dir,
+                    additional_scripts_dirs=additional_dirs,
+                    recursive=recursive,
+                    placeholders=placeholders,
+                    dir_recursive_map=dir_map,
+                    license_tier=resolve_tier(ctx.args),
+                )
+            )
+    except CapabilityDeniedError as exc:
+        message = str(exc).strip() or _LICENSE_FALLBACK
+        raise CommandInvocationError(
+            f"{message} (exit code {EXIT_LICENSE_REQUIRED})", EXIT_LICENSE_REQUIRED
+        ) from exc
+    except SystemExit as exc:
+        code = exc.code if isinstance(exc.code, int) else 1
+        detail = stderr_buf.getvalue().strip()[-_TAIL:]
+        raise CommandInvocationError(
+            f"dblift {command} exited with code {code}: {detail}", code
+        ) from exc
+    except Exception as exc:
+        raise CommandInvocationError(f"{type(exc).__name__}: {exc}", 1) from exc
+    finally:
+        close = getattr(client, "close", None)
+        if callable(close):
+            try:
+                close()
+            except Exception as exc:  # a failed close must not mask the result
+                if log is not None:
+                    log.debug(f"Closing the client for '{command}' failed: {exc}")
+        if log is not None:
+            cli_main._close_logs(log)
+
+    stdout = stdout_buf.getvalue()
+    if json_argv is None:
+        # A text-mode command's content may land on either console: some
+        # commands render through the stdout console, others through the
+        # console logger, which writes to stderr. Join both, stdout first,
+        # so the caller gets the actual output regardless of which stream
+        # carried it.
+        parts = [part.strip() for part in (stdout, stderr_buf.getvalue()) if part.strip()]
+        return {"success": bool(success), "output": "\n".join(parts)}
+    try:
+        payload = json.loads(stdout)
+    except json.JSONDecodeError as exc:
+        raise CommandInvocationError(
+            f"dblift {command} produced no JSON on stdout: {stdout.strip()[-_TAIL:]}", 1
+        ) from exc
+    if not isinstance(payload, dict):
+        return {"success": True, "result": payload}
+    return payload