aetherius 0.2.0__py3-none-any.whl

aetherius/builder/templates.py

@@ -0,0 +1,150 @@
+"""Starter Blueprint templates per Act and per common use case.
+
+Each template is a small, zero-config demonstration against a public endpoint, returned as a fresh
+:class:`~.factory.BlueprintDraft` the Studio can then edit. Every template is guaranteed valid by a
+test that runs it through the canonical build path, so "Load a template" always yields a runnable
+starting point.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+from ..core.errors import BuilderError
+from .factory import BlueprintDraft, StepDraft
+
+
+@dataclass(frozen=True)
+class TemplateInfo:
+    """A template's identity for the picker: a stable key, its Act, a title and a one-liner."""
+
+    key: str
+    act: str
+    title: str
+    summary: str
+
+
+def _vector_api_fetch() -> BlueprintDraft:
+    return BlueprintDraft(
+        name="api.fetch",
+        act="vector",
+        description="Fetch a JSON collection over HTTP and extract fields.",
+        steps=[
+            StepDraft(
+                action="http.request",
+                id="fetch",
+                params={
+                    "method": "GET",
+                    "url": "https://jsonplaceholder.typicode.com/posts",
+                    "expect": {"status": 200},
+                    "extract": {
+                        "posts": {
+                            "from": "json",
+                            "path": "$[*]",
+                            "fields": {"id": "$.id", "title": "$.title"},
+                        }
+                    },
+                },
+            )
+        ],
+        outputs={"posts": "{{ steps.fetch.posts }}"},
+    )
+
+
+def _continuum_scrape() -> BlueprintDraft:
+    return BlueprintDraft(
+        name="site.scrape",
+        act="continuum",
+        description="Open a page, wait for content, and extract a list of records.",
+        steps=[
+            StepDraft(action="navigate", params={"url": "https://quotes.toscrape.com/"}),
+            StepDraft(action="wait_for", params={"selector": ".quote"}),
+            StepDraft(
+                action="extract",
+                id="data",
+                params={
+                    "outputs": {
+                        "quotes": {
+                            "each": ".quote",
+                            "fields": {
+                                "text": {"selector": ".text", "as": "text"},
+                                "author": {"selector": ".author", "as": "text"},
+                            },
+                        }
+                    }
+                },
+            ),
+        ],
+        outputs={"quotes": "{{ steps.data.quotes }}"},
+    )
+
+
+def _continuum_login() -> BlueprintDraft:
+    return BlueprintDraft(
+        name="site.login",
+        act="continuum",
+        description="Log in through a form, keeping the password as a runtime secret.",
+        inputs={"username": {"type": "string", "required": True}},
+        secrets=["password"],
+        steps=[
+            StepDraft(action="navigate", params={"url": "https://quotes.toscrape.com/login"}),
+            StepDraft(
+                action="fill", params={"selector": "#username", "value": "{{ inputs.username }}"}
+            ),
+            StepDraft(
+                action="fill", params={"selector": "#password", "value": "{{ secrets.password }}"}
+            ),
+            StepDraft(action="click", params={"selector": "input[type='submit']"}),
+            StepDraft(
+                action="wait_for",
+                params={"selector": "a[href='/logout']", "on_timeout": "fail:LOGIN_FAILED"},
+            ),
+        ],
+    )
+
+
+# key -> (TemplateInfo, builder). The builder returns a fresh draft on every call.
+_TEMPLATES: dict[str, tuple[TemplateInfo, Callable[[], BlueprintDraft]]] = {
+    "vector.api-fetch": (
+        TemplateInfo(
+            "vector.api-fetch",
+            "vector",
+            "API fetch",
+            "GET a JSON collection and extract fields (jsonplaceholder).",
+        ),
+        _vector_api_fetch,
+    ),
+    "continuum.scrape": (
+        TemplateInfo(
+            "continuum.scrape",
+            "continuum",
+            "Scrape a page",
+            "Navigate, wait, extract records (quotes.toscrape.com).",
+        ),
+        _continuum_scrape,
+    ),
+    "continuum.login": (
+        TemplateInfo(
+            "continuum.login",
+            "continuum",
+            "Form login",
+            "Fill a login form with an input and a secret (quotes.toscrape.com).",
+        ),
+        _continuum_login,
+    ),
+}
+
+
+def list_templates(act: str | None = None) -> list[TemplateInfo]:
+    """Every template, optionally filtered to a single *act*, in registration order."""
+    infos = [info for info, _ in _TEMPLATES.values()]
+    return [info for info in infos if act is None or info.act == act]
+
+
+def template_draft(key: str) -> BlueprintDraft:
+    """Return a fresh draft for template *key* or raise :class:`BuilderError`."""
+    entry = _TEMPLATES.get(key)
+    if entry is None:
+        raise BuilderError(f"Unknown template {key!r} (known: {sorted(_TEMPLATES)}).")
+    return entry[1]()

aetherius/builder/validation.py

@@ -0,0 +1,120 @@
+"""Incremental Blueprint validation for the live editor.
+
+:func:`validate_draft` never raises: it returns a flat list of :class:`ValidationIssue` (errors and
+warnings) that the Studio's preview renders on every change. It layers the same checks the runtime
+enforces — JSON Schema structure, the Pydantic model, then the semantic Act/action rules — so what
+reads as valid here is what will actually load and run. Finalisation (raising) stays in
+``factory.build_blueprint``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal
+
+from jsonschema import Draft202012Validator
+from pydantic import ValidationError
+
+from ..core.actions.base import ACT_CAPABILITIES, PENDING_ACTIONS, Capability
+from ..core.actions.registry import action_specs
+from ..core.blueprint.loader import blueprint_schema
+from ..core.blueprint.models import Blueprint
+from ..core.runtime.engine import IMPLEMENTED_ACTS
+
+if TYPE_CHECKING:
+    from .factory import BlueprintDraft
+
+Severity = Literal["error", "warning"]
+
+
+@dataclass(frozen=True)
+class ValidationIssue:
+    """One problem found in a draft: its severity, a dotted path, and a human message."""
+
+    severity: Severity
+    path: str
+    message: str
+
+
+def _format_path(parts: Any) -> str:
+    """Render a jsonschema/pydantic location (['steps', 2, 'url']) as 'steps[2].url'."""
+    out = ""
+    for part in parts:
+        if isinstance(part, int):
+            out += f"[{part}]"
+        else:
+            out += f".{part}" if out else str(part)
+    return out or "<root>"
+
+
+def _missing(value: Any) -> bool:
+    """True when a required parameter is effectively empty (absent, blank, or empty container)."""
+    if value is None:
+        return True
+    if isinstance(value, str):
+        return value.strip() == ""
+    if isinstance(value, (dict, list)):
+        return len(value) == 0
+    return False
+
+
+def _semantic_issues(draft: "BlueprintDraft") -> list[ValidationIssue]:
+    """Act/action rules the JSON Schema deliberately leaves open (steps are additionalProperties)."""
+    issues: list[ValidationIssue] = []
+    caps = ACT_CAPABILITIES.get(draft.act)
+    specs = action_specs()
+    pending: frozenset[Capability] = PENDING_ACTIONS.get(draft.act, frozenset())
+
+    if draft.act and draft.act not in IMPLEMENTED_ACTS:
+        issues.append(ValidationIssue("warning", "act", f"Act {draft.act!r} is not runnable yet."))
+
+    for index, step in enumerate(draft.steps):
+        base = f"steps[{index}]"
+        action = step.action
+        if not action:
+            issues.append(ValidationIssue("error", base, "Step is missing an action."))
+            continue
+        if action not in specs:
+            issues.append(ValidationIssue("error", base, f"Unknown action {action!r}."))
+            continue
+        if caps is not None and action not in {c.value for c in caps}:
+            issues.append(
+                ValidationIssue(
+                    "error", base, f"Action {action!r} is not supported by act {draft.act!r}."
+                )
+            )
+            continue
+        cap = Capability(action)
+        if cap in pending:
+            issues.append(
+                ValidationIssue("warning", base, f"Action {action!r} is not runnable yet.")
+            )
+            continue
+        for param in specs[action].required_params():
+            if _missing(step.params.get(param.name)):
+                issues.append(
+                    ValidationIssue("error", f"{base}.{param.name}", f"'{param.name}' is required.")
+                )
+    return issues
+
+
+def validate_draft(draft: "BlueprintDraft") -> list[ValidationIssue]:
+    """Return every issue in *draft*, most structural first. Never raises."""
+    data = draft.to_data()
+    issues: list[ValidationIssue] = []
+
+    validator = Draft202012Validator(blueprint_schema())
+    schema_errors = sorted(validator.iter_errors(data), key=lambda e: list(e.path))
+    for error in schema_errors:
+        issues.append(ValidationIssue("error", _format_path(error.path), error.message))
+
+    # Only run the Pydantic model when the schema is clean, to avoid reporting the same shape twice.
+    if not schema_errors:
+        try:
+            Blueprint.model_validate(data)
+        except ValidationError as exc:
+            for err in exc.errors():
+                issues.append(ValidationIssue("error", _format_path(err["loc"]), err["msg"]))
+
+    issues.extend(_semantic_issues(draft))
+    return issues

aetherius/cli.py

@@ -0,0 +1,236 @@
+"""Command-line entry point.
+
+Running ``aetherius`` with no argument opens the interactive Console (the terminal control center).
+Subcommands (``run``, ``validate``, ``serve``, ``record``) are the scriptable, non-interactive paths.
+
+Kept dependency-light on purpose: heavy imports (Textual for the Console, the Aetherius facade)
+happen inside the relevant command, not at module import time.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+app = typer.Typer(add_completion=False, no_args_is_help=False)
+
+
+def _parse_pairs(pairs: list[str], *, label: str) -> dict[str, str]:
+    """Parse a list of ``key=value`` CLI options into a dict.
+
+    Raises:
+        typer.BadParameter: an entry has no ``=``.
+    """
+    result: dict[str, str] = {}
+    for pair in pairs:
+        if "=" not in pair:
+            raise typer.BadParameter(f"Malformed {label} {pair!r}: expected key=value.")
+        key, _, value = pair.partition("=")
+        result[key] = value
+    return result
+
+
+@app.callback(invoke_without_command=True)
+def main_callback(ctx: typer.Context) -> None:
+    """Dispatch to the Console when no subcommand is given."""
+    if ctx.invoked_subcommand is None:
+        console()
+
+
+@app.command()
+def console() -> None:
+    """Open the interactive terminal Console."""
+    from .console.app import AetheriusConsoleApp
+
+    AetheriusConsoleApp().run()
+
+
+@app.command()
+def run(
+    blueprint: Path,
+    input: list[str] = typer.Option([], "--input", help="Blueprint input as key=value."),
+    secret: list[str] = typer.Option([], "--secret", help="Runtime secret as key=value."),
+    debug: bool = typer.Option(False, "--debug", help="Force verbose step-by-step logging."),
+) -> None:
+    """Execute a Blueprint file and print its result."""
+    from rich.console import Console as RichConsole
+    from rich.table import Table
+
+    from .core.blueprint.loader import load_blueprint
+    from .core.errors import AetheriusError
+    from .core.runtime.engine import RunEngine
+
+    rich_console = RichConsole()
+    inputs = _parse_pairs(input, label="--input")
+    secrets = _parse_pairs(secret, label="--secret")
+
+    try:
+        loaded = load_blueprint(blueprint)
+        if debug:
+            loaded.options.debug = True
+        result = RunEngine().run(loaded, inputs=inputs, secrets=secrets)
+    except AetheriusError as exc:
+        rich_console.print(f"[bold red]Error:[/bold red] {exc}")
+        raise typer.Exit(1) from exc
+
+    table = Table(title=f"{result.blueprint_name} ({result.run_id})")
+    table.add_column("Field")
+    table.add_column("Value")
+    table.add_row("Status", result.status.value)
+    table.add_row("Duration", f"{result.duration_ms:.1f} ms")
+    if result.error:
+        table.add_row("Error", result.error)
+    rich_console.print(table)
+
+    steps = Table(title="Steps")
+    steps.add_column("Step")
+    steps.add_column("Action")
+    steps.add_column("Status")
+    steps.add_column("Duration")
+    for step in result.step_results:
+        steps.add_row(
+            step.step_id or "-", step.action, step.status.value, f"{step.duration_ms:.1f} ms"
+        )
+    rich_console.print(steps)
+
+    if result.outputs:
+        rich_console.print("[bold]Outputs:[/bold]")
+        rich_console.print(json.dumps(result.outputs, indent=2, default=str))
+
+    if result.status.value != "success":
+        raise typer.Exit(1)
+
+
+@app.command()
+def validate(blueprint: Path) -> None:
+    """Load a Blueprint and check it against the schema and its Act's capabilities."""
+    from rich.console import Console as RichConsole
+
+    from .core.blueprint.loader import load_blueprint
+    from .core.blueprint.validator import validate_for_act
+    from .core.errors import AetheriusError
+
+    rich_console = RichConsole()
+    try:
+        loaded = load_blueprint(blueprint)
+        validate_for_act(loaded)
+    except AetheriusError as exc:
+        rich_console.print(f"[bold red]Invalid:[/bold red] {exc}")
+        raise typer.Exit(1) from exc
+
+    rich_console.print(
+        f"[bold green]OK[/bold green] act={loaded.act!r}, "
+        f"{len(loaded.steps)} step(s), {len(loaded.inputs)} input(s)."
+    )
+
+
+@app.command()
+def serve(
+    host: str | None = typer.Option(None, "--host", help="Bind address (default 127.0.0.1)."),
+    port: int | None = typer.Option(None, "--port", help="Bind port (default 8787)."),
+    token: str | None = typer.Option(
+        None, "--token", help="Require this bearer token on every request."
+    ),
+) -> None:
+    """Start the local daemon exposing the engine over HTTP and WebSocket.
+
+    Options override the environment (`AETHERIUS_DAEMON_HOST/PORT/TOKEN`). The daemon binds to
+    loopback by default: it serves local processes only, never the network.
+    """
+    import uvicorn
+
+    from .server import DaemonConfig, create_app
+
+    # Start from the environment (AETHERIUS_DAEMON_*), then let explicit CLI options win.
+    config = DaemonConfig()
+    if host is not None:
+        config.host = host
+    if port is not None:
+        config.port = port
+    if token is not None:
+        config.token = token
+
+    uvicorn.run(create_app(config), host=config.host, port=config.port, log_level="info")
+
+
+@app.command()
+def record(
+    name: str,
+    url: str = typer.Option(..., "--url", help="Start URL for the demonstration."),
+    act: str = typer.Option(
+        "continuum", "--act", help="Recorder backend: 'continuum' (browser) or 'vector' (API)."
+    ),
+    out: Path | None = typer.Option(
+        None, "--out", help="Directory for the recorded Blueprint (default ./blueprints)."
+    ),
+    no_secrets: bool = typer.Option(
+        False,
+        "--no-secrets",
+        help="Keep username-like fields literal (passwords are always secrets).",
+    ),
+) -> None:
+    """Record a Blueprint by demonstrating a task in a visible browser."""
+    from rich.console import Console as RichConsole
+
+    from .core.errors import AetheriusError
+    from .recorder import record_blueprint
+
+    rich_console = RichConsole()
+    rich_console.print(f"[bold]Recording[/bold] {name!r} — a browser opens at {url}.")
+    rich_console.print("Demonstrate the task, then close the window to finish.")
+
+    def on_event(description: str) -> None:
+        rich_console.print(f"  [dim]{description}[/dim]")
+
+    try:
+        path = record_blueprint(
+            name,
+            url,
+            act=act,
+            out_dir=out,
+            on_event=on_event,
+            credentials_as_secrets=not no_secrets,
+        )
+    except AetheriusError as exc:
+        rich_console.print(f"[bold red]Error:[/bold red] {exc}")
+        raise typer.Exit(1) from exc
+
+    rich_console.print(f"[bold green]Saved[/bold green] {path}")
+
+
+@app.command(name="record-gestures")
+def record_gestures_command(
+    out: Path | None = typer.Option(
+        None, "--out", help="Gesture library file to write (default: bundled human_library.json)."
+    ),
+) -> None:
+    """Capture real mouse gestures to extend the stealth gesture library."""
+    from rich.console import Console as RichConsole
+
+    from .core.errors import AetheriusError
+    from .recorder import record_gestures
+
+    rich_console = RichConsole()
+    rich_console.print("A browser opens. Move and click naturally, then close the window to save.")
+    try:
+        path, count = record_gestures(out_path=out)
+    except AetheriusError as exc:
+        rich_console.print(f"[bold red]Error:[/bold red] {exc}")
+        raise typer.Exit(1) from exc
+
+    rich_console.print(f"[bold green]Added[/bold green] {count} gesture(s) to {path}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point used by the ``aetherius`` console script."""
+    try:
+        result = app(args=argv, standalone_mode=False)
+    except typer.Abort:
+        return 1
+    return result if isinstance(result, int) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

aetherius/config/__init__.py

@@ -0,0 +1 @@
+"""Global configuration package."""

aetherius/config/secrets.py

@@ -0,0 +1,71 @@
+"""Secret resolution: fill a Blueprint's declared secrets from the environment.
+
+A Blueprint never stores secret values, only their names. At run time each declared secret is
+resolved, in order of precedence:
+
+1. a value passed explicitly by the caller (``run(..., secrets=...)`` / ``--secret``);
+2. an environment variable ``AETHERIUS_SECRET_<NAME>`` (name upper-cased);
+
+A local ``.env`` file (git-ignored) is loaded into the environment first, so a developer or another
+agent can keep credentials on their machine without ever committing them to a public repo. Existing
+environment variables always win over the file, which keeps CI and production in control.
+"""
+
+from __future__ import annotations
+
+from typing import Mapping
+
+from dotenv import find_dotenv, load_dotenv
+
+_SECRET_ENV_PREFIX = "AETHERIUS_SECRET_"
+_dotenv_loaded = False
+
+
+def _secret_env_key(name: str) -> str:
+    """Environment variable backing the declared secret *name* (``cas_pass`` -> ...``CAS_PASS``)."""
+    return _SECRET_ENV_PREFIX + name.upper()
+
+
+def load_dotenv_once() -> None:
+    """Load the nearest ``.env`` into the environment, once per process, without overriding it."""
+    global _dotenv_loaded
+    if _dotenv_loaded:
+        return
+    path = find_dotenv(usecwd=True)
+    if path:
+        load_dotenv(path, override=False)
+    _dotenv_loaded = True
+
+
+def resolve_secrets(
+    declared: list[str],
+    provided: Mapping[str, str] | None,
+) -> dict[str, str]:
+    """Return the secret values for *declared*, merging caller values over environment ones.
+
+    Secrets left unresolved are simply omitted; the template engine surfaces a clear error if a
+    step actually references one that was never provided.
+    """
+    import os
+
+    resolved: dict[str, str] = dict(provided or {})
+    missing = [name for name in declared if name not in resolved]
+    if missing:
+        load_dotenv_once()
+        for name in missing:
+            value = os.environ.get(_secret_env_key(name))
+            if value is not None:
+                resolved[name] = value
+    return resolved
+
+
+def available_from_env(declared: list[str]) -> set[str]:
+    """Subset of *declared* secrets that can be resolved from the environment right now.
+
+    Used by the Console to mark those fields optional instead of forcing the user to retype them.
+    """
+    import os
+
+    if declared:
+        load_dotenv_once()
+    return {name for name in declared if os.environ.get(_secret_env_key(name)) is not None}

aetherius/config/settings.py

@@ -0,0 +1,44 @@
+"""Environment-driven settings via pydantic-settings.
+
+Central place for filesystem locations shared across runs: persistent browser profiles,
+run artifacts (screenshots, HAR, DOM snapshots). Kept intentionally small; it grows as later
+milestones (daemon, sessions warmup) need more knobs. Everything is overridable through the
+``AETHERIUS_`` environment prefix so deployments never hardcode paths.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+def _default_data_dir() -> Path:
+    """Base directory for Aetherius state, resolved once from the home directory."""
+    return Path.home() / ".aetherius"
+
+
+class AetheriusSettings(BaseSettings):
+    """Runtime configuration resolved from the environment (prefix ``AETHERIUS_``)."""
+
+    model_config = SettingsConfigDict(env_prefix="AETHERIUS_", extra="ignore")
+
+    data_dir: Path = Field(default_factory=_default_data_dir)
+
+    @property
+    def profiles_dir(self) -> Path:
+        """Where persistent browser profiles live (one subdirectory per named profile)."""
+        return self.data_dir / "profiles"
+
+    @property
+    def runs_dir(self) -> Path:
+        """Where per-run artifacts are written (one subdirectory per run id)."""
+        return self.data_dir / "runs"
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> AetheriusSettings:
+    """Return the process-wide settings singleton (cached; reads the environment once)."""
+    return AetheriusSettings()

aetherius/console/__init__.py

@@ -0,0 +1 @@
+"""The Aetherius Console: the interactive terminal control center. Never required at execution time."""

aetherius/console/app.py

@@ -0,0 +1,66 @@
+"""Textual application: screen routing and global bindings for the Console."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from textual.app import App
+from textual.binding import Binding
+
+from .theme import AETHERIUS_THEME
+
+if TYPE_CHECKING:
+    from .daemon_control import DaemonController
+
+
+class AetheriusConsoleApp(App[None]):
+    """The Aetherius Console: navigation shell for Home, Library, Runs, Catalog, Recorder, the
+    Blueprint Studio and the daemon Settings (Sessions is still pending)."""
+
+    CSS_PATH = Path(__file__).parent / "console.tcss"
+    TITLE = "Aetherius"
+    SUB_TITLE = "Console"
+
+    BINDINGS = [
+        Binding("q", "quit", "Quit"),
+        Binding("escape", "pop_screen", "Back"),
+        Binding("h", "go_home", "Home"),
+    ]
+
+    def __init__(self) -> None:
+        super().__init__()
+        # Created lazily the first time Settings is opened; a single session-scoped daemon so its
+        # running state survives navigation. Its own atexit guard stops it when the process exits.
+        self._daemon: DaemonController | None = None
+
+    @property
+    def daemon(self) -> DaemonController:
+        """The session's local daemon controller (lazily created)."""
+        if self._daemon is None:
+            from .daemon_control import DaemonController
+
+            self._daemon = DaemonController()
+        return self._daemon
+
+    def on_mount(self) -> None:
+        self.register_theme(AETHERIUS_THEME)
+        self.theme = "aetherius"
+
+        from .screens.home import HomeScreen
+
+        self.push_screen(HomeScreen())
+
+    async def action_pop_screen(self) -> None:
+        # screen_stack[0] is Textual's own default screen, never shown to the user (HomeScreen
+        # is pushed on top of it in on_mount) — never pop back down to it.
+        if len(self.screen_stack) > 2:
+            self.pop_screen()
+
+    def action_go_home(self) -> None:
+        from .screens.home import HomeScreen
+
+        while len(self.screen_stack) > 1:
+            self.pop_screen()
+        if not isinstance(self.screen, HomeScreen):
+            self.push_screen(HomeScreen())