dataface 0.1.2__py3-none-any.whl

dataface/cli/commands/search.py

@@ -0,0 +1,49 @@
+"""CLI command for `dft search`."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from dataface.agent_api.search import SearchResult, search_dashboards
+
+
+def search_command(
+    query: str,
+    json_output: bool = False,
+    limit: int = 10,
+    project_dir: Path | None = None,
+) -> None:
+    """Search dashboards by keyword with ranked results."""
+    result = search_dashboards(
+        query=query,
+        project_dir=(project_dir or Path(".")).resolve(),
+        limit=limit,
+    )
+
+    if json_output:
+        typer.echo(result.model_dump_json(indent=2, exclude_none=True))
+        if not result.success:
+            raise typer.Exit(1)
+        return
+
+    _print_rich(result)
+    if not result.success:
+        raise typer.Exit(1)
+
+
+def _print_rich(result: SearchResult) -> None:
+    if not result.success:
+        for e in result.errors:
+            typer.echo(f"Error: {e}", err=True)
+        return
+
+    if not result.results:
+        typer.echo("No results found.")
+        return
+
+    for hit in result.results:
+        typer.echo(f"  [{hit.match_score:.2f}] {hit.title}  {hit.source_path}")
+        if hit.summary:
+            typer.echo(f"           {hit.summary}")

dataface/cli/commands/serve.py

@@ -0,0 +1,114 @@
+"""Serve command implementation."""
+
+import os
+import sys
+from pathlib import Path
+
+import typer
+import uvicorn
+
+
+def serve_command(
+    port: int | None = None,
+    host: str = "localhost",
+    project_dir: Path | None = None,
+    connection: str | None = None,
+    dialect: str | None = None,
+    target: str | None = None,
+) -> None:
+    """Start unified Dataface server.
+
+    This command starts a FastAPI server that serves:
+    - Profile templates at /profile/{template}/?model=X&column=Y
+    - Any face file at /{path}/?var=value (path.yml → /path/)
+    - Health check at /health
+
+    Example URLs:
+        http://localhost:9876/health
+        http://localhost:9876/profile/model/?model=fct_orders&theme=dark
+        http://localhost:9876/profile/numeric_column/?model=fct_orders&column=revenue
+        http://localhost:9876/sales/?region=West
+
+    Args:
+        port: Port number to serve on (auto-resolved if not specified)
+        host: Host address to bind to
+        project_dir: Project directory for resolving face file paths
+        connection: Database connection string
+        dialect: SQL dialect (auto-detected from dbt profile, or duckdb)
+        target: dbt target name (defaults to DBT_TARGET env var, then profile default)
+
+    Returns:
+        None (exits with code 0 on success, 1 on errors)
+    """
+    from dataface.core.project_roots import (
+        discover_project_root,
+        infer_dialect_from_dbt,
+    )
+    from dataface.core.serve.bootstrap import apply_default_theme_from_env
+    from dataface.core.serve.port import resolve_port
+    from dataface.core.serve.server import create_server
+
+    # Discover project root when not explicitly provided
+    resolved_dir = project_dir if project_dir else discover_project_root()
+
+    # Apply DFT_DEFAULT_THEME before anything else — fails fast on invalid names.
+    try:
+        apply_default_theme_from_env()
+    except ValueError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1) from None
+
+    # Resolve port: --port > DFT_PORT > dataface.yml > hash(project_dir)
+    port = resolve_port(
+        explicit_port=port,
+        project_dir=resolved_dir,
+        host=host,
+    )
+
+    # Resolve dbt target: CLI flag > DBT_TARGET env > profile default
+    effective_target = target or os.environ.get("DBT_TARGET") or None
+
+    # Infer dialect from dbt profile when not explicitly provided
+    effective_dialect = dialect
+    if effective_dialect is None:
+        inferred = infer_dialect_from_dbt(resolved_dir, effective_target)
+        if inferred:
+            typer.echo(f"  Auto-detected dialect: {inferred} (from dbt profile)")
+        effective_dialect = inferred or "duckdb"
+
+    # Create FastAPI app
+    app = create_server(
+        project_dir=resolved_dir,
+        connection=connection,
+        dialect=effective_dialect,
+        target=effective_target,
+    )
+
+    # Start server
+    typer.echo("🚀 Starting dashboard server")
+    typer.echo(f"   URL: http://{host}:{port}")
+    typer.echo(f"   Health: http://{host}:{port}/health")
+    typer.echo("")
+    typer.echo("   Routes:")
+    typer.echo(f"     http://{host}:{port}/profile/model/?model=<table>")
+    typer.echo(
+        f"     http://{host}:{port}/profile/numeric_column/?model=<table>&column=<col>"
+    )
+    typer.echo(f"     http://{host}:{port}/<name>/?var=value")
+    typer.echo("")
+    typer.echo("   Press CTRL+C to stop")
+
+    try:
+        uvicorn.run(
+            app,
+            host=host,
+            port=port,
+            log_level="info",
+            timeout_graceful_shutdown=3,
+        )
+    except KeyboardInterrupt:
+        typer.echo("\n👋 Server stopped")
+        sys.exit(0)
+    except Exception as e:  # noqa: BLE001
+        typer.echo(f"Error starting server: {e}", err=True)
+        raise typer.Exit(1) from None

dataface/cli/commands/skills.py

@@ -0,0 +1,133 @@
+"""Skills command — thin wrapper over dataface.agent_api.skills."""
+
+from __future__ import annotations
+
+import sys
+
+import typer
+from rich.padding import Padding
+from rich.table import Table
+
+from dataface.agent_api import skills as _api
+from dataface.cli._console import dft_console
+from dataface.cli._json_output import print_json_result
+
+err_console = dft_console(stderr=True)
+
+
+def skills_command(
+    name: str | None = None,
+    search: str | None = None,
+    limit: int = 10,
+    as_json: bool = False,
+) -> None:
+    """List packaged agent skills, search them, or show one by name — selected from the input args."""
+    if name is not None and search is not None:
+        err_console.print(
+            "[red]Error:[/red] cannot combine a skill name with --search; use one or the other."
+        )
+        raise typer.Exit(1)
+
+    if search is not None:
+        result = _api.search_skills(search, limit=limit, surface="cli")
+        if as_json:
+            print_json_result(result)
+            return
+        _print_search_results(result)
+        return
+
+    if name is None:
+        listing = _api.list_skills(surface="cli")
+        if as_json:
+            print_json_result(listing)
+            return
+        _print_skills_table(listing)
+        return
+
+    try:
+        skill = _api.get_skill(name, surface="cli")
+    except _api.SkillNotFound as exc:
+        print(str(exc), file=sys.stderr)
+        sys.exit(1)
+    if as_json:
+        print_json_result(skill)
+    else:
+        print(skill.body)
+
+
+def _print_skills_table(result: _api.SkillList) -> None:
+    if not result.skills:
+        typer.echo("No skills available.")
+        return
+
+    console = dft_console()
+
+    workflows = [s for s in result.skills if s.kind == "workflow"]
+    patterns = [s for s in result.skills if s.kind == "pattern"]
+
+    typer.echo(
+        "Agent skills — workflows and layout patterns for building Dataface dashboards."
+    )
+    typer.echo("YAML field reference is `dft docs`, not skills.\n")
+
+    name_width = max(len(s.name) for s in result.skills)
+
+    if workflows:
+        console.print("[bold]Workflows[/bold]")
+        console.print(Padding(_skill_table(workflows, name_width), (0, 0, 0, 2)))
+        console.print()
+
+    if patterns:
+        console.print("[bold]Patterns[/bold]")
+        console.print(Padding(_skill_table(patterns, name_width), (0, 0, 0, 2)))
+        console.print()
+
+    typer.echo("Next steps")
+    typer.echo(
+        "  dft skills <name>  Read the full skill body and copy the example YAML"
+    )
+    typer.echo("  dft docs           YAML syntax reference")
+    typer.echo("")
+    typer.echo('Find a skill: dft skills -s "<query>"')
+    typer.echo('YAML syntax:  dft docs -s "<query>"')
+
+
+def _skill_table(skills: list[_api.Skill], name_width: int) -> Table:
+    t = Table(show_header=False, box=None, padding=(0, 2, 0, 0))
+    t.add_column("Name", style="bold", no_wrap=True, width=name_width)
+    t.add_column("Description", overflow="fold")
+    for skill in skills:
+        suffix = r"  [dim]\[scaffold][/dim]" if skill.has_examples else ""
+        t.add_row(skill.name, f"{_first_sentence(skill.description)}{suffix}")
+    return t
+
+
+def _print_search_results(result: _api.SkillSearchResult) -> None:
+    if not result.hits:
+        typer.echo(f'Agent skills — search results for "{result.query}"\n')
+        typer.echo(
+            'No skills matched. Try `dft skills -s "kpi"` or `dft skills` (full list).'
+        )
+        return
+
+    console = dft_console()
+    typer.echo(f'Agent skills — search results for "{result.query}"\n')
+    for hit in result.hits:
+        scaffold = r" \[scaffold]" if hit.has_examples else ""
+        console.print(
+            f"  [bold]{hit.name}[/bold] \\[{hit.kind}]{scaffold}  "
+            f"[dim]score {hit.score:.2f}[/dim]"
+        )
+        console.print(f"    {_first_sentence(hit.description)}")
+    typer.echo("")
+    typer.echo(
+        f"{len(result.hits)} matches. "
+        "Read one: `dft skills <name>` — copy the example YAML directly."
+    )
+
+
+def _first_sentence(text: str) -> str:
+    """Collapse a YAML block-scalar description to a single sentence."""
+    flat = " ".join(text.split())
+    head, sep, _ = flat.partition(".")
+    return head + sep if sep else flat

dataface/cli/commands/skills_init.py

@@ -0,0 +1,161 @@
+"""`dft init skills` thin wrapper: parse args, call agent_api.skill_install."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from dataface.agent_api import skill_install
+from dataface.core.project_roots import find_dataface_project, find_git_root
+
+_VALID_TARGETS = skill_install.SKILL_INSTALL_TARGETS
+
+
+def _resolve_project_dir(start: Path) -> Path:
+    """Return the directory where skills should be installed.
+
+    Skills are agent tooling that belong at the git root, not the operational
+    project root. When a .git directory exists above the dataface.yml, install
+    at the git root so monorepos with nested dataface projects don't accumulate
+    divergent skill copies.
+    """
+    project_root = find_dataface_project(start)
+    if project_root is None:
+        project_root = start.resolve()
+    git_root = find_git_root(project_root)
+    if git_root is not None:
+        return git_root
+    return project_root
+
+
+def _resolve_targets(
+    target: str | None,
+    *,
+    all_targets: bool,
+    dir_override: Path | None,
+    project_root: Path,
+) -> list[Path]:
+    if dir_override is not None:
+        return [dir_override.resolve()]
+
+    if target is not None:
+        key = target.lower()
+        if key not in _VALID_TARGETS:
+            typer.echo(
+                f"Unknown target: {target}. "
+                f"Supported: {', '.join(sorted(_VALID_TARGETS))}",
+                err=True,
+            )
+            raise typer.Exit(1)
+        return [skill_install.target_dir_for(key, project_root=project_root)]
+
+    detected = skill_install.detect_skill_targets(project_root)
+    if all_targets:
+        if not detected:
+            typer.echo(
+                "No agent skill targets detected (.cursor/, AGENTS.md, CLAUDE.md).\n"
+                "Pass an explicit target: dft init skills agents | claude",
+                err=True,
+            )
+            raise typer.Exit(1)
+        keys = detected
+    elif detected:
+        keys = detected
+    else:
+        typer.echo(
+            "No agent skill targets detected (.cursor/, AGENTS.md, CLAUDE.md).\n"
+            "Specify a target or pass --dir:\n"
+            "  dft init skills agents\n"
+            "  dft init skills claude\n"
+            "  dft init skills --all\n"
+            "  dft init skills --dir .agents/skills",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    return [skill_install.target_dir_for(k, project_root=project_root) for k in keys]
+
+
+def _format_legacy_note(legacy_dirs: list[Path], project_root: Path) -> str | None:
+    if not legacy_dirs:
+        return None
+    first = legacy_dirs[0]
+    try:
+        rel = first.relative_to(project_root)
+    except ValueError:
+        rel = first
+    return (
+        f"Legacy skill install detected at {rel} — "
+        "re-run `dft init skills agents` and remove the legacy dir manually."
+    )
+
+
+def run_init_skills(
+    target: str | None,
+    all_targets: bool,
+    dir_override: Path | None,
+    force: bool,
+    check: bool,
+    project_dir: Path | None = None,
+) -> None:
+    """Shared implementation for ``dft init skills``."""
+    if target is not None and (all_targets or dir_override is not None):
+        typer.echo(
+            "Specify one of: a target name, --all, or --dir — not combined.",
+            err=True,
+        )
+        raise typer.Exit(1)
+    if all_targets and dir_override is not None:
+        typer.echo("Specify either --all or --dir, not both.", err=True)
+        raise typer.Exit(1)
+
+    project_root = _resolve_project_dir(
+        project_dir if project_dir is not None else Path.cwd()
+    )
+    target_dirs = _resolve_targets(
+        target,
+        all_targets=all_targets,
+        dir_override=dir_override,
+        project_root=project_root,
+    )
+
+    prefix = "Would install" if check else "Installed"
+    any_legacy = False
+    for target_dir in target_dirs:
+        result = skill_install.install_skills(
+            target_dir=target_dir,
+            project_root=project_root,
+            force=force,
+            check=check,
+        )
+        try:
+            rel = target_dir.relative_to(project_root)
+        except ValueError:
+            rel = target_dir
+        if result.installed:
+            typer.echo(f"  {prefix} workflow skills ({len(result.installed)}) → {rel}/")
+            for name in sorted(result.installed):
+                typer.echo(f"    ✓ {name}")
+        elif result.skipped_existing:
+            typer.echo(
+                f"  Workflow skills unchanged ({len(result.skipped_existing)})"
+                f" → {rel}/"
+            )
+        if result.retired_removed:
+            typer.echo(f"  Removed retired: {', '.join(result.retired_removed)}")
+        if result.skipped_existing:
+            typer.echo(f"  Unchanged (identical): {', '.join(result.skipped_existing)}")
+        legacy_note = _format_legacy_note(result.legacy_dirs_detected, project_root)
+        if legacy_note:
+            any_legacy = True
+            typer.echo(f"  {legacy_note}")
+
+    if check:
+        typer.echo("")
+        typer.echo("  Dry run — no files written.")
+    elif any_legacy:
+        typer.echo("")
+        typer.echo(
+            "  Re-run after removing legacy .cursor/skills or .codex/skills dirs."
+        )

dataface/cli/commands/validate.py

@@ -0,0 +1,63 @@
+"""validate command — thin wrapper over dataface.agent_api.validate."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from dataface.agent_api.validate import ValidateResult
+from dataface.cli._console import dft_console
+from dataface.cli._error_format import print_render_warnings, print_structured_errors
+
+_console = dft_console()
+
+
+def validate_command(
+    paths: list[Path] | None,
+    project_dir: Path | None = None,
+    json_output: bool = False,
+    strict: bool = False,
+) -> None:
+    from dataface.agent_api.validate import validate_paths
+
+    results = validate_paths(paths, project_dir=project_dir)
+    _emit(results, json_output=json_output, strict=strict)
+
+
+def _emit(
+    results: list[ValidateResult],
+    *,
+    json_output: bool,
+    strict: bool,
+) -> None:
+    if json_output:
+        if len(results) == 1:
+            typer.echo(results[0].model_dump_json(exclude_none=True, indent=2))
+        else:
+            typer.echo(
+                json.dumps(
+                    [r.model_dump(mode="json", exclude_none=True) for r in results],
+                    indent=2,
+                )
+            )
+        has_errors = any(r.errors for r in results)
+        raise typer.Exit(0 if not has_errors else 1)
+
+    has_errors = False
+    has_warnings = False
+    for r in results:
+        if r.errors:
+            has_errors = True
+            print_structured_errors(r.errors)
+        if r.warnings:
+            has_warnings = True
+            print_render_warnings(r.warnings, path=r.path)
+        if not r.errors and not r.warnings:
+            _console.print(f"✓ {r.path} OK")
+
+    if has_errors:
+        raise typer.Exit(1)
+    if strict and has_warnings:
+        raise typer.Exit(1)