aetherius 0.2.0__py3-none-any.whl

aetherius/console/screens/library.py

@@ -0,0 +1,124 @@
+"""Browse the Blueprint library: discover, validate, and open one into the Runs screen."""
+
+from __future__ import annotations
+
+from rich.text import Text
+
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.containers import Vertical
+from textual.screen import Screen
+from textual.widgets import DataTable, Footer, Header, Static
+
+from ...core.runtime.engine import IMPLEMENTED_ACTS
+from ..theme import ACT_LABELS, AMBER, LAUREL, POMPEIAN, STONE, act_color, starred
+from .library_scan import (
+    BlueprintEntry,
+    EntryStatus,
+    discover_blueprint_dirs,
+    entry_status,
+    scan_blueprints,
+)
+
+# How each status reads in the table: label + colour. Runnable is the only "go" state.
+_STATUS_STYLE: dict[EntryStatus, tuple[str, str]] = {
+    EntryStatus.READY: ("ready", f"bold {LAUREL}"),
+    EntryStatus.ACT_PENDING: ("act pending", AMBER),
+    EntryStatus.INVALID: ("invalid", f"bold {POMPEIAN}"),
+}
+
+
+class LibraryScreen(Screen[None]):
+    """Lists every Blueprint found under the discovered directories."""
+
+    BINDINGS = [
+        Binding("r", "rescan", "Rescan"),
+        Binding("e", "edit", "Edit in Studio"),
+    ]
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._entries: list[BlueprintEntry] = []
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        with Vertical(classes="console-body"):
+            yield Static(starred("Blueprint Library"), classes="console-title")
+            yield Static(
+                "Enter opens a Blueprint in Runs. 'ready' runs now; 'act pending' is well-formed "
+                "but its Act has no driver yet; 'invalid' fails the schema or its Act's actions.",
+                classes="console-subtitle",
+            )
+            yield DataTable(id="library-table", cursor_type="row")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self._rescan()
+
+    def action_rescan(self) -> None:
+        self._rescan()
+
+    def action_edit(self) -> None:
+        """Open the highlighted Blueprint in the Studio (any file that parsed)."""
+        entry = self._highlighted_entry()
+        if entry is None:
+            return
+        if entry.blueprint is None:
+            self.app.notify(
+                "This file does not parse — edit the JSON by hand.", severity="error", timeout=8
+            )
+            return
+        from .builder.screen import BlueprintStudioScreen
+
+        self.app.push_screen(BlueprintStudioScreen(entry.path))
+
+    def _highlighted_entry(self) -> BlueprintEntry | None:
+        table = self.query_one("#library-table", DataTable)
+        if table.row_count == 0:
+            return None
+        row_key = table.coordinate_to_cell_key(table.cursor_coordinate).row_key
+        return next((e for e in self._entries if str(e.path) == str(row_key.value)), None)
+
+    def _rescan(self) -> None:
+        dirs = discover_blueprint_dirs()
+        self._entries = scan_blueprints(dirs)
+        self._render_table()
+
+    def _render_table(self) -> None:
+        table = self.query_one("#library-table", DataTable)
+        table.clear(columns=True)
+        table.add_columns("Name", "Act", "Status", "Path")
+        for entry in self._entries:
+            status = entry_status(entry)
+            label_text, style = _STATUS_STYLE[status]
+            # Surface the concrete error inline; keep the muted note for a pending Act.
+            if status is EntryStatus.INVALID and entry.error:
+                label_text = f"invalid: {entry.error}"
+            elif status is EntryStatus.ACT_PENDING:
+                label_text = "act pending — no driver yet"
+            status_cell = Text(label_text, style=style)
+
+            if entry.act is None:
+                act_cell: str | Text = Text("-", style=STONE)
+            else:
+                act_label = ACT_LABELS.get(entry.act, entry.act)
+                act_cell = Text(
+                    act_label, style=act_color(entry.act, entry.act in IMPLEMENTED_ACTS)
+                )
+
+            name = entry.blueprint.name if entry.blueprint else entry.path.stem
+            table.add_row(name, act_cell, status_cell, str(entry.path), key=str(entry.path))
+
+    def on_data_table_row_selected(self, event: DataTable.RowSelected) -> None:
+        entry = next((e for e in self._entries if str(e.path) == str(event.row_key.value)), None)
+        if entry is None:
+            return
+        if entry.error or entry.blueprint is None:
+            self.app.notify(
+                f"Cannot open an invalid Blueprint: {entry.error}", severity="error", timeout=8
+            )
+            return
+
+        from .runs import RunsScreen
+
+        self.app.push_screen(RunsScreen(entry.path))

aetherius/console/screens/library_scan.py

@@ -0,0 +1,99 @@
+"""Blueprint discovery and validation for the Library screen.
+
+Pure functions, deliberately free of Textual imports, so they're trivially unit-testable and
+reusable (e.g. by a future `aetherius list` CLI command) without pulling in the TUI.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+from ...core.blueprint.loader import load_blueprint
+from ...core.blueprint.models import Blueprint
+from ...core.blueprint.validator import validate_for_act
+from ...core.errors import BlueprintError
+from ...core.runtime.engine import IMPLEMENTED_ACTS
+
+_BLUEPRINT_GLOBS = ("*.blueprint.json", "*.blueprint.yaml", "*.blueprint.yml")
+
+
+@dataclass(frozen=True)
+class BlueprintEntry:
+    path: Path
+    blueprint: Blueprint | None
+    act: str | None
+    error: str | None
+
+
+class EntryStatus(str, Enum):
+    """A Blueprint's real state in the Library: well-formed and runnable, or why not."""
+
+    INVALID = "invalid"  # schema or capability error: unusable as-is
+    READY = "ready"  # valid and its Act has a driver: runnable now
+    ACT_PENDING = "act pending"  # valid but its Act is not implemented yet
+
+
+def entry_status(entry: BlueprintEntry) -> EntryStatus:
+    """Classify *entry* by validity and Act runnability (the single source is IMPLEMENTED_ACTS)."""
+    if entry.error is not None or entry.act is None:
+        return EntryStatus.INVALID
+    if entry.act in IMPLEMENTED_ACTS:
+        return EntryStatus.READY
+    return EntryStatus.ACT_PENDING
+
+
+def discover_blueprint_dirs(start: Path | None = None) -> list[Path]:
+    """Directories scanned by the Library: a repo checkout's `examples/`, plus `./blueprints/`
+    relative to the current working directory, whichever of the two actually exist."""
+    dirs: list[Path] = []
+
+    repo_examples = _find_repo_examples(Path(__file__).resolve())
+    if repo_examples is not None:
+        dirs.append(repo_examples)
+
+    cwd_blueprints = (start or Path.cwd()) / "blueprints"
+    if cwd_blueprints.is_dir() and cwd_blueprints not in dirs:
+        dirs.append(cwd_blueprints)
+
+    return dirs
+
+
+def _find_repo_examples(start: Path) -> Path | None:
+    """Walk up from this file looking for a sibling `examples/` directory (repo checkout only;
+    absent from an installed, non-editable distribution)."""
+    for parent in start.parents:
+        candidate = parent / "examples"
+        if candidate.is_dir():
+            return candidate
+    return None
+
+
+def scan_blueprints(dirs: list[Path]) -> list[BlueprintEntry]:
+    """Load and validate every Blueprint file found in *dirs*, recursively.
+
+    The scan recurses so examples can be organised into per-Act subdirectories (examples/vector,
+    examples/continuum, ...) and user libraries into any tree. Invalid files are kept in the result
+    with their error instead of raising."""
+    entries: list[BlueprintEntry] = []
+    seen: set[Path] = set()
+
+    for directory in dirs:
+        for pattern in _BLUEPRINT_GLOBS:
+            for path in sorted(directory.rglob(pattern)):
+                if path in seen:
+                    continue
+                seen.add(path)
+                entries.append(_load_entry(path))
+
+    return entries
+
+
+def _load_entry(path: Path) -> BlueprintEntry:
+    try:
+        blueprint = load_blueprint(path)
+        validate_for_act(blueprint)
+    except BlueprintError as exc:
+        return BlueprintEntry(path=path, blueprint=None, act=None, error=str(exc))
+    return BlueprintEntry(path=path, blueprint=blueprint, act=blueprint.act, error=None)

aetherius/console/screens/recorder.py

@@ -0,0 +1,193 @@
+"""Launch and drive the Blueprint recorder from the Console.
+
+Captures a browser demonstration and synthesizes a clean Blueprint with robust selectors, instead of
+writing steps by hand. The recorder engine (`aetherius.recorder`) is synchronous and blocking (it
+owns a live browser), so it runs in a Textual `@work(thread=True)` worker, exactly like a Blueprint
+run. Captured actions stream into the event log through the same Sink pattern (`run_bridge`); Stop
+sets a threading.Event the recorder's pump loop honors to close the browser.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from pathlib import Path
+
+from textual import work
+from textual.app import ComposeResult
+from textual.containers import Horizontal, Vertical, VerticalScroll
+from textual.css.query import NoMatches
+from textual.screen import Screen
+from textual.widgets import Button, Footer, Header, Input, Label, Select, Static, Switch
+
+from ...core.errors import AetheriusError
+from ...core.events.models import EventType, RunEvent
+from ...recorder import record_blueprint
+from ...recorder.base import recorder_acts
+from ..run_bridge import TextualRunSink
+from ..theme import starred
+from ..widgets.event_log import EventLog
+from ..widgets.json_preview import JsonPreview
+
+# How each recorder Act reads in the picker. Derived list stays in sync with recorder_acts().
+_ACT_LABELS: dict[str, str] = {
+    "continuum": "Continuum — browser (DOM)",
+    "vector": "Vector — API (network)",
+}
+
+
+class RecorderScreen(Screen[None]):
+    """Record a Blueprint by demonstration: enter a name and start URL, act in the browser, save."""
+
+    AUTO_FOCUS = "#rec-name"
+
+    DEFAULT_CSS = """
+    RecorderScreen .rec-field {
+        height: auto;
+        padding: 1 1 0 1;
+    }
+    RecorderScreen #rec-creds-row {
+        height: auto;
+        padding: 1 1 0 1;
+    }
+    RecorderScreen #rec-creds-label {
+        padding: 1 1 0 0;
+    }
+    RecorderScreen #rec-start, RecorderScreen #rec-stop {
+        border: double $accent;
+        background: $panel;
+        color: $accent;
+        text-style: bold;
+        padding: 0 3;
+    }
+    RecorderScreen #rec-start:hover, RecorderScreen #rec-stop:hover {
+        background: $accent 20%;
+    }
+    RecorderScreen #rec-result {
+        border: double $primary;
+        padding: 0 1;
+        margin: 1 0;
+    }
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._stop = threading.Event()
+        self._sink: TextualRunSink | None = None
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        with VerticalScroll(classes="console-body"):
+            yield Static(starred("Recorder"), classes="console-title")
+            yield Static(
+                "Pick an Act, enter a name and a start URL, then Start: a browser opens. Continuum "
+                "records DOM actions and the floating menu picks data; Vector observes API calls. "
+                "Closing the window (or Stop) saves the Blueprint to ./blueprints.",
+                classes="console-subtitle",
+            )
+            with Vertical(classes="rec-field"):
+                yield Label("Act")
+                yield Select(
+                    [(_ACT_LABELS.get(a, a), a) for a in sorted(recorder_acts())],
+                    value="continuum",
+                    allow_blank=False,
+                    id="rec-act",
+                )
+            with Vertical(classes="rec-field"):
+                yield Label("Blueprint name (e.g. quotes.login)")
+                yield Input(placeholder="domain.task", id="rec-name")
+            with Vertical(classes="rec-field"):
+                yield Label("Start URL")
+                yield Input(placeholder="https://…", id="rec-url")
+            with Horizontal(id="rec-creds-row"):
+                yield Static("Turn credential fields into secrets", id="rec-creds-label")
+                yield Switch(value=True, id="rec-creds")
+            with Horizontal(classes="run-actions"):
+                yield Button("✦ Start recording ✦", id="rec-start", variant="primary")
+                stop = Button("Stop", id="rec-stop")
+                stop.display = False
+                yield stop
+            event_log = EventLog(id="rec-events")
+            event_log.border_title = "✦ Captured actions ✦"
+            yield event_log
+            result = JsonPreview(id="rec-result")
+            result.border_title = "✦ Result ✦"
+            result.display = False
+            yield result
+        yield Footer()
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        if event.button.id == "rec-stop":
+            self._stop.set()
+            self.app.notify("Stopping — closing the browser…", timeout=4)
+            return
+        if event.button.id != "rec-start":
+            return
+
+        name = self.query_one("#rec-name", Input).value.strip()
+        url = self.query_one("#rec-url", Input).value.strip()
+        if not name or not url:
+            self.app.notify("A name and a start URL are required.", severity="warning")
+            return
+
+        act = str(self.query_one("#rec-act", Select).value)
+        credentials = self.query_one("#rec-creds", Switch).value
+        self._stop = threading.Event()
+        self._sink = TextualRunSink(self.app, self.query_one("#rec-events", EventLog))
+        self.query_one("#rec-events", EventLog).clear()
+        self.query_one("#rec-result", JsonPreview).display = False
+        self._set_recording(True)
+        self._record(name, url, act, credentials)
+
+    @work(thread=True, exclusive=True)
+    def _record(self, name: str, url: str, act: str, credentials: bool) -> None:
+        try:
+            path = record_blueprint(
+                name,
+                url,
+                act=act,
+                on_event=self._push_event,
+                stop_event=self._stop,
+                credentials_as_secrets=credentials,
+            )
+        except AetheriusError as exc:
+            self.app.call_from_thread(self._fail, exc)
+            return
+        self.app.call_from_thread(self._finish, path)
+
+    def _push_event(self, description: str) -> None:
+        """Forward one captured action's description into the event log (from the worker thread)."""
+        if self._sink is None:
+            return
+        self._sink.on_event(
+            RunEvent(
+                run_id="recorder",
+                type=EventType.STEP_FINISHED,
+                level="info",
+                message=description,
+            )
+        )
+
+    def _finish(self, path: Path) -> None:
+        self._set_recording(False)
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            data = {}
+        result = self.query_one("#rec-result", JsonPreview)
+        result.display = True
+        result.show(data)
+        result.scroll_visible()
+        self.app.notify(f"Saved {path}", timeout=6)
+
+    def _fail(self, exc: Exception) -> None:
+        self._set_recording(False)
+        self.app.notify(str(exc), title="Recorder error", severity="error", timeout=8)
+
+    def _set_recording(self, recording: bool) -> None:
+        """Toggle the Start/Stop buttons; tolerate the screen being popped mid-run."""
+        try:
+            self.query_one("#rec-start", Button).disabled = recording
+            self.query_one("#rec-stop", Button).display = recording
+        except NoMatches:
+            pass

aetherius/console/screens/runs.py

@@ -0,0 +1,138 @@
+"""Run a Blueprint and follow its events, logs and artifacts live."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from textual import work
+from textual.app import ComposeResult
+from textual.containers import Horizontal, VerticalScroll
+from textual.css.query import NoMatches
+from textual.screen import Screen
+from textual.widgets import Button, Footer, Header, Static, Switch
+
+from ...core.blueprint.loader import load_blueprint
+from ...core.blueprint.models import Blueprint
+from ...core.blueprint.validator import validate_for_act
+from ...core.errors import AetheriusError
+from ...core.runtime.engine import IMPLEMENTED_ACTS, RunEngine
+from ...core.runtime.result import Result
+from ..run_bridge import TextualRunSink
+from ..theme import starred
+from ..widgets.event_log import EventLog
+from ..widgets.form import BlueprintInputForm
+from ..widgets.run_summary import RunSummary
+
+
+class RunsScreen(Screen[None]):
+    """Load a Blueprint, collect its inputs, run it, and show live events + the final result.
+
+    The body is a VerticalScroll so every section stays reachable in short terminals.
+    """
+
+    # Land directly in the first form field instead of the scroll container.
+    AUTO_FOCUS = "BlueprintInputForm Input"
+
+    def __init__(self, blueprint_path: Path) -> None:
+        super().__init__()
+        self._blueprint_path = blueprint_path
+        self._blueprint: Blueprint | None = None
+        self._load_error: str | None = None
+
+        try:
+            self._blueprint = load_blueprint(blueprint_path)
+            validate_for_act(self._blueprint)
+        except AetheriusError as exc:
+            self._load_error = str(exc)
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        with VerticalScroll(classes="console-body"):
+            if self._load_error is not None:
+                yield Static(f"Cannot load Blueprint: {self._load_error}", classes="console-title")
+                yield Footer()
+                return
+
+            assert self._blueprint is not None
+            bp = self._blueprint
+            yield Static(starred(f"Run — {bp.name}"), classes="console-title")
+            yield Static(f"Path: {self._blueprint_path}", classes="console-subtitle")
+
+            if bp.act not in IMPLEMENTED_ACTS:
+                yield Static(
+                    f"Act {bp.act!r} has no driver yet — only Vector (Act I) is runnable. "
+                    "This Blueprint is valid but cannot be executed from the Console.",
+                    classes="console-subtitle",
+                )
+                yield Footer()
+                return
+
+            from ...config.secrets import available_from_env
+
+            form = BlueprintInputForm(bp.inputs, bp.secrets, available_from_env(bp.secrets))
+            form.border_title = "✦ Inputs ✦"
+            yield form
+            with Horizontal(classes="run-actions"):
+                yield Switch(value=bp.options.debug, id="run-debug")
+                yield Static("Debug — visible browser + slow-mo", id="run-debug-label")
+            with Horizontal(classes="run-actions"):
+                yield Button("✦ Run ✦", id="run-button", variant="primary")
+            event_log = EventLog(id="run-event-log")
+            event_log.border_title = "✦ Events ✦"
+            yield event_log
+            summary = RunSummary(id="run-summary")
+            summary.border_title = "✦ Result ✦"
+            yield summary
+        yield Footer()
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        if event.button.id != "run-button":
+            return
+        assert self._blueprint is not None
+
+        form = self.query_one(BlueprintInputForm)
+        errors = form.validation_errors()
+        if errors:
+            self.app.notify("\n".join(errors), title="Missing inputs", severity="warning")
+            return
+
+        # Debug is a per-run choice here, not baked into the file: toggle it on the loaded model.
+        self._blueprint.options.debug = self.query_one("#run-debug", Switch).value
+
+        input_values, secret_values = form.collect()
+        event.button.disabled = True
+        self.query_one("#run-event-log", EventLog).clear()
+        self.query_one("#run-summary", RunSummary).reset()
+        self._run_blueprint(input_values, secret_values)
+
+    @work(thread=True, exclusive=True)
+    def _run_blueprint(self, inputs: dict[str, object], secrets: dict[str, str]) -> None:
+        assert self._blueprint is not None
+        event_log = self.query_one("#run-event-log", EventLog)
+        sink = TextualRunSink(self.app, event_log)
+
+        try:
+            result = RunEngine().run(self._blueprint, inputs=inputs, secrets=secrets, sinks=[sink])
+        except AetheriusError as exc:
+            self.app.call_from_thread(self._notify_error, exc)
+            self.app.call_from_thread(self._reenable_run_button)
+            return
+
+        self.app.call_from_thread(self._show_result, result)
+
+    def _show_result(self, result: Result) -> None:
+        summary = self.query_one("#run-summary", RunSummary)
+        summary.show(result)
+        summary.scroll_visible()
+        self._reenable_run_button()
+
+    def _reenable_run_button(self) -> None:
+        # The screen may have been popped while the worker was still running; that's fine,
+        # there's nothing left to re-enable.
+        try:
+            self.query_one("#run-button", Button).disabled = False
+        except NoMatches:
+            pass
+
+    def _notify_error(self, exc: Exception) -> None:
+        self.app.notify(str(exc), title="Error", severity="error", timeout=8)

aetherius/console/screens/sessions.py

@@ -0,0 +1,14 @@
+"""Manage persistent profiles and sessions, and launch warmup."""
+
+from __future__ import annotations
+
+from ._pending import PendingScreen
+
+
+class SessionsScreen(PendingScreen):
+    title_text = "Sessions"
+    description_text = (
+        "Will manage persistent browser profiles (cookies, cache) and let you launch a warmup "
+        "run to build an authentic history before automation."
+    )
+    milestone_text = "the discretion/stealth subsystem (src/aetherius/stealth/session/)."