dataface 0.1.2__py3-none-any.whl

dataface/cli/commands/describe.py

@@ -0,0 +1,107 @@
+"""describe command — thin wrapper over dataface.agent_api.describe."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import typer
+from rich.table import Table
+
+from dataface.agent_api.describe import DescribeFaceResult
+from dataface.cli._console import dft_console
+from dataface.cli._error_format import print_structured_errors
+
+console = dft_console()
+
+
+def describe_command(
+    paths: list[Path], *, json_output: bool = False, project_dir: Path | None = None
+) -> None:
+    """Describe the structure of one or more face files."""
+    from dataface.agent_api.describe import describe_paths
+
+    results = describe_paths(paths, project_dir=project_dir)
+    _emit(results, json_output=json_output)
+
+
+def _emit(results: list[DescribeFaceResult], *, json_output: 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
+    for r in results:
+        if len(results) > 1:
+            console.rule(str(r.path))
+        if r.errors:
+            has_errors = True
+            print_structured_errors(r.errors)
+            continue
+
+        if r.title:
+            console.print(f"\n[bold]{r.title}[/bold]")
+        if r.description:
+            console.print(f"[dim]{r.description}[/dim]")
+        console.print()
+
+        if r.queries:
+            console.print("[bold]Queries[/bold]")
+            t: Any = Table(
+                show_header=True, header_style="bold", box=None, padding=(0, 2, 0, 0)
+            )
+            t.add_column("Name")
+            t.add_column("Type")
+            t.add_column("Summary")
+            for q in r.queries:
+                t.add_row(q.name, q.type, q.summary)
+            console.print(t)
+            console.print()
+
+        if r.charts:
+            console.print("[bold]Charts[/bold]")
+            t = Table(
+                show_header=True, header_style="bold", box=None, padding=(0, 2, 0, 0)
+            )
+            t.add_column("Name")
+            t.add_column("Type")
+            t.add_column("Query")
+            t.add_column("Encoding")
+            for c in r.charts:
+                enc = ", ".join(f"{k}={v}" for k, v in c.encoding.items())
+                t.add_row(c.name, c.type, c.query, enc)
+            console.print(t)
+            console.print()
+
+        if r.variables:
+            console.print("[bold]Variables[/bold]")
+            t = Table(
+                show_header=True, header_style="bold", box=None, padding=(0, 2, 0, 0)
+            )
+            t.add_column("Name")
+            t.add_column("Type")
+            t.add_column("Default")
+            for v in r.variables:
+                t.add_row(
+                    v.name, v.type, str(v.default) if v.default is not None else ""
+                )
+            console.print(t)
+            console.print()
+
+        if r.layout:
+            console.print("[bold]Layout[/bold]")
+            console.print(f"  {r.layout.primitive}: {', '.join(r.layout.items)}")
+            console.print()
+
+    if has_errors:
+        raise typer.Exit(1)

dataface/cli/commands/docs.py

@@ -0,0 +1,131 @@
+"""CLI command for `dft docs`."""
+
+import typer
+from rich.markdown import Markdown
+from rich.padding import Padding
+from rich.table import Table
+
+from dataface._docs_site import docs_site_url
+from dataface.agent_api.docs import docs as _docs
+from dataface.cli._console import dft_console, is_plain_output
+from dataface.cli._json_output import print_json_result
+
+console = dft_console()
+
+
+def docs_command(
+    topic: str | None,
+    search: str | None,
+    json_output: bool,
+    limit: int,
+) -> None:
+    result = _docs(topic=topic, search=search, limit=limit)
+
+    if json_output:
+        print_json_result(result)
+        if not result.success:
+            raise typer.Exit(1)
+        return
+
+    if not result.success:
+        for err in result.errors:
+            typer.echo(err, err=True)
+        for hint in result.hints:
+            typer.echo(hint, err=True)
+        raise typer.Exit(1)
+
+    if result.mode == "index":
+        _emit_topic_index(result.topics)
+        return
+
+    if result.mode == "search":
+        if not result.search:
+            typer.echo("No results found.")
+            return
+        for hit in result.search:
+            typer.echo(f"{hit.topic}  ({hit.score:.2f})  {hit.snippet}")
+        return
+
+    if result.topic is not None:
+        _emit_markdown(result.topic.content)
+
+
+def _emit_topic_index(topics: list) -> None:
+    if not topics:
+        typer.echo("No topics found.")
+        return
+
+    web_docs = f"{docs_site_url()}/cli/docs/"
+    if not is_plain_output():
+        _emit_topic_index_rich(topics, web_docs)
+    else:
+        _emit_topic_index_plain(topics, web_docs)
+
+
+def _emit_topic_index_rich(topics: list, web_docs: str) -> None:
+    typer.echo(
+        "Dataface (`dft`) is a dbt-native dashboard layer. You author dashboards as "
+        'YAML "faces" — queries, charts, variables, and layout — and `dft` compiles '
+        "and renders them."
+    )
+    typer.echo("")
+    typer.echo(
+        "These docs are the offline YAML language reference bundled with `dft`. "
+        "Every field here is enforced by the compiler — unknown keys are errors."
+    )
+    typer.echo("")
+    console.print(f"Web docs: [link={web_docs}]{web_docs}[/link]")
+    console.print("[dim]Override base URL with DFT_DOCS_URL[/dim]")
+    console.print("")
+    console.print("[bold]Topics[/bold]")
+    console.print(Padding(_topic_table(topics), (0, 0, 0, 2)))
+    console.print("")
+    typer.echo("Next steps")
+    typer.echo("  dft docs <topic>       Read one section with full formatting")
+    typer.echo("  dft docs cheatsheet    One-screen essentials")
+    typer.echo("  dft docs all           Full reference, unsliced")
+    typer.echo('  dft docs -s "<query>"  Search across topics')
+    typer.echo("  dft skills             Agent workflows and layout patterns")
+
+
+def _emit_topic_index_plain(topics: list, web_docs: str) -> None:
+    typer.echo(
+        "Dataface (`dft`) is a dbt-native dashboard layer. You author dashboards as "
+        'YAML "faces" — queries, charts, variables, and layout — and `dft` compiles '
+        "and renders them.\n"
+    )
+    typer.echo(
+        "These docs are the offline YAML language reference bundled with `dft`. "
+        "Every field here is enforced by the compiler — unknown keys are errors.\n"
+    )
+    typer.echo(f"Web docs: {web_docs}")
+    typer.echo("Override base URL with DFT_DOCS_URL\n")
+    typer.echo("Topics")
+    width = max(len(entry.id) for entry in topics)
+    for entry in topics:
+        suffix = f"  {entry.description}" if entry.description else ""
+        typer.echo(f"  {entry.id.ljust(width)}{suffix}")
+    typer.echo("")
+    typer.echo("Next steps")
+    typer.echo("  dft docs <topic>       Read one section")
+    typer.echo("  dft docs cheatsheet    One-screen essentials")
+    typer.echo("  dft docs all           Full reference, unsliced")
+    typer.echo('  dft docs -s "<query>"  Search across topics')
+    typer.echo("  dft skills             Agent workflows and layout patterns")
+
+
+def _topic_table(topics: list) -> Table:
+    name_width = max(len(entry.id) for entry in topics)
+    table = Table(show_header=False, box=None, padding=(0, 2, 0, 0))
+    table.add_column("Topic", style="bold", no_wrap=True, width=name_width)
+    table.add_column("Description", overflow="fold")
+    for entry in topics:
+        table.add_row(entry.id, entry.description)
+    return table
+
+
+def _emit_markdown(content: str) -> None:
+    if not is_plain_output():
+        console.print(Markdown(content))
+    else:
+        typer.echo(content, nl=False)

dataface/cli/commands/extension.py

@@ -0,0 +1,179 @@
+"""Install the Dataface VS Code / Cursor extension.
+
+The extension is currently distributed as a `.vsix` via GitHub Releases on
+the (private) ``fivetran/dataface`` repo, tagged ``vscode-ext-v*``.
+Marketplace publish is gated on M3 launch criteria. ``dft init code`` (and
+``dft init cursor``):
+
+1. Uses ``gh`` (the user's authenticated GitHub CLI — required for private
+   repo asset downloads) to find the latest ``vscode-ext-v*`` release and
+   download its ``.vsix``.
+2. Runs ``code --install-extension <path>`` (or
+   ``cursor --install-extension <path>``).
+
+Once the extension is on the Marketplace, the implementation will switch to
+``code --install-extension dataface.dataface`` (a one-line change) and
+the ``gh`` requirement goes away.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import tempfile
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+REPO = "fivetran/dataface"
+RELEASES_HTML = f"https://github.com/{REPO}/releases"
+TAG_PREFIX = "vscode-ext-v"
+
+# Editor name → CLI binary on PATH.
+EDITORS: dict[str, str] = {
+    "code": "code",
+    "vscode": "code",  # alias
+    "cursor": "cursor",
+}
+
+
+@dataclass(frozen=True)
+class ReleaseAsset:
+    tag: str
+    version: str
+    vsix_name: str
+
+
+def _gh_available() -> bool:
+    return shutil.which("gh") is not None
+
+
+def _latest_vsix_release() -> ReleaseAsset | None:
+    """Return the most recent vscode-ext-v* release with a .vsix asset.
+
+    Uses `gh api` for authenticated access (private repo). Returns None if
+    `gh` is missing, the user isn't authenticated, or no matching release
+    exists.
+    """
+    if not _gh_available():
+        return None
+    try:
+        proc = subprocess.run(
+            [
+                "gh",
+                "api",
+                f"repos/{REPO}/releases?per_page=20",
+            ],
+            capture_output=True,
+            text=True,
+            timeout=15,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if proc.returncode != 0:
+        return None
+    try:
+        releases = json.loads(proc.stdout)
+    except ValueError:
+        return None
+    if not isinstance(releases, list):
+        return None
+    for release in releases:
+        tag = release.get("tag_name", "")
+        if not tag.startswith(TAG_PREFIX):
+            continue
+        for asset in release.get("assets") or []:
+            name = asset.get("name", "")
+            if name.endswith(".vsix"):
+                return ReleaseAsset(
+                    tag=tag,
+                    version=tag.removeprefix(TAG_PREFIX),
+                    vsix_name=name,
+                )
+    return None
+
+
+def install_extension(editor: str, emit: Callable[[str], None] = print) -> int:
+    """Auto-install the latest VSIX into the named editor.
+
+    Returns shell-style exit code: 0 on success, non-zero on failure.
+    ``editor`` is one of ``EDITORS`` keys (``code``, ``vscode``, ``cursor``).
+    """
+    cli = EDITORS.get(editor.lower())
+    if cli is None:
+        emit(f"Unknown editor '{editor}'. Supported: {', '.join(sorted(EDITORS))}.")
+        return 2
+
+    binary = shutil.which(cli)
+    if binary is None:
+        emit(
+            f"'{cli}' not found on PATH — install the editor first, or open\n"
+            f"{cli} once and enable its shell command from the command palette."
+        )
+        return 1
+
+    if not _gh_available():
+        emit(
+            "`gh` (GitHub CLI) is required to download the .vsix from the\n"
+            f"private {REPO} repo. Install it (https://cli.github.com) and\n"
+            "run `gh auth login`, then retry."
+        )
+        return 1
+
+    release = _latest_vsix_release()
+    if release is None:
+        emit(
+            f"Could not find a vscode-ext-v* release with a .vsix asset on {REPO}.\n"
+            f"Browse {RELEASES_HTML} or build from source via\n"
+            "`apps/ide/vscode-extension/justfile`'s `vsix` recipe."
+        )
+        return 1
+
+    with tempfile.TemporaryDirectory(prefix="dft-ext-") as tmpdir:
+        vsix_path = Path(tmpdir) / release.vsix_name
+        emit(f"Downloading {release.vsix_name} from {release.tag}…")
+        try:
+            dl = subprocess.run(
+                [
+                    "gh",
+                    "release",
+                    "download",
+                    release.tag,
+                    "--repo",
+                    REPO,
+                    "--pattern",
+                    release.vsix_name,
+                    "--output",
+                    str(vsix_path),
+                ],
+                capture_output=True,
+                text=True,
+                timeout=60,
+            )
+        except subprocess.TimeoutExpired:
+            emit("  gh release download timed out after 60s.")
+            return 1
+        if dl.returncode != 0:
+            for line in (dl.stderr or "").rstrip().splitlines():
+                emit(f"  {line}")
+            return dl.returncode
+        emit(f"Installing into {cli}…")
+        try:
+            result = subprocess.run(
+                [binary, "--install-extension", str(vsix_path)],
+                capture_output=True,
+                text=True,
+                timeout=60,
+            )
+        except subprocess.TimeoutExpired:
+            emit(f"  {cli} --install-extension timed out after 60s.")
+            return 1
+        for line in (result.stdout or "").rstrip().splitlines():
+            emit(f"  {line}")
+        if result.returncode != 0:
+            for line in (result.stderr or "").rstrip().splitlines():
+                emit(f"  {line}")
+            return result.returncode
+        emit(f"✓ Installed Dataface {release.version} in {cli}.")
+        return 0

dataface/cli/commands/init.py

@@ -0,0 +1,240 @@
+"""Init command — wizard that bootstraps a Dataface project."""
+
+from __future__ import annotations
+
+import shutil
+import sys
+from pathlib import Path
+
+import typer
+
+from dataface.agent_api._project_agents_md import has_dataface_markers
+from dataface.agent_api.init import init_project
+
+
+def _resolve(
+    flag: bool | None,
+    yes: bool,
+    prompt: str,
+    default: bool,
+) -> bool:
+    """Resolve a wizard question: explicit flag > yes/non-TTY default > prompt."""
+    if flag is not None:
+        return flag
+    if yes or not sys.stdin.isatty():
+        return default
+    return typer.confirm(prompt, default=default)
+
+
+def run_wizard(
+    *,
+    project_dir: Path | None,
+    force: bool,
+    yes: bool,
+    agents_md: bool | None,
+    claude_md: bool | None,
+    skills: bool | None,
+    mcp: bool | None,
+    chat_extra: bool | None,
+    with_playground: bool | None,
+    vscode: bool | None,
+    cursor: bool | None,
+) -> None:
+    """Run the dft init wizard: prompt, scaffold, dispatch opt-ins."""
+    root = (project_dir or Path(".")).resolve()
+
+    # Detection-aware AGENTS.md prompt
+    agents_md_path = root / "AGENTS.md"
+    if not agents_md_path.exists():
+        agents_md_prompt = (
+            "Create AGENTS.md at the project root with Dataface instructions?"
+        )
+    elif has_dataface_markers(agents_md_path.read_text()):
+        agents_md_prompt = "Refresh the Dataface section in AGENTS.md?"
+    else:
+        agents_md_prompt = "Append Dataface instructions to your existing AGENTS.md?"
+
+    do_agents_md = _resolve(agents_md, yes=yes, prompt=agents_md_prompt, default=True)
+
+    # CLAUDE.md — skip prompt entirely if file already exists (never overwrite)
+    claude_md_path = root / "CLAUDE.md"
+    if claude_md_path.exists():
+        do_claude_md = False
+    else:
+        do_claude_md = _resolve(
+            claude_md,
+            yes=yes,
+            prompt="Create CLAUDE.md (one-line @AGENTS.md pointer for Claude Code)?",
+            default=True,
+        )
+
+    from dataface.agent_api import skill_install
+
+    will_have_skill_markers = (
+        do_agents_md or do_claude_md or bool(skill_install.detect_skill_targets(root))
+    )
+    if skills is not None:
+        do_skills = skills
+    elif will_have_skill_markers:
+        do_skills = _resolve(
+            None,
+            yes=yes,
+            prompt="Install Dataface workflow skills for AI assistants?",
+            default=True,
+        )
+    else:
+        do_skills = False
+
+    # MCP
+    do_mcp = _resolve(
+        mcp,
+        yes=yes,
+        prompt="Set up the Dataface MCP server for AI assistants?",
+        default=True,
+    )
+
+    # Chat extra — skip prompt if already installed
+    from dataface.cli._extras import _missing_packages
+
+    if not _missing_packages("chat"):
+        do_chat_extra = False
+    else:
+        do_chat_extra = _resolve(
+            chat_extra,
+            yes=yes,
+            prompt="Install the dataface[chat] extra now (so 'dft chat' works without prompting later)?",
+            default=True,
+        )
+
+    # Playground extra — skip prompt if already installed
+    if not _missing_packages("playground"):
+        do_with_playground = False
+    else:
+        do_with_playground = _resolve(
+            with_playground,
+            yes=yes,
+            prompt="Install the dataface[playground] extra now (so 'dft playground' works without prompting later)?",
+            default=True,
+        )
+
+    # IDE detection — only prompt for IDEs found on PATH
+    code_found = shutil.which("code") is not None
+    cursor_found = shutil.which("cursor") is not None
+
+    if vscode is not None:
+        do_vscode = vscode
+    elif code_found:
+        do_vscode = _resolve(
+            None,
+            yes=yes,
+            prompt="Install the Dataface extension into VS Code?",
+            default=True,
+        )
+    else:
+        do_vscode = False
+
+    if cursor is not None:
+        do_cursor = cursor
+    elif cursor_found:
+        do_cursor = _resolve(
+            None,
+            yes=yes,
+            prompt="Install the Dataface extension into Cursor?",
+            default=True,
+        )
+    else:
+        do_cursor = False
+
+    if not code_found and not cursor_found and vscode is None and cursor is None:
+        typer.echo(
+            "  VS Code / Cursor not found on PATH; skipping extension install. "
+            "Run 'dft init code' or 'dft init cursor' later if you install one."
+        )
+
+    # Core scaffold
+    result = init_project(
+        project_dir=root,
+        force=force,
+        write_agents_md=do_agents_md,
+        write_claude_md=do_claude_md,
+        eject_inspect=False,
+    )
+
+    # Output scaffold results
+    if result.dbt_detected:
+        typer.echo(f"  dbt project detected: {result.project_dir / 'dbt_project.yml'}")
+    for f in result.created_files:
+        typer.echo(f"  created {f}")
+    for f in result.refreshed_files:
+        typer.echo(f"  refreshed {f}")
+    for f in result.appended_files:
+        typer.echo(f"  appended {f}")
+    for f in result.skipped_files:
+        typer.echo(f"  skipped {f} (already exists)")
+    for hint in result.hints:
+        typer.echo(f"\n  Tip: {hint}")
+
+    # Opt-in dispatches
+    install_warnings: list[str] = []
+
+    if do_skills:
+        from dataface.cli.commands import skills_init
+
+        skills_init.run_init_skills(
+            target=None,
+            all_targets=False,
+            dir_override=None,
+            force=force,
+            check=False,
+            project_dir=root,
+        )
+
+    if do_mcp:
+        from dataface.cli.commands import mcp_init
+
+        mcp_init.run_init(
+            client=None,
+            all_clients=False,
+            force=False,
+            project_dir=root,
+        )
+
+    if do_chat_extra:
+        from dataface.cli._extras import install_extras
+
+        install_extras("chat", interactive=False)
+
+    if do_with_playground:
+        from dataface.cli._extras import install_extras
+
+        install_extras("playground", interactive=False)
+
+    if do_vscode:
+        from dataface.cli.commands import extension as extension_cmd
+
+        rc = extension_cmd.install_extension("code", emit=typer.echo)
+        if rc != 0:
+            install_warnings.append(
+                "VS Code extension install failed (see output above)."
+            )
+
+    if do_cursor:
+        from dataface.cli.commands import extension as extension_cmd
+
+        rc = extension_cmd.install_extension("cursor", emit=typer.echo)
+        if rc != 0:
+            install_warnings.append(
+                "Cursor extension install failed (see output above)."
+            )
+
+    # Final success block
+    typer.echo("")
+    for warning in install_warnings:
+        typer.echo(f"  Warning: {warning}")
+    if install_warnings:
+        typer.echo("")
+    typer.echo(
+        "  You're all set. Your project has a faces/ directory with a starter dashboard."
+    )
+    typer.echo("")
+    typer.echo("  Run `dft serve` to preview it in your browser.")