picotty 1.0.0__tar.gz

picotty-1.0.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: picotty
+Version: 1.0.0
+Summary: Networked serial console + USB HID keyboard injection for a fleet of headless machines — hub server, client SDK, and wire protocol.
+Keywords: serial,console,kvm,homelab,raspberry-pi,pico,circuitpython,hid,keyboard,out-of-band,fastapi
+Author: morpheuslord
+Author-email: morpheuslord <gopalkrishna.bs1971@gmail.com>
+License-Expression: GPL-3.0-or-later
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Hardware
+Classifier: Topic :: System :: Systems Administration
+Requires-Dist: httpx>=0.27
+Requires-Dist: websockets>=12
+Requires-Dist: fastapi>=0.110 ; extra == 'hub'
+Requires-Dist: uvicorn[standard]>=0.27 ; extra == 'hub'
+Requires-Dist: aiosqlite>=0.19 ; extra == 'hub'
+Requires-Dist: pydantic>=2.0 ; extra == 'hub'
+Requires-Dist: pyyaml>=6.0 ; extra == 'hub'
+Requires-Dist: python-telegram-bot[rate-limiter]>=21,<22 ; extra == 'telegram'
+Requires-Dist: pyotp>=2.9 ; extra == 'telegram'
+Maintainer: morpheuslord
+Maintainer-email: morpheuslord <gopalkrishna.bs1971@gmail.com>
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/morpheuslord/PICOTTY
+Project-URL: Repository, https://github.com/morpheuslord/PICOTTY
+Project-URL: Documentation, https://github.com/morpheuslord/PICOTTY/tree/main/docs
+Project-URL: Issues, https://github.com/morpheuslord/PICOTTY/issues
+Provides-Extra: hub
+Provides-Extra: telegram
+Description-Content-Type: text/markdown
+
+# Hub — the `picotty` package
+
+The management side, packaged as the **`picotty`** Python distribution (uv). One
+process on one asyncio event loop runs two faces at once — a raw TCP server for
+the node swarm and a FastAPI app for the browser — over a shared in-memory
+registry and one SQLite database.
+
+One distribution, three import surfaces:
+
+| Import | What | Needs |
+|---|---|---|
+| `picotty.hub` | the server (registry + SQLite + :9000 TCP + FastAPI dashboard) | `[hub]` extra |
+| `picotty.client` | the SDK: `HubClient` (REST) + `HubEvents` (WebSocket) | base install |
+| `picotty.protocol` | wire framing, validation, `PROTOCOL_VERSION` | base install |
+
+The lean base (httpx + websockets) is all a client needs; the server stack
+(FastAPI, uvicorn, aiosqlite, pydantic, pyyaml) comes from the `[hub]` extra, so a
+Pi Zero 2 W running only the Telegram sidecar stays small.
+
+## Layout
+
+```
+hub/
+  pyproject.toml        # the picotty distribution (uv_build backend)
+  uv.lock               # pinned, reproducible installs
+  .python-version       # 3.11 floor
+  src/picotty/
+    __init__.py         # version, single-sourced from distribution metadata
+    protocol.py         # public wire-protocol surface (re-exports hub/protocol.py)
+    client/             # the SDK: HubClient (REST) + HubEvents (WS async iterator)
+    sim.py              # the node simulator (picotty-sim console script)
+    static/             # the dashboard, shipped inside the wheel (served at /)
+    hub/                # the server
+      main.py           # wires TCP + FastAPI + background tasks on one loop
+      config.py         # process config (env) + operator-tunable defaults
+      protocol.py       # length-prefixed JSON framing (authoritative)
+      registry.py       # in-memory NodeState registry
+      db.py             # aiosqlite: schema, queries, batched output, retention
+      eventbus.py       # WebSocket fan-out with subscription filtering
+      core.py           # the shared Hub: dispatch, ping/pong, audit, view-merge
+      tcp_server.py     # swarm face on :9000
+      telegram_setup.py # writes the sidecar .env for the dashboard's Telegram page
+      tasks.py          # sweep, output flush, retention, stats, loop-lag
+      api/{rest,ws,models}.py
+  tests/                # test_db.py, test_integration.py, driver.py
+  scripts/              # install / run / systemd unit
+```
+
+## Run it (from source, with uv)
+
+```bash
+bash scripts/install.sh          # uv sync --extra hub (+ fetches terminal libs)
+bash scripts/run.sh              # foreground (dev), loads private/hub-token.txt
+# or install as a service that starts on boot:
+bash scripts/install-service.sh  # renders + enables the systemd unit
+journalctl -u swarm-hub -f       # follow logs
+```
+
+Manual equivalent:
+
+```bash
+cd hub
+uv sync --extra hub
+uv run --extra hub picotty-hub
+```
+
+Or install it as a tool (no repo checkout): `uv tool install picotty`, which puts
+`picotty-hub` and `picotty-sim` on PATH. See **[../docs/packaging.md](../docs/packaging.md)**.
+
+On first start the hub mints a **shared node token** and prints it once — put it
+in each node's `settings.toml` as `NODE_TOKEN`. It listens on `:9000` (swarm) and
+`:8080` (browser). Open http://localhost:8080 for the dashboard.
+
+Configuration via environment (all optional): `HUB_TCP_PORT`, `HUB_HTTP_PORT`,
+`HUB_DB_PATH`, `HUB_STATIC_DIR`, `HUB_TCP_HOST`, `HUB_HTTP_HOST`, `TELEGRAM_ENV_PATH`.
+Runtime state (the SQLite DB) defaults to `~/.local/share/picotty/hub.db` (honors
+`XDG_DATA_HOME`); the systemd unit uses `/var/lib/picotty`. Static assets ship
+inside the wheel. Operator-tunable settings (heartbeat, stale timeout, retention,
+confirm-dangerous, alerts) live in the DB and change via `PATCH /api/settings`.
+
+Run under **one** uvicorn worker only. The single event loop is the design: a
+second worker would get its own registry and node sockets and the two would
+disagree about who is online.
+
+## Test without hardware
+
+Start the hub, grab the printed token, then run one or more fake nodes with the
+packaged simulator:
+
+```bash
+uv run picotty-sim --id node-01 --token <TOKEN>
+uv run picotty-sim --id node-02 --token <TOKEN>
+```
+
+Each simulator connects, heartbeats, answers commands, and streams fake serial
+output — enough to exercise the full dashboard. The suites:
+
+```bash
+uv run python tests/test_db.py           # offline db checks
+uv run python tests/test_integration.py  # end-to-end over real TCP + REST
+```
+
+## Using the client SDK
+
+```python
+from picotty.client import HubClient
+
+async with HubClient("http://hub:8080") as hub:
+    print(await hub.health())
+    async with hub.events_stream() as stream:   # the /ws feed
+        await stream.subscribe("node-01")
+        async for ev in stream:
+            ...
+```
+
+This is what the Telegram sidecar imports; it needs only the base install.
+
+## Notes
+
+- **Registry is disposable.** On restart it starts empty and refills as nodes
+  reconnect; the SQLite record survives.
+- **Output is batched** to SQLite (default every 500 ms) to protect SD-card write
+  throughput; the live WebSocket stream is immediate and independent.
+- **Auth is optional** and off by default — the design assumes an isolated
+  management VLAN reached through a VPN/tunnel, not port exposure.

picotty-1.0.0/README.md

@@ -0,0 +1,125 @@
+# Hub — the `picotty` package
+
+The management side, packaged as the **`picotty`** Python distribution (uv). One
+process on one asyncio event loop runs two faces at once — a raw TCP server for
+the node swarm and a FastAPI app for the browser — over a shared in-memory
+registry and one SQLite database.
+
+One distribution, three import surfaces:
+
+| Import | What | Needs |
+|---|---|---|
+| `picotty.hub` | the server (registry + SQLite + :9000 TCP + FastAPI dashboard) | `[hub]` extra |
+| `picotty.client` | the SDK: `HubClient` (REST) + `HubEvents` (WebSocket) | base install |
+| `picotty.protocol` | wire framing, validation, `PROTOCOL_VERSION` | base install |
+
+The lean base (httpx + websockets) is all a client needs; the server stack
+(FastAPI, uvicorn, aiosqlite, pydantic, pyyaml) comes from the `[hub]` extra, so a
+Pi Zero 2 W running only the Telegram sidecar stays small.
+
+## Layout
+
+```
+hub/
+  pyproject.toml        # the picotty distribution (uv_build backend)
+  uv.lock               # pinned, reproducible installs
+  .python-version       # 3.11 floor
+  src/picotty/
+    __init__.py         # version, single-sourced from distribution metadata
+    protocol.py         # public wire-protocol surface (re-exports hub/protocol.py)
+    client/             # the SDK: HubClient (REST) + HubEvents (WS async iterator)
+    sim.py              # the node simulator (picotty-sim console script)
+    static/             # the dashboard, shipped inside the wheel (served at /)
+    hub/                # the server
+      main.py           # wires TCP + FastAPI + background tasks on one loop
+      config.py         # process config (env) + operator-tunable defaults
+      protocol.py       # length-prefixed JSON framing (authoritative)
+      registry.py       # in-memory NodeState registry
+      db.py             # aiosqlite: schema, queries, batched output, retention
+      eventbus.py       # WebSocket fan-out with subscription filtering
+      core.py           # the shared Hub: dispatch, ping/pong, audit, view-merge
+      tcp_server.py     # swarm face on :9000
+      telegram_setup.py # writes the sidecar .env for the dashboard's Telegram page
+      tasks.py          # sweep, output flush, retention, stats, loop-lag
+      api/{rest,ws,models}.py
+  tests/                # test_db.py, test_integration.py, driver.py
+  scripts/              # install / run / systemd unit
+```
+
+## Run it (from source, with uv)
+
+```bash
+bash scripts/install.sh          # uv sync --extra hub (+ fetches terminal libs)
+bash scripts/run.sh              # foreground (dev), loads private/hub-token.txt
+# or install as a service that starts on boot:
+bash scripts/install-service.sh  # renders + enables the systemd unit
+journalctl -u swarm-hub -f       # follow logs
+```
+
+Manual equivalent:
+
+```bash
+cd hub
+uv sync --extra hub
+uv run --extra hub picotty-hub
+```
+
+Or install it as a tool (no repo checkout): `uv tool install picotty`, which puts
+`picotty-hub` and `picotty-sim` on PATH. See **[../docs/packaging.md](../docs/packaging.md)**.
+
+On first start the hub mints a **shared node token** and prints it once — put it
+in each node's `settings.toml` as `NODE_TOKEN`. It listens on `:9000` (swarm) and
+`:8080` (browser). Open http://localhost:8080 for the dashboard.
+
+Configuration via environment (all optional): `HUB_TCP_PORT`, `HUB_HTTP_PORT`,
+`HUB_DB_PATH`, `HUB_STATIC_DIR`, `HUB_TCP_HOST`, `HUB_HTTP_HOST`, `TELEGRAM_ENV_PATH`.
+Runtime state (the SQLite DB) defaults to `~/.local/share/picotty/hub.db` (honors
+`XDG_DATA_HOME`); the systemd unit uses `/var/lib/picotty`. Static assets ship
+inside the wheel. Operator-tunable settings (heartbeat, stale timeout, retention,
+confirm-dangerous, alerts) live in the DB and change via `PATCH /api/settings`.
+
+Run under **one** uvicorn worker only. The single event loop is the design: a
+second worker would get its own registry and node sockets and the two would
+disagree about who is online.
+
+## Test without hardware
+
+Start the hub, grab the printed token, then run one or more fake nodes with the
+packaged simulator:
+
+```bash
+uv run picotty-sim --id node-01 --token <TOKEN>
+uv run picotty-sim --id node-02 --token <TOKEN>
+```
+
+Each simulator connects, heartbeats, answers commands, and streams fake serial
+output — enough to exercise the full dashboard. The suites:
+
+```bash
+uv run python tests/test_db.py           # offline db checks
+uv run python tests/test_integration.py  # end-to-end over real TCP + REST
+```
+
+## Using the client SDK
+
+```python
+from picotty.client import HubClient
+
+async with HubClient("http://hub:8080") as hub:
+    print(await hub.health())
+    async with hub.events_stream() as stream:   # the /ws feed
+        await stream.subscribe("node-01")
+        async for ev in stream:
+            ...
+```
+
+This is what the Telegram sidecar imports; it needs only the base install.
+
+## Notes
+
+- **Registry is disposable.** On restart it starts empty and refills as nodes
+  reconnect; the SQLite record survives.
+- **Output is batched** to SQLite (default every 500 ms) to protect SD-card write
+  throughput; the live WebSocket stream is immediate and independent.
+- **Auth is optional** and off by default — the design assumes an isolated
+  management VLAN reached through a VPN/tunnel, not port exposure.

picotty-1.0.0/pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["uv_build>=0.11,<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "picotty"
+version = "1.0.0"
+description = "Networked serial console + USB HID keyboard injection for a fleet of headless machines — hub server, client SDK, and wire protocol."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "GPL-3.0-or-later"
+authors = [{ name = "morpheuslord", email = "gopalkrishna.bs1971@gmail.com" }]
+maintainers = [{ name = "morpheuslord", email = "gopalkrishna.bs1971@gmail.com" }]
+keywords = ["serial", "console", "kvm", "homelab", "raspberry-pi", "pico",
+            "circuitpython", "hid", "keyboard", "out-of-band", "fastapi"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Environment :: Web Environment",
+    "Framework :: FastAPI",
+    "Intended Audience :: System Administrators",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Hardware",
+    "Topic :: System :: Systems Administration",
+]
+
+# Base install is the lean CLIENT: enough to talk to a running hub (SDK, scripts,
+# the Telegram sidecar, CI). The server pulls its heavier stack via the [hub]
+# extra so a client — or a Pi Zero 2 W running only the sidecar — stays small.
+dependencies = [
+    "httpx>=0.27",
+    "websockets>=12",
+]
+
+[project.optional-dependencies]
+hub = [
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.27",
+    "aiosqlite>=0.19",
+    "pydantic>=2.0",
+    "pyyaml>=6.0",
+]
+telegram = [
+    "python-telegram-bot[rate-limiter]>=21,<22",
+    "pyotp>=2.9",
+]
+
+[project.scripts]
+picotty-hub = "picotty.hub.main:main"
+picotty-sim = "picotty.sim:main"
+
+[project.urls]
+Homepage = "https://github.com/morpheuslord/PICOTTY"
+Repository = "https://github.com/morpheuslord/PICOTTY"
+Documentation = "https://github.com/morpheuslord/PICOTTY/tree/main/docs"
+Issues = "https://github.com/morpheuslord/PICOTTY/issues"
+
+# Dev tooling lives in a uv dependency group, NOT an extra, so it never leaks
+# into user installs. `uv sync` installs it; `uv sync --no-dev` omits it.
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "httpx>=0.27",
+]
+
+[tool.uv.build-backend]
+# src/ layout: the package is src/picotty. (module-name/module-root shown
+# explicitly even though these are the backend defaults, so the intent is clear.)
+module-name = "picotty"
+module-root = "src"

picotty-1.0.0/src/picotty/__init__.py

@@ -0,0 +1,28 @@
+"""PICOTTY — networked serial console + HID keyboard injection for a fleet of
+headless machines.
+
+One distribution, three import surfaces (see Dev-Docs/improvement-docs/picotty-packaging.md):
+
+- ``picotty.hub``      — the server (registry + SQLite + :9000 TCP + FastAPI).
+                         Needs the ``[hub]`` extra.
+- ``picotty.client``   — the SDK: :class:`~picotty.client.HubClient` (REST) and
+                         :class:`~picotty.client.HubEvents` (WebSocket feed).
+                         Lean; base install (httpx + websockets) only.
+- ``picotty.protocol`` — the wire protocol: frame pack/unpack, validation,
+                         ``PROTOCOL_VERSION`` and command constants. The single
+                         authoritative definition shared by hub, client, sim.
+
+The version is single-sourced from the installed distribution metadata (the
+``version`` field in pyproject.toml).
+"""
+
+from __future__ import annotations
+
+try:
+    from importlib.metadata import PackageNotFoundError, version
+
+    __version__ = version("picotty")
+except Exception:  # running from a source tree with no metadata yet
+    __version__ = "0.0.0+source"
+
+__all__ = ["__version__"]

picotty-1.0.0/src/picotty/client/__init__.py

@@ -0,0 +1,175 @@
+"""``picotty.client`` — the hub SDK.
+
+Everything a program needs to talk to a running hub, over the same REST API and
+``/ws`` event stream the dashboard uses:
+
+- :class:`HubClient`  — async REST wrapper (health, stats, nodes, commands, send).
+- :class:`HubEvents`  — async iterator over the WebSocket event feed, with
+                        per-node subscribe/unsubscribe.
+
+Lean by design: only ``httpx`` and ``websockets``, so the base ``picotty`` install
+(no ``[hub]`` extra, no FastAPI) is all a client — the Telegram sidecar, a cron
+health check, CI — needs.
+
+    from picotty.client import HubClient
+
+    async with HubClient("http://hub:8080") as hub:
+        print(await hub.health())
+        async with hub.events_stream() as stream:
+            await stream.subscribe("node-01")
+            async for ev in stream:
+                ...
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+from typing import AsyncIterator, Optional
+
+import httpx
+import websockets
+
+
+class HubError(Exception):
+    """A hub REST call returned a non-JSON body or a server (5xx) error."""
+
+
+def _derive_ws(base_url: str) -> str:
+    base = base_url.rstrip("/")
+    if base.startswith("https://"):
+        return "wss://" + base[len("https://"):] + "/ws"
+    if base.startswith("http://"):
+        return "ws://" + base[len("http://"):] + "/ws"
+    return "ws://" + base + "/ws"
+
+
+class HubClient:
+    """Async REST client for a running hub. The hub mounts REST under ``/api`` and
+    the WebSocket at ``/ws``; pass the server root as ``base_url``."""
+
+    def __init__(self, base_url: str, *, timeout: float = 10.0,
+                 ws_url: Optional[str] = None):
+        self._base = base_url.rstrip("/")
+        self._ws_url = ws_url or _derive_ws(self._base)
+        self._http = httpx.AsyncClient(base_url=self._base + "/api", timeout=timeout)
+
+    async def __aenter__(self) -> "HubClient":
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    # -- generic REST ---------------------------------------------------------
+
+    async def get(self, path: str, **params) -> dict:
+        params = {k: v for k, v in params.items() if v is not None}
+        r = await self._http.get(path, params=params)
+        r.raise_for_status()
+        return r.json()
+
+    async def post(self, path: str, body: Optional[dict] = None) -> dict:
+        r = await self._http.post(path, json=body or {})
+        if r.status_code >= 500:
+            r.raise_for_status()
+        try:
+            return r.json()
+        except ValueError:
+            raise HubError("non-JSON reply from hub (%s)" % r.status_code)
+
+    # -- typed convenience ----------------------------------------------------
+
+    async def health(self) -> dict:
+        return await self.get("/health")
+
+    async def stats(self) -> dict:
+        return await self.get("/stats")
+
+    async def nodes(self, **filters) -> list[dict]:
+        return (await self.get("/nodes", **filters)).get("nodes", [])
+
+    async def node(self, node_id: str) -> Optional[dict]:
+        data = await self.get("/nodes/%s" % node_id)
+        return data.get("node") if data.get("ok") else None
+
+    async def events(self, since: Optional[int] = None, limit: int = 100,
+                     type_: Optional[str] = None) -> list[dict]:
+        data = await self.get("/events", since=since, limit=limit, type=type_)
+        return data.get("events", [])
+
+    async def cmd(self, node_id: str, command: dict) -> dict:
+        return await self.post("/nodes/%s/cmd" % node_id, command)
+
+    async def send_serial(self, node_id: str, *, data: Optional[str] = None,
+                          raw: Optional[str] = None) -> dict:
+        """Write into a node's serial getty (the hub `send` command). Exactly one
+        of ``data`` (UTF-8 text) or ``raw`` (hex bytes), mirroring firmware."""
+        body: dict = {"type": "send"}
+        if data is not None:
+            body["data"] = data
+        if raw is not None:
+            body["raw"] = raw
+        return await self.cmd(node_id, body)
+
+    async def reboot(self, node_id: str) -> dict:
+        return await self.post("/nodes/%s/reboot" % node_id)
+
+    async def sysrq(self, node_id: str, command: str) -> dict:
+        return await self.post("/nodes/%s/sysrq" % node_id, {"command": command})
+
+    # -- live event stream ----------------------------------------------------
+
+    def events_stream(self, **connect_kwargs) -> "HubEventsCM":
+        """Return an async context manager yielding a :class:`HubEvents`."""
+        return HubEventsCM(self._ws_url, connect_kwargs)
+
+    # Short alias used in the docstring / common case.
+    def events_ws(self, **connect_kwargs) -> "HubEventsCM":
+        return self.events_stream(**connect_kwargs)
+
+
+class HubEventsCM:
+    def __init__(self, ws_url: str, connect_kwargs: dict):
+        self._ws_url = ws_url
+        self._connect_kwargs = connect_kwargs
+        self._sock = None
+
+    async def __aenter__(self) -> "HubEvents":
+        kwargs = {"ping_interval": 20, "ping_timeout": 20, "max_size": 2 ** 20}
+        kwargs.update(self._connect_kwargs)
+        self._sock = await websockets.connect(self._ws_url, **kwargs)
+        return HubEvents(self._sock)
+
+    async def __aexit__(self, *exc) -> None:
+        if self._sock is not None:
+            await self._sock.close()
+
+
+class HubEvents:
+    """An async iterator over the hub's WebSocket event feed.
+
+    Low-volume events (node up/down, heartbeat, node_state) arrive to everyone;
+    high-volume per-node ``output``/``result`` events arrive only after
+    :meth:`subscribe`."""
+
+    def __init__(self, sock):
+        self._sock = sock
+
+    async def subscribe(self, node_id: str) -> None:
+        await self._sock.send(json.dumps({"type": "subscribe", "node_id": node_id}))
+
+    async def unsubscribe(self, node_id: str) -> None:
+        await self._sock.send(json.dumps({"type": "unsubscribe", "node_id": node_id}))
+
+    async def __aiter__(self) -> AsyncIterator[dict]:
+        async for raw in self._sock:
+            try:
+                yield json.loads(raw)
+            except (ValueError, TypeError):
+                continue
+
+
+__all__ = ["HubClient", "HubEvents", "HubEventsCM", "HubError"]

picotty-1.0.0/src/picotty/hub/__init__.py

@@ -0,0 +1,35 @@
+"""``picotty.hub`` — the server.
+
+A single asyncio process that runs two faces on one event loop:
+
+- a raw TCP server on :9000 facing the node swarm (the wire protocol), and
+- a FastAPI app on :8080 facing the browser (REST + WebSocket + static dashboard).
+
+They share one in-memory registry and one SQLite database. Import this only with
+the ``[hub]`` extra installed (FastAPI, uvicorn, aiosqlite, pydantic, pyyaml); a
+plain client needs :mod:`picotty.client` instead.
+
+Public surface:
+
+- :class:`Hub`  — the shared owner of the registry, SQLite, protocol and events.
+- :func:`serve` — bring the hub up (the ``picotty-hub`` console entry point).
+"""
+
+from __future__ import annotations
+
+from .. import __version__  # single-sourced from the distribution metadata
+from .core import Hub
+
+__all__ = ["Hub", "serve", "build_app", "__version__"]
+
+
+def build_app():
+    """Return the FastAPI application (lazy: imports the server stack on demand)."""
+    from .main import build_app as _build_app
+    return _build_app()
+
+
+def serve() -> None:
+    """Run the hub (uvicorn). Backs the ``picotty-hub`` console script."""
+    from .main import main as _main
+    _main()