rigbox 0.1.0__py3-none-any.whl

rigbox/__init__.py

@@ -0,0 +1 @@
+"""Main package for Rigbox."""

rigbox/cli.py

@@ -0,0 +1,142 @@
+"""Main CLI entrypoint for Rigbox."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from rigbox.constants import RenderFormat, RenderLevel
+from rigbox.core.context import Context
+from rigbox.core.plugins import load_all
+from rigbox.core.registry import CommandError, Registry, UsageError
+from rigbox.core.render import RenderError, RigboxCmdResult
+from rigbox.core.workspace import Workspace
+
+cli = typer.Typer()
+
+
+def _build_context(workspace: str | None, fmt: RenderFormat) -> Context:
+    """Find the workspace (from `workspace` or the cwd), load plugins and return a ready Context."""
+    ws = Workspace.find(Path(workspace) if workspace else Path.cwd())
+    registry = Registry()
+    load_all(registry, ws)
+    return Context(registry=registry, workspace=ws, fmt=fmt)
+
+
+@cli.callback(invoke_without_command=True)
+def main(ctx: typer.Context) -> None:
+    """Main entrypoint for the Rigbox CLI. Overridden to allow for REPL launch when no arguments are provided.
+
+    Args:
+        ctx (typer.Context): The Typer context object for the CLI invocation.
+    """
+    # If no subcommand was invoked, we default to spawning the interactive REPL interface
+    if ctx.invoked_subcommand is None:
+        from rigbox.repl import run_repl
+
+        rigbox_ctx = _build_context(None, RenderFormat.default())
+        run_repl(rigbox_ctx)
+
+
+@cli.command(help="Initialize a new Rigbox workspace.")
+def init(
+    path: Path = typer.Argument(Path("."), help="The path to create the workspace in."),
+    name: str | None = typer.Option(None, "--name", help="The name of the workspace."),
+) -> None:
+    """Initialize a new Rigbox workspace.
+
+    Args:
+        path (Path, optional): The path to create the workspace in. Defaults to the current directory.
+        name (str | None, optional): The name of the workspace. Defaults to None.
+
+    Raises:
+        typer.Exit(code=1): Raised if the workspace already exists.
+        typer.Exit(code=0): Raised after successful initialization.
+    """
+    try:
+        ws = Workspace.init(path, name)
+    except FileExistsError as e:
+        typer.echo(f"Error: {e}")
+        raise typer.Exit(code=1) from e
+    typer.echo(f"Workspace initialized at {ws.root}")
+    raise typer.Exit(code=0)
+
+
+@cli.command(context_settings={"ignore_unknown_options": True, "allow_interspersed_args": False}, help="Run one command non-interactively.")
+def run(
+    tokens: Annotated[list[str], typer.Argument(help="<command> [args...]")],
+    workspace: Annotated[str | None, typer.Option(help="Start the workspace search here (default: cwd)")] = None,
+    fmt: Annotated[RenderFormat, typer.Option("--format", "-f", help=f"Output format (default: {RenderFormat.default()})")] = RenderFormat.default(),
+) -> None:
+    """Run one command non-interactively.
+
+    Args:
+        tokens (Annotated[list[str], typer.Argument): The command and its arguments to run.
+        workspace (str | None, optional): The workspace to start the search from. Defaults to cwd.
+        fmt: The output format, including plain text, tables, JSON, and NDJSON. Defaults to "auto".
+
+    Raises:
+        typer.Exit(code=2): Raised if no command is specified.
+        typer.Exit(code=2): Raised if there is a usage error.
+        typer.Exit(code=1): Raised if there is a command error.
+        typer.Exit(code=0): Raised after successful execution.
+    """
+    if not tokens:
+        typer.echo("Error: No command specified.")
+        raise typer.Exit(code=2)
+    ctx = _build_context(workspace, fmt)
+    try:
+        response = ctx.run_tokens(tokens)
+        out = response.render(fmt)
+    except UsageError as e:
+        raise typer.Exit(code=e.exit_code) from e
+    except (CommandError, RenderError) as e:
+        typer.echo(RigboxCmdResult(text=str(e), level=RenderLevel.ERROR).render(RenderFormat.PLAINTEXT), err=True)
+        raise typer.Exit(code=1) from e
+    finally:
+        ctx.close()
+    if out:
+        typer.echo(out)
+    raise typer.Exit(code=0)
+
+
+@cli.command(help="Execute a script file within the Rigbox workspace.")
+def script(
+    file: Annotated[Path, typer.Argument(help="The script file to execute.")],
+    workspace: Annotated[str | None, typer.Option(help="Start the workspace search here (default: cwd)")] = None,
+    fmt: Annotated[RenderFormat, typer.Option("--format", "-f", help=f"Output format (default: {RenderFormat.default()})")] = RenderFormat.default(),
+    var: Annotated[list[str] | None, typer.Option("--var", "-v", help="key=value override")] = None,
+) -> None:
+    """Execute a script file within the Rigbox workspace.
+
+    Args:
+        file (Annotated[Path, typer.Argument): The script file to execute.
+        workspace (str | None, optional): The workspace to start the search from. Defaults to cwd.
+        fmt: The output format, including plain text, rich renderables, JSON, and NDJSON. Defaults to "auto".
+        var (Annotated[list[str] | None, typer.Option, optional): Key=value overrides for the script. Defaults to None.
+
+    Raises:
+        typer.Exit(code=2): Raised if there is a usage error.
+        typer.Exit(code=1): Raised if there is a command error.
+        typer.Exit(code=0): Raised after successful execution.
+    """
+    ctx = _build_context(workspace, fmt)
+    try:
+        response = ctx.run("workflow.run", {"workflow": str(file), "var": var or []})
+        out = response.render(fmt)
+    except UsageError as e:
+        raise typer.Exit(code=e.exit_code) from e
+    except (CommandError, RenderError) as e:
+        typer.echo(RigboxCmdResult(text=str(e), level=RenderLevel.ERROR).render(RenderFormat.PLAINTEXT), err=True)
+        raise typer.Exit(code=1) from e
+    finally:
+        ctx.close()
+    if out:
+        typer.echo(out)
+    raise typer.Exit(code=0)
+
+
+if __name__ == "__main__":
+    cli()

rigbox/constants.py

@@ -0,0 +1,89 @@
+"""Common constants for Rigbox."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from importlib.metadata import version
+from typing import Final, Self
+
+
+class AppMetadata:
+    """Namespace class for application metadata-related constants."""
+
+    NAME: Final[str] = "rigbox"
+    VERSION: Final[str] = version(NAME)
+
+
+class AppFiles:
+    """Namespace class for file-related constants."""
+
+    SHELL_HISTORY: Final[str] = "shell_history.json"
+    WORKSPACE_CONFIG: Final[str] = "rigbox.yaml"
+
+
+class RenderFormat(StrEnum):
+    """Enumeration of output rendering formats.
+
+    This dictates how the output should be formatted when rendered, including options for JSON, NDJSON, Rich text, plain text,
+    or automatic detection based on the terminal capabilities.
+    """
+
+    JSON = "json"
+    NDJSON = "ndjson"
+    RICH = "rich"
+    PLAINTEXT = "plaintext"
+    AUTO = "auto"
+
+    @classmethod
+    def default(cls) -> Self:
+        """Get the default rendering format."""
+        return cls.AUTO
+
+
+class RenderLevel(StrEnum):
+    """Enumeration of output rendering severity levels.
+
+    This dictates how messages of different severity levels should be rendered, including their associated colors.
+    """
+
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+    SUCCESS = "success"
+
+    @classmethod
+    def default(cls) -> Self:
+        """Get the default rendering level."""
+        return cls.INFO
+
+    @property
+    def color(self) -> str:
+        """Get the associated color for this `RenderLevel`.
+
+        Raises:
+            KeyError: If the `RenderLevel` does not have an associated color mapping.
+
+        Returns:
+            str: The rich color associated with this `RenderLevel`.
+        """
+        return {
+            "error": "bold red",
+            "warning": "yellow",
+            "info": "default",  # No color
+            "success": "green",
+        }[self]
+
+
+class Plugins:
+    """Namespace class for plugin-related constants."""
+
+    PROJECT: Final[str] = AppMetadata.NAME
+    ENTRYPOINT_GROUP: Final[str] = f"{PROJECT}.plugins".lower()
+    BUILTIN_MODULES: tuple[str, ...] = (
+        f"{ENTRYPOINT_GROUP}.builtin",
+        f"{ENTRYPOINT_GROUP}.manifests.commands",
+        f"{ENTRYPOINT_GROUP}.device.commands",
+        f"{ENTRYPOINT_GROUP}.statemachine.commands",
+        f"{ENTRYPOINT_GROUP}.code.commands",
+        f"{ENTRYPOINT_GROUP}.dsp.commands",
+    )

rigbox/core/__init__.py

@@ -0,0 +1 @@
+"""Framework core: registry, context, parsing, rendering, workspace, workflows and plugin loading."""

rigbox/core/cli_parser.py

@@ -0,0 +1,145 @@
+"""Module for command-line parsing using pydantic models.
+
+Rigbox defines all commands using pydantic models to represent their arguments.
+
+This module provides functions to convert these pydantic models into argparse parsers,
+so that commands can be run both from the command line and the interactive shell with consistent argument handling.
+
+Required fields in the pydantic model become positional arguments, while optional fields become named options with `--`.
+Boolean fields become bare flags, list fields can repeat, and Literal fields become validated choices.
+
+Values stay as strings when parsed from the command line, and pydantic handles conversion and validation when the command runs.
+"""
+
+from __future__ import annotations
+
+import argparse
+import functools
+import shlex
+import typing
+from types import UnionType
+from typing import Any, NoReturn
+
+import cmd2
+from pydantic import BaseModel, Field
+from pydantic.fields import FieldInfo
+
+from rigbox.core.registry import Command, UsageError
+
+
+def path_field(default: Any = ..., **kwargs: Any) -> Any:  # noqa: ANN401 - mirrors pydantic's Field()
+    """Declare a ``str`` argument that holds a file path, so the shell can tab-complete file names for it.
+
+    This exists because some fields may represent both a file path
+    and other types of string data, and we want the shell to provide
+    tab-completion for the file path case.
+
+    Takes the same arguments as pydantic's ``Field``; with no default the argument is required.
+    """
+    return Field(default, json_schema_extra={"path": True}, **kwargs)
+
+
+class RigboxParser(cmd2.Cmd2ArgumentParser):
+    """The parser for one command. It remembers the last error so non-interactive callers can report it."""
+
+    fields: tuple[str, ...] = ()
+    """Names of the args model's fields, used to pick them out of the parsed namespace."""
+
+    error_message: str = ""
+
+    def error(self, message: str) -> NoReturn:
+        """Record `message`, then let argparse print the usage and exit as usual."""
+        self.error_message = message
+        super().error(message)
+
+
+def _unwrap(annotation: object) -> object:
+    """Strip Optional[...] so `bool | None` still counts as bool."""
+    if typing.get_origin(annotation) in (typing.Union, UnionType):
+        args = [a for a in typing.get_args(annotation) if a is not type(None)]
+        if len(args) == 1:
+            return args[0]
+    return annotation
+
+
+def _is_bool(info: FieldInfo) -> bool:
+    return _unwrap(info.annotation) is bool
+
+
+def _is_list(info: FieldInfo) -> bool:
+    return typing.get_origin(_unwrap(info.annotation)) in (list, tuple, set)
+
+
+def _is_path(info: FieldInfo) -> bool:
+    extra = info.json_schema_extra
+    return isinstance(extra, dict) and extra.get("path") is True
+
+
+def _help_text(info: FieldInfo) -> str:
+    """The field's description, with its default appended; `%` is doubled because argparse formats help text."""
+    text = info.description or ""
+    if info.default_factory is None and info.default not in (None, "", False) and not info.is_required():
+        text = f"{text} (default: {info.default})".strip()
+    return text.replace("%", "%%")
+
+
+def build_parser(name: str, model: type[BaseModel], summary: str) -> RigboxParser:
+    """Build the parser for command `name` from its args `model`; `summary` is shown as the description."""
+    # First, create a parser instance
+    parser = RigboxParser(prog=name, description=summary, allow_abbrev=False, suggest_on_error=True)
+    # Then, create the fields using the pydantic model's field definitions
+    parser.fields = tuple(model.model_fields)
+    # Now, we add each field as an argument to the parser based on its properties
+    for field, info in model.model_fields.items():
+        annotation = _unwrap(info.annotation)
+        options: dict[str, Any] = {"help": _help_text(info)}
+        if typing.get_origin(annotation) is typing.Literal:
+            options["choices"] = list(typing.get_args(annotation))
+        # Automatically set up path completion for path fields
+        if _is_path(info):
+            options["completer"] = cmd2.Cmd.path_complete
+        if info.is_required():
+            parser.add_argument(field, **options)
+            continue
+        flag = "--" + field.replace("_", "-")
+        if _is_bool(info):
+            parser.add_argument(flag, dest=field, action="store_true", default=argparse.SUPPRESS, help=options["help"])
+        elif _is_list(info):
+            parser.add_argument(flag, dest=field, action="append", default=argparse.SUPPRESS, **options)
+        else:
+            parser.add_argument(flag, dest=field, default=argparse.SUPPRESS, **options)
+    return parser
+
+
+@functools.cache  # Cache the parser for each command to avoid rebuilding it multiple times
+def parser_for(command: Command) -> RigboxParser:
+    """Return the (cached) parser for a registered command."""
+    return build_parser(command.name, command.args_model, command.help)
+
+
+def parse_args(parser: RigboxParser, tokens: list[str]) -> dict[str, Any]:
+    """Parse command-line `tokens` into a raw args dict holding only the options actually given.
+
+    Raises:
+        UsageError: If the tokens are invalid, or ``--help`` was given. The parser has already printed the usage
+            message or help text; the error's ``exit_code`` is 2 for a bad command line and 0 for help.
+    """
+    try:
+        namespace = parser.parse_args(tokens)
+    except SystemExit as exit_:
+        code = exit_.code
+        raise UsageError(parser.error_message, code if isinstance(code, int) else 0) from None
+    return {key: value for key, value in vars(namespace).items() if key in parser.fields}
+
+
+def split_line(line: str) -> list[str]:
+    """Split a line into tokens. Quotes group words; backslashes are kept (Windows paths)."""
+    lexer = shlex.shlex(line, posix=False)
+    lexer.whitespace_split = True
+    lexer.commenters = ""
+    tokens: list[str] = []
+    for tok in lexer:
+        if len(tok) >= 2 and tok[0] == tok[-1] and tok[0] in "\"'":
+            tok = tok[1:-1]
+        tokens.append(tok)
+    return tokens

rigbox/core/context.py

@@ -0,0 +1,129 @@
+"""Execution context shared by REPL, CLI and workflows."""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass, field
+from typing import Any, Protocol, TextIO
+
+from pydantic import ValidationError
+from rich.console import Console, RenderableType
+
+from rigbox.constants import RenderFormat
+from rigbox.core.cli_parser import parse_args, parser_for, split_line
+from rigbox.core.history import History
+from rigbox.core.registry import CommandError, Registry
+from rigbox.core.render import RigboxCmdResult, resolve_render_format
+from rigbox.core.workspace import Workspace
+
+
+class Closable(Protocol):
+    """Anything with a ``close()`` method, such as a device connection."""
+
+    def close(self) -> None:
+        """Release the resource."""
+
+
+@dataclass
+class Context:
+    """Shared state for one session: registry, workspace, history, output format and open connections."""
+
+    registry: Registry
+    workspace: Workspace | None = None
+    fmt: RenderFormat = RenderFormat.default()
+    history: History = field(init=False)  # created in __post_init__
+    # Open resources owned by plugins (e.g. device connections), closed in `close()`; any object with .close()
+    connections: dict[str, Closable] = field(default_factory=dict)
+    output_stream: TextIO | None = None
+
+    def __post_init__(self) -> None:
+        """Create the session history, persisted in the workspace if there is one."""
+        path = self.workspace.data_dir / "history.jsonl" if self.workspace else None
+        self.history = History(path)
+
+    def close(self) -> None:
+        """Attempt every resource's cleanup, log failures, and forget the closed session."""
+        connections = list(self.connections.items())
+        self.connections.clear()
+        for name, conn in connections:
+            try:
+                conn.close()
+            except Exception as error:
+                self.log(f"warning: cannot close connection '{name}': {error}")
+
+    def log(self, message: str) -> None:
+        """Write a progress or diagnostic message to stderr, keeping stdout pipe-clean.
+
+        Args:
+            message (str): The message to log.
+        """
+        print(message, file=sys.stderr)
+
+    def print(self, renderable: RenderableType, *, style: str | None = None) -> None:
+        """Print a Rich renderable to stdout in plaintext or rich mode.
+
+        Args:
+            renderable: The text or Rich renderable to display.
+            style: Optional Rich style applied to the renderable.
+
+        Raises:
+            CommandError: If the selected output format is not plaintext or rich.
+        """
+        stream = self.output_stream if self.output_stream is not None else sys.stdout
+        resolved_fmt = resolve_render_format(self.fmt, stream)
+        if resolved_fmt not in (RenderFormat.RICH, RenderFormat.PLAINTEXT):
+            raise CommandError("Rich output is only available in plaintext or rich format")
+        Console(file=stream).print(renderable, style=style, markup=False)
+
+    def run(self, name: str, raw_args: dict[str, Any] | None = None) -> RigboxCmdResult:
+        """Validate arguments, invoke the handler, and normalize its response.
+
+        Args:
+            name (str): The name of the command to run.
+            raw_args (dict[str, Any] | None, optional): The raw arguments to pass to the command. Defaults to None.
+
+        Returns:
+            The response containing normalized data and any explicit plaintext message.
+
+        Raises:
+            CommandError: If the command is unknown, the args are invalid, or the handler fails.
+        """
+        cmd = self.registry.get(name)
+        try:
+            args = cmd.args_model.model_validate(raw_args or {})
+        except ValidationError as e:
+            problems = "; ".join(f"{'.'.join(str(p) for p in err['loc']) or 'args'}: {err['msg']}" for err in e.errors())
+            raise CommandError(f"{name}: invalid arguments: {problems}") from None
+        result = cmd.handler(self, args)
+        if cmd.record:
+            self.history.append(name, args.model_dump(mode="json", exclude_unset=True))
+        return RigboxCmdResult.normalized(result)
+
+    def run_tokens(self, tokens: list[str]) -> RigboxCmdResult:
+        """Run a command from tokens: the command name followed by CLI-style arguments.
+
+        Args:
+            tokens (list[str]): The command name followed by CLI-style arguments.
+
+        Returns:
+            The normalized command response.
+
+        Raises:
+            UsageError: If the arguments are invalid or ``--help`` was given; the parser has already printed
+                the usage message or help text.
+        """
+        if not tokens:
+            return RigboxCmdResult.empty()
+        cmd = self.registry.get(tokens[0])
+        return self.run(cmd.name, parse_args(parser_for(cmd), tokens[1:]))
+
+    def run_line(self, line: str) -> RigboxCmdResult:
+        """Split `line` into tokens and run it as a command.
+
+        Args:
+            line (str): The command line to split and run.
+
+        Returns:
+            The normalized command response.
+        """
+        return self.run_tokens(split_line(line))

rigbox/core/history.py

@@ -0,0 +1,44 @@
+"""Structured session history (JSONL). Steps replay and convert to workflows."""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+
+class History:
+    """The commands run in a session, optionally persisted to a JSONL file."""
+
+    def __init__(self, path: Path | None = None) -> None:
+        """Load existing entries from `path` if it exists; with no path, keep history in memory only."""
+        self.path = path
+        self._entries: list[dict[str, Any]] = []
+        if path is not None and path.is_file():
+            for line in path.read_text(encoding="utf-8").splitlines():
+                if line.strip():
+                    self._entries.append(json.loads(line))
+
+    def append(self, run: str, args: dict[str, Any], ok: bool = True) -> None:
+        """Record a command run (name, args, success flag) and write it to the file, if any.
+
+        Args:
+            run (str): The name of the command that was run.
+            args (dict[str, Any]): The arguments passed to the command.
+            ok (bool, optional): Whether the command ran successfully. Defaults to True.
+        """
+        entry = {"ts": round(time.time(), 3), "run": run, "args": args, "ok": ok}
+        self._entries.append(entry)
+        if self.path is not None:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            with self.path.open("a", encoding="utf-8") as f:
+                f.write(json.dumps(entry) + "\n")
+
+    def entries(self) -> list[dict[str, Any]]:
+        """Return a copy of all entries, oldest first.
+
+        Returns:
+            list[dict[str, Any]]: A list of all history entries, each being a dictionary with keys "ts", "run", "args", and "ok".
+        """
+        return list(self._entries)

rigbox/core/plugins.py

@@ -0,0 +1,76 @@
+"""Plugin discovery on top of pluggy: built-ins, installed entry points, workspace-local files.
+
+pluggy owns hook definition and dispatch; this module only gathers plugin modules from our three
+sources and records per-plugin failures (a broken plugin never aborts startup).
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+from collections.abc import Callable
+from functools import partial
+from importlib.metadata import entry_points
+from pathlib import Path
+from types import ModuleType
+
+import pluggy
+
+from rigbox import hooks
+from rigbox.constants import Plugins as PluginConstants
+from rigbox.core.registry import PluginInfo, Registry
+from rigbox.core.workspace import Workspace
+
+
+def load_all(registry: Registry, workspace: Workspace | None = None) -> None:
+    """Load every plugin and let each register its commands on `registry`.
+
+    Failures are recorded in ``registry.plugins`` rather than raised.
+
+    Args:
+        registry (Registry): The registry where plugins should register their commands.
+        workspace (Workspace | None, optional): The workspace to look for workspace-local plugins. Defaults to None.
+    """
+    pm = pluggy.PluginManager(PluginConstants.PROJECT)
+    pm.add_hookspecs(hooks)
+    sources: dict[str, str] = {}
+
+    def add(name: str, source: str, loader: Callable[[], object]) -> None:
+        try:
+            pm.register(loader(), name=name)
+            sources[name] = source
+        except Exception as e:  # plugin code must never crash the host
+            registry.plugins.append(PluginInfo(name, source, error=f"{type(e).__name__}: {e}"))
+
+    for mod in PluginConstants.BUILTIN_MODULES:
+        add(mod, "builtin", partial(importlib.import_module, mod))
+    for ep in entry_points(group=PluginConstants.ENTRYPOINT_GROUP):
+        add(ep.name, "entry-point", ep.load)
+    if workspace is not None and workspace.plugins_dir.is_dir():
+        for path in sorted(workspace.plugins_dir.glob("*.py")):
+            if not path.name.startswith("_"):
+                add(path.stem, "workspace", partial(_import_file, path))
+
+    called: set[str] = set()
+    for impl in pm.hook.rigbox_register.get_hookimpls():
+        called.add(impl.plugin_name)
+        before = set(registry.names())
+        info = PluginInfo(impl.plugin_name, sources[impl.plugin_name])
+        try:
+            impl.function(registry=registry)
+        except Exception as e:
+            info.error = f"{type(e).__name__}: {e}"
+        info.commands = sorted(set(registry.names()) - before)
+        registry.plugins.append(info)
+    for name, source in sources.items():
+        if name not in called:
+            registry.plugins.append(PluginInfo(name, source, error="no rigbox_register hook"))
+
+
+def _import_file(path: Path) -> ModuleType:
+    spec = importlib.util.spec_from_file_location(f"rigbox_workspace_plugin_{path.stem}", path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"cannot load plugin file: {path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module