dataface 0.1.2__py3-none-any.whl

dataface/cli/commands/inspect.py

@@ -0,0 +1,94 @@
+"""Inspect command — OSS template-management verbs only.
+
+The profiler verbs (inspect_command, inspect_all_command, audit_command) live
+in the private ``dataface-super-schema`` package and are registered via the
+``dataface.cli_plugins`` entry-point when that package is installed.
+
+This module contains only the template-management commands that ship with the
+OSS ``dataface`` wheel: eject, templates, and validate-templates.
+"""
+
+from pathlib import Path
+
+import typer
+
+from dataface.agent_api import inspect as _api
+from dataface.cli._console import dft_console
+
+console = dft_console()
+
+
+def eject_command(
+    templates: list[str],
+    all_templates: bool = False,
+    force: bool = False,
+    output_dir: Path | None = None,
+) -> None:
+    target_dir = output_dir or (Path.cwd() / "faces" / "inspect")
+    to_eject: list[str] | None = None if all_templates else (templates or None)
+    if not all_templates and not templates:
+        console.print("[bold red]Error:[/bold red] Specify template names or --all")
+        console.print(f"Available: {', '.join(t.name for t in _api.list_templates())}")
+        raise typer.Exit(1)
+    try:
+        ejected = _api.eject_templates(target_dir, templates=to_eject, force=force)
+    except ValueError as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+        raise typer.Exit(1) from None
+    skipped_count = len(to_eject or [t.name for t in _api.list_templates()]) - len(
+        ejected
+    )
+    console.print(f"[dim]Output directory: {target_dir}[/dim]\n")
+    for p in ejected:
+        console.print(f"  [green]✓[/green] {p.name}")
+    console.print()
+    if ejected:
+        console.print(
+            f"[bold green]✓[/bold green] Ejected {len(ejected)} template(s) to {target_dir}"
+        )
+    if skipped_count > 0:
+        console.print(f"[dim]Skipped {skipped_count} existing file(s)[/dim]")
+    if ejected and not force:
+        console.print(
+            "\n[dim]To reset to built-in defaults: dft inspect eject --all --force[/dim]"
+        )
+
+
+def validate_ejected_templates_command(output_dir: Path | None = None) -> None:
+    try:
+        result = _api.validate_ejected_templates(output_dir)
+    except FileNotFoundError as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+        raise typer.Exit(1) from None
+    for label, names, style in [
+        ("Missing ejected templates", result.missing, "bold red"),
+        (
+            "Upstream changed since eject (manual rebase needed)",
+            result.upstream_changed,
+            "bold yellow",
+        ),
+        (
+            "Customized templates still aligned to built-ins",
+            result.custom_safe,
+            "bold cyan",
+        ),
+        ("Unchanged templates", result.unchanged, "dim"),
+    ]:
+        if names:
+            console.print(f"[{style}]{label}:[/{style}]")
+            for name in names:
+                console.print(f"  - {name}")
+    if not result.success:
+        raise typer.Exit(1)
+    console.print("\n[bold green]✓[/bold green] Ejected templates are compatible.")
+
+
+def templates_command() -> None:
+    console.print("\n[bold]Available Inspect Templates[/bold]\n")
+    for t in _api.list_templates():
+        console.print(f"  • {t.name}")
+    console.print("\n[dim]To customize a template:[/dim]")
+    console.print("  dft inspect eject <template>       # Copy to faces/inspect/")
+    console.print("  dft inspect eject --all            # Copy all templates")
+    console.print("  dft inspect validate-templates     # Check compatibility")
+    console.print()

dataface/cli/commands/mcp_init.py

@@ -0,0 +1,167 @@
+"""`dft init mcp` thin wrapper: parse args, call agent_api.mcp_install, format output."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import sys
+from pathlib import Path
+
+import typer
+
+from dataface.agent_api import mcp_install
+from dataface.core.compile.meta import find_project_root
+from dataface.core.project_roots import PROJECT_MARKERS, find_dataface_project
+
+
+def _resolve_dft_executable() -> str:
+    """Path to this `dft` install for embedding in MCP client configs.
+
+    GUI apps (Cursor, VS Code) often spawn MCP with a minimal ``PATH``. A
+    config entry ``"command": "dft"`` then fails with ``spawn dft ENOENT``.
+    When this code runs as the real ``dft`` console script, ``sys.argv[0]``
+    is an absolute (or resolvable) path to that binary — use it first, then
+    ``shutil.which``, then fall back to the bare name.
+    """
+    invoked = Path(sys.argv[0]).expanduser()
+    try:
+        resolved = invoked.resolve(strict=False)
+    except OSError:
+        resolved = invoked
+    name = resolved.name.casefold()
+    if name in ("dft", "dft.exe") and resolved.is_file():
+        return str(resolved)
+    return shutil.which("dft") or "dft"
+
+
+def _resolve_project_dir(explicit: Path | None) -> Path:
+    markers_str = ", ".join(PROJECT_MARKERS)
+    if explicit is not None:
+        nearest = find_dataface_project(explicit)
+        if nearest != explicit:
+            msg = (
+                f"Error: --project-dir {explicit} does not contain a Dataface "
+                f"or dbt project.\n"
+                f"Looked for: {markers_str}."
+            )
+            if nearest is not None:
+                msg += f"\nTip: did you mean {nearest}?"
+            typer.echo(msg, err=True)
+            raise typer.Exit(1)
+        return explicit
+
+    found = find_dataface_project(Path.cwd())
+    if found is None:
+        typer.echo(
+            f"Error: No Dataface or dbt project found at or above {Path.cwd()}.\n"
+            f"Looked for: {markers_str}.\n"
+            f"Re-run from inside your Dataface project, "
+            f"or pass --project-dir <path>.",
+            err=True,
+        )
+        raise typer.Exit(1)
+    return found
+
+
+def run_init(
+    client: str | None,
+    all_clients: bool,
+    force: bool,
+    project_dir: Path | None = None,
+) -> None:
+    """Shared implementation for `dft init mcp`."""
+    config_root = find_project_root(Path.cwd())
+    project_dir_resolved = _resolve_project_dir(project_dir)
+
+    dft_path = _resolve_dft_executable()
+    server_command = [dft_path, "mcp", "serve"]
+    if project_dir_resolved != config_root:
+        server_command += ["--project-dir", str(project_dir_resolved)]
+
+    if client and client.lower() == "print":
+        entry = {"command": server_command[0], "args": server_command[1:]}
+        typer.echo(json.dumps({"mcpServers": {"dataface": entry}}, indent=2))
+        return
+
+    if client and all_clients:
+        typer.echo("Specify either a client or --all, not both.", err=True)
+        raise typer.Exit(1)
+
+    all_known = mcp_install.list_clients()
+    known_names = {c.name for c in all_known}
+
+    if all_clients:
+        targets = all_known
+    elif client:
+        target = client.lower()
+        if target not in known_names:
+            typer.echo(
+                f"Unknown client: {client}. "
+                f"Supported: {', '.join(sorted(known_names) + ['print'])}",
+                err=True,
+            )
+            raise typer.Exit(1)
+        targets = [c for c in all_known if c.name == target]
+    else:
+        targets = [
+            c
+            for c in all_known
+            if any((config_root / dp).exists() for dp in c.detect_paths)
+        ]
+        if not targets:
+            typer.echo(
+                "No AI client markers detected (.cursor/, .codex/, .vscode/, "
+                ".github/, CLAUDE.md, AGENTS.md, ~/.config/claude/)."
+            )
+            typer.echo("")
+            typer.echo("To configure manually, specify a client:")
+            typer.echo("  dft init mcp cursor        # Cursor")
+            typer.echo("  dft init mcp vscode        # VS Code")
+            typer.echo("  dft init mcp claude        # Claude Desktop")
+            typer.echo("  dft init mcp claude-code   # Claude Code")
+            typer.echo("  dft init mcp codex         # OpenAI Codex CLI")
+            typer.echo("  dft init mcp copilot       # GitHub Copilot Coding Agent")
+            typer.echo("  dft init mcp --all         # Write every supported config")
+            typer.echo("  dft init mcp print         # Print JSON config to stdout")
+            return
+
+    configured = []
+    for c in targets:
+        result = mcp_install.install_for_client(
+            c, server_command=server_command, config_root=config_root, force=force
+        )
+        typer.echo(result.message)
+        if not result.already_configured:
+            configured.append(c.name)
+
+    if configured:
+        typer.echo("")
+        # Trailer pinned to dataface.ai.tool_schemas.ALL_TOOLS and
+        # dataface.ai.mcp.server._BASE_RESOURCES by
+        # test_configured_trailer_advertises_every_tool_and_resource_family.
+        # Update these strings when either registry changes.
+        typer.echo(
+            "  MCP tools: describe_dashboard, describe_query, docs, execute_query, "
+            "get_skill, list_skills, query_face, render_dashboard, schema, "
+            "schema_search, search_dashboards, search_skills, validate_dashboard"
+        )
+        typer.echo(
+            "  Resources: dataface://dashboards, dataface://dashboard/{path}, "
+            "dataface://docs/{all,reference,<topic>}, "
+            "dataface://guide/{dashboard-design,dashboard-build,dashboard-review,report-design}"
+        )
+
+    typer.echo("")
+    if configured:
+        if "cursor" in configured:
+            typer.echo(
+                "  Next: Open Cursor Settings → MCP and enable the 'dataface' server."
+            )
+        elif "claude" in configured:
+            typer.echo("  Restart Claude Desktop for changes to take effect.")
+        else:
+            clients_str = ", ".join(sorted(configured))
+            typer.echo(f"  Restart {clients_str} for changes to take effect.")
+        typer.echo(
+            "  Install workflow skills: dft init skills (separate from MCP wiring)."
+        )

dataface/cli/commands/query.py

@@ -0,0 +1,386 @@
+"""Query command implementation — named face queries and raw SQL dispatch."""
+
+from __future__ import annotations
+
+import difflib
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, NoReturn
+
+import typer
+from rich.markup import escape
+from rich.table import Table
+
+if TYPE_CHECKING:
+    from rich.console import Console
+
+from dataface.agent_api._paths import project_root_for
+from dataface.agent_api.describe_query import DescribeQueryResult, describe_query
+from dataface.agent_api.query import (
+    ExecuteQueryResult,
+    FaceQueryLookupResult,
+    QueryFaceResult,
+    execute_query,
+    lookup_face_query_sql,
+    query_face,
+)
+from dataface.agent_api.validate_query import ValidateQueryResult, validate_query
+from dataface.cli._console import dft_console
+from dataface.cli._json_output import print_json_result
+from dataface.core.execute.adapters import build_adapter_registry
+
+console = dft_console()
+err_console = dft_console(stderr=True)
+
+# ---------------------------------------------------------------------------
+# Output helpers
+# ---------------------------------------------------------------------------
+
+_SEVERITY_ICON = {"error": "❌", "warning": "⚠️ ", "info": "ℹ️ "}
+
+
+def _rows_table(columns: list[str], data: list[dict[str, Any]]) -> Table:
+    t = Table(show_header=True, header_style="bold", box=None, padding=(0, 2, 0, 0))
+    for col in columns:
+        t.add_column(escape(col))
+    for row in data:
+        t.add_row(*(escape(str(row.get(col, ""))) for col in columns))
+    return t
+
+
+def _print_rows(
+    columns: list[str], data: list[dict[str, Any]], row_count: int, truncated: bool
+) -> None:
+    if columns:
+        console.print(_rows_table(columns, data))
+    err_console.print(f"\n{row_count} rows{' (truncated)' if truncated else ''}")
+
+
+def _print_diagnostic(d: dict[str, Any], target: Console = err_console) -> None:
+    icon = _SEVERITY_ICON.get(d.get("severity", ""), "⚠️ ")
+    target.print(f"{icon} [{d['code']}] {d['message']}", markup=False)
+    if d.get("detail"):
+        target.print(f"   {d['detail']}", markup=False)
+    if d.get("recommendation"):
+        target.print(f"   → {d['recommendation']}", markup=False)
+    if d.get("confidence") is not None:
+        target.print(f"   confidence: {d['confidence']:.0%}")
+    for ev in d.get("evidence", []):
+        target.print(f"   evidence: {ev}", markup=False)
+
+
+def _print_query_face_rich(result: QueryFaceResult) -> None:
+    if not result.success:
+        for err in result.errors:
+            err_console.print(f"[red]Error:[/red] {escape(err)}")
+        if result.available_queries:
+            matches = difflib.get_close_matches(
+                result.name, result.available_queries, n=3
+            )
+            if matches:
+                err_console.print(f"Did you mean: {escape(', '.join(matches))}?")
+            elif _looks_like_sql(result.name):
+                err_console.print("Did you mean to drop --in for raw SQL?")
+            err_console.print(
+                f"Available queries: {escape(', '.join(result.available_queries))}"
+            )
+        raise typer.Exit(1)
+    _print_rows(result.columns, result.data, result.row_count, result.truncated)
+
+
+def _print_execute_query_rich(result: ExecuteQueryResult) -> None:
+    if not result.success:
+        err_console.print(f"[red]Error:[/red] {escape(result.error or '')}")
+        raise typer.Exit(1)
+    _print_rows(result.columns, result.data, result.row_count, result.truncated)
+
+
+def _print_validate_result(
+    result: ValidateQueryResult,
+    show_suppressed: bool = False,
+    json_output: bool = False,
+) -> None:
+    """Print validate result and exit 1 on errors."""
+    if json_output:
+        payload: Any = (
+            {"diagnostics": result.diagnostics, "suppressed": result.suppressed or []}
+            if show_suppressed
+            else result.diagnostics
+        )
+        typer.echo(json.dumps(payload, indent=2))
+    elif not result.diagnostics and not (show_suppressed and result.suppressed):
+        console.print("No issues found.")
+    else:
+        for d in result.diagnostics:
+            _print_diagnostic(d, target=console)
+        if show_suppressed and result.suppressed:
+            console.print(f"\nSuppressed ({len(result.suppressed)}):")
+            for d in result.suppressed:
+                console.print(f"  ~ [{d['code']}] {d['message']}", markup=False)
+
+    if result.has_errors:
+        raise typer.Exit(1)
+
+
+def _print_describe_result(
+    result: DescribeQueryResult, json_output: bool = False
+) -> None:
+    """Print describe result and exit 1 on failure."""
+    if json_output:
+        print_json_result(result)
+        if not result.success:
+            raise typer.Exit(1)
+        return
+
+    if not result.success:
+        err_console.print(f"[red]Error:[/red] {escape(result.error or '')}")
+        for d in result.diagnostics:
+            _print_diagnostic(d)
+        raise typer.Exit(1)
+
+    if result.columns:
+        t = Table(show_header=True, header_style="bold", box=None, padding=(0, 2, 0, 0))
+        t.add_column("name")
+        t.add_column("type")
+        for col in result.columns:
+            t.add_row(escape(col.name), escape(col.type))
+        console.print(t)
+
+    for d in result.diagnostics:
+        _print_diagnostic(d)
+
+
+# ---------------------------------------------------------------------------
+# SQL-source resolution helpers
+# ---------------------------------------------------------------------------
+
+
+def _resolve_sql_text(
+    target: str | None,
+    file: Path | None,
+    face: Path | None,
+) -> tuple[str, bool, str | None]:
+    """Resolve the SQL text and whether we are in named-query mode.
+
+    Returns (sql_text, mode_is_named, name_or_none).
+    Raises typer.Exit(1) on any resolution error.
+    """
+    if face and file:
+        typer.echo(
+            "Error: use --in (named query) or --file (SQL file), not both.", err=True
+        )
+        raise typer.Exit(1)
+
+    if face:
+        # Named-query mode — TARGET is the query name, SQL resolved later.
+        if not target:
+            typer.echo(
+                "Error: provide a query name when using --in"
+                " (e.g. dft query revenue --in face.yml).",
+                err=True,
+            )
+            raise typer.Exit(1)
+        return "", True, target
+
+    if file:
+        if not file.exists():
+            typer.echo(f"Error: file not found: {file}", err=True)
+            raise typer.Exit(1)
+        return file.read_text(), False, None
+
+    if not target:
+        typer.echo(
+            "Error: provide SQL, --file, or NAME --in face.yml.",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    return target, False, None
+
+
+_SQL_SHAPE_CHARS = frozenset(" \t\n()")
+
+
+def _looks_like_sql(name: str) -> bool:
+    """Return True if name resembles a SQL expression rather than a query identifier."""
+    upper = name.upper()
+    return (
+        upper.startswith("SELECT")
+        or upper.startswith("WITH")
+        or any(c in name for c in _SQL_SHAPE_CHARS)
+    )
+
+
+def _handle_lookup_failure(lr: FaceQueryLookupResult, query_name: str) -> NoReturn:
+    """Emit errors from a failed FaceQueryLookupResult and raise typer.Exit(1)."""
+    for err in lr.errors:
+        typer.echo(f"Error: {err}", err=True)
+    if lr.available_queries:
+        matches = difflib.get_close_matches(query_name, lr.available_queries, n=3)
+        if matches:
+            typer.echo("Did you mean: " + ", ".join(matches) + "?", err=True)
+        elif _looks_like_sql(query_name):
+            typer.echo("Did you mean to drop --in for raw SQL?", err=True)
+        typer.echo("Available queries: " + ", ".join(lr.available_queries), err=True)
+    raise typer.Exit(1)
+
+
+def _resolve_source(source_flag: str | None, face_source: str | None) -> str:
+    """Resolve the effective source, raising if neither is available."""
+    resolved = source_flag or face_source
+    if resolved is None:
+        typer.echo(
+            "Error: SQL execute requires --source. "
+            "Add --validate for static lint, or --source <name> to execute.",
+            err=True,
+        )
+        raise typer.Exit(1)
+    return resolved
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+
+def query_command(
+    target: str | None,
+    face: Path | None = None,
+    source: str | None = None,
+    validate: bool = False,
+    describe: bool = False,
+    file: Path | None = None,
+    dialect: str | None = None,
+    vars: dict[str, Any] | None = None,
+    limit: int = 20,
+    show_suppressed: bool = False,
+    json_output: bool = False,
+    project_dir: Path | None = None,
+) -> None:
+    """Run a named face query, raw SQL, or static SQL lint/describe — selected from the input args."""
+    project_root = project_root_for(project_dir)
+
+    # --- 1. Resolve input shape ---
+    sql_text, mode_is_named, query_name = _resolve_sql_text(target, file, face)
+
+    # --- 2. Apply mode flags ---
+    if not validate and not describe:
+        # Execute path — keep the named-query branch as a direct query_face call so
+        # that file-not-found and compile errors are returned as structured JSON
+        # (QueryFaceResult.success=False) rather than plain stderr messages.
+        if mode_is_named:
+            assert query_name is not None
+            assert face is not None
+            adapter_registry = build_adapter_registry(project_root, read_only=True)
+            face_result = query_face(
+                name=query_name,
+                path=face,
+                project_dir=project_root,
+                vars=vars,
+                limit=limit,
+                adapter_registry=adapter_registry,
+            )
+            if json_output:
+                print_json_result(face_result)
+                if not face_result.success:
+                    raise SystemExit(1)
+            else:
+                _print_query_face_rich(face_result)
+        else:
+            # Raw SQL — if the positional doesn't look like SQL, hint --in instead.
+            if not _looks_like_sql(sql_text):
+                typer.echo(
+                    f"Did you mean `dft query {sql_text} --in <face.yml>`?",
+                    err=True,
+                )
+                raise typer.Exit(1)
+            # Requires --source
+            resolved_source = _resolve_source(source, None)
+            adapter_registry = build_adapter_registry(project_root, read_only=True)
+            exec_result = execute_query(
+                sql_text,
+                variables=vars,
+                source=resolved_source,
+                limit=limit,
+                adapter_registry=adapter_registry,
+            )
+            if json_output:
+                print_json_result(exec_result)
+                if not exec_result.success:
+                    raise SystemExit(1)
+            else:
+                _print_execute_query_rich(exec_result)
+        return
+
+    # For validate/describe modes on named queries, extract SQL from the compiled face.
+    face_source: str | None = None
+    if mode_is_named:
+        assert query_name is not None
+        assert face is not None
+        lr = lookup_face_query_sql(query_name, face, project_root)
+        if not lr.success:
+            _handle_lookup_failure(lr, query_name)
+        sql_text = lr.sql
+        face_source = lr.source
+
+    if validate and describe:
+        # Run validate first; skip describe on error-severity diagnostics.
+        vr = validate_query(
+            sql_text, dialect=dialect, return_suppressed=show_suppressed
+        )
+        # Build the validate payload the same way on both error and success paths.
+        validate_payload: Any = (
+            {"diagnostics": vr.diagnostics, "suppressed": vr.suppressed or []}
+            if show_suppressed
+            else vr.diagnostics
+        )
+        if vr.has_errors:
+            if json_output:
+                typer.echo(json.dumps({"validate": validate_payload}, indent=2))
+            else:
+                _print_validate_result(vr, show_suppressed=show_suppressed)
+            raise typer.Exit(1)
+
+        resolved_source = _resolve_source(source, face_source)
+        adapter_registry = build_adapter_registry(project_root, read_only=True)
+        dr = describe_query(
+            sql_text,
+            source=resolved_source,
+            dialect=dialect,
+            adapter_registry=adapter_registry,
+        )
+
+        if json_output:
+            typer.echo(
+                json.dumps(
+                    {
+                        "validate": validate_payload,
+                        "describe": dr.model_dump(mode="json", exclude_none=True),
+                    },
+                    indent=2,
+                )
+            )
+            if not dr.success:
+                raise typer.Exit(1)
+        else:
+            _print_validate_result(vr, show_suppressed=show_suppressed)
+            _print_describe_result(dr)
+
+    elif validate:
+        vr = validate_query(
+            sql_text, dialect=dialect, return_suppressed=show_suppressed
+        )
+        _print_validate_result(
+            vr, show_suppressed=show_suppressed, json_output=json_output
+        )
+
+    else:  # describe only
+        resolved_source = _resolve_source(source, face_source)
+        adapter_registry = build_adapter_registry(project_root, read_only=True)
+        dr = describe_query(
+            sql_text,
+            source=resolved_source,
+            dialect=dialect,
+            adapter_registry=adapter_registry,
+        )
+        _print_describe_result(dr, json_output=json_output)