jstdata 0.2.0__py3-none-any.whl

jstdata/workflows/session_manager.py

@@ -0,0 +1,277 @@
+"""Host-level session modal: list, remove, and inspect session resources."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any
+
+from textual import on, work
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.containers import Horizontal, Vertical
+from textual.screen import ModalScreen
+from textual.widgets import Label, ListItem, ListView, Static
+
+from ..client import JSTDataClient
+from ..session import Session
+from .base import label_for
+
+_PLACEHOLDER = "Highlight an item and press i to inspect."
+
+
+class SessionResourceRow(ListItem):
+    """One staged resource in the session list (single compact line)."""
+
+    def __init__(self, resource_id: str, resource_type: str, display_name: str) -> None:
+        super().__init__()
+        self.resource_id = resource_id
+        self.resource_type = resource_type
+        self.display_name = display_name
+
+    def compose(self) -> ComposeResult:
+        yield Label(
+            f"{self.resource_type.upper():<8} {self.display_name}  [{self.resource_id}]",
+            classes="sess-row-label",
+        )
+
+
+class SessionManagerModal(ModalScreen[None]):
+    """Shared session browser: remove items, inspect API payloads."""
+
+    DEFAULT_CSS = """
+    SessionManagerModal {
+        align: center middle;
+        background: rgba(0, 0, 0, 0.7);
+    }
+
+    #session-mgr-container {
+        width: 90%;
+        height: 80%;
+        max-width: 140;
+        max-height: 40;
+        border: thick #4ade80;
+        background: #111111;
+        padding: 1 1;
+    }
+
+    #session-mgr-title {
+        text-style: bold;
+        color: #4ade80;
+        text-align: center;
+        height: 1;
+        margin-bottom: 1;
+    }
+
+    #session-mgr-body {
+        height: 1fr;
+        width: 100%;
+    }
+
+    #session-list-pane {
+        width: 1fr;
+        height: 100%;
+        border-right: solid #333;
+        padding-right: 1;
+    }
+
+    #session-inspect-pane {
+        width: 1fr;
+        height: 100%;
+        padding-left: 1;
+    }
+
+    .session-pane-header {
+        color: #4ade80;
+        text-style: bold;
+        height: 1;
+        margin-bottom: 1;
+    }
+
+    #session-resource-list {
+        height: 1fr;
+        width: 100%;
+        background: #0a0a0a;
+        border: solid #222;
+    }
+
+    SessionResourceRow {
+        height: 1;
+        min-height: 1;
+        max-height: 1;
+        width: 100%;
+        padding: 0 1;
+        overflow: hidden;
+    }
+
+    SessionResourceRow:hover,
+    SessionResourceRow.-highlighted {
+        background: #1a3a1a;
+    }
+
+    .sess-row-label {
+        width: 100%;
+        height: 1;
+        color: #e0e0e0;
+        overflow: hidden;
+    }
+
+    ListView > ListItem {
+        height: 1;
+        min-height: 1;
+        max-height: 1;
+    }
+
+    #session-inspect-payload {
+        height: 1fr;
+        width: 100%;
+        background: #0a0a0a;
+        border: solid #222;
+        color: #e0e0e0;
+        padding: 1;
+        overflow-y: auto;
+        overflow-x: auto;
+    }
+
+    #session-mgr-hint {
+        color: #888;
+        height: 1;
+        margin-top: 1;
+        dock: bottom;
+    }
+    """
+
+    BINDINGS = [
+        Binding("escape", "dismiss", "Close"),
+        Binding("i", "inspect", "Inspect"),
+        Binding("backspace", "remove", "Remove"),
+        Binding("delete", "remove", "Remove", show=False),
+        Binding("j", "cursor_down", "Down", show=False),
+        Binding("k", "cursor_up", "Up", show=False),
+        Binding("down", "cursor_down", "Down", show=False),
+        Binding("up", "cursor_up", "Up", show=False),
+    ]
+
+    def __init__(
+        self,
+        client: JSTDataClient,
+        session: Session,
+        labels: dict[str, str],
+    ) -> None:
+        super().__init__()
+        self.client = client
+        self.session = session
+        self.labels = labels
+        self._inspected_id: str | None = None
+
+    def compose(self) -> ComposeResult:
+        with Vertical(id="session-mgr-container"):
+            yield Label("SESSION // STAGED RESOURCES", id="session-mgr-title")
+            with Horizontal(id="session-mgr-body"):
+                with Vertical(id="session-list-pane"):
+                    yield Label("RESOURCES", classes="session-pane-header")
+                    yield ListView(id="session-resource-list")
+                with Vertical(id="session-inspect-pane"):
+                    yield Label("INSPECT", classes="session-pane-header")
+                    yield Static(_PLACEHOLDER, id="session-inspect-payload", markup=False)
+            yield Label(
+                "[bold]i[/bold] inspect  //  [bold]backspace[/bold] remove  //  "
+                "[bold]j[/bold]/[bold]k[/bold] or [bold]↑[/bold]/[bold]↓[/bold]  //  [bold]esc[/bold] close",
+                id="session-mgr-hint",
+                markup=True,
+            )
+
+    def on_mount(self) -> None:
+        self._rebuild_list()
+        self.query_one("#session-resource-list", ListView).focus()
+
+    def _iter_session_entries(self) -> list[tuple[str, str]]:
+        """(resource_type, id) in stable metric → entity → series order."""
+        entries: list[tuple[str, str]] = []
+        for mid in self.session.metric:
+            entries.append(("metric", mid))
+        for eid in self.session.entity:
+            entries.append(("entity", eid))
+        for sid in self.session.series:
+            entries.append(("series", sid))
+        return entries
+
+    def _rebuild_list(self) -> None:
+        list_view = self.query_one("#session-resource-list", ListView)
+        list_view.clear()
+        entries = self._iter_session_entries()
+        if not entries:
+            list_view.append(
+                ListItem(Label("Session is empty", classes="sess-row-label"), disabled=True)
+            )
+            self._show_placeholder()
+            return
+        for rtype, rid in entries:
+            list_view.append(
+                SessionResourceRow(rid, rtype, label_for(self.labels, rid))
+            )
+
+    def _show_placeholder(self) -> None:
+        self._inspected_id = None
+        self.query_one("#session-inspect-payload", Static).update(_PLACEHOLDER)
+
+    def _highlighted_row(self) -> SessionResourceRow | None:
+        list_view = self.query_one("#session-resource-list", ListView)
+        child = list_view.highlighted_child
+        if isinstance(child, SessionResourceRow):
+            return child
+        return None
+
+    @on(ListView.Highlighted, "#session-resource-list")
+    def on_highlight_changed(self, event: ListView.Highlighted) -> None:
+        row = event.item if isinstance(event.item, SessionResourceRow) else None
+        if row is None or row.resource_id != self._inspected_id:
+            self._show_placeholder()
+
+    def action_inspect(self) -> None:
+        row = self._highlighted_row()
+        if row is None:
+            self.notify("Select a resource to inspect", severity="warning")
+            return
+        self.query_one("#session-inspect-payload", Static).update("Fetching...")
+        self._fetch_payload(row.resource_type, row.resource_id)
+
+    @work(exclusive=True)
+    async def _fetch_payload(self, resource_type: str, resource_id: str) -> None:
+        try:
+            data = await asyncio.to_thread(
+                self.client.make_request, f"{resource_type}/{resource_id}"
+            )
+            text = json.dumps(data, indent=2, default=str)
+            self._inspected_id = resource_id
+            self.query_one("#session-inspect-payload", Static).update(text)
+        except Exception as e:
+            self._inspected_id = None
+            self.query_one("#session-inspect-payload", Static).update(
+                f"Inspect failed: {e}"
+            )
+
+    def action_remove(self) -> None:
+        row = self._highlighted_row()
+        if row is None:
+            return
+        self._remove_resource(row)
+
+    def _remove_resource(self, row: SessionResourceRow) -> None:
+        rid = row.resource_id
+        self.session.remove_id(rid)
+        self.labels.pop(rid, None)
+        if self._inspected_id == rid:
+            self._show_placeholder()
+        self._rebuild_list()
+        self.notify(f"Removed {rid}")
+        self.query_one("#session-resource-list", ListView).focus()
+
+    def action_cursor_down(self) -> None:
+        self.query_one("#session-resource-list", ListView).action_cursor_down()
+
+    def action_cursor_up(self) -> None:
+        self.query_one("#session-resource-list", ListView).action_cursor_up()
+
+    def action_dismiss(self) -> None:
+        self.dismiss()

jstdata/workflows/store.py

@@ -0,0 +1,308 @@
+"""Persisted workflows: named pipelines saved as YAML under ``~/.jstdata/workflows``.
+
+Steps are the catalog units (``jst steps`` / ``jst run``). Workflows are
+user-saved compositions of those steps.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+import yaml
+
+from importlib.resources import files
+
+from ..client import APP_DIR
+from .base import PipelineError, ResolvedStep, resolve_pipeline
+
+WORKFLOWS_DIR = APP_DIR / "workflows"
+TUTORIAL_WORKFLOW_ID = "tutorial"
+BUNDLED_WORKFLOW_IDS = frozenset({TUTORIAL_WORKFLOW_ID})
+_SLUG_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+
+
+class WorkflowStoreError(ValueError):
+    """Invalid workflow id, missing file, or corrupt YAML."""
+
+
+@dataclass(frozen=True)
+class SavedStep:
+    """One step in a saved workflow (id + seed args)."""
+
+    id: str
+    args: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        data: dict[str, Any] = {"id": self.id}
+        if self.args:
+            data["args"] = dict(self.args)
+        return data
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> SavedStep:
+        if not isinstance(data, dict) or "id" not in data:
+            raise WorkflowStoreError("Each step must be a mapping with an 'id'.")
+        args = data.get("args") or {}
+        if not isinstance(args, dict):
+            raise WorkflowStoreError(f"Step {data['id']!r} args must be a mapping.")
+        return cls(id=str(data["id"]), args=dict(args))
+
+
+@dataclass(frozen=True)
+class SavedWorkflow:
+    """User-saved pipeline stored on disk."""
+
+    id: str
+    description: str = ""
+    steps: tuple[SavedStep, ...] = ()
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "description": self.description or "",
+            "steps": [s.to_dict() for s in self.steps],
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> SavedWorkflow:
+        if not isinstance(data, dict):
+            raise WorkflowStoreError("Workflow file must be a YAML mapping.")
+        wid = data.get("id")
+        if not wid or not isinstance(wid, str):
+            raise WorkflowStoreError("Workflow is missing a string 'id'.")
+        validate_workflow_id(wid)
+        raw_steps = data.get("steps")
+        if not isinstance(raw_steps, list) or not raw_steps:
+            raise WorkflowStoreError(f"Workflow {wid!r} must list at least one step.")
+        steps = tuple(SavedStep.from_dict(s) for s in raw_steps)
+        description = data.get("description") or ""
+        if not isinstance(description, str):
+            raise WorkflowStoreError("Workflow 'description' must be a string.")
+        return cls(id=wid, description=description, steps=steps)
+
+    @classmethod
+    def from_resolved(
+        cls,
+        workflow_id: str,
+        description: str,
+        resolved: list[ResolvedStep],
+    ) -> SavedWorkflow:
+        validate_workflow_id(workflow_id)
+        if not resolved:
+            raise WorkflowStoreError("Pipeline is empty.")
+        steps = tuple(
+            SavedStep(id=r.spec.id, args=dict(r.kwargs)) for r in resolved
+        )
+        return cls(id=workflow_id, description=description or "", steps=steps)
+
+
+def validate_workflow_id(workflow_id: str) -> str:
+    """Require a lowercase slug: ``gdp-rank``, not ``GDP Rank``."""
+    if not _SLUG_RE.match(workflow_id):
+        raise WorkflowStoreError(
+            f"Invalid workflow id {workflow_id!r}. "
+            "Use a slug like 'gdp-rank' (lowercase letters, digits, hyphens)."
+        )
+    return workflow_id
+
+
+def is_bundled_workflow(workflow_id: str) -> bool:
+    return workflow_id in BUNDLED_WORKFLOW_IDS
+
+
+def load_bundled_workflow(workflow_id: str) -> SavedWorkflow:
+    if not is_bundled_workflow(workflow_id):
+        raise WorkflowStoreError(f"No built-in workflow named {workflow_id!r}.")
+    try:
+        text = files("jstdata.workflows.bundled").joinpath(
+            f"{workflow_id}.yaml"
+        ).read_text(encoding="utf-8")
+    except FileNotFoundError as exc:
+        raise WorkflowStoreError(
+            f"Built-in workflow {workflow_id!r} is missing from the package."
+        ) from exc
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError as exc:
+        raise WorkflowStoreError(f"Could not parse built-in {workflow_id!r}: {exc}") from exc
+    workflow = SavedWorkflow.from_dict(data or {})
+    if workflow.id != workflow_id:
+        raise WorkflowStoreError(
+            f"Built-in workflow file has id {workflow.id!r}, expected {workflow_id!r}."
+        )
+    return workflow
+
+
+def list_bundled_workflows() -> list[SavedWorkflow]:
+    return [load_bundled_workflow(wid) for wid in sorted(BUNDLED_WORKFLOW_IDS)]
+
+
+def workflow_path(workflow_id: str, *, root: Optional[Path] = None) -> Path:
+    validate_workflow_id(workflow_id)
+    base = root if root is not None else WORKFLOWS_DIR
+    return base / f"{workflow_id}.yaml"
+
+
+def ensure_workflows_dir(*, root: Optional[Path] = None) -> Path:
+    base = root if root is not None else WORKFLOWS_DIR
+    base.mkdir(parents=True, exist_ok=True)
+    return base
+
+
+def workflow_exists(workflow_id: str, *, root: Optional[Path] = None) -> bool:
+    return workflow_path(workflow_id, root=root).is_file()
+
+
+def save_workflow(
+    workflow: SavedWorkflow,
+    *,
+    root: Optional[Path] = None,
+) -> Path:
+    """Write workflow YAML; overwrites if the file already exists."""
+    ensure_workflows_dir(root=root)
+    path = workflow_path(workflow.id, root=root)
+    with path.open("w", encoding="utf-8") as f:
+        yaml.safe_dump(
+            workflow.to_dict(),
+            f,
+            default_flow_style=False,
+            sort_keys=False,
+            allow_unicode=True,
+        )
+    return path
+
+
+def load_workflow(
+    workflow_id: str,
+    *,
+    root: Optional[Path] = None,
+) -> SavedWorkflow:
+    validate_workflow_id(workflow_id)
+    if root is not None:
+        path = root / f"{workflow_id}.yaml"
+        if not path.is_file():
+            raise WorkflowStoreError(f"No workflow named {workflow_id!r}.")
+        try:
+            with path.open(encoding="utf-8") as f:
+                data = yaml.safe_load(f)
+        except yaml.YAMLError as exc:
+            raise WorkflowStoreError(f"Could not parse {path}: {exc}") from exc
+        workflow = SavedWorkflow.from_dict(data or {})
+        if workflow.id != workflow_id:
+            raise WorkflowStoreError(
+                f"Workflow file {path.name} has id {workflow.id!r}, "
+                f"expected {workflow_id!r}."
+            )
+        return workflow
+
+    path = workflow_path(workflow_id)
+    if path.is_file():
+        try:
+            with path.open(encoding="utf-8") as f:
+                data = yaml.safe_load(f)
+        except yaml.YAMLError as exc:
+            raise WorkflowStoreError(f"Could not parse {path}: {exc}") from exc
+        workflow = SavedWorkflow.from_dict(data or {})
+        if workflow.id != workflow_id:
+            raise WorkflowStoreError(
+                f"Workflow file {path.name} has id {workflow.id!r}, "
+                f"expected {workflow_id!r}."
+            )
+        return workflow
+    if is_bundled_workflow(workflow_id):
+        return load_bundled_workflow(workflow_id)
+    raise WorkflowStoreError(f"No workflow named {workflow_id!r}.")
+
+
+def delete_workflow(workflow_id: str, *, root: Optional[Path] = None) -> None:
+    if root is None and is_bundled_workflow(workflow_id):
+        raise WorkflowStoreError(
+            f"Cannot remove built-in workflow {workflow_id!r}."
+        )
+    path = workflow_path(workflow_id, root=root)
+    if not path.is_file():
+        raise WorkflowStoreError(f"No workflow named {workflow_id!r}.")
+    path.unlink()
+
+
+def list_saved_workflows(*, root: Optional[Path] = None) -> list[SavedWorkflow]:
+    if root is not None:
+        base = root
+        if not base.is_dir():
+            return []
+        out: list[SavedWorkflow] = []
+        for path in sorted(base.glob("*.yaml")):
+            try:
+                with path.open(encoding="utf-8") as f:
+                    data = yaml.safe_load(f)
+                out.append(SavedWorkflow.from_dict(data or {}))
+            except (WorkflowStoreError, yaml.YAMLError, OSError):
+                continue
+        return out
+
+    seen: set[str] = set()
+    out: list[SavedWorkflow] = []
+    for wf in list_bundled_workflows():
+        out.append(wf)
+        seen.add(wf.id)
+    base = WORKFLOWS_DIR
+    if base.is_dir():
+        for path in sorted(base.glob("*.yaml")):
+            try:
+                with path.open(encoding="utf-8") as f:
+                    data = yaml.safe_load(f)
+                wf = SavedWorkflow.from_dict(data or {})
+            except (WorkflowStoreError, yaml.YAMLError, OSError):
+                continue
+            if wf.id in seen:
+                continue
+            out.append(wf)
+            seen.add(wf.id)
+    return out
+
+
+def workflow_to_tokens(workflow: SavedWorkflow) -> list[str]:
+    """Rebuild ``jst run``-style argv from structured YAML (no raw argv stored)."""
+    tokens: list[str] = []
+    for i, step in enumerate(workflow.steps):
+        if i:
+            tokens.append(":")
+        tokens.append(step.id)
+        for name, value in step.args.items():
+            flag = "--" + str(name).replace("_", "-")
+            if isinstance(value, bool):
+                if value:
+                    tokens.append(flag)
+                continue
+            values = value if isinstance(value, (list, tuple)) else [value]
+            for item in values:
+                tokens.append(flag)
+                tokens.append(str(item))
+    return tokens
+
+
+def format_pipeline(workflow: SavedWorkflow) -> str:
+    """One-line pipeline summary for ``jst workflow ls``."""
+    return " ".join(workflow_to_tokens(workflow))
+
+
+def resolve_saved_workflow(workflow: SavedWorkflow) -> list[ResolvedStep]:
+    """Validate a saved workflow against the live step catalog (no UI)."""
+    try:
+        return resolve_pipeline(workflow_to_tokens(workflow))
+    except KeyError as exc:
+        raise PipelineError(str(exc)) from exc
+
+
+def create_workflow_from_tokens(
+    workflow_id: str,
+    description: str,
+    tokens: list[str],
+) -> SavedWorkflow:
+    """Parse/validate pipeline tokens, then build a SavedWorkflow."""
+    validate_workflow_id(workflow_id)
+    resolved = resolve_pipeline(tokens)
+    return SavedWorkflow.from_resolved(workflow_id, description, resolved)