dataface 0.1.5.dev151__py3-none-any.whl → 0.1.5.dev206__py3-none-any.whl

dataface/DATAFACE_SYNTAX.md

@@ -597,12 +597,14 @@ support:                # Optional support line (same shape: value/label/format/
   glyph: "▲"
   tone: positive
 
-# table — renders all query columns unless `style.columns` selects a subset
+# table — renders all query columns unless `style.columns` selects a subset.
+# `columns` is a MAPPING keyed by column name (NOT a list). Omit it to show
+# every query column; include it to choose a subset and/or style columns.
 type: table
 style:
   columns:
-    - column: order_id
-    - column: amount
+    order_id: {}                         # include with default styling
+    amount:                              # the key is the column name
       label: Amount
       format: currency_whole
       align: right                       # left | center | right
@@ -876,7 +878,6 @@ Common variable fields:
 | `default` | any | Default value when no URL param is set |
 | `placeholder` | string | Placeholder text |
 | `required` | bool | Block rendering until a value exists |
-| `allow_null` | bool | `null` is a valid selection |
 | `visible` | bool | Hidden when `false`; still settable via URL param |
 | `disabled` | bool \| string \| `{query, column}` | Static, Jinja expr, or query-backed disable |
 | `data_type` | string | Upstream type hint (informational; preserved through migrations) |
@@ -905,7 +906,7 @@ variables:
 
 Top-level option-source binding (alternative to `options:`): `column`, `query`, `dimension` (MetricFlow), `measure` (MetricFlow), `model` (dbt).
 
-For `select` and `multiselect`, omitting `default` starts the variable unset. The renderer adds a blank `-- All --` option for that unset state; `{{ filter('column', variable) }}` emits `1=1` unless the SQL call site opts into `none='deny'`.
+Variables are optional by default. For `select` and `multiselect`, omitting `default` starts the variable unset. The renderer adds a blank `-- All --` option for that unset state; `{{ filter('column', variable) }}` emits `1=1` unless the SQL call site opts into `none='deny'`. Add `required: true` only when the dashboard cannot render without a value.
 
 Disabled forms:
 

dataface/agent_api/_paths.py

@@ -5,10 +5,6 @@ from __future__ import annotations
 from dataclasses import dataclass
 from pathlib import Path
 
-from dataface.core.execute.adapters import (
-    AdapterRegistry as AdapterRegistry,
-    build_adapter_registry as build_adapter_registry,
-)
 from dataface.core.project_roots import (
     discover_render_context as discover_render_context,
     discovery_boundary_for_face as discovery_boundary_for_face,
@@ -75,23 +71,26 @@ def no_project_hint(project_dir: Path | None) -> str:
 
 @dataclass(frozen=True)
 class FaceRenderContext:
-    """Resources resolved from a face path + project root for rendering."""
+    """Path resolution result from a face path + project root.
+
+    Adapter registry is built by `Project.open`, not by the context — call sites
+    open a `Project` with `project_root` + `dbt_project_path` and read the
+    registry off `project.adapter_registry`.
+    """
 
     face_file: Path
     scoped_path: Path | None
     scoped_base: Path
     project_root: Path
     output_dir: Path
-    adapter_registry: AdapterRegistry
+    dbt_project_path: Path | None = None
 
 
 def build_face_render_context(
     face_path: Path,
     project_dir: Path | None = None,
-    *,
-    read_only: bool = True,
 ) -> FaceRenderContext:
-    """Resolve a face path, walk for dbt context, and build the adapter registry.
+    """Resolve a face path and walk for dbt context.
 
     ``project_dir=None`` means "walk freely from the face's parent" — used by
     the CLI when ``--project-dir`` is omitted so a face under a dbt sub-project
@@ -127,27 +126,26 @@ def build_face_render_context(
         scoped_base=project_root,
         project_root=project_root,
         output_dir=project_root,
-        adapter_registry=build_adapter_registry(
-            project_root, read_only=read_only, dbt_project_path=dbt_project_path
-        ),
+        dbt_project_path=dbt_project_path,
     )
 
 
 @dataclass(frozen=True)
 class YamlRenderContext:
-    """Resources resolved from a project root for rendering inline YAML."""
+    """Path resolution result for rendering inline YAML against a project root.
+
+    Adapter registry is built by `Project.open`, not by the context.
+    """
 
     project_root: Path
     output_dir: Path
-    adapter_registry: AdapterRegistry
+    dbt_project_path: Path | None = None
 
 
 def build_yaml_render_context(
     project_dir: Path | None = None,
-    *,
-    read_only: bool = True,
 ) -> YamlRenderContext:
-    """Walk for dbt context and build the adapter registry for inline YAML.
+    """Walk for dbt context anchored at the given project root.
 
     ``project_dir=None`` walks from cwd to discover the project root; a given
     ``project_dir`` is authoritative.
@@ -160,7 +158,5 @@ def build_yaml_render_context(
     return YamlRenderContext(
         project_root=project_root,
         output_dir=project_root,
-        adapter_registry=build_adapter_registry(
-            project_root, read_only=read_only, dbt_project_path=dbt_project_path
-        ),
+        dbt_project_path=dbt_project_path,
     )

dataface/agent_api/cache.py

@@ -0,0 +1,24 @@
+"""Cache constructors at the agent_api boundary."""
+
+from collections.abc import Generator
+from contextlib import contextmanager
+
+from dataface.core.execute.duckdb_cache import DuckDBCache, open_cache_from_env
+
+__all__ = ["cache_from_env", "open_cache_from_env"]
+
+
+@contextmanager
+def cache_from_env() -> Generator[DuckDBCache | None]:
+    """Open DFT_CACHE_PATH-backed cache (or None) and close it on exit.
+
+    Use for CLI verbs and composition roots that need a cache scoped to
+    a single command invocation. Long-lived processes (server boot, MCP
+    server) use ``open_cache_from_env()`` directly and own the lifecycle.
+    """
+    cache = open_cache_from_env()
+    try:
+        yield cache
+    finally:
+        if cache is not None:
+            cache.close()

dataface/agent_api/chat.py

@@ -2,12 +2,18 @@
 
 from __future__ import annotations
 
+import sys
 from collections.abc import Generator
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
 from dataface.agent_api._session_store import (
     SessionIndex,
     SessionWriter,
@@ -40,6 +46,17 @@ class ChatSession:
     client: Any = field(repr=False)
     writer: SessionWriter = field(repr=False)
 
+    def close(self) -> None:
+        """Flush the session log and release the project's resources."""
+        self.writer.close()
+        self.context.project.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
 
 @dataclass
 class ChatSessionSummary:
@@ -64,19 +81,13 @@ def start_session(
         project_dir: Working directory for the session. Defaults to cwd.
         server_port: Port of the embedded HTTP preview server, if running.
     """
-    from dataface.core.execute.adapters import (
-        LOCAL_AUTHORING_REGISTRY_KWARGS,
-        build_adapter_registry,
-    )
+    from dataface.agent_api.project import Project
+    from dataface.core.execute.adapters import LOCAL_AUTHORING_REGISTRY_KWARGS
 
     cwd = (project_dir or Path.cwd()).resolve()
     client = create_client(model=model)
     context = DatafaceAIContext(
-        adapter_registry=build_adapter_registry(
-            cwd,
-            **LOCAL_AUTHORING_REGISTRY_KWARGS,
-        ),
-        default_project_dir=cwd,
+        project=Project.open(cwd, **LOCAL_AUTHORING_REGISTRY_KWARGS),
         server_port=server_port,
     )
     writer, _ = new_session(cwd, provider=client.provider, model=client.model)
@@ -112,10 +123,8 @@ def resume_session(
     Raises:
         ValueError: If session not found, provider mismatch, or context window exceeded.
     """
-    from dataface.core.execute.adapters import (
-        LOCAL_AUTHORING_REGISTRY_KWARGS,
-        build_adapter_registry,
-    )
+    from dataface.agent_api.project import Project
+    from dataface.core.execute.adapters import LOCAL_AUTHORING_REGISTRY_KWARGS
 
     cwd = (project_dir or Path.cwd()).resolve()
     client = create_client(model=model)
@@ -134,11 +143,7 @@ def resume_session(
         )
 
     context = DatafaceAIContext(
-        adapter_registry=build_adapter_registry(
-            cwd,
-            **LOCAL_AUTHORING_REGISTRY_KWARGS,
-        ),
-        default_project_dir=cwd,
+        project=Project.open(cwd, **LOCAL_AUTHORING_REGISTRY_KWARGS),
         server_port=server_port,
     )
     writer, _ = new_session(cwd, provider=client.provider, model=client.model)

dataface/agent_api/dashboards.py

@@ -79,7 +79,7 @@ class RenderDashboardArgs(BaseModel):
     variables: dict[str, Any] | None = Field(
         None, description="Variable values to apply to the dashboard"
     )
-    format: Literal["json", "text", "yaml", "svg"] | None = Field(
+    format: Literal["json", "text", "yaml", "svg", "terminal"] | None = Field(
         None,
         description=(
             "Output format. 'json' (default) returns resolved chart "
@@ -89,7 +89,9 @@ class RenderDashboardArgs(BaseModel):
             "YAML with inline data — valid input for re-compilation, "
             "ideal for round-trip editing. 'svg' returns the rendered "
             "dashboard as inline SVG (under result['data']) for hosts "
-            "that embed the rendered output directly."
+            "that embed the rendered output directly. 'terminal' returns "
+            "the charts as ANSI text (under result['data']) for display "
+            "in a terminal."
         ),
     )
     as_link: bool = Field(

dataface/agent_api/describe.py

@@ -87,7 +87,7 @@ class DescribeFaceArgs(BaseModel):
         default=None,
         description=(
             "Project root for resolving relative paths. Optional on the wire; "
-            "the MCP server injects ctx.default_project_dir or cwd when omitted."
+            "the MCP server injects ctx.project.project_root when omitted."
         ),
     )
 

dataface/agent_api/docs/yaml-reference.md

@@ -11,6 +11,7 @@ AuthoredFace (dataface) definition from YAML.
 | `tags` | list[str] | ✓ | Tags for categorization and search. |
 | `docs` | str | ✓ | Relative path under the docs site for the canonical doc page that explains this face. Surfaced as a 'Docs →' link in the playground gallery when DFT_DOCS_URL is set. |
 | `text` | str | ✓ | Markdown text content for text-only sections. |
+| `allow_html` | bool | ✓ | Render the face's body text as raw HTML via foreignObject instead of markdown. TRUSTED-CONTENT ONLY: the HTML (including any Jinja-interpolated values) is rendered as-authored — this is NOT a security sandbox. mdsvg strips <script>/event-handlers as a best-effort guard, not a guarantee. Enable only on first-party faces you fully control. |
 | `sources` | [SourcesSection](#sourcessection) | ✓ | Database source configuration. Use 'default:' to set the default source for all queries. |
 | `source` | str | ✓ | Default source name shorthand (equivalent to sources.default). Sets the connection for all queries. |
 | `variables` | dict[str, [Variable](#variable) \| VariableRef] | ✓ | Variable definitions for dynamic filtering and UI controls. |
@@ -51,7 +52,6 @@ Variable definition from YAML.
 | `default` | Any | ✓ | Default value used when no URL param is set. |
 | `placeholder` | str | ✓ | Placeholder text shown in the input when empty. |
 | `required` | bool | ✓ | When True, a value must be provided before queries execute. |
-| `allow_null` | bool | ✓ | When True, 'null' is a valid selection (useful for optional filters). |
 | `visible` | bool | ✓ | When False, the variable is not rendered in the UI but can still be set via URL params. |
 | `disabled` | bool \| str \| [SingleRowBoolProbe](#singlerowboolprobe) | ✓ | Disable this control. Accepts: static bool; a variable name or Jinja boolean expression string (no {{ }} required — bare names auto-wrap); or a {query, column} form that reads a single boolean cell from a named query. Absent variable in a string expression raises (use a default). |
 | `column` | str | ✓ | Column name in the query result to use as option values. |
@@ -491,6 +491,8 @@ Authored overlay for Style — all fields optional. Adds CSS shorthand coercers.
 | `layout` | [LayoutStyle](#layoutstyle) | ✓ | Layout container styles (rows, cols, grid, tabs, details). |
 | `variables` | [VariablesStyle](#variablesstyle) | ✓ | Variable controls chrome style. |
 | `page` | [PageStyle](#pagestyle) | ✓ | Page-level canvas style (behind the board). |
+| `footer` | [FooterStyle](#footerstyle) | ✓ | Page footer chrome visibility. |
+| `timestamp` | [TimestampStyle](#timestampstyle) | ✓ | Render-timestamp chrome: visibility, format, and font. |
 | `formats` | dict[str, str] | ✓ | Format alias map; None means no aliases at this cascade level. |
 | `palettes` | dict[str, str] | ✓ | Theme palette role assignments: open dict mapping role name to palette file name. Default seed: chrome, negative, positive, warning, category, sequence, diverge. |
 | `roles` | dict[str, str] | ✓ | Optional top-level theme role aliases: bare name → role.alias. e.g. ink: chrome.heading |
@@ -1064,8 +1066,7 @@ Authored overlay for BoardStyle. Face-level structural dimensions. Do NOT cascad
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
 | `width` | float | ✓ | Board width in pixels. |
-| `default_height` | float | ✓ | Default row height in pixels. |
-| `min_height` | float | ✓ | Minimum row height in pixels. |
+| `min_height` | float | ✓ | Minimum board height in pixels. |
 | `margin` | float | ✓ | Board outer margin in pixels. |
 | `card_padding` | float | ✓ | Padding added to each card side in pixels. |
 | `card_gap` | float | ✓ | Gap between cards in pixels. |
@@ -1222,6 +1223,24 @@ Authored overlay for PageStyle. Page-level (outer HTML canvas) styling.
 |-------|------|:--------:|-------------|
 | `background` | str | ✓ | Page canvas background color (behind the face board). |
 
+<a id="footerstyle"></a>
+## FooterStyle
+Authored overlay for FooterStyle. Authored visibility toggle for the page footer chrome.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `visible` | bool | ✓ | Show the footer attribution line. |
+
+<a id="timestampstyle"></a>
+## TimestampStyle
+Authored overlay for TimestampStyle. Authored timestamp chrome: visibility, strftime format, and font.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `visible` | bool | ✓ | Show the render-timestamp line. |
+| `format` | str | ✓ | strftime format string for the render timestamp. |
+| `font` | [FontStyle](#fontstyle) | ✓ | Timestamp font style overrides (size, color, weight, ...). |
+
 <a id="spacingvalues"></a>
 ## SpacingValues
 Pre-parsed CSS spacing (margin/padding).

dataface/agent_api/files.py

@@ -0,0 +1,262 @@
+"""General project-file tools for the chat agent.
+
+Claude-Code-style primitives — read, write, edit, glob, grep — that let an
+agent author and save faces directly, rather than via a domain-specific
+"write a dashboard" verb. The agent composes these with the typed dft tools
+(``validate_dashboard``, ``render_dashboard``, ``schema``, ``execute_query``).
+
+Every path is resolved against and confined to the project root. A path that
+escapes the root (``..`` traversal, absolute path outside, symlink out) is
+refused — these tools never touch the wider filesystem.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+# Cap grep/glob payloads — read_file returns full content (model must handle size).
+_MAX_GREP_MATCHES = 200
+_MAX_GLOB_MATCHES = 500
+
+# Directory names to skip on whole-tree scans — avoids traversing .venv,
+# .git, node_modules, target, etc. which can be huge and contain no user code.
+_SKIP_DIRS = frozenset(
+    {".git", ".venv", "venv", "node_modules", "target", "__pycache__", ".tox"}
+)
+
+
+class ReadFileArgs(BaseModel):
+    """Read a UTF-8 text file from the project. Path is relative to the project root."""
+
+    path: str = Field(description="File path relative to the project root.")
+
+
+class WriteFileArgs(BaseModel):
+    """Write a UTF-8 text file in the project, creating parent directories.
+
+    Overwrites an existing file. To change part of an existing file, prefer
+    edit_file so you don't clobber content you haven't read. Path is relative
+    to the project root and may not escape it.
+    """
+
+    path: str = Field(description="File path relative to the project root.")
+    content: str = Field(description="Full file contents to write.")
+
+
+class EditFileArgs(BaseModel):
+    """Replace an exact string in a project file. old_string must occur exactly once.
+
+    Fails (writing nothing) if old_string is absent or appears more than once —
+    include enough surrounding context to make it unique. Path is relative to
+    the project root and may not escape it.
+    """
+
+    path: str = Field(description="File path relative to the project root.")
+    old_string: str = Field(description="Exact text to replace (must be unique).")
+    new_string: str = Field(description="Replacement text.")
+
+
+class GlobFilesArgs(BaseModel):
+    """List files matching a glob pattern under the project root (e.g. 'faces/*.yml')."""
+
+    pattern: str = Field(description="Glob pattern relative to the project root.")
+
+
+class GrepFilesArgs(BaseModel):
+    """Search file contents for a substring under the project root.
+
+    Optionally restrict to files matching a glob (e.g. only 'faces/**/*.yml').
+    Skips .git, .venv, node_modules, target, and other large non-user directories.
+    """
+
+    pattern: str = Field(description="Substring to search for (case-sensitive).")
+    glob: str | None = Field(
+        default=None, description="Optional glob to restrict which files are searched."
+    )
+
+
+class ReadFileResult(BaseModel):
+    success: bool
+    path: str
+    content: str | None = None
+    error: str | None = None
+
+
+class WriteFileResult(BaseModel):
+    success: bool
+    path: str
+    bytes_written: int = 0
+    error: str | None = None
+
+
+class EditFileResult(BaseModel):
+    success: bool
+    path: str
+    replacements: int = 0
+    error: str | None = None
+
+
+class GlobResult(BaseModel):
+    success: bool
+    matches: list[str] = Field(default_factory=list)
+    truncated: bool = False
+    error: str | None = None
+
+
+class GrepMatch(BaseModel):
+    path: str
+    line_number: int
+    line: str
+
+
+class GrepResult(BaseModel):
+    success: bool
+    matches: list[GrepMatch] = Field(default_factory=list)
+    truncated: bool = False
+    error: str | None = None
+
+
+def _resolve_within(project_dir: Path, raw: str) -> Path:
+    """Resolve ``raw`` against the project root, refusing anything that escapes it."""
+    root = project_dir.resolve()
+    candidate = Path(raw)
+    candidate = candidate if candidate.is_absolute() else root / candidate
+    resolved = candidate.resolve()
+    if resolved != root and root not in resolved.parents:
+        raise ValueError(f"path {raw!r} escapes the project root")
+    return resolved
+
+
+def _rel(project_dir: Path, p: Path) -> str:
+    return str(p.resolve().relative_to(project_dir.resolve()))
+
+
+def _walk_project(root: Path) -> list[Path]:
+    """Return files under root, skipping known large/irrelevant directories."""
+    result: list[Path] = []
+    for item in sorted(root.iterdir()):
+        if item.is_dir():
+            if item.name in _SKIP_DIRS or item.name.startswith("."):
+                continue
+            result.extend(_walk_project(item))
+        elif item.is_file():
+            result.append(item)
+    return result
+
+
+def read_file(path: str, project_dir: Path) -> ReadFileResult:
+    try:
+        target = _resolve_within(project_dir, path)
+    except ValueError as exc:
+        return ReadFileResult(success=False, path=path, error=str(exc))
+    if not target.is_file():
+        return ReadFileResult(success=False, path=path, error=f"file not found: {path}")
+    try:
+        content = target.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        return ReadFileResult(success=False, path=path, error=str(exc))
+    return ReadFileResult(success=True, path=_rel(project_dir, target), content=content)
+
+
+def write_file(path: str, content: str, project_dir: Path) -> WriteFileResult:
+    try:
+        target = _resolve_within(project_dir, path)
+    except ValueError as exc:
+        return WriteFileResult(success=False, path=path, error=str(exc))
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content, encoding="utf-8")
+    except OSError as exc:
+        return WriteFileResult(success=False, path=path, error=str(exc))
+    return WriteFileResult(
+        success=True,
+        path=_rel(project_dir, target),
+        bytes_written=len(content.encode("utf-8")),
+    )
+
+
+def edit_file(
+    path: str, old_string: str, new_string: str, project_dir: Path
+) -> EditFileResult:
+    try:
+        target = _resolve_within(project_dir, path)
+    except ValueError as exc:
+        return EditFileResult(success=False, path=path, error=str(exc))
+    if not target.is_file():
+        return EditFileResult(success=False, path=path, error=f"file not found: {path}")
+    try:
+        original = target.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        return EditFileResult(success=False, path=path, error=str(exc))
+    count = original.count(old_string)
+    if count == 0:
+        return EditFileResult(
+            success=False, path=path, error="old_string not found in file"
+        )
+    if count > 1:
+        return EditFileResult(
+            success=False,
+            path=path,
+            error=f"old_string is not unique ({count} occurrences) — add surrounding context",
+        )
+    try:
+        target.write_text(original.replace(old_string, new_string), encoding="utf-8")
+    except OSError as exc:
+        return EditFileResult(success=False, path=path, error=str(exc))
+    return EditFileResult(success=True, path=_rel(project_dir, target), replacements=1)
+
+
+def glob_files(pattern: str, project_dir: Path) -> GlobResult:
+    root = project_dir.resolve()
+    matches: list[str] = []
+    try:
+        candidates = root.glob(pattern)
+    except (ValueError, OSError, NotImplementedError) as exc:
+        return GlobResult(success=False, error=str(exc))
+    for p in sorted(candidates):
+        if not p.is_file():
+            continue
+        try:
+            rel = p.resolve().relative_to(root)
+        except ValueError:
+            continue  # symlink escaping the root
+        matches.append(str(rel))
+        if len(matches) >= _MAX_GLOB_MATCHES:
+            return GlobResult(success=True, matches=matches, truncated=True)
+    return GlobResult(success=True, matches=matches)
+
+
+def grep_files(pattern: str, project_dir: Path, glob: str | None = None) -> GrepResult:
+    root = project_dir.resolve()
+    matches: list[GrepMatch] = []
+    try:
+        candidates: list[Path] = (
+            sorted(root.glob(glob)) if glob else _walk_project(root)
+        )
+    except (ValueError, OSError, NotImplementedError) as exc:
+        return GrepResult(success=False, error=str(exc))
+    for p in candidates:
+        if not p.is_file():
+            continue
+        try:
+            rel = p.resolve().relative_to(root)
+        except ValueError:
+            continue
+        try:
+            with p.open(encoding="utf-8") as fh:
+                for i, line in enumerate(fh, start=1):
+                    if pattern in line:
+                        matches.append(
+                            GrepMatch(
+                                path=str(rel), line_number=i, line=line.rstrip("\n")
+                            )
+                        )
+                        if len(matches) >= _MAX_GREP_MATCHES:
+                            return GrepResult(
+                                success=True, matches=matches, truncated=True
+                            )
+        except (OSError, UnicodeDecodeError):
+            continue  # skip binary / unreadable files
+    return GrepResult(success=True, matches=matches)