functualize-flow-viz 0.1.0__tar.gz

functualize_flow_viz-0.1.0/.gitignore

@@ -0,0 +1,101 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Agents
+.spec/archive/
+.spec/features/
+.spec/scrutiny-reports/
+.spec/.agentic-coding
+.spec/STATE.md
+.spec/PROJECT.md
+.spec/REQUIREMENTS.md
+.spec/ROADMAP.md
+.opencode/
+
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing
+.coverage
+.pytest_cache/
+htmlcov/
+.hypothesis/
+snapshot_report.html
+_*_result*.txt
+_debug.txt
+_tui_debug.txt
+_tui_eval_debug.txt
+
+# IDE
+.idea/
+*.swp
+*.swo
+*~
+*.code-workspace
+
+# Coding-agent tooling state (guards — these dirs are not part of the repo)
+.kiro/
+.moai/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment / secrets
+.env
+.env.*
+!.env.example
+
+# Agent scratch space (test output, temp scripts)
+tmp/
+
+# Local-only files (not for the repo)
+*.local.md
+*.local.*
+
+# Personal notes
+HUMAN_NOTE.md
+
+# Distribution
+dist/
+
+# Documentation site build output
+site/
+
+# uv
+.python-version
+.functualize/cache.json
+.functualize_cache.json
+.todos/
+.sidecar/
+.sidecar-agent
+.sidecar-task
+.sidecar-pr
+.sidecar-start.sh
+.sidecar-base
+.td-root
+.functualize/
+.import_linter_cache/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# OmO / OpenCode agent run-continuation scratch state
+.omo/
+.mcp.json
+.agentsroom/handoff-transcript-*.txt
+.agentsroom/handoff-summary-*.md
+
+# Internal pre-release audit reports (contain session IDs / local infra notes)
+.release/

functualize_flow_viz-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: functualize-flow-viz
+Version: 0.1.0
+Summary: Inline flow visualization plugin for functualize job execution
+Author-email: Mohammad Hakim Adiprasetya <viltohmyst@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: functualize<1.0.0,>=0.1.0
+Requires-Dist: textual>=0.40.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# functualize-flow-viz
+
+> **Status: Published** — Independently installable from PyPI.
+
+Inline execution tree visualization plugin for functualize. Renders a live job execution tree in the terminal showing step status, durations, and nested invocations updating in real time. Automatically detects TTY capabilities and falls back to structured plain-text output for non-interactive terminals.
+
+## Installation
+
+```bash
+pip install functualize-flow-viz
+```
+
+## Quick Start
+
+```python
+from functualize_flow_viz import FlowVizPlugin
+
+# Register the plugin with your functualize app
+plugin = FlowVizPlugin()
+plugin.on_job_start("deploy", {"env": "production"})
+plugin.on_log("info", "Starting deployment...")
+plugin.on_invoke_start("migrate", {"target": "latest"})
+plugin.on_invoke_end("migrate", None)
+plugin.on_job_end("deploy", None)
+```
+
+## Features
+
+- **Live execution tree** — Renders a real-time tree of job execution with status icons (⏳ running, ✓ success, ✗ failure, ○ pending, ⊘ timeout)
+- **Nested invocation tracking** — Shows `rc.invoke()` calls as indented children in the tree, preserving parent-child relationships
+- **Real-time duration refresh** — Background thread updates elapsed durations at ≤1s intervals for running nodes
+- **TTY auto-detection** — Uses ANSI inline rendering on interactive terminals; falls back to plain-text output for piped/CI environments
+- **Custom event handling** — Renders domain-specific visualizations including progress bars for events with progress payloads
+- **Log streaming** — Buffers log messages and prints them above the inline tree widget to avoid visual corruption
+
+## API Reference
+
+Public classes and functions exported by this plugin:
+
+- `FlowVizPlugin` — Main plugin class implementing the OutputRenderer protocol. Auto-selects between TTY and plain-text rendering. Methods:
+  - `on_job_start(job_name, metadata)` — Initialize the execution tree for a job
+  - `on_log(level, message)` — Render a log message
+  - `on_status_change(old_status, new_status, message)` — Handle status transitions
+  - `on_phase_change(step, action)` — Add or update a job phase node
+  - `on_invoke_start(child_job_name, kwargs)` — Begin tracking a nested invocation
+  - `on_invoke_end(child_job_name, result)` — Complete a nested invocation
+  - `on_job_end(job_name, result)` — Finalize the tree and render final state
+  - `on_event(event)` — Handle custom structured events
+  - `render_log(message, level)` — OutputRenderer protocol: render log
+  - `render_phase(phase, status)` — OutputRenderer protocol: render phase update
+  - `render_progress(current, total, label)` — OutputRenderer protocol: render progress
+
+Internal (non-public) classes used by `FlowVizPlugin`:
+
+- `TreeNode` — Dataclass representing a node in the execution tree with label, status, timing, and children
+- `InlineTTYRenderer` — ANSI-based renderer for interactive terminals with background refresh
+- `PlainTextRenderer` — Fallback renderer producing structured plain-text without escape sequences
+
+## Development
+
+Run plugin tests:
+
+```bash
+uv run pytest plugins/functualize-flow-viz/tests/ -v
+```

functualize_flow_viz-0.1.0/README.md

@@ -0,0 +1,65 @@
+# functualize-flow-viz
+
+> **Status: Published** — Independently installable from PyPI.
+
+Inline execution tree visualization plugin for functualize. Renders a live job execution tree in the terminal showing step status, durations, and nested invocations updating in real time. Automatically detects TTY capabilities and falls back to structured plain-text output for non-interactive terminals.
+
+## Installation
+
+```bash
+pip install functualize-flow-viz
+```
+
+## Quick Start
+
+```python
+from functualize_flow_viz import FlowVizPlugin
+
+# Register the plugin with your functualize app
+plugin = FlowVizPlugin()
+plugin.on_job_start("deploy", {"env": "production"})
+plugin.on_log("info", "Starting deployment...")
+plugin.on_invoke_start("migrate", {"target": "latest"})
+plugin.on_invoke_end("migrate", None)
+plugin.on_job_end("deploy", None)
+```
+
+## Features
+
+- **Live execution tree** — Renders a real-time tree of job execution with status icons (⏳ running, ✓ success, ✗ failure, ○ pending, ⊘ timeout)
+- **Nested invocation tracking** — Shows `rc.invoke()` calls as indented children in the tree, preserving parent-child relationships
+- **Real-time duration refresh** — Background thread updates elapsed durations at ≤1s intervals for running nodes
+- **TTY auto-detection** — Uses ANSI inline rendering on interactive terminals; falls back to plain-text output for piped/CI environments
+- **Custom event handling** — Renders domain-specific visualizations including progress bars for events with progress payloads
+- **Log streaming** — Buffers log messages and prints them above the inline tree widget to avoid visual corruption
+
+## API Reference
+
+Public classes and functions exported by this plugin:
+
+- `FlowVizPlugin` — Main plugin class implementing the OutputRenderer protocol. Auto-selects between TTY and plain-text rendering. Methods:
+  - `on_job_start(job_name, metadata)` — Initialize the execution tree for a job
+  - `on_log(level, message)` — Render a log message
+  - `on_status_change(old_status, new_status, message)` — Handle status transitions
+  - `on_phase_change(step, action)` — Add or update a job phase node
+  - `on_invoke_start(child_job_name, kwargs)` — Begin tracking a nested invocation
+  - `on_invoke_end(child_job_name, result)` — Complete a nested invocation
+  - `on_job_end(job_name, result)` — Finalize the tree and render final state
+  - `on_event(event)` — Handle custom structured events
+  - `render_log(message, level)` — OutputRenderer protocol: render log
+  - `render_phase(phase, status)` — OutputRenderer protocol: render phase update
+  - `render_progress(current, total, label)` — OutputRenderer protocol: render progress
+
+Internal (non-public) classes used by `FlowVizPlugin`:
+
+- `TreeNode` — Dataclass representing a node in the execution tree with label, status, timing, and children
+- `InlineTTYRenderer` — ANSI-based renderer for interactive terminals with background refresh
+- `PlainTextRenderer` — Fallback renderer producing structured plain-text without escape sequences
+
+## Development
+
+Run plugin tests:
+
+```bash
+uv run pytest plugins/functualize-flow-viz/tests/ -v
+```

functualize_flow_viz-0.1.0/examples/README.md

@@ -0,0 +1,31 @@
+# functualize-flow-viz Examples
+
+Live inline execution tree — zero code changes to your jobs. The plugin subscribes to `invoke_start`, `invoke_end`, and `phase_change` events and renders phase status, durations, and nested invocations.
+
+| Directory | Demonstrates |
+|-----------|--------------|
+| [`pipeline/`](pipeline/) | A job invoking sub-jobs with phase tracking — the shape flow-viz visualizes |
+
+## See it live
+
+```bash
+cd plugins/functualize-flow-viz/examples/pipeline
+func jobs.py morning_report --city Tokyo
+```
+
+With `functualize-flow-viz` installed, the run renders as a live tree:
+
+```
+⏳ morning_report
+├─ ✓ forecast — Forecast retrieved (0.1s)
+├─ ✓ alerts — Alerts checked (0.1s)
+└─ ✓ morning_report (0.3s)
+```
+
+Uninstall the plugin and the same command prints plain logs — jobs never know the difference.
+
+## Tests
+
+```bash
+uv run pytest plugins/functualize-flow-viz/examples/ -v
+```

functualize_flow_viz-0.1.0/examples/pipeline/jobs.py

@@ -0,0 +1,42 @@
+"""A nested-invocation pipeline for flow-viz to visualize.
+
+Run with:
+    func jobs.py morning_report --city Tokyo
+"""
+
+from pydantic import BaseModel, Field
+
+from functualize.job import RunContext
+from functualize.types import RunStatus
+
+
+class ForecastConfig(BaseModel):
+    """Configuration for weather jobs."""
+
+    city: str = Field(description="City to check")
+    days: int = Field(default=3, ge=1, le=7, description="Days to forecast")
+
+
+def forecast(config: ForecastConfig, rc: RunContext) -> str:
+    """Fetch the weather forecast for the configured city."""
+    rc.log(f"Fetching {config.days}-day forecast for {config.city}...")
+    return f"{config.city}: 24°C, sunny"
+
+
+def alert(config: ForecastConfig, rc: RunContext) -> str:
+    """Check forecast and send alerts if needed."""
+    rc.log(f"No severe weather for {config.city} — all clear")
+    return "all clear"
+
+
+def morning_report(config: ForecastConfig, rc: RunContext) -> None:
+    """Run the full morning weather pipeline (watch the tree render)."""
+    rc.track_phase("forecast", "Fetching forecast", RunStatus.RUNNING)
+    rc.invoke("forecast", city=config.city, days=config.days)
+    rc.track_phase("forecast", "Forecast retrieved", RunStatus.SUCCESS)
+
+    rc.track_phase("alerts", "Checking alerts", RunStatus.RUNNING)
+    rc.invoke("alert", city=config.city)
+    rc.track_phase("alerts", "Alerts checked", RunStatus.SUCCESS)
+
+    rc.log("Morning report complete")

functualize_flow_viz-0.1.0/examples/pipeline/test_pipeline.py

@@ -0,0 +1,17 @@
+"""Tests for the pipeline example (the jobs flow-viz visualizes)."""
+
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+from jobs import ForecastConfig, morning_report
+
+
+def test_pipeline_emits_invokes_and_phases():
+    rc = MagicMock()
+    morning_report(ForecastConfig(city="Tokyo"), rc)
+    invoked = [call.args[0] for call in rc.invoke.call_args_list]
+    assert invoked == ["forecast", "alert"]
+    assert rc.track_phase.call_count == 4

functualize_flow_viz-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "functualize-flow-viz"
+version = "0.1.0"
+description = "Inline flow visualization plugin for functualize job execution"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Mohammad Hakim Adiprasetya", email = "viltohmyst@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "functualize>=0.1.0,<1.0.0",
+    "textual>=0.40.0",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.entry-points."functualize.plugins"]
+flow-viz = "functualize_flow_viz:FlowVizPlugin"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv.sources]
+functualize = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/functualize_flow_viz"]

functualize_flow_viz-0.1.0/src/functualize_flow_viz/__init__.py

@@ -0,0 +1,5 @@
+"""Functualize Flow Viz Plugin - Inline execution tree visualization."""
+
+from functualize_flow_viz.plugin import FlowVizConstruct, FlowVizPlugin, TreeNode
+
+__all__ = ["FlowVizConstruct", "FlowVizPlugin", "TreeNode"]

functualize_flow_viz-0.1.0/src/functualize_flow_viz/plugin.py

@@ -0,0 +1,363 @@
+"""Functualize Flow Viz Plugin — inline execution tree visualization.
+
+Renders a live job execution tree — status icons, durations, nested
+``rc.invoke()`` children, custom ``rc.emit`` events — as a hosted
+``LiveConstruct``.
+
+Architecture note: this plugin used to be a self-rendering ``Surface`` with two
+hand-rolled renderers (a non-TTY plain-text printer and a TTY renderer doing
+its own ANSI cursor math on a 0.5s daemon thread). That made it a second writer
+competing for the cursor with whatever else was drawing — the collision class
+the surface architecture exists to remove.
+
+Now it is a construct **hosted by a live zone**. The zone (``StdoutSurface`` on
+a direct run, ``PanelLiveZone`` in the TUI) owns the cursor and the refresh
+cadence, and Rich's own ``Live`` handles non-TTY degradation by printing final
+state only. That deletes the daemon thread, the cursor math, and the two-renderer
+split in one move.
+
+It registers as an **ambient construct**: it renders by default for jobs that
+invoke children (where a tree has something to show), with no job-author code.
+Users turn it off with ``[flow-viz] enabled = false``, ``[live] suppress``,
+``@job(suppress_live=["flow-viz"])``, or ``live.suppress("flow-viz")``.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = ["FlowVizConstruct", "FlowVizPlugin", "TreeNode"]
+
+
+# ─── Status Icons ─────────────────────────────────────────────────────
+
+ICON_RUNNING = "⏳"
+ICON_SUCCESS = "✓"
+ICON_FAILURE = "✗"
+ICON_PENDING = "○"
+ICON_TIMEOUT = "⊘"
+
+_STATUS_STYLES = {
+    "running": "yellow",
+    "success": "green",
+    "failure": "red",
+    "timeout": "red",
+    "pending": "dim",
+}
+
+
+def _status_icon(status: str) -> str:
+    """Return the icon for a status string."""
+    return {
+        "running": ICON_RUNNING,
+        "success": ICON_SUCCESS,
+        "failure": ICON_FAILURE,
+        "timeout": ICON_TIMEOUT,
+        "pending": ICON_PENDING,
+    }.get(status, ICON_PENDING)
+
+
+def _format_duration(duration_ms: float) -> str:
+    """Format a duration in ms as a compact human string."""
+    if duration_ms < 1000:
+        return f"{duration_ms:.0f}ms"
+    if duration_ms < 60_000:
+        return f"{duration_ms / 1000:.1f}s"
+    minutes = int(duration_ms // 60_000)
+    seconds = (duration_ms % 60_000) / 1000
+    return f"{minutes}m{seconds:.1f}s"
+
+
+# ─── Tree Node ────────────────────────────────────────────────────────
+
+
+@dataclass
+class TreeNode:
+    """A node in the execution tree representing a job or step."""
+
+    label: str
+    status: str = "pending"  # pending, running, success, failure, timeout
+    start_time: float | None = None
+    end_time: float | None = None
+    children: list[TreeNode] = field(default_factory=list)
+    events: list[str] = field(default_factory=list)
+    depth: int = 0
+
+    @property
+    def duration_ms(self) -> float:
+        """Elapsed duration in milliseconds."""
+        if self.start_time is None:
+            return 0.0
+        end = self.end_time if self.end_time is not None else time.time()
+        return (end - self.start_time) * 1000
+
+    def render_line(self) -> str:
+        """Render this node as a single line with icon, label, and duration."""
+        icon = _status_icon(self.status)
+        # `is not None`, not truthiness — matches `duration_ms` above, which
+        # already treats 0.0 as a real start time rather than "unstarted".
+        duration = (
+            _format_duration(self.duration_ms) if self.start_time is not None else ""
+        )
+        suffix = f" ({duration})" if duration else ""
+        return f"{icon} {self.label}{suffix}"
+
+
+# ─── Live Construct ───────────────────────────────────────────────────
+
+
+class FlowVizConstruct:
+    """A ``LiveConstruct`` that renders the execution tree.
+
+    ``__rich__()`` builds a ``rich.tree.Tree`` from current state;
+    ``handle_event()`` mutates that state from the structured event stream.
+    The hosting live zone decides when to repaint, so there is no refresh
+    thread and no cursor management here.
+    """
+
+    name: str = "flow-viz"
+
+    def __init__(self) -> None:
+        self._root: TreeNode | None = None
+        self._node_stack: list[TreeNode] = []
+
+    # ─── Rendering ────────────────────────────────────────────────────
+
+    def __rich__(self) -> Any:
+        """Return a ``rich.tree.Tree`` for the current execution state."""
+        from rich.tree import Tree
+
+        if self._root is None:
+            return Tree("")
+        tree = Tree(self._styled(self._root))
+        self._attach(tree, self._root)
+        return tree
+
+    def _styled(self, node: TreeNode) -> str:
+        """Render one node's line with a status-appropriate style."""
+        style = _STATUS_STYLES.get(node.status, "")
+        line = node.render_line()
+        return f"[{style}]{line}[/{style}]" if style else line
+
+    def _attach(self, branch: Any, node: TreeNode) -> None:
+        """Recursively attach a node's events and children to a Rich branch."""
+        for event in node.events:
+            branch.add(f"[dim]◆ {event}[/dim]")
+        for child in node.children:
+            child_branch = branch.add(self._styled(child))
+            self._attach(child_branch, child)
+
+    # ─── Event handling ───────────────────────────────────────────────
+
+    @property
+    def current_node(self) -> TreeNode | None:
+        """The node currently receiving events (deepest open scope)."""
+        if self._node_stack:
+            return self._node_stack[-1]
+        return self._root
+
+    def handle_event(self, event: Any) -> None:
+        """Update tree state from one structured event.
+
+        The engine's job vocabulary is ``job.execute.start`` /
+        ``job.execute.end`` / ``job.execute.error`` (see
+        ``_events/_catalog_entries.py``). Nesting is **not** a separate
+        ``invoke.*`` event pair — a child started via ``rc.invoke()`` emits the
+        same ``job.execute.*`` names carrying an ``invoke_depth`` payload, so
+        the tree is built from that depth rather than from an open/close stack.
+
+        Caveat — the lifecycle branch is currently unreachable: ``job.execute.``
+        is one of ``RunContext._FRAMEWORK_EVENT_PREFIXES``, which
+        ``_dispatch_to_surfaces`` filters out, so surfaces (and therefore
+        hosted constructs) only ever see custom ``rc.emit`` events. The
+        handling is kept because it is the correct mapping the moment lifecycle
+        events are surfaced, and because it costs nothing meanwhile. See
+        ``contributor/architecture/event-vocabulary.md``.
+
+        Unrecognized events are recorded on the current node rather than
+        dropped, so a domain's custom ``rc.emit`` still shows up in the tree.
+        """
+        event_name = str(getattr(event, "event_name", "") or "")
+        payload = getattr(event, "payload", {}) or {}
+        resource = getattr(event, "resource", "") or ""
+
+        if event_name == "job.execute.start":
+            self._job_started(event_name, resource, payload)
+        elif event_name in ("job.execute.end", "job.execute.error"):
+            self._job_ended(event_name, resource, payload)
+        else:
+            self._record_custom(event_name, resource, payload)
+
+    # ─── State transitions ────────────────────────────────────────────
+
+    def _label_for(self, resource: str, payload: dict[str, Any], fallback: str) -> str:
+        for key in ("job_name", "name", "step", "child_job_name"):
+            value = payload.get(key)
+            if value:
+                return str(value)
+        return resource or fallback
+
+    def _job_started(
+        self, event_name: str, resource: str, payload: dict[str, Any]
+    ) -> None:
+        """Open a node at the event's ``invoke_depth``.
+
+        Depth 0 is the top-level job (the root); deeper events are children
+        started by ``rc.invoke()``. Unwinding to the right parent by depth is
+        what makes nesting work without paired invoke events.
+        """
+        label = self._label_for(resource, payload, "job")
+        depth = _depth_of(payload)
+        node = TreeNode(
+            label=label, status="running", start_time=time.time(), depth=depth
+        )
+
+        if self._root is None or depth == 0:
+            if self._root is None:
+                self._root = node
+                self._node_stack = [node]
+            else:
+                # A second depth-0 job in one window (a fresh run against a
+                # reused construct): restart rather than graft onto the old
+                # tree, which would misreport the previous run as this one.
+                self._root = node
+                self._node_stack = [node]
+            return
+
+        # Unwind to this node's parent, then attach.
+        while self._node_stack and self._node_stack[-1].depth >= depth:
+            self._node_stack.pop()
+        parent = self._node_stack[-1] if self._node_stack else self._root
+        parent.children.append(node)
+        self._node_stack.append(node)
+
+    def _job_ended(
+        self, event_name: str, resource: str, payload: dict[str, Any]
+    ) -> None:
+        """Close the node this event terminates, matched by name then depth."""
+        status = _status_from(event_name, payload)
+        label = self._label_for(resource, payload, "job")
+
+        for index in range(len(self._node_stack) - 1, -1, -1):
+            node = self._node_stack[index]
+            if node.label == label:
+                node.status = status
+                node.end_time = time.time()
+                del self._node_stack[index:]
+                return
+
+        # No open node matched (a end without its start) — fall back to the
+        # root so a completed run is never left rendering as still running.
+        if self._root is not None and self._root.end_time is None:
+            self._root.status = status
+            self._root.end_time = time.time()
+
+    def _record_custom(
+        self, event_name: str, resource: str, payload: dict[str, Any]
+    ) -> None:
+        """Attach a custom ``rc.emit`` event to the current node."""
+        node = self.current_node
+        if node is None:
+            # No job scope yet — start one so custom events are still visible.
+            self._root = TreeNode(
+                label="events", status="running", start_time=time.time()
+            )
+            node = self._root
+
+        if "progress" in payload:
+            progress = payload["progress"]
+            bar_width = 20
+            try:
+                filled = int(bar_width * float(progress) / 100)
+            except (TypeError, ValueError):
+                filled = 0
+            filled = max(0, min(bar_width, filled))
+            bar = "█" * filled + "░" * (bar_width - filled)
+            node.events.append(f"{event_name}: [{bar}] {progress}%")
+        elif resource:
+            node.events.append(f"{event_name} ({resource})")
+        elif event_name:
+            node.events.append(event_name)
+
+
+def _depth_of(payload: dict[str, Any]) -> int:
+    """Read ``invoke_depth`` off a job event payload (0 when absent)."""
+    try:
+        return max(0, int(payload.get("invoke_depth", 0) or 0))
+    except (TypeError, ValueError):
+        return 0
+
+
+def _status_from(event_name: str, payload: dict[str, Any]) -> str:
+    """Derive a node status from a terminal event name or its payload."""
+    if event_name.endswith(".error") or event_name.endswith(".failed"):
+        return "failure"
+    status = payload.get("status")
+    if status is not None:
+        value = getattr(status, "value", status)
+        text = str(value).lower()
+        if text in _STATUS_STYLES:
+            return text
+    return "success"
+
+
+# ─── Plugin Class ─────────────────────────────────────────────────────
+
+
+class FlowVizPlugin:
+    """Registers the flow-viz tree as an ambient live construct.
+
+    Implements PluginConfigProtocol (``__call__``) for auto-registration via
+    the ``functualize.plugins`` entry point.
+
+    Deliberately not a ``PromptCollector``: it draws, it does not ask. Giving
+    it a stub ``collect`` would make it win prompt resolution and swallow
+    prompts it cannot answer — and it auto-loads, so that would break
+    prompting for every project that installs it.
+    """
+
+    name: str = "flow-viz"
+    version: str = "0.2.0"
+    description: str = "Inline flow visualization for job execution"
+
+    def __call__(self, app: Any) -> None:
+        """Register the construct as an ambient default, unless disabled."""
+        if not _enabled(app):
+            return
+        with contextlib.suppress(Exception):
+            app.register_ambient_construct(
+                FlowVizConstruct,
+                name="flow-viz",
+                predicate=_renders_for,
+            )
+
+
+def _renders_for(descriptor: Any) -> bool:
+    """Only render for jobs that invoke children — a tree needs branches.
+
+    A single-step job's tree is one line that repeats what the log already
+    says, so the default stays out of the way.
+    """
+    if descriptor is None:
+        return False
+    if getattr(descriptor, "uses_invoke", False):
+        return True
+    steps = getattr(descriptor, "workflow_steps", None)
+    return bool(steps) and len(steps) > 1
+
+
+def _enabled(app: Any) -> bool:
+    """Whether ``[flow-viz] enabled`` permits registration (default True)."""
+    try:
+        settings = getattr(app, "settings", None)
+        if settings is None:
+            return True
+        value = settings.get("flow-viz.enabled", True)
+        if isinstance(value, str):
+            return value.strip().lower() not in {"false", "0", "no", "off"}
+        return bool(value)
+    except Exception:
+        return True

functualize_flow_viz-0.1.0/tests/conftest.py

@@ -0,0 +1 @@
+"""Shared fixtures for functualize-flow-viz plugin tests."""

functualize_flow_viz-0.1.0/tests/test_flow_viz_plugin.py

@@ -0,0 +1,265 @@
+"""Tests for the flow-viz plugin as a hosted LiveConstruct.
+
+The plugin used to be a self-rendering Surface with two hand-rolled renderers
+(``PlainTextRenderer`` / ``InlineTTYRenderer``); this suite replaced the tests
+written around those. What matters now is:
+
+- ``handle_event`` builds the right tree state from the event stream,
+- ``__rich__`` renders that state as a ``rich.tree.Tree``,
+- the plugin registers as an *ambient* construct with a sensible predicate,
+- the config lever actually suppresses registration.
+"""
+
+from __future__ import annotations
+
+import io
+from typing import Any
+
+import pytest
+from functualize_flow_viz import FlowVizConstruct, FlowVizPlugin, TreeNode
+from rich.console import Console
+
+
+class _Event:
+    """Minimal stand-in for a StructuredEvent."""
+
+    def __init__(self, event_name: str, resource: str = "", **payload: Any) -> None:
+        self.event_name = event_name
+        self.resource = resource
+        self.payload = payload
+
+
+def _render(construct: FlowVizConstruct) -> str:
+    console = Console(file=io.StringIO(), width=100, force_terminal=False)
+    console.print(construct.__rich__())
+    return console.file.getvalue()  # type: ignore[union-attr]
+
+
+# ─── Tree state from events ───────────────────────────────────────────
+
+
+def test_job_started_creates_the_root() -> None:
+    c = FlowVizConstruct()
+    c.handle_event(_Event("job.execute.start", job_name="deploy", invoke_depth=0))
+
+    assert c._root is not None
+    assert c._root.label == "deploy"
+    assert c._root.status == "running"
+    assert "deploy" in _render(c)
+
+
+def test_job_completed_marks_the_root_successful() -> None:
+    c = FlowVizConstruct()
+    c.handle_event(_Event("job.execute.start", job_name="deploy", invoke_depth=0))
+    c.handle_event(_Event("job.execute.end", job_name="deploy", status="success"))
+
+    assert c._root is not None
+    assert c._root.status == "success"
+    assert c._root.end_time is not None
+
+
+def test_job_failed_marks_the_root_failed() -> None:
+    c = FlowVizConstruct()
+    c.handle_event(_Event("job.execute.start", job_name="deploy", invoke_depth=0))
+    c.handle_event(_Event("job.execute.error", job_name="deploy"))
+
+    assert c._root is not None
+    assert c._root.status == "failure"
+
+
+def test_invoke_depth_nests_a_child_under_the_job() -> None:
+    c = FlowVizConstruct()
+    c.handle_event(_Event("job.execute.start", job_name="deploy", invoke_depth=0))
+    c.handle_event(_Event("job.execute.start", job_name="migrate", invoke_depth=1))
+    c.handle_event(_Event("job.execute.end", job_name="migrate", status="success"))
+
+    assert c._root is not None
+    assert [child.label for child in c._root.children] == ["migrate"]
+    assert c._root.children[0].status == "success"
+
+    rendered = _render(c)
+    assert "deploy" in rendered
+    assert "migrate" in rendered
+
+
+def test_deeper_invoke_depth_nests_and_unwinds() -> None:
+    c = FlowVizConstruct()
+    c.handle_event(_Event("job.execute.start", job_name="deploy", invoke_depth=0))
+    c.handle_event(_Event("job.execute.start", job_name="migrate", invoke_depth=1))
+    c.handle_event(_Event("job.execute.start", job_name="seed", invoke_depth=2))
+
+    assert c.current_node is not None
+    assert c.current_node.label == "seed"
+
+    c.handle_event(_Event("job.execute.end", job_name="seed", status="success"))
+    assert c.current_node is not None
+    assert c.current_node.label == "migrate"
+
+    c.handle_event(_Event("job.execute.end", job_name="migrate", status="success"))
+    assert c.current_node is c._root
+
+    assert c._root is not None
+    migrate = c._root.children[0]
+    assert [g.label for g in migrate.children] == ["seed"]
+
+
+def test_failed_child_is_marked_failure() -> None:
+    c = FlowVizConstruct()
+    c.handle_event(_Event("job.execute.start", job_name="deploy", invoke_depth=0))
+    c.handle_event(_Event("job.execute.start", job_name="migrate", invoke_depth=1))
+    c.handle_event(_Event("job.execute.error", job_name="migrate"))
+
+    assert c._root is not None
+    assert c._root.children[0].status == "failure"
+
+
+def test_custom_events_attach_to_the_current_node() -> None:
+    c = FlowVizConstruct()
+    c.handle_event(_Event("job.execute.start", job_name="deploy", invoke_depth=0))
+    c.handle_event(_Event("upload.chunk", resource="s3://bucket"))
+
+    assert c._root is not None
+    assert any("upload.chunk" in e for e in c._root.events)
+    assert "upload.chunk" in _render(c)
+
+
+def test_progress_payload_renders_a_bar() -> None:
+    c = FlowVizConstruct()
+    c.handle_event(_Event("job.execute.start", job_name="deploy", invoke_depth=0))
+    c.handle_event(_Event("upload.progress", progress=50))
+
+    assert c._root is not None
+    recorded = c._root.events[0]
+    assert "█" in recorded and "░" in recorded
+    assert "50%" in recorded
+
+
+def test_custom_event_before_any_job_still_renders() -> None:
+    """Events with no job scope must not be silently dropped."""
+    c = FlowVizConstruct()
+    c.handle_event(_Event("standalone.thing"))
+
+    assert c._root is not None
+    assert "standalone.thing" in _render(c)
+
+
+def test_empty_construct_renders_without_error() -> None:
+    assert _render(FlowVizConstruct()) is not None
+
+
+def test_each_construct_has_independent_state() -> None:
+    """The plugin registers a factory, so runs must not share a tree."""
+    a, b = FlowVizConstruct(), FlowVizConstruct()
+    a.handle_event(_Event("job.execute.start", job_name="first", invoke_depth=0))
+
+    assert b._root is None
+
+
+# ─── Node rendering ───────────────────────────────────────────────────
+
+
+def test_node_line_includes_icon_and_duration() -> None:
+    node = TreeNode(label="deploy", status="success", start_time=0.0, end_time=1.5)
+    line = node.render_line()
+
+    assert "deploy" in line
+    assert "✓" in line
+    assert "1.5s" in line
+
+
+def test_pending_node_has_no_duration_suffix() -> None:
+    assert TreeNode(label="deploy").render_line().strip().endswith("deploy")
+
+
+# ─── Plugin registration ──────────────────────────────────────────────
+
+
+class _FakeSettings:
+    def __init__(self, values: dict[str, Any] | None = None) -> None:
+        self._values = values or {}
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self._values.get(key, default)
+
+
+class _FakeApp:
+    def __init__(self, settings: _FakeSettings | None = None) -> None:
+        self.settings = settings
+        self.registered: list[tuple[Any, str, Any]] = []
+
+    def register_ambient_construct(
+        self, factory: Any, *, name: str | None = None, predicate: Any = None
+    ) -> None:
+        self.registered.append((factory, name or "", predicate))
+
+
+class _Descriptor:
+    def __init__(self, uses_invoke: bool = False, workflow_steps: Any = None) -> None:
+        self.uses_invoke = uses_invoke
+        self.workflow_steps = workflow_steps or []
+
+
+def test_plugin_registers_an_ambient_construct() -> None:
+    app = _FakeApp()
+    FlowVizPlugin()(app)
+
+    assert len(app.registered) == 1
+    factory, name, predicate = app.registered[0]
+    assert factory is FlowVizConstruct
+    assert name == "flow-viz"
+    assert predicate is not None
+
+
+def test_plugin_registers_a_factory_not_an_instance() -> None:
+    """Each run needs fresh tree state, so registration must pass the class."""
+    app = _FakeApp()
+    FlowVizPlugin()(app)
+
+    factory = app.registered[0][0]
+    assert isinstance(factory(), FlowVizConstruct)
+    assert factory() is not factory()
+
+
+@pytest.mark.parametrize(
+    ("descriptor", "expected"),
+    [
+        (_Descriptor(uses_invoke=True), True),
+        (_Descriptor(workflow_steps=["a", "b"]), True),
+        (_Descriptor(uses_invoke=False), False),
+        (_Descriptor(workflow_steps=["only-one"]), False),
+        (None, False),
+    ],
+)
+def test_predicate_targets_jobs_with_branches(descriptor: Any, expected: bool) -> None:
+    """The tree renders only where it has something to show."""
+    app = _FakeApp()
+    FlowVizPlugin()(app)
+    predicate = app.registered[0][2]
+
+    assert predicate(descriptor) is expected
+
+
+def test_disabled_by_config_skips_registration() -> None:
+    app = _FakeApp(_FakeSettings({"flow-viz.enabled": False}))
+    FlowVizPlugin()(app)
+
+    assert app.registered == []
+
+
+def test_disabled_by_string_config_skips_registration() -> None:
+    app = _FakeApp(_FakeSettings({"flow-viz.enabled": "false"}))
+    FlowVizPlugin()(app)
+
+    assert app.registered == []
+
+
+def test_enabled_by_default_without_settings() -> None:
+    app = _FakeApp(_FakeSettings({}))
+    FlowVizPlugin()(app)
+
+    assert len(app.registered) == 1
+
+
+def test_plugin_is_not_a_prompt_collector() -> None:
+    """It draws; it must never win prompt resolution."""
+    assert not hasattr(FlowVizPlugin(), "collect")

functualize_flow_viz-0.1.0/tests/test_plugin.py

@@ -0,0 +1,15 @@
+"""Unit tests for functualize-flow-viz plugin.
+
+Tests the flow visualization plugin's graph rendering and export.
+"""
+
+from __future__ import annotations
+
+
+class TestImports:
+    """Verify the plugin is importable."""
+
+    def test_import_package(self):
+        import functualize_flow_viz
+
+        assert dir(functualize_flow_viz)