dataface 0.1.2__py3-none-any.whl

dataface/agent_api/file_refs.py

@@ -0,0 +1,118 @@
+"""File-ref expansion for Dataface agent surfaces.
+
+Scans a prompt for @<path> tokens and inlines matching file contents.
+Reusable from any surface: CLI, Cloud chat, MCP tools, IDE clients.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from pydantic import BaseModel
+
+_AT_REF_RE = re.compile(r"(?<![\w.])@(?P<path>[\w./-]+)")
+_MAX_INLINE_BYTES = 200 * 1024
+_STUB_LINES = 50
+_STUB_HEAD_BYTES = 64 * 1024
+
+
+class FileRef(BaseModel):
+    token: str  # original @token (e.g. "@faces/foo.yml")
+    path: Path  # resolved absolute path
+
+
+class ExpandedPrompt(BaseModel):
+    text: str
+    references: list[FileRef]
+
+
+def _has_dotdot(path_str: str) -> bool:
+    return any(seg == ".." for seg in path_str.split("/"))
+
+
+def _fenced(text: str) -> str:
+    longest = run = 0
+    for ch in text:
+        if ch == "`":
+            run += 1
+            longest = max(longest, run)
+        else:
+            run = 0
+    fence = "`" * max(3, longest + 1)
+    return f"{fence}\n{text}\n{fence}"
+
+
+def _inline(path_str: str, project_dir: Path) -> tuple[str, Path] | None:
+    """Return (replacement_text, resolved_path) or None if token is unresolvable."""
+    if _has_dotdot(path_str):
+        return None
+
+    resolved = (project_dir / path_str).resolve()
+    try:
+        resolved.relative_to(project_dir.resolve())
+    except ValueError:
+        return None
+
+    if not resolved.exists() or not resolved.is_file():
+        return None
+
+    try:
+        size = resolved.stat().st_size
+    except OSError:
+        return None
+
+    if size > _MAX_INLINE_BYTES:
+        try:
+            with resolved.open("rb") as f:
+                head_bytes = f.read(_STUB_HEAD_BYTES)
+        except OSError:
+            return None
+        try:
+            head_text = head_bytes.decode("utf-8")
+        except UnicodeDecodeError:
+            return None
+        head_lines = head_text.splitlines()
+        truncated = "\n".join(head_lines[:_STUB_LINES])
+        if size <= len(head_bytes):
+            line_count = len(head_lines)
+        else:
+            avg_line_bytes = max(1, len(head_bytes) // max(1, len(head_lines)))
+            line_count = size // avg_line_bytes
+        header = (
+            f"(@{path_str}: {size // 1024} KB, ~{line_count} lines,"
+            f" first {_STUB_LINES} lines below)"
+        )
+        return f"{header}\n{_fenced(truncated)}", resolved
+
+    try:
+        text = resolved.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return None
+
+    return _fenced(text), resolved
+
+
+def expand_file_refs(message: str, *, project_dir: Path) -> ExpandedPrompt:
+    """Replace @<path> tokens in *message* with file contents.
+
+    Tokens that cannot be resolved (out of project_dir, non-existent, binary,
+    dotdot traversal) are left as-is and not recorded in references.
+    """
+    references: list[FileRef] = []
+
+    def replace(match: re.Match[str]) -> str:
+        full_match = match.group(0)
+        path_str = match.group("path").rstrip(".")
+        if not path_str:
+            return full_match
+        suffix = full_match[1 + len(path_str) :]
+        result = _inline(path_str, project_dir)
+        if result is None:
+            return full_match
+        replacement, resolved_path = result
+        references.append(FileRef(token=f"@{path_str}", path=resolved_path))
+        return replacement + suffix
+
+    text = _AT_REF_RE.sub(replace, message)
+    return ExpandedPrompt(text=text, references=references)

dataface/agent_api/init.py

@@ -0,0 +1,126 @@
+"""Bootstrap (or refresh) a Dataface project layout."""
+
+from __future__ import annotations
+
+import importlib.resources
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from dataface.agent_api._project_agents_md import (
+    load_agents_snippet,
+    merge_agents_snippet,
+)
+
+GITIGNORE_ENTRIES = ("renders/", ".venv/", "__pycache__/", "*.duckdb")
+
+_TEMPLATES = importlib.resources.files("dataface.agent_api._init_templates")
+
+
+class InitResult(BaseModel):
+    project_dir: Path
+    dbt_detected: bool
+    created_files: list[Path] = []
+    skipped_files: list[Path] = []
+    refreshed_files: list[Path] = []
+    appended_files: list[Path] = []
+    hints: list[str] = []
+
+
+def init_project(
+    project_dir: Path | None = None,
+    *,
+    force: bool = False,
+    write_agents_md: bool = True,
+    write_claude_md: bool = True,
+    eject_inspect: bool = False,
+) -> InitResult:
+    """Bootstrap (or refresh) a Dataface project layout.
+
+    Safe to re-run: scaffold files are skipped unless *force* is set.
+    AGENTS.md: appends a short Dataface blurb when the file already exists;
+    creates the blurb alone when missing. Re-run refreshes only the marked
+    ``<!-- dft-dataface:* -->`` section. CLAUDE.md is create-only.
+    """
+    root = (project_dir or Path(".")).resolve()
+    dbt_detected = (root / "dbt_project.yml").exists()
+
+    result = InitResult(project_dir=root, dbt_detected=dbt_detected)
+
+    (root / "faces").mkdir(exist_ok=True)
+    (root / "faces" / "partials").mkdir(exist_ok=True)
+
+    scaffolds: list[tuple[str, str]] = [
+        ("dataface.yml", _TEMPLATES.joinpath("dataface.yml").read_text()),
+        ("faces/index.md", _TEMPLATES.joinpath("index.md").read_text()),
+        ("faces/dataface.yml", _TEMPLATES.joinpath("faces-dataface.yml").read_text()),
+        ("faces/partials/.gitkeep", ""),
+    ]
+
+    for rel, content in scaffolds:
+        target = root / rel
+        if target.exists() and not force:
+            result.skipped_files.append(Path(rel))
+        elif target.exists():
+            target.write_text(content)
+            result.refreshed_files.append(Path(rel))
+        else:
+            target.write_text(content)
+            result.created_files.append(Path(rel))
+
+    _ensure_gitignore_entries(root, result)
+
+    if write_agents_md:
+        snippet = load_agents_snippet()
+        agents_md_path = root / "AGENTS.md"
+        existing: str | None = (
+            agents_md_path.read_text() if agents_md_path.exists() else None
+        )
+        final_text, action = merge_agents_snippet(existing, snippet)
+        agents_md_path.write_text(final_text)
+        if action == "created":
+            result.created_files.append(Path("AGENTS.md"))
+        elif action == "refreshed":
+            result.refreshed_files.append(Path("AGENTS.md"))
+        else:
+            result.appended_files.append(Path("AGENTS.md"))
+
+    if write_claude_md:
+        claude_md_path = root / "CLAUDE.md"
+        if not claude_md_path.exists():
+            claude_md_path.write_text("@AGENTS.md\n")
+            result.created_files.append(Path("CLAUDE.md"))
+
+    if eject_inspect:
+        from dataface.agent_api import inspect as _api_inspect
+
+        try:
+            ejected = _api_inspect.eject_templates(
+                root / "faces" / "inspect", templates=None, force=False
+            )
+            result.created_files.extend(p.relative_to(root) for p in ejected)
+        except (FileNotFoundError, ModuleNotFoundError) as exc:
+            result.hints.append(
+                f"warning: inspect templates could not be ejected ({exc!r}); "
+                "your install may be partial. Run 'pip show dataface' to verify."
+            )
+
+    return result
+
+
+def _ensure_gitignore_entries(root: Path, result: InitResult) -> None:
+    gitignore = root / ".gitignore"
+    if not gitignore.exists():
+        gitignore.write_text("\n".join(GITIGNORE_ENTRIES) + "\n")
+        result.created_files.append(Path(".gitignore"))
+        return
+
+    text = gitignore.read_text()
+    existing = set(text.splitlines())
+    missing = [e for e in GITIGNORE_ENTRIES if e not in existing]
+    if not missing:
+        return
+
+    separator = "" if not text or text.endswith("\n") else "\n"
+    gitignore.write_text(f"{text}{separator}" + "\n".join(missing) + "\n")
+    result.refreshed_files.append(Path(".gitignore"))

dataface/agent_api/inspect.py

@@ -0,0 +1,128 @@
+"""Inspect template-management verbs (OSS).
+
+Profiler verbs (inspect_table, inspect_all, audit_tables, bake_schema_metadata)
+live in the private ``dataface-super-schema`` package and are exposed via the
+CLI entry-point plugin. This module ships the template-management verbs that
+belong in the OSS wheel: list, eject, validate.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from hashlib import sha256
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from dataface import __version__
+from dataface.core.inspect import INSPECT_TEMPLATES
+from dataface.core.inspect.manifest_utils import (
+    INSPECT_TEMPLATE_MANIFEST,
+    MANIFEST_SCHEMA_VERSION,
+    compare_templates,
+    load_manifest,
+    save_manifest,
+)
+
+
+class InspectTemplate(BaseModel):
+    name: str
+
+
+class ValidateTemplatesResult(BaseModel):
+    success: bool
+    missing: list[str] = []
+    upstream_changed: list[str] = []
+    custom_safe: list[str] = []
+    unchanged: list[str] = []
+
+
+def list_templates() -> list[InspectTemplate]:
+    """List all built-in inspect templates."""
+    return [InspectTemplate(name=name) for name in INSPECT_TEMPLATES]
+
+
+def eject_templates(
+    target_dir: Path,
+    *,
+    templates: list[str] | None = None,
+    force: bool = False,
+) -> list[Path]:
+    """Write built-in inspect templates to target_dir.
+
+    Returns paths of files actually written (skipped files are omitted).
+    Raises ValueError for unknown template names.
+    """
+    from importlib.resources import files as _pkg_files
+
+    to_eject = templates if templates is not None else list(INSPECT_TEMPLATES)
+
+    invalid = [t for t in to_eject if t not in INSPECT_TEMPLATES]
+    if invalid:
+        raise ValueError(f"Unknown templates: {', '.join(invalid)}")
+
+    target_dir.mkdir(parents=True, exist_ok=True)
+    templates_pkg = _pkg_files("dataface.core.inspect.templates")
+    manifest = load_manifest(target_dir, dataface_version=__version__)
+    manifest["schema_version"] = MANIFEST_SCHEMA_VERSION
+    manifest["dataface_version"] = __version__
+    manifest["generated_at"] = datetime.now(timezone.utc).isoformat()
+    manifest_templates = manifest.setdefault("templates", {})
+
+    ejected: list[Path] = []
+
+    for name in to_eject:
+        source_file = templates_pkg.joinpath(f"{name}.yml")
+        target_file = target_dir / f"{name}.yml"
+
+        if target_file.exists() and not force:
+            continue
+
+        content = source_file.read_text()
+        source_hash = sha256(content.encode("utf-8")).hexdigest()
+        target_file.write_text(content)
+
+        manifest_templates[name] = {
+            "filename": f"{name}.yml",
+            "ejected_at": datetime.now(timezone.utc).isoformat(),
+            "source_version": __version__,
+            "source_sha256": source_hash,
+        }
+        ejected.append(target_file)
+
+    save_manifest(target_dir, manifest)
+    return ejected
+
+
+def validate_ejected_templates(
+    target_dir: Path | None = None,
+) -> ValidateTemplatesResult:
+    """Compare ejected templates against built-in versions using the manifest.
+
+    Returns a ValidateTemplatesResult. Call .success to check overall status.
+    Raises FileNotFoundError if the manifest is missing.
+    """
+    from importlib.resources import files as _pkg_files
+
+    resolved = target_dir or (Path.cwd() / "faces" / "inspect")
+    manifest_path = resolved / INSPECT_TEMPLATE_MANIFEST
+    if not manifest_path.exists():
+        raise FileNotFoundError(
+            f"Missing manifest at {manifest_path}. Run eject_templates() first."
+        )
+
+    manifest = load_manifest(resolved, dataface_version=__version__)
+    manifest_templates: dict[str, dict] = manifest.get("templates", {})
+    templates_pkg = _pkg_files("dataface.core.inspect.templates")
+
+    missing, upstream_changed, custom_safe, unchanged = compare_templates(
+        resolved, manifest_templates, templates_pkg
+    )
+
+    return ValidateTemplatesResult(
+        success=not missing and not upstream_changed,
+        missing=missing,
+        upstream_changed=upstream_changed,
+        custom_safe=custom_safe,
+        unchanged=unchanged,
+    )

dataface/agent_api/mcp_install.py

@@ -0,0 +1,170 @@
+"""Typed MCP client install verbs — per-client config writers for agent surfaces."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any, Literal
+
+import tomli_w
+from pydantic import BaseModel
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover - exercised on 3.10 CI
+    import tomli as tomllib
+
+
+# Client name → (config file path, servers key, detection paths, format).
+# Kept as a plain dict so tests can patch individual entries (e.g. redirect
+# the Claude Desktop path into a tmp directory).
+MCP_CLIENTS: dict[str, tuple[Path, str, tuple[Path, ...], str]] = {
+    "cursor": (Path(".cursor/mcp.json"), "mcpServers", (Path(".cursor"),), "json"),
+    "codex": (
+        Path(".codex/config.toml"),
+        "mcp_servers",
+        (Path(".codex"), Path("AGENTS.md")),
+        "toml",
+    ),
+    "claude": (
+        Path.home() / ".config" / "claude" / "config.json",
+        "mcpServers",
+        (Path.home() / ".config" / "claude",),
+        "json",
+    ),
+    "vscode": (Path(".vscode/mcp.json"), "servers", (Path(".vscode"),), "json"),
+    "claude-code": (Path(".mcp.json"), "mcpServers", (Path("CLAUDE.md"),), "json"),
+    "copilot": (
+        Path(".github/copilot/mcp.json"),
+        "servers",
+        (Path(".github"),),
+        "json",
+    ),
+}
+
+
+class McpClient(BaseModel):
+    name: str
+    config_path: Path
+    servers_key: str
+    detect_paths: tuple[Path, ...]
+    config_format: Literal["json", "toml"]
+    current_config: dict[str, Any] | None = None
+
+
+class InstallResult(BaseModel):
+    client_name: str
+    config_path: Path
+    already_configured: bool
+    updated: bool
+    message: str
+
+
+def list_clients() -> list[McpClient]:
+    """Return all supported MCP clients from the current MCP_CLIENTS registry."""
+    return [
+        McpClient(
+            name=name,
+            config_path=cfg,
+            servers_key=sk,
+            detect_paths=dp,
+            config_format=fmt,  # type: ignore[arg-type]
+        )
+        for name, (cfg, sk, dp, fmt) in MCP_CLIENTS.items()
+    ]
+
+
+def install_for_client(
+    client: McpClient,
+    *,
+    server_command: list[str],
+    config_root: Path,
+    force: bool = False,
+) -> InstallResult:
+    """Write the MCP server entry for one client config file.
+
+    server_command: full argv for the server, e.g. ["dft", "mcp", "serve"].
+    config_root: workspace root for resolving relative config paths.
+    """
+    server_entry: dict[str, Any] = {
+        "command": server_command[0],
+        "args": server_command[1:],
+    }
+    abs_path = (
+        client.config_path
+        if client.config_path.is_absolute()
+        else config_root / client.config_path
+    )
+    if client.config_format == "toml":
+        msg = _upsert_toml_mcp_config(abs_path, client.servers_key, server_entry, force)
+    else:
+        msg = _upsert_mcp_config(abs_path, client.servers_key, server_entry, force)
+
+    already = msg is None
+    return InstallResult(
+        client_name=client.name,
+        config_path=abs_path,
+        already_configured=already,
+        updated=not already and "Updated" in (msg or ""),
+        message=msg or f"  {abs_path} already has dataface (use -f to update)",
+    )
+
+
+def _upsert_mcp_config(
+    config_path: Path,
+    servers_key: str,
+    server_entry: dict[str, Any],
+    force: bool,
+) -> str | None:
+    """Add dataface to a JSON MCP config file, preserving existing content.
+
+    Returns a status message, or None if skipped (already configured).
+    """
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+
+    existing: dict[str, Any] = {}
+    if config_path.exists():
+        try:
+            existing = json.loads(config_path.read_text())
+            if not isinstance(existing, dict):
+                existing = {}
+        except (json.JSONDecodeError, OSError):
+            existing = {}
+
+    already_has = servers_key in existing and "dataface" in existing.get(
+        servers_key, {}
+    )
+    if already_has and not force:
+        return None
+
+    existing.setdefault(servers_key, {})
+    existing[servers_key]["dataface"] = server_entry
+    config_path.write_text(json.dumps(existing, indent=2) + "\n")
+    return f"  {'Updated' if already_has else 'Added dataface to'} {config_path}"
+
+
+def _upsert_toml_mcp_config(
+    config_path: Path,
+    servers_key: str,
+    server_entry: dict[str, Any],
+    force: bool,
+) -> str | None:
+    """Add dataface to a TOML MCP config file, preserving existing content.
+
+    Returns a status message, or None if skipped (already configured).
+    """
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+
+    existing: dict[str, Any] = {}
+    if config_path.exists():
+        existing = tomllib.loads(config_path.read_text())
+
+    already_has = "dataface" in existing.get(servers_key, {})
+    if already_has and not force:
+        return None
+
+    existing.setdefault(servers_key, {})
+    existing[servers_key]["dataface"] = server_entry
+    config_path.write_text(tomli_w.dumps(existing))
+    return f"  {'Updated' if already_has else 'Added dataface to'} {config_path}"