bricklogger 0.2.0__py3-none-any.whl

bricklogger/__init__.py

@@ -0,0 +1,17 @@
+"""Bricklogger: a data bridge for building automation, driven by a Brick model.
+
+The package is laid out after the architecture in ``docs/architecture.md``:
+
+- ``bricklogger.daemon`` — the long-running core that collects and writes,
+- ``bricklogger.cli`` — the ``bricklogger`` command, the control plane,
+- ``bricklogger.web`` — the web interface served by ``bricklogger serve``,
+- ``bricklogger.mcp`` — the MCP server served by ``bricklogger mcp serve``, for
+  an AI assistant,
+- ``bricklogger.ops`` — the operations the CLI and the MCP server share,
+- ``bricklogger.sdk`` — the contract and the helpers plugins are built on,
+- ``bricklogger.plugins`` — the built-in source (BACnet/IP) and
+  destination (TimescaleDB), registered through the same entry points as
+  external plugins.
+"""
+
+__version__ = "0.2.0"

bricklogger/__main__.py

@@ -0,0 +1,6 @@
+"""``python -m bricklogger``: the same as the ``bricklogger`` command."""
+
+from bricklogger.cli import main
+
+if __name__ == "__main__":
+    main()

bricklogger/cli/__init__.py

@@ -0,0 +1,107 @@
+"""The ``bricklogger`` command: the control plane and the primary user interface.
+
+Every command maps to one operation on the daemon's API; see
+``docs/features/cli.md``. This module holds the root of the command tree and
+the global options; the command groups live in their own modules.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from bricklogger import __version__
+from bricklogger.cli.config import rules_app, validate_command
+from bricklogger.cli.context import CliContext
+from bricklogger.cli.daemon_commands import daemon_app, points_command, status_command
+from bricklogger.cli.init import init_command
+from bricklogger.cli.mcp_command import mcp_app
+from bricklogger.cli.model import model_app
+from bricklogger.cli.notify import notify_app
+from bricklogger.cli.plugins import plugins_app
+from bricklogger.cli.query import query_command
+from bricklogger.cli.roles import destinations_app, sources_app
+from bricklogger.cli.serve import serve_command
+from bricklogger.config import resolve_config_dir
+
+app = typer.Typer(
+    name="bricklogger",
+    help="Data bridge for building automation, driven by a Brick model.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _show_version(value: bool) -> None:
+    if value:
+        typer.echo(f"bricklogger {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    ctx: typer.Context,
+    config_dir: Annotated[
+        Path | None,
+        typer.Option(
+            "--config-dir",
+            help="The config directory; default $BRICKLOGGER_CONFIG_DIR, "
+            "then /etc/bricklogger when it exists, then ~/.config/bricklogger.",
+            show_default=False,
+        ),
+    ] = None,
+    api: Annotated[
+        str | None,
+        typer.Option(
+            "--api",
+            help="The daemon's API URL, for a deliberately exposed daemon; "
+            "default the binding in daemon.yaml.",
+            show_default=False,
+        ),
+    ] = None,
+    token: Annotated[
+        str | None,
+        typer.Option(
+            "--token",
+            envvar="BRICKLOGGER_API_TOKEN",
+            help="The API token; default the one in daemon.yaml.",
+            show_default=False,
+        ),
+    ] = None,
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            callback=_show_version,
+            is_eager=True,
+            help="Show the version and exit.",
+        ),
+    ] = False,
+) -> None:
+    """Collect data from a building's automation systems based on its Brick model."""
+    ctx.obj = CliContext(
+        config_dir=resolve_config_dir(config_dir), api_url=api, token=token
+    )
+
+
+app.command("init")(init_command)
+app.command("validate")(validate_command)
+app.command("status")(status_command)
+app.command("points")(points_command)
+app.add_typer(daemon_app, name="daemon")
+app.add_typer(sources_app, name="sources")
+app.add_typer(destinations_app, name="destinations")
+app.add_typer(rules_app, name="rules")
+app.add_typer(notify_app, name="notify")
+app.add_typer(plugins_app, name="plugins")
+app.add_typer(model_app, name="model")
+app.command("query")(query_command)
+app.command("serve")(serve_command)
+app.add_typer(mcp_app, name="mcp")
+
+
+def main() -> None:
+    """Entry point of the ``bricklogger`` console script."""
+    app()

bricklogger/cli/client.py

@@ -0,0 +1,62 @@
+"""The CLI's client for the daemon's API: the shared client, with every failure
+turned into the CLI's error message and exit."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Self
+
+import typer
+
+from bricklogger.cli.context import CliContext
+from bricklogger.cli.output import fail
+from bricklogger.ops.client import DaemonApi, describe_problem, format_error
+from bricklogger.ops.errors import OperationError
+
+if TYPE_CHECKING:
+    import httpx
+
+__all__ = ["ApiClient", "describe_problem", "format_error", "reachable_client"]
+
+
+class ApiClient(DaemonApi):
+    """Talks to one daemon; raises a CLI exit when it cannot be reached."""
+
+    @classmethod
+    def from_context(cls, context: CliContext) -> Self:
+        try:
+            return cls.from_directory(
+                context.config_dir, context.api_url, context.token
+            )
+        except OperationError as exc:
+            raise fail(exc.message) from exc
+
+    def prefixes(self) -> dict[str, str]:
+        """The active model's prefixes, for shortening URIs; empty when unknown."""
+        try:
+            found = self.get("/v1/models").get("prefixes")
+        except typer.Exit:
+            return {}
+        return dict(found) if isinstance(found, dict) else {}
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        try:
+            return super()._request(method, path, **kwargs)
+        except OperationError as exc:
+            raise fail(exc.message) from exc
+
+
+def reachable_client(context: CliContext) -> ApiClient | None:
+    """The client when ``--api`` names a daemon or one answers at the binding.
+
+    ``None`` means: work without a daemon. With ``--api`` the daemon is
+    required, so a client comes back whether it answers or not.
+    """
+    try:
+        client = ApiClient.from_context(context)
+    except typer.Exit:
+        if context.api_url is not None:
+            raise
+        return None
+    if context.api_url is not None or client.reachable():
+        return client
+    return None

bricklogger/cli/config.py

@@ -0,0 +1,199 @@
+"""The ``config`` views — one per owner of a file — and ``validate``.
+
+``daemon config``, ``sources config``, ``destinations config`` and ``rules
+config`` print their file as written; ``… config edit`` opens it in ``$EDITOR``
+and writes it validated as a whole, through the API when a daemon answers and
+directly to the file otherwise. ``validate`` checks the whole directory with
+the daemon's validation, or asks the daemon with ``--api``.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import Annotated, Any
+
+import click
+import typer
+
+from bricklogger.cli.client import ApiClient, reachable_client
+from bricklogger.cli.context import CliContext, cli_context, operations_of
+from bricklogger.cli.output import fail, issues_table, print_json, stderr
+from bricklogger.config import (
+    CONFIG_FILES,
+    ConfigIssue,
+    config_file,
+    parse_text,
+    read_texts,
+    validate_configuration,
+)
+from bricklogger.ops.config import write_file as write_config_file
+from bricklogger.ops.errors import OperationError
+from bricklogger.sdk.registry import PluginError, PluginRegistry
+
+JsonFlag = Annotated[
+    bool, typer.Option("--json", help="Emit the API's JSON instead of a table.")
+]
+YAML = "application/yaml"
+
+
+def edit_text(text: str) -> str | None:
+    """Open the text in the user's editor; ``None`` when it was not saved."""
+    return click.edit(text, extension=".yaml", require_save=True)
+
+
+def registry() -> PluginRegistry:
+    """The installed plugins, or a plain failure when one cannot be loaded."""
+    try:
+        return PluginRegistry.from_entry_points()
+    except PluginError as exc:
+        raise fail(str(exc)) from exc
+
+
+def validate_command(ctx: typer.Context, json_output: JsonFlag = False) -> None:
+    """Validate the whole config directory, including the plugins' schemas."""
+    context = cli_context(ctx)
+    if context.api_url is not None:
+        client = ApiClient.from_context(context)
+        data = client.post("/v1/config/validate")
+        report_validation(data, json_output, ok_line=f"ok: {client.base_url}")
+        return
+    result = validate_configuration(context.config_dir, registry())
+    summary = ""
+    if result.configuration is not None:
+        config = result.configuration
+        summary = ", ".join(
+            (
+                count(len(config.sources), "source"),
+                count(len(config.destinations), "destination"),
+                count(len(config.rules), "rule"),
+            )
+        )
+    report_validation(
+        result.as_dict(),
+        json_output,
+        ok_line=f"ok: {context.config_dir} ({summary})",
+        where=str(context.config_dir),
+    )
+
+
+def report_validation(
+    data: Mapping[str, Any], json_output: bool, *, ok_line: str, where: str = ""
+) -> None:
+    """Print a validation answer the way every command does, and exit on errors."""
+    if json_output:
+        print_json(data)
+        raise typer.Exit(0 if data["valid"] else 1)
+    if data["errors"]:
+        stderr.print(_issues_table("Errors", data["errors"]))
+    if data["warnings"]:
+        stderr.print(_issues_table("Warnings", data["warnings"]))
+    if not data["valid"]:
+        prefix = f"{where}: " if where else ""
+        typer.echo(f"{prefix}{count(len(data['errors']), 'error')}", err=True)
+        raise typer.Exit(1)
+    typer.echo(ok_line)
+
+
+def count(number: int, noun: str) -> str:
+    return f"{number} {noun}{'' if number == 1 else 's'}"
+
+
+def _issues_table(title: str, issues: list[dict[str, Any]]) -> Any:
+    from bricklogger.cli.output import issues_table
+
+    return issues_table(title, [ConfigIssue.from_dict(issue) for issue in issues])
+
+
+def config_view(name: str) -> typer.Typer:
+    """A ``config`` group for one file: ``show`` prints it, ``edit`` edits it."""
+    if name not in CONFIG_FILES:
+        raise ValueError(f"unknown configuration file {name!r}")
+    app = typer.Typer(
+        no_args_is_help=True,
+        help=f"{name}.yaml: show it as written, or edit it in $EDITOR.",
+    )
+
+    @app.command("show")
+    def show(ctx: typer.Context, json_output: JsonFlag = False) -> None:
+        """Print the file as written; environment variables are not expanded."""
+        show_file(cli_context(ctx), name, json_output)
+
+    @app.command("edit")
+    def edit(ctx: typer.Context) -> None:
+        """Edit the file in $EDITOR; validated as a whole before it is written."""
+        edit_file(cli_context(ctx), name)
+
+    return app
+
+
+def show_file(context: CliContext, name: str, json_output: bool) -> None:
+    """One file as written — through the API when asked for, from disk otherwise."""
+    if context.api_url is not None:
+        client = ApiClient.from_context(context)
+        if json_output:
+            parsed = client.get_text(f"/v1/config/{name}", accept="application/json")
+            print_json(json.loads(parsed))
+            return
+        typer.echo(f"# {client.base_url}")
+        typer.echo(client.get_text(f"/v1/config/{name}", accept=YAML).rstrip("\n"))
+        return
+    text = read_texts(context.config_dir)[name]
+    if json_output:
+        parsed, issues = parse_text(name, text)
+        if issues:
+            raise fail(str(issues[0]))
+        print_json(parsed)
+        return
+    path = config_file(context.config_dir, name)
+    typer.echo(f"# {context.config_dir}")
+    if text is None:
+        typer.echo(f"# {path.name} does not exist and is read as empty")
+    else:
+        typer.echo(text.rstrip("\n"))
+
+
+def edit_file(context: CliContext, name: str) -> None:
+    """Edit one file: through the API when a daemon answers, on disk otherwise."""
+    client = reachable_client(context)
+    if client is not None:
+        original = client.get_text(f"/v1/config/{name}", accept=YAML)
+    else:
+        original = read_texts(context.config_dir)[name] or ""
+    edited = edit_text(original)
+    if edited is None or edited == original:
+        typer.echo("no change")
+        return
+    result = write_file(context, client, name, edited)
+    if client is not None:
+        typer.echo(f"{name}.yaml written and applied")
+    else:
+        typer.echo(f"wrote {config_file(context.config_dir, name)}")
+    for warning in result.get("warnings", []):
+        typer.echo(f"warning: {warning['message']}")
+
+
+def write_file(
+    context: CliContext, client: ApiClient | None, name: str, text: str
+) -> Mapping[str, Any]:
+    """Write one file validated as a whole, and return what the validation said.
+
+    Through the API the daemon validates and applies; without one the directory
+    is validated with the change in place of the file, and nothing is written
+    when it does not hold.
+    """
+    try:
+        return write_config_file(operations_of(context), client, name, text)
+    except OperationError as exc:
+        raise failure(exc) from exc
+
+
+def failure(exc: OperationError) -> typer.Exit:
+    """The exit of a failed operation: its issues as a table, then the message."""
+    if exc.issues:
+        stderr.print(issues_table("Errors", exc.issues))
+    return fail(exc.message)
+
+
+rules_app = typer.Typer(no_args_is_help=True, help="The rule set: rules.yaml.")
+rules_app.add_typer(config_view("rules"), name="config")

bricklogger/cli/context.py

@@ -0,0 +1,32 @@
+"""What every command needs from the root: the config directory and API access."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import typer
+
+from bricklogger.ops import Operations
+
+
+@dataclass
+class CliContext:
+    config_dir: Path
+    api_url: str | None = None
+    token: str | None = None
+
+
+def cli_context(ctx: typer.Context) -> CliContext:
+    """The context the root callback stored, whichever subcommand is running."""
+    found = ctx.find_object(CliContext)
+    if found is None:
+        raise RuntimeError("the CLI root has not set up its context")
+    return found
+
+
+def operations_of(context: CliContext) -> Operations:
+    """The operations the command works through, from the root options."""
+    return Operations(
+        config_dir=context.config_dir, api_url=context.api_url, token=context.token
+    )