rigbox 0.1.0__tar.gz

rigbox-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 parsimonix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rigbox-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: rigbox
+Version: 0.1.0
+Summary: Embedded developer's toolbox: a manifest-driven REPL and CLI.
+Author-email: Jonathan Bailey <jonathan.bailey@comcast.net>
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cmd2<5,>=4.3
+Requires-Dist: construct>=2.10
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: networkx<4,>=3.4
+Requires-Dist: numpy>=1.24
+Requires-Dist: pluggy>=1.3
+Requires-Dist: pydantic>=2
+Requires-Dist: pyserial>=3.5
+Requires-Dist: pyyaml>=6
+Requires-Dist: rich>=15
+Requires-Dist: scipy>=1.10
+Requires-Dist: simpleeval>=1.0
+Requires-Dist: transitions>=0.9
+Requires-Dist: typer>=0.27.3
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == "plot"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: matplotlib>=3.7; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: ty==0.0.89; extra == "dev"
+Dynamic: license-file
+
+# rigbox
+
+A manifest-driven REPL and CLI toolbox for embedded and DSP developers.
+
+## Setup
+
+Requires Python 3.11 or newer.
+
+```shell
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
+.\.venv\Scripts\python.exe -m pytest -q
+.\.venv\Scripts\ruff.exe check    # lint
+.\.venv\Scripts\ty.exe check      # type check
+```
+
+## Use
+
+```shell
+rigbox init my-project        # create a workspace (rigbox.yaml)
+rigbox                        # interactive shell (run from inside a workspace)
+rigbox run commands           # list the commands
+rigbox run commands --help    # one command's arguments
+rigbox run --format json commands
+rigbox script workflows\x.yaml --var key=value
+```
+
+Output is a human message (or a table for data-only commands) on a terminal and NDJSON when piped.
+Select `--format plaintext`, `rich`, `json`, or `ndjson` explicitly when needed.
+Human formats fall back to available text or a table of structured data; plaintext output omits styling.
+JSON and NDJSON never fall back to human text: human-only results produce an explicit error.
+Empty results produce `[]` in JSON or no NDJSON records, without warnings.
+
+### The shell
+
+The shell is a [cmd2](https://github.com/python-cmd2/cmd2) app; every rigbox command is a shell command with the same
+arguments and `--help` as `rigbox run`. Tab completes command names, option names, choices and file names. cmd2's own
+commands work too:
+
+```shell
+rigbox> help                           # commands grouped by area; `help commands` or `commands --help` for one
+rigbox> set format json                # print results as JSON (plaintext, rich, json, ndjson, auto)
+rigbox> alias create list commands     # then: list
+rigbox> commands | findstr workspace   # pipe to a shell command
+rigbox> commands > commands.txt        # redirect to a file
+rigbox> history                        # what you typed (kept in .rigbox/ inside a workspace)
+rigbox> exit                           # or quit, or Ctrl-D
+```
+
+The bar under the prompt shows the workspace, open device connections and output format.
+
+## Plugins
+
+See each plugin's README for commands, examples and behavior:
+
+- [Manifests](src/rigbox/plugins/manifests/README.md)
+- [Devices and transports](src/rigbox/plugins/device/README.md)
+- [State machines](src/rigbox/plugins/statemachine/README.md)
+- [Code generation](src/rigbox/plugins/code/README.md)
+- [DSP](src/rigbox/plugins/dsp/README.md)
+- [Built-in utilities and adding plugins](src/rigbox/plugins/README.md)
+
+## Layout
+
+- `src/rigbox/core/`: framework (registry, parsing, rendering, workspace, workflows, plugin loading)
+- `src/rigbox/plugins/`: built-in plugins
+- `docs/decisions.md`: architecture decisions and rationale
+- `CLAUDE.md`: conventions and preferences for contributors and Claude Code

rigbox-0.1.0/README.md

@@ -0,0 +1,68 @@
+# rigbox
+
+A manifest-driven REPL and CLI toolbox for embedded and DSP developers.
+
+## Setup
+
+Requires Python 3.11 or newer.
+
+```shell
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
+.\.venv\Scripts\python.exe -m pytest -q
+.\.venv\Scripts\ruff.exe check    # lint
+.\.venv\Scripts\ty.exe check      # type check
+```
+
+## Use
+
+```shell
+rigbox init my-project        # create a workspace (rigbox.yaml)
+rigbox                        # interactive shell (run from inside a workspace)
+rigbox run commands           # list the commands
+rigbox run commands --help    # one command's arguments
+rigbox run --format json commands
+rigbox script workflows\x.yaml --var key=value
+```
+
+Output is a human message (or a table for data-only commands) on a terminal and NDJSON when piped.
+Select `--format plaintext`, `rich`, `json`, or `ndjson` explicitly when needed.
+Human formats fall back to available text or a table of structured data; plaintext output omits styling.
+JSON and NDJSON never fall back to human text: human-only results produce an explicit error.
+Empty results produce `[]` in JSON or no NDJSON records, without warnings.
+
+### The shell
+
+The shell is a [cmd2](https://github.com/python-cmd2/cmd2) app; every rigbox command is a shell command with the same
+arguments and `--help` as `rigbox run`. Tab completes command names, option names, choices and file names. cmd2's own
+commands work too:
+
+```shell
+rigbox> help                           # commands grouped by area; `help commands` or `commands --help` for one
+rigbox> set format json                # print results as JSON (plaintext, rich, json, ndjson, auto)
+rigbox> alias create list commands     # then: list
+rigbox> commands | findstr workspace   # pipe to a shell command
+rigbox> commands > commands.txt        # redirect to a file
+rigbox> history                        # what you typed (kept in .rigbox/ inside a workspace)
+rigbox> exit                           # or quit, or Ctrl-D
+```
+
+The bar under the prompt shows the workspace, open device connections and output format.
+
+## Plugins
+
+See each plugin's README for commands, examples and behavior:
+
+- [Manifests](src/rigbox/plugins/manifests/README.md)
+- [Devices and transports](src/rigbox/plugins/device/README.md)
+- [State machines](src/rigbox/plugins/statemachine/README.md)
+- [Code generation](src/rigbox/plugins/code/README.md)
+- [DSP](src/rigbox/plugins/dsp/README.md)
+- [Built-in utilities and adding plugins](src/rigbox/plugins/README.md)
+
+## Layout
+
+- `src/rigbox/core/`: framework (registry, parsing, rendering, workspace, workflows, plugin loading)
+- `src/rigbox/plugins/`: built-in plugins
+- `docs/decisions.md`: architecture decisions and rationale
+- `CLAUDE.md`: conventions and preferences for contributors and Claude Code

rigbox-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rigbox"
+version = "0.1.0"
+description = "Embedded developer's toolbox: a manifest-driven REPL and CLI."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [
+    { name = "Jonathan Bailey", email = "jonathan.bailey@comcast.net" }
+]
+dependencies = [
+    "cmd2>=4.3,<5",
+    "construct>=2.10",
+    "jinja2>=3.1.6",
+    "networkx>=3.4,<4",
+    "numpy>=1.24",
+    "pluggy>=1.3",
+    "pydantic>=2",
+    "pyserial>=3.5",
+    "pyyaml>=6",
+    "rich>=15",
+    "scipy>=1.10",
+    "simpleeval>=1.0",
+    "transitions>=0.9",
+    "typer>=0.27.3",
+]
+
+[project.optional-dependencies]
+plot = ["matplotlib>=3.7"]
+# ty is pinned exactly: it is in beta (0.0.x) and its rules change between releases
+dev = ["pytest>=7", "matplotlib>=3.7", "ruff>=0.6", "ty==0.0.89"]
+
+[project.scripts]
+rigbox = "rigbox.cli:cli"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"rigbox.plugins.code" = ["macros/**/*.j2", "templates/**/*.j2"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ty.environment]
+python-version = "3.11"
+
+[tool.ty.src]
+include = ["src", "tests"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 160
+
+[tool.ruff.lint]
+# E/F: pycodestyle and pyflakes; I: import order; UP: modern syntax; B: likely bugs;
+# D: docstrings (Google style); ANN: type annotations
+select = ["E", "F", "I", "UP", "B", "D", "ANN"]
+ignore = [
+    "B008", # Do not perform function call `typer.Argument` in argument defaults
+    "ANN401", # Dynamically typed expressions are disallowed
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D"]  # tests are annotated like other code, but test functions don't need docstrings

rigbox-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

rigbox-0.1.0/src/rigbox/__init__.py

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

rigbox-0.1.0/src/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-0.1.0/src/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-0.1.0/src/rigbox/core/__init__.py

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

rigbox-0.1.0/src/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