dbqm 2.3.2__tar.gz → 2.4.1__tar.gz

{dbqm-2.3.2 → dbqm-2.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dbqm
-Version: 2.3.2
+Version: 2.4.1
 Summary: Multi-database interactive query tool with fullscreen TUI
 Author: Silvio Chagas
 License-Expression: MIT

{dbqm-2.3.2 → dbqm-2.4.1}/README.md

@@ -225,7 +225,9 @@ offer `table|json|csv|raw`; every other command — `test`, `list`, `ddl`,
 `connection` group — offers `table|json`. `raw` prints plain values with no
 headers/decoration, handy for piping the body of a view, package, or
 procedure to another tool.
-`--export csv|json|txt` writes the result to a file regardless of `-f`.
+`--export csv|json|txt|html` writes the result to a file regardless of `-f`.
+`html` writes a standalone report meant to be read in a browser, and is not
+available together with `--flat`.
 
 `-f json` wraps every command in one envelope: a success prints
 `{"ok": true, "command": "...", "data": {...}}` to stdout; a failure prints

dbqm-2.4.1/dbqm/_version.py

@@ -0,0 +1 @@
+__version__ = "2.4.1"

{dbqm-2.3.2 → dbqm-2.4.1}/dbqm/cli/__init__.py

@@ -33,7 +33,7 @@ def build_parser() -> argparse.ArgumentParser:
                        help="Parametro (pode repetir)")
     p_run.add_argument("-f", "--format", choices=["table", "json", "csv", "raw"], default="table",
                        help="Formato de saida (padrao: table). 'raw' imprime valores sem decoracao.")
-    p_run.add_argument("-e", "--export", choices=["csv", "json", "txt"],
+    p_run.add_argument("-e", "--export", choices=["csv", "json", "txt", "html"],
                        help="Exportar resultado para arquivo")
 
     # --- run-group ---
@@ -43,8 +43,8 @@ def build_parser() -> argparse.ArgumentParser:
                        help="Parametro compartilhado (pode repetir)")
     p_grp.add_argument("-f", "--format", choices=["table", "json"], default="table",
                        help="Formato de saida")
-    p_grp.add_argument("-e", "--export", choices=["csv", "json", "txt"],
-                       help="Exportar resultado para arquivo")
+    p_grp.add_argument("-e", "--export", choices=["csv", "json", "txt", "html"],
+                       help="Exportar resultado para arquivo. 'html' nao pode ser usado com --flat.")
     p_grp.add_argument("--flat", action="store_true",
                        help="Usar formato flat (um bloco por coluna)")
 
@@ -69,7 +69,7 @@ def build_parser() -> argparse.ArgumentParser:
                        help="Parametro (pode repetir)")
     p_sql.add_argument("-f", "--format", choices=["table", "json", "csv", "raw"], default="table",
                        help="Formato de saida. 'raw' imprime valores sem decoracao.")
-    p_sql.add_argument("-e", "--export", choices=["csv", "json", "txt"],
+    p_sql.add_argument("-e", "--export", choices=["csv", "json", "txt", "html"],
                        help="Exportar resultado para arquivo")
     p_sql.add_argument("--commit", action="store_true",
                        help="Auto-commit para DML (INSERT/UPDATE/DELETE)")

{dbqm-2.3.2 → dbqm-2.4.1}/dbqm/cli/commands/query.py

@@ -133,6 +133,8 @@ def cmd_run(args: argparse.Namespace) -> None:
             path = deps.export_query_json(result, table_name, param_values)
         elif fmt == "txt":
             path = deps.export_query_txt(result, table_name, param_values)
+        elif fmt == "html":
+            path = deps.export_query_html(result, table_name, param_values)
         else:
             _fail_or_print(args, "run", "usage", f"Formato de export invalido: {fmt}")
         if args.format == "json":
@@ -162,6 +164,14 @@ def cmd_run_group(args: argparse.Namespace) -> None:
     on stdout. The exit code alone is what lets a shell branch on the verdict
     without parsing anything.
     """
+    # An argument combination that can never be valid is refused before any
+    # work happens -- before the group is even resolved, let alone any query
+    # run or any history record written.
+    if args.export == "html" and args.flat:
+        _fail_or_print(args, "run-group", "usage",
+                       "--flat nao tem versao HTML. Use --export html sem --flat, "
+                       "ou --flat com csv, json ou txt.")
+
     group = deps.find_group(args.group)
     if not group:
         _fail_or_print(args, "run-group", "not_found", f"Grupo '{args.group}' nao encontrado.")
@@ -219,15 +229,21 @@ def cmd_run_group(args: argparse.Namespace) -> None:
                 path = deps.export_group_flat_csv(group_result, param_values)
             elif fmt == "json":
                 path = deps.export_group_flat_json(group_result, param_values)
-            else:
+            elif fmt == "txt":
                 path = deps.export_group_flat_txt(group_result, param_values)
+            else:
+                _fail_or_print(args, "run-group", "usage", f"Formato de export invalido: {fmt}")
         else:
             if fmt == "csv":
                 path = deps.export_group_csv(group_result, param_values)
             elif fmt == "json":
                 path = deps.export_group_json(group_result, param_values)
-            else:
+            elif fmt == "txt":
                 path = deps.export_group_txt(group_result, param_values)
+            elif fmt == "html":
+                path = deps.export_group_html(group_result, param_values)
+            else:
+                _fail_or_print(args, "run-group", "usage", f"Formato de export invalido: {fmt}")
         if args.format == "json":
             ok("run-group", {"exported": str(path), "format": fmt})
         else:
@@ -412,8 +428,12 @@ def cmd_sql(args: argparse.Namespace) -> None:
                 path = deps.export_query_csv(qr, "adhoc", param_values)
             elif fmt == "json":
                 path = deps.export_query_json(qr, "adhoc", param_values)
-            else:
+            elif fmt == "txt":
                 path = deps.export_query_txt(qr, "adhoc", param_values)
+            elif fmt == "html":
+                path = deps.export_query_html(qr, "adhoc", param_values)
+            else:
+                _fail_or_print(args, "sql", "usage", f"Formato de export invalido: {fmt}")
             if args.format == "json":
                 ok("sql", {"exported": str(path), "format": fmt})
                 return

{dbqm-2.3.2 → dbqm-2.4.1}/dbqm/cli/deps.py

@@ -39,6 +39,7 @@ from dbqm.core.exporter import (
     export_query_txt,
 )
 from dbqm.core.group_engine import build_group_result
+from dbqm.core.html_report import export_group_html, export_query_html
 from dbqm.core.history import (
     clear_history,
     load_history,
@@ -83,9 +84,11 @@ __all__ = [
     "export_group_flat_csv",
     "export_group_flat_json",
     "export_group_flat_txt",
+    "export_group_html",
     "export_group_json",
     "export_group_txt",
     "export_query_csv",
+    "export_query_html",
     "export_query_json",
     "export_query_txt",
     "extract_ddl",

{dbqm-2.3.2 → dbqm-2.4.1}/dbqm/core/group_engine.py

@@ -2,9 +2,10 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import Any
+from typing import Any, Callable, Protocol
 
-from dbqm.core.query_engine import QueryResult
+from dbqm.core.query_engine import AdhocResult, QueryResult
+from dbqm.models.connection import Connection
 
 
 @dataclass
@@ -68,6 +69,144 @@ class GroupResult:
         }
 
 
+class NoComparableColumns(Exception):
+    """The results have no column in common, so there is nothing to compare."""
+
+
+class ResultLike(Protocol):
+    """What the comparison actually reads. `run_comparison` has always been
+    annotated `QueryResult` while the Multi-Exec screen passed it
+    `AdhocResult`; naming the real requirement retires that mismatch for new
+    code without touching the old signature."""
+    columns: list[str]
+    rows: list[list[Any]]
+
+
+def derive_comparison_columns(
+    results: dict[str, ResultLike],
+) -> tuple[str, list[str]]:
+    """Derive the join key and compare columns from the columns common to
+    every result.
+
+    The first result's column order wins -- not sorted, not any other
+    result's order. The join key is the first common column, the compare
+    columns are the rest. Raises `NoComparableColumns` when no column is
+    common to every result, or when there is no result to derive from at all.
+    """
+    if not results:
+        raise NoComparableColumns(
+            "Consultas nao retornaram colunas comparaveis."
+        )
+    first = next(iter(results))
+    base_cols = list(results[first].columns)
+    common = [
+        c for c in base_cols
+        if all(c in r.columns for r in results.values())
+    ]
+    if not common:
+        raise NoComparableColumns(
+            "Consultas nao retornaram colunas comparaveis."
+        )
+    return common[0], common[1:]
+
+
+def build_adhoc_group_result(
+    results: dict[str, ResultLike],
+    join_key: str = "",
+    compare_columns: list[str] | None = None,
+) -> GroupResult:
+    """Build a `GroupResult` for an ad-hoc, group-name-less comparison.
+
+    When `join_key` is not given, both it and `compare_columns` are derived
+    from the columns common to every result (see `derive_comparison_columns`).
+    """
+    if not join_key:
+        join_key, compare_columns = derive_comparison_columns(results)
+    elif compare_columns is None:
+        compare_columns = []
+
+    comparisons = run_comparison(results, join_key, compare_columns)
+    all_match = all(
+        c.diff_count == 0 and c.absent_count == 0 for c in comparisons
+    )
+    return GroupResult(
+        group_name="(ad-hoc)",
+        query_results=results,
+        comparisons=comparisons,
+        all_match=all_match,
+    )
+
+
+def execute_across(
+    sql: str,
+    conns: list[tuple[str, Connection | None]],
+    param_values: dict[str, str],
+    on_progress: Callable[[str], None] | None = None,
+    on_result: Callable[[str, AdhocResult], None] | None = None,
+    on_missing: Callable[[str], None] | None = None,
+) -> dict[str, AdhocResult]:
+    """Run the same SQL on each resolved connection, in order.
+
+    `conns` is a list of `(name, connection)` pairs, already resolved by the
+    caller -- core does not look connections up itself. `dbqm/cli/deps.py`
+    exists precisely so the CLI's connection lookup can be rebound in tests;
+    a lookup done here would route around that seam. A pair whose connection
+    is `None` fires `on_missing(name)`, in sequence with the pairs around it,
+    and contributes **no entry** to the returned dict -- it was never run,
+    so there is nothing to report. A pair that *did* run, successfully or
+    not, always gets an entry; Task 3 tells the two apart by entry
+    membership (`not_found`) versus `AdhocResult.error_kind` (`connection_failed`
+    vs `sql_error`).
+
+    Decides nothing about what a failure means -- the TUI carries on so a
+    dead connection does not discard the comparison on screen, the CLI stops
+    because a comparison over a subset answers a different question. A core
+    that picked one policy would force the other to work around it.
+
+    A raised exception becomes an unsuccessful AdhocResult with
+    `error_kind="connection"`, so one unreachable host cannot end the loop.
+
+    `on_progress`, `on_result` and `on_missing` each fire once per pair, in
+    the same sequential order as `conns` -- a caller that wants to react
+    per-connection (notify, log, stop) does not have to wait for every other
+    connection to finish first.
+    """
+    from dbqm.core.query_engine import execute_adhoc
+
+    results: dict[str, AdhocResult] = {}
+    for name, conn in conns:
+        if conn is None:
+            if on_missing is not None:
+                on_missing(name)
+            continue
+
+        if on_progress is not None:
+            on_progress(name)
+
+        try:
+            res = execute_adhoc(sql, conn, param_values)
+        except Exception as e:
+            res = AdhocResult(
+                sql_type="",
+                connection_name=name,
+                sql=sql,
+                db_type=conn.db_type,
+                success=False,
+                error=str(e),
+                error_kind="connection",
+            )
+        else:
+            # DML without auto_commit returns (AdhocResult, db_connection).
+            if isinstance(res, tuple):
+                res = res[0]
+
+        results[name] = res
+        if on_result is not None:
+            on_result(name, res)
+
+    return results
+
+
 def run_comparison(
     results: dict[str, QueryResult],
     join_key: str,

{dbqm-2.3.2 → dbqm-2.4.1}/dbqm/core/html_report.py

@@ -6,6 +6,7 @@ from html import escape as h
 from typing import Any
 
 from dbqm.core.group_engine import GroupResult
+from dbqm.core.query_engine import QueryResult
 from dbqm.core.exporter import _build_filepath
 from dbqm.design.tokens import LIGHT_TOKENS, DARK_TOKENS
 
@@ -29,6 +30,25 @@ def _light_theme_block(tokens: dict[str, str]) -> str:
     return f"@media (prefers-color-scheme: light) {{\n  :root {{\n{linhas}\n  }}\n}}"
 
 
+#: Layout rules shared by every report shell -- reset, body, header, the
+#: params table and the data table. Renderer-specific rules (status
+#: colouring, filter bar, search box, …) stay in their own `_build_*`
+#: function; only what both renderers actually share lives here, so a change
+#: to shared padding cannot drift between the two documents.
+_BASE_STYLE_RULES = """\
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; background: var(--ds-background); color: var(--ds-text); padding: 24px; }
+    .header { background: var(--ds-panel); border-radius: 8px; padding: 20px; margin-bottom: 20px; }
+    .header h1 { color: var(--ds-identity); font-size: 1.4em; }
+    .header .meta { color: var(--ds-text-muted); font-size: 0.85em; margin-top: 8px; }
+    .params { margin: 12px 0; border-collapse: collapse; }
+    .params td { padding: 4px 16px 4px 0; color: var(--ds-text-muted); font-size: 0.9em; }
+    table.data { width: 100%; border-collapse: collapse; margin-bottom: 8px; font-size: 0.9em; }
+    table.data th { background: var(--ds-panel); color: var(--ds-identity); padding: 8px 12px; text-align: left; border-bottom: 2px solid var(--ds-border); }
+    table.data td { padding: 6px 12px; border-bottom: 1px solid var(--ds-border); }
+    table.data tr:hover { background: var(--ds-surface-raised); }"""
+
+
 def export_group_html(group_result: GroupResult, params: dict[str, str] | None = None) -> str:
     """Export group comparison as a standalone HTML file. Returns file path."""
     query_names = list(group_result.query_results.keys())
@@ -39,6 +59,18 @@ def export_group_html(group_result: GroupResult, params: dict[str, str] | None =
     return str(filepath)
 
 
+def export_query_html(
+    result: QueryResult,
+    table: str = "",
+    params: dict[str, str] | None = None,
+) -> str:
+    """Export one result set as a standalone HTML file. Returns file path."""
+    label = table or result.query_name
+    filepath = _build_filepath("consultas", label, result.connection_name, params, "html")
+    filepath.write_text(_build_query_html(result, label, params), encoding="utf-8")
+    return str(filepath)
+
+
 def _status_class(status: str) -> str:
     return {"OK": "ok", "OK*": "ok", "DIFF": "diff", "ABSENT": "absent"}.get(status, "")
 
@@ -106,26 +138,16 @@ def _build_html(group_result: GroupResult, query_names: list[str], params: dict[
        despercebido. Por isso: nenhuma cor composta em CSS pode carregar
        texto; texto so usa var(--token) puro, e estado em superficie e
        borda/marcador, nunca preenchimento. */
-    * {{ margin: 0; padding: 0; box-sizing: border-box; }}
-    body {{ font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; background: var(--ds-background); color: var(--ds-text); padding: 24px; }}
-    .header {{ background: var(--ds-panel); border-radius: 8px; padding: 20px; margin-bottom: 20px; }}
-    .header h1 {{ color: var(--ds-identity); font-size: 1.4em; }}
-    .header .meta {{ color: var(--ds-text-muted); font-size: 0.85em; margin-top: 8px; }}
+{_BASE_STYLE_RULES}
     .badge {{ display: inline-block; padding: 4px 12px; border-radius: 4px; font-weight: bold; font-size: 0.85em; }}
     /* Estado em superficie e borda/marcador, nunca preenchimento: um preenchimento
        misturado a partir do proprio texto sempre compromete um dos dois. */
     .badge.ok {{ background: var(--ds-panel); color: var(--ds-verdict-match); border: 1px solid var(--ds-verdict-match); }}
     .badge.diff {{ background: var(--ds-panel); color: var(--ds-verdict-diff); border: 1px solid var(--ds-verdict-diff); }}
-    .params {{ margin: 12px 0; border-collapse: collapse; }}
-    .params td {{ padding: 4px 16px 4px 0; color: var(--ds-text-muted); font-size: 0.9em; }}
     h3 {{ color: var(--ds-identity); margin: 24px 0 8px; }}
     .filter-bar {{ margin-bottom: 8px; }}
     .filter-btn {{ background: var(--ds-panel); color: var(--ds-text-muted); border: 1px solid var(--ds-border); padding: 4px 12px; border-radius: 4px; cursor: pointer; margin-right: 4px; font-size: 0.8em; }}
     .filter-btn.active {{ background: var(--ds-surface-raised); color: var(--ds-identity); border-color: var(--ds-identity); }}
-    table.data {{ width: 100%; border-collapse: collapse; margin-bottom: 8px; font-size: 0.9em; }}
-    table.data th {{ background: var(--ds-panel); color: var(--ds-identity); padding: 8px 12px; text-align: left; border-bottom: 2px solid var(--ds-border); }}
-    table.data td {{ padding: 6px 12px; border-bottom: 1px solid var(--ds-border); }}
-    table.data tr:hover {{ background: var(--ds-surface-raised); }}
     .key {{ color: var(--ds-text-strong); font-weight: 600; }}
     .ok {{ color: var(--ds-verdict-match); font-weight: 600; }}
     .diff {{ color: var(--ds-verdict-diff); font-weight: 600; }}
@@ -182,3 +204,53 @@ function filterSearch(term) {{
 </script>
 </body>
 </html>"""
+
+
+def _build_query_html(result: QueryResult, label: str, params: dict[str, str] | None) -> str:
+    now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+    params_html = ""
+    if params:
+        rows = "".join(
+            f"<tr><td><strong>{h(str(k))}</strong></td><td>{h(str(v))}</td></tr>"
+            for k, v in params.items()
+        )
+        params_html = f'<div class="meta">Parametros:</div><table class="params">{rows}</table>'
+
+    header_cols = "".join(f"<th>{h(str(col))}</th>" for col in result.columns)
+    rows_html = ""
+    for row in result.rows:
+        cells = "".join(f"<td>{'' if v is None else h(str(v))}</td>" for v in row)
+        rows_html += f"<tr>{cells}</tr>"
+
+    return f"""<!DOCTYPE html>
+<html lang="pt-BR">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Relatorio - {h(label)}</title>
+<style>
+{css_variables(DARK_TOKENS)}
+{_light_theme_block(LIGHT_TOKENS)}
+{_BASE_STYLE_RULES}
+</style>
+</head>
+<body>
+<div class="header">
+    <h1>DB Query Manager - Relatorio de Consulta</h1>
+    <div class="meta">
+        Consulta: <strong>{h(label)}</strong> |
+        Conexao: <strong>{h(result.connection_name)}</strong> |
+        Data: {now} |
+        Linhas: {result.row_count} |
+        Tempo: {result.elapsed:.3f}s
+    </div>
+    {params_html}
+</div>
+
+<table class="data">
+    <thead><tr>{header_cols}</tr></thead>
+    <tbody>{rows_html}</tbody>
+</table>
+</body>
+</html>"""

{dbqm-2.3.2 → dbqm-2.4.1}/dbqm/ui/screens/group_exec.py

@@ -256,51 +256,44 @@ class GroupExecScreen(Vertical):
     def _run(self, sql: str, conn_names: list[str]) -> None:
         """Run the same SQL on each connection and compare the results."""
         from dbqm.models.connection import find_connection
-        from dbqm.core.query_engine import execute_adhoc
-        from dbqm.core.group_engine import run_comparison, GroupResult
+        from dbqm.core.group_engine import (
+            NoComparableColumns,
+            build_adhoc_group_result,
+            execute_across,
+        )
+        from dbqm.core.query_engine import AdhocResult
 
-        try:
-            results = {}
-            for cname in conn_names:
-                conn = find_connection(cname)
-                if conn is None:
-                    self.app.call_from_thread(
-                        self.notify,
-                        f"Conexao '{cname}' nao encontrada.",
-                        severity="warning",
-                    )
-                    continue
+        def on_progress(cname: str) -> None:
+            self.app.call_from_thread(
+                self._update_progress,
+                f"Executando em [bold]{escape_markup(cname)}[/]...",
+            )
 
+        def on_result(cname: str, res: AdhocResult) -> None:
+            if not res.success:
                 self.app.call_from_thread(
-                    self._update_progress,
-                    f"Executando em [bold]{escape_markup(cname)}[/]...",
+                    self.notify,
+                    f"Erro em '{cname}': {res.error}",
+                    severity="error",
+                    timeout=8,
                 )
 
-                try:
-                    res = execute_adhoc(sql, conn, {})
-                except Exception as e:
-                    self.app.call_from_thread(
-                        self.notify,
-                        f"Erro em '{cname}': {e}",
-                        severity="error",
-                        timeout=8,
-                    )
-                    continue
-
-                # DML without auto_commit returns (AdhocResult, db_connection).
-                if isinstance(res, tuple):
-                    res = res[0]
-
-                if not res.success:
-                    self.app.call_from_thread(
-                        self.notify,
-                        f"Erro em '{cname}': {res.error}",
-                        severity="error",
-                        timeout=8,
-                    )
-                    continue
-
-                results[cname] = res
+        def on_missing(cname: str) -> None:
+            self.app.call_from_thread(
+                self.notify,
+                f"Conexao '{cname}' nao encontrada.",
+                severity="warning",
+            )
+
+        try:
+            conns = [(cname, find_connection(cname)) for cname in conn_names]
+            all_results = execute_across(
+                sql, conns, {},
+                on_progress=on_progress, on_result=on_result, on_missing=on_missing,
+            )
+            results = {
+                cname: res for cname, res in all_results.items() if res.success
+            }
 
             if len(results) < 1:
                 self.app.call_from_thread(
@@ -308,34 +301,14 @@ class GroupExecScreen(Vertical):
                 )
                 return
 
-            # Auto-derive the join key + compare columns from the columns that
-            # are common to every result (defensive intersection).
-            first = next(iter(results))
-            base_cols = list(results[first].columns)
-            common = [
-                c for c in base_cols
-                if all(c in r.columns for r in results.values())
-            ]
-            if not common:
+            try:
+                group_result = build_adhoc_group_result(results)
+            except NoComparableColumns:
                 self.app.call_from_thread(
                     self._on_error, "Consultas nao retornaram colunas comparaveis."
                 )
                 return
 
-            join_key = common[0]
-            compare_columns = common[1:]
-
-            comparisons = run_comparison(results, join_key, compare_columns)
-            all_match = all(
-                c.diff_count == 0 and c.absent_count == 0 for c in comparisons
-            )
-            group_result = GroupResult(
-                group_name="(ad-hoc)",
-                query_results=results,
-                comparisons=comparisons,
-                all_match=all_match,
-            )
-
             self.app.call_from_thread(self._show_result, group_result)
         except Exception as e:
             self.app.call_from_thread(self._on_error, f"Erro inesperado: {e}")

{dbqm-2.3.2 → dbqm-2.4.1}/dbqm.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dbqm
-Version: 2.3.2
+Version: 2.4.1
 Summary: Multi-database interactive query tool with fullscreen TUI
 Author: Silvio Chagas
 License-Expression: MIT

{dbqm-2.3.2 → dbqm-2.4.1}/tests/test_cli.py

@@ -261,6 +261,20 @@ class TestCmdRun:
             run_cli(["run", "test_query", "-e", "csv"])
             mock_exp.assert_called_once()
 
+    def test_run_export_html(self, tmp_config_dir):
+        query = _make_query()
+        conn = _make_connection()
+        result = _make_query_result()
+
+        with patch("dbqm.cli.deps.find_query", return_value=query), \
+             patch("dbqm.cli.deps.find_connection", return_value=conn), \
+             patch("dbqm.cli.deps.execute_query", return_value=result), \
+             patch("dbqm.cli.deps.record_query_execution"), \
+             patch("dbqm.cli.deps.log_execution"), \
+             patch("dbqm.cli.deps.export_query_html", return_value="/tmp/out.html") as mock_exp:
+            run_cli(["run", "test_query", "-e", "html"])
+            mock_exp.assert_called_once()
+
     def test_run_format_json(self, capsys):
         """`data` is `QueryResult.to_dict()` verbatim: `rows` are parallel
         arrays (a list per row, indexed by `columns`), not a dict per row —
@@ -428,6 +442,83 @@ class TestCmdRunGroup:
             run_cli(["run-group", "test_group", "-e", "csv"])
             mock_exp.assert_called_once()
 
+    def test_group_export_html(self):
+        group = _make_group()
+        q1 = _make_query("q1", "c1")
+        q2 = _make_query("q2", "c2")
+        c1 = _make_connection("c1")
+        c2 = _make_connection("c2")
+        gr = _make_group_result()
+
+        def find_query_side(name):
+            return {"q1": q1, "q2": q2}.get(name)
+
+        def find_conn_side(name):
+            return {"c1": c1, "c2": c2}.get(name)
+
+        with patch("dbqm.cli.deps.find_group", return_value=group), \
+             patch("dbqm.cli.deps.find_query", side_effect=find_query_side), \
+             patch("dbqm.cli.deps.find_connection", side_effect=find_conn_side), \
+             patch("dbqm.cli.deps.execute_query", return_value=_make_query_result()), \
+             patch("dbqm.cli.deps.build_group_result", return_value=gr), \
+             patch("dbqm.cli.deps.record_group_execution"), \
+             patch("dbqm.cli.deps.export_group_html", return_value="/tmp/g.html") as mock_exp:
+            run_cli(["run-group", "test_group", "-e", "html"])
+            mock_exp.assert_called_once()
+
+    def test_group_flat_html_is_refused_table_format(self, capsys):
+        """The trap: `--flat` is a CSV-shaped denormalisation with no HTML
+        equivalent. Silently ignoring the flag would hand back a different
+        shape (the non-flat report) with no signal that `--flat` was
+        dropped. Checked under `table` too, not just `json`: a refusal that
+        only fires under one renderer is the bug class 2.3.0 existed to
+        fix.
+
+        The refusal fires before the group is even resolved (a bad argument
+        combination costs no work), so `find_group` is mocked but must never
+        be called -- that is also what proves this test is pinned to *this*
+        refusal and not to the flat arm's generic bare-`else` fallback,
+        which would also exit 2 with no export call but only after
+        resolving the group and running every query in it.
+        """
+        with patch("dbqm.cli.deps.find_group") as mock_find_group, \
+             patch("dbqm.cli.deps.export_group_flat_csv") as mock_flat_csv, \
+             patch("dbqm.cli.deps.export_group_flat_json") as mock_flat_json, \
+             patch("dbqm.cli.deps.export_group_flat_txt") as mock_flat_txt:
+            with pytest.raises(SystemExit) as excinfo:
+                run_cli(["run-group", "test_group", "--flat", "-e", "html"])
+            assert excinfo.value.code == 2
+            saida = capsys.readouterr().out
+            assert "--flat" in saida, "must name the refused flag, not just exit 2"
+            assert "Exportado:" not in saida, "no export must have happened"
+            mock_find_group.assert_not_called()
+            mock_flat_csv.assert_not_called()
+            mock_flat_json.assert_not_called()
+            mock_flat_txt.assert_not_called()
+
+    def test_group_flat_html_is_refused_json_format(self, capsys):
+        """Same refusal, `-f json` side: the contract is that stdout stays
+        empty and the failure carries the usage token on stderr. Also fires
+        before the group is resolved -- see the table-format sibling above
+        for why `find_group` must stay uncalled."""
+        with patch("dbqm.cli.deps.find_group") as mock_find_group, \
+             patch("dbqm.cli.deps.export_group_flat_csv") as mock_flat_csv, \
+             patch("dbqm.cli.deps.export_group_flat_json") as mock_flat_json, \
+             patch("dbqm.cli.deps.export_group_flat_txt") as mock_flat_txt:
+            with pytest.raises(SystemExit) as excinfo:
+                run_cli(["run-group", "test_group", "--flat", "-e", "html", "-f", "json"])
+            assert excinfo.value.code == 2
+            saida = capsys.readouterr()
+            assert saida.out == ""
+            corpo = json.loads(saida.err)
+            assert corpo["error"]["code"] == "usage"
+            assert "--flat" in corpo["error"]["message"]
+            assert "html" in corpo["error"]["message"]
+            mock_find_group.assert_not_called()
+            mock_flat_csv.assert_not_called()
+            mock_flat_json.assert_not_called()
+            mock_flat_txt.assert_not_called()
+
     def test_group_export_json_format_emits_envelope(self, capsys):
         """CRITICAL fix: `-e` used to print bare prose and return under
         `-f json`."""
@@ -683,6 +774,24 @@ class TestCmdSql:
             run_cli(["sql", "SELECT 1", "test_conn", "-e", "csv"])
             mock_exp.assert_called_once()
 
+    def test_sql_export_html_does_not_fall_through_to_txt(self):
+        """The trap: `sql`'s export branch used to end in a bare `else` that
+        wrote TXT, so a new format would have written the wrong file and
+        reported success."""
+        conn = _make_connection()
+        from dbqm.core.query_engine import AdhocResult
+        adhoc = AdhocResult(
+            sql_type="SELECT", connection_name="test_conn",
+            columns=["x"], rows=[[1]], row_count=1, elapsed=0.01,
+        )
+        with patch("dbqm.cli.deps.find_connection", return_value=conn), \
+             patch("dbqm.cli.deps.execute_adhoc", return_value=adhoc), \
+             patch("dbqm.cli.deps.export_query_html", return_value="/tmp/o.html") as mock_html, \
+             patch("dbqm.cli.deps.export_query_txt") as mock_txt:
+            run_cli(["sql", "SELECT 1", "test_conn", "-e", "html"])
+            mock_html.assert_called_once()
+            mock_txt.assert_not_called()
+
     def test_sql_export_json_format_emits_envelope(self, capsys):
         """CRITICAL fix: `-e` used to print bare prose and return under
         `-f json`."""

dbqm-2.3.2/dbqm/_version.py

@@ -1 +0,0 @@
-__version__ = "2.3.2"