beamboard 0.0.1__tar.gz

beamboard-0.0.1/.gitignore

@@ -0,0 +1,9 @@
+.DS_Store
+__pycache__/
+server/data/
+mac/.build/
+mac/BeamBoard.app/
+.venv/
+dist/
+build/
+*.egg-info/

beamboard-0.0.1/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.5
+Name: beamboard
+Version: 0.0.1
+Summary: Beam your clipboard between devices: the pbd server plus the pb client
+Author-email: Jonas Eschmann <jonas.eschmann@gmail.com>
+Keywords: clipboard,pasteboard,pbcopy,pbpaste,self-hosted,sync
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# beamboard — pasteboard sync
+
+Self-hosted clipboard sync for devices on a Tailnet (or any private network).
+Three small programs (the two Python ones ship as one package, `beamboard`),
+one tiny HTTP+JSON protocol:
+
+```
+ macOS app  ──┐                      ┌── TrueNAS docker-compose
+ (menubar,    ├── HTTP over Tailnet ─┤    pbd + SQLite
+  pasteboard  │                      └── history capped at N clips
+  sync)       │
+ pb CLI    ───┘  (copy / paste / history / watch)
+```
+
+The server is the single source of truth; every clip gets a monotonically
+increasing `seq`. Clients are stateless and reconcile against `seq`.
+Everything is plain text, stdlib-only Python, and dependency-free Swift.
+
+## Server (TrueNAS / docker-compose)
+
+```sh
+cd server
+docker compose up -d --build
+```
+
+Point the volume in `docker-compose.yml` at a dataset
+(e.g. `/mnt/tank/apps/pb:/data`, writable by uid 1000) for persistent history.
+
+Or run it anywhere with Python: `pipx install beamboard` (from a checkout:
+`pipx install .`), then `PB_DATA=./data pbd` (alias: `pb serve`). No dependencies.
+
+| Env | Default | |
+|---|---|---|
+| `PB_PORT` | `8737` | listen port |
+| `PB_DATA` | `~/.local/share/pb` (`/data` in Docker) | directory for `pb.db` |
+| `PB_TOKEN` | *(unset)* | optional shared bearer token; unset = no auth (trust the Tailnet) |
+| `PB_HISTORY` | `100` | clips to keep |
+| `PB_MAX_BYTES` | `1048576` | max clip size |
+
+## CLI client (Linux or anywhere)
+
+```sh
+pipx install beamboard     # from a checkout: pipx install .   (or: make install)
+pb config url http://truenas:8737   # saved to ~/.config/pb/config.json
+# pb config token ...               # if the server sets PB_TOKEN
+
+echo "text" | pb copy      # copy to the shared pasteboard
+pb paste > file.txt        # paste from it (byte-verbatim)
+pb history [n] [--json]    # recent clips
+pb watch                   # print each new clip as it arrives (pipeable)
+```
+
+The same stdlib-only package (`beamboard`) provides the `pbd` server and the
+`pb` command, also installed as `beamboard` (`beamboard/server.py` and `cli.py`).
+`pb copy`/`pb paste` behave like macOS `pbcopy`/`pbpaste`; a symlink or alias
+named `pbcopy`/`pbpaste` pointing at `pb` restores the old spelling.
+`pb config` shows the effective settings; `PB_URL`, `PB_TOKEN` and `PB_DEVICE`
+override the config file (device defaults to the hostname). `make check` builds
+the sdist and wheel and validates them for PyPI.
+
+## macOS menubar app
+
+```sh
+make -C mac app        # builds BeamBoard.app (SwiftPM, no Xcode project)
+make -C mac install    # copies it to /Applications
+```
+
+Open BeamBoard, click the clipboard icon in the menu bar, and set the server URL
+(and token) in the settings. The app then:
+
+- watches the system pasteboard (polls `changeCount` twice a second — the
+  pasteboard has no change notifications) and pushes new local clips,
+- long-polls the server and writes clips from other devices into the
+  system pasteboard,
+- shows the shared history in the menu bar; clicking an entry copies it.
+
+It never overwrites your pasteboard at launch — syncing starts with the first
+actual change on either side. Requires macOS 13+. The build is ad-hoc signed;
+add it to Login Items for autostart.
+
+## Protocol
+
+Clip: `{seq: int, ts: float, mime: "text/plain", text: str, device: str}`
+
+| Endpoint | Behavior |
+|---|---|
+| `GET /clip` | latest clip, `204` if empty |
+| `POST /clip` `{text, device}` | store new head, returns `{seq}`; identical to current head → deduped (returns existing seq) |
+| `GET /history?limit=50` | recent clips, newest first |
+| `GET /watch?since=SEQ&timeout=30` | long-poll: latest clip once head `seq > SEQ`, else `204` on timeout |
+| `GET /healthz` | `200 ok` (never requires auth) |
+
+With `PB_TOKEN` set, all other endpoints require `Authorization: Bearer <token>`.
+Long-polling keeps every client a dumb HTTP GET loop — no streams, no state,
+self-healing across server restarts.
+
+Echo loops are broken by three cheap layers: the server dedups identical
+consecutive text, the macOS app skips pasteboard changes it caused itself,
+and the `device` field lets clients ignore their own clips from `/watch`.
+
+## Security
+
+There is no TLS and (by default) no auth: the design assumes the server is
+only reachable over a trusted private network such as a Tailnet. Set
+`PB_TOKEN` for a cheap second layer. Do not expose the port to the internet.

beamboard-0.0.1/README.md

@@ -0,0 +1,105 @@
+# beamboard — pasteboard sync
+
+Self-hosted clipboard sync for devices on a Tailnet (or any private network).
+Three small programs (the two Python ones ship as one package, `beamboard`),
+one tiny HTTP+JSON protocol:
+
+```
+ macOS app  ──┐                      ┌── TrueNAS docker-compose
+ (menubar,    ├── HTTP over Tailnet ─┤    pbd + SQLite
+  pasteboard  │                      └── history capped at N clips
+  sync)       │
+ pb CLI    ───┘  (copy / paste / history / watch)
+```
+
+The server is the single source of truth; every clip gets a monotonically
+increasing `seq`. Clients are stateless and reconcile against `seq`.
+Everything is plain text, stdlib-only Python, and dependency-free Swift.
+
+## Server (TrueNAS / docker-compose)
+
+```sh
+cd server
+docker compose up -d --build
+```
+
+Point the volume in `docker-compose.yml` at a dataset
+(e.g. `/mnt/tank/apps/pb:/data`, writable by uid 1000) for persistent history.
+
+Or run it anywhere with Python: `pipx install beamboard` (from a checkout:
+`pipx install .`), then `PB_DATA=./data pbd` (alias: `pb serve`). No dependencies.
+
+| Env | Default | |
+|---|---|---|
+| `PB_PORT` | `8737` | listen port |
+| `PB_DATA` | `~/.local/share/pb` (`/data` in Docker) | directory for `pb.db` |
+| `PB_TOKEN` | *(unset)* | optional shared bearer token; unset = no auth (trust the Tailnet) |
+| `PB_HISTORY` | `100` | clips to keep |
+| `PB_MAX_BYTES` | `1048576` | max clip size |
+
+## CLI client (Linux or anywhere)
+
+```sh
+pipx install beamboard     # from a checkout: pipx install .   (or: make install)
+pb config url http://truenas:8737   # saved to ~/.config/pb/config.json
+# pb config token ...               # if the server sets PB_TOKEN
+
+echo "text" | pb copy      # copy to the shared pasteboard
+pb paste > file.txt        # paste from it (byte-verbatim)
+pb history [n] [--json]    # recent clips
+pb watch                   # print each new clip as it arrives (pipeable)
+```
+
+The same stdlib-only package (`beamboard`) provides the `pbd` server and the
+`pb` command, also installed as `beamboard` (`beamboard/server.py` and `cli.py`).
+`pb copy`/`pb paste` behave like macOS `pbcopy`/`pbpaste`; a symlink or alias
+named `pbcopy`/`pbpaste` pointing at `pb` restores the old spelling.
+`pb config` shows the effective settings; `PB_URL`, `PB_TOKEN` and `PB_DEVICE`
+override the config file (device defaults to the hostname). `make check` builds
+the sdist and wheel and validates them for PyPI.
+
+## macOS menubar app
+
+```sh
+make -C mac app        # builds BeamBoard.app (SwiftPM, no Xcode project)
+make -C mac install    # copies it to /Applications
+```
+
+Open BeamBoard, click the clipboard icon in the menu bar, and set the server URL
+(and token) in the settings. The app then:
+
+- watches the system pasteboard (polls `changeCount` twice a second — the
+  pasteboard has no change notifications) and pushes new local clips,
+- long-polls the server and writes clips from other devices into the
+  system pasteboard,
+- shows the shared history in the menu bar; clicking an entry copies it.
+
+It never overwrites your pasteboard at launch — syncing starts with the first
+actual change on either side. Requires macOS 13+. The build is ad-hoc signed;
+add it to Login Items for autostart.
+
+## Protocol
+
+Clip: `{seq: int, ts: float, mime: "text/plain", text: str, device: str}`
+
+| Endpoint | Behavior |
+|---|---|
+| `GET /clip` | latest clip, `204` if empty |
+| `POST /clip` `{text, device}` | store new head, returns `{seq}`; identical to current head → deduped (returns existing seq) |
+| `GET /history?limit=50` | recent clips, newest first |
+| `GET /watch?since=SEQ&timeout=30` | long-poll: latest clip once head `seq > SEQ`, else `204` on timeout |
+| `GET /healthz` | `200 ok` (never requires auth) |
+
+With `PB_TOKEN` set, all other endpoints require `Authorization: Bearer <token>`.
+Long-polling keeps every client a dumb HTTP GET loop — no streams, no state,
+self-healing across server restarts.
+
+Echo loops are broken by three cheap layers: the server dedups identical
+consecutive text, the macOS app skips pasteboard changes it caused itself,
+and the `device` field lets clients ignore their own clips from `/watch`.
+
+## Security
+
+There is no TLS and (by default) no auth: the design assumes the server is
+only reachable over a trusted private network such as a Tailnet. Set
+`PB_TOKEN` for a cheap second layer. Do not expose the port to the internet.

beamboard-0.0.1/beamboard/__init__.py

@@ -0,0 +1,3 @@
+"""beamboard: self-hosted pasteboard sync (pbd server + pb client)."""
+
+__version__ = "0.0.1"

beamboard-0.0.1/beamboard/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

beamboard-0.0.1/beamboard/cli.py

@@ -0,0 +1,243 @@
+"""pb -- pasteboard sync client (beamboard is a synonym). stdlib only.
+
+Usage:
+  echo "text" | pb copy
+  pb paste > file.txt
+  pb history [n] [--json]
+  pb watch
+  pb config                     show effective settings and where they come from
+  pb config url http://truenas:8737     save the server URL (keys: url, token, device)
+  pb --version
+  pbd                           (or: pb serve)
+
+Settings come from the environment, then the config file
+(~/.config/pb/config.json, honoring $XDG_CONFIG_HOME; %APPDATA%\\pb on Windows):
+  PB_URL     server base URL, e.g. http://truenas:8737   (required)
+  PB_TOKEN   bearer token, if the server has PB_TOKEN set
+  PB_DEVICE  device name reported to the server          (default: hostname)
+"""
+
+import json
+import os
+import socket
+import sys
+import time
+import urllib.error
+import urllib.request
+
+from . import __version__
+
+KEYS = ("url", "token", "device")
+
+
+class PbError(Exception):
+    def __init__(self, msg, transient=False):
+        super().__init__(msg)
+        self.transient = transient  # worth retrying (network), vs. fatal (4xx)
+
+
+def config_path():
+    if os.name == "nt":
+        base = os.environ.get("APPDATA") or os.path.expanduser("~")
+    else:
+        base = os.environ.get("XDG_CONFIG_HOME") or os.path.expanduser("~/.config")
+    return os.path.join(base, "pb", "config.json")
+
+
+def load_config():
+    try:
+        with open(config_path(), encoding="utf-8") as f:
+            cfg = json.load(f)
+    except FileNotFoundError:
+        return {}
+    except (OSError, ValueError) as e:
+        raise PbError(f"cannot read {config_path()}: {e}") from e
+    return cfg if isinstance(cfg, dict) else {}
+
+
+def save_config(cfg):
+    path = config_path()
+    os.makedirs(os.path.dirname(path), mode=0o700, exist_ok=True)
+    tmp = path + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(cfg, f, indent=2)
+        f.write("\n")
+    os.chmod(tmp, 0o600)  # the file may hold the token
+    os.replace(tmp, path)
+
+
+_settings = None
+
+
+def settings():
+    """Effective (url, token, device) and per-key source, env over config file."""
+    global _settings
+    if _settings is None:
+        cfg = load_config()
+        values, sources = {}, {}
+        for key in KEYS:
+            env = "PB_" + key.upper()
+            if os.environ.get(env):
+                values[key], sources[key] = os.environ[env], env
+            elif cfg.get(key):
+                values[key], sources[key] = str(cfg[key]), "config"
+            else:
+                values[key], sources[key] = "", "unset"
+        if not values["device"]:
+            values["device"], sources["device"] = socket.gethostname(), "hostname"
+        values["url"] = values["url"].rstrip("/")
+        _settings = values, sources
+    return _settings
+
+
+def request(method, path, body=None, timeout=10):
+    """Returns (status, parsed-json-or-None). Raises PbError on failure."""
+    values, _ = settings()
+    url, token = values["url"], values["token"]
+    if not url:
+        raise PbError("server URL not set: run `pb config url http://host:8737` or export PB_URL")
+    headers = {"Content-Type": "application/json"}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    data = json.dumps(body).encode() if body is not None else None
+    req = urllib.request.Request(url + path, data=data, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            raw = resp.read()
+            return resp.status, json.loads(raw) if raw else None
+    except urllib.error.HTTPError as e:
+        detail = e.read().decode(errors="replace").strip()
+        raise PbError(f"server returned {e.code}: {detail or e.reason}") from e
+    except (urllib.error.URLError, TimeoutError, ConnectionError) as e:
+        reason = getattr(e, "reason", e)
+        raise PbError(f"cannot reach {url}: {reason}", transient=True) from e
+
+
+def cmd_config(args):
+    if not args:
+        values, sources = settings()
+        path = config_path()
+        print(f"config: {path}" + ("" if os.path.exists(path) else " (not created yet)"))
+        for key in KEYS:
+            shown = values[key] or "(unset)"
+            if key == "token" and values[key]:
+                shown = "*" * 8
+            print(f"{key + ':':8}{shown}  [{sources[key]}]")
+        return
+    key = args[0]
+    if key not in KEYS or len(args) > 2:
+        raise PbError("usage: pb config [url|token|device] [VALUE]  (empty VALUE unsets)")
+    cfg = load_config()
+    if len(args) == 1:
+        print(cfg.get(key, ""))
+        return
+    value = args[1].strip()
+    if key == "url" and value:
+        value = value.rstrip("/")
+        if not value.startswith(("http://", "https://")):
+            raise PbError("url must start with http:// or https://")
+    if value:
+        cfg[key] = value
+    else:
+        cfg.pop(key, None)
+    save_config(cfg)
+    print(f"{key} {'saved to' if value else 'removed from'} {config_path()}")
+
+
+def cmd_copy():
+    text = sys.stdin.buffer.read().decode("utf-8", "replace")
+    request("POST", "/clip", {"text": text, "device": settings()[0]["device"]})
+
+
+def cmd_paste():
+    status, clip = request("GET", "/clip")
+    if status == 204:
+        return  # empty history: no output, exit 0 (matches macOS pbpaste)
+    sys.stdout.buffer.write(clip["text"].encode())
+    sys.stdout.buffer.flush()
+
+
+def cmd_history(args):
+    as_json = "--json" in args
+    args = [a for a in args if a != "--json"]
+    limit = int(args[0]) if args else 20
+    _, resp = request("GET", f"/history?limit={limit}")
+    if as_json:
+        json.dump(resp, sys.stdout, ensure_ascii=False, indent=2)
+        print()
+        return
+    for clip in resp["clips"]:
+        ts = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(clip["ts"]))
+        preview = " ".join(clip["text"].split())
+        if len(preview) > 80:
+            preview = preview[:79] + "…"
+        print(f"{clip['seq']}\t{ts}\t{clip['device']}\t{preview}")
+
+
+def cmd_watch():
+    """Print each new clip as it arrives. Composable; survives server restarts."""
+    since = 0
+    primed = False
+    while True:
+        try:
+            if not primed:
+                status, clip = request("GET", "/clip")
+                since = clip["seq"] if status == 200 else 0
+                primed = True
+            _, resp = request("GET", f"/watch?since={since}&timeout=30", timeout=45)
+        except PbError as e:
+            if not e.transient:
+                raise
+            time.sleep(2)  # server unreachable: retry quietly
+            continue
+        if resp is None:
+            continue  # long-poll timeout, ask again
+        since = resp["seq"]
+        print(resp["text"], flush=True)
+
+
+def run(cmd, args):
+    try:
+        if cmd == "copy":
+            cmd_copy()
+        elif cmd == "paste":
+            cmd_paste()
+        elif cmd == "history":
+            cmd_history(args)
+        elif cmd == "watch":
+            cmd_watch()
+        elif cmd == "config":
+            cmd_config(args)
+        elif cmd == "serve":
+            from .server import main as serve
+            serve()
+        elif cmd in ("version", "--version", "-V"):
+            print(f"pb {__version__}")
+        else:
+            print(__doc__.strip(), file=sys.stderr)
+            sys.exit(0 if cmd in ("help", "--help", "-h") else 2)
+    except PbError as e:
+        print(f"pb: {e}", file=sys.stderr)
+        sys.exit(1)
+    except KeyboardInterrupt:
+        sys.exit(130)
+    except BrokenPipeError:
+        sys.exit(0)
+
+
+def main(argv=None):
+    args = sys.argv[1:] if argv is None else list(argv)
+    prog = os.path.basename(sys.argv[0])
+    if prog == "pbcopy":
+        cmd = "copy"
+    elif prog == "pbpaste":
+        cmd = "paste"
+    elif args:
+        cmd, args = args[0], args[1:]
+    else:
+        cmd = "help"
+    run(cmd, args)
+
+
+if __name__ == "__main__":
+    main()

beamboard-0.0.1/beamboard/server.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+"""pbd -- minimal pasteboard sync server.
+
+Stdlib only. HTTP+JSON, SQLite persistence, long-poll watch.
+
+Env:
+  PB_PORT       listen port                    (default 8737)
+  PB_DATA       data directory for pb.db       (default ~/.local/share/pb; /data in Docker)
+  PB_TOKEN      optional shared bearer token   (default: no auth)
+  PB_HISTORY    number of clips to keep        (default 100)
+  PB_MAX_BYTES  max request body size          (default 1 MiB)
+"""
+
+import hmac
+import json
+import os
+import sqlite3
+import sys
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import parse_qs, urlparse
+
+from . import __version__
+
+PORT = int(os.environ.get("PB_PORT", "8737"))
+DATA = os.environ.get("PB_DATA") or os.path.join(os.path.expanduser("~"), ".local", "share", "pb")
+TOKEN = os.environ.get("PB_TOKEN", "")
+HISTORY = int(os.environ.get("PB_HISTORY", "100"))
+MAX_BYTES = int(os.environ.get("PB_MAX_BYTES", str(1024 * 1024)))
+
+WATCH_TIMEOUT_MAX = 60.0
+
+
+class Store:
+    """All access serialized under one lock; watchers wait on the condition."""
+
+    def __init__(self, path):
+        self.cond = threading.Condition()
+        self.db = sqlite3.connect(path, check_same_thread=False)
+        self.db.execute("PRAGMA journal_mode=WAL")
+        self.db.execute(
+            "CREATE TABLE IF NOT EXISTS clips("
+            " seq INTEGER PRIMARY KEY AUTOINCREMENT,"
+            " ts REAL NOT NULL,"
+            " mime TEXT NOT NULL,"
+            " text TEXT NOT NULL,"
+            " device TEXT NOT NULL)"
+        )
+        self.db.commit()
+
+    @staticmethod
+    def _clip(row):
+        if row is None:
+            return None
+        seq, ts, mime, text, device = row
+        return {"seq": seq, "ts": ts, "mime": mime, "text": text, "device": device}
+
+    def _latest(self):
+        row = self.db.execute(
+            "SELECT seq, ts, mime, text, device FROM clips ORDER BY seq DESC LIMIT 1"
+        ).fetchone()
+        return self._clip(row)
+
+    def latest(self):
+        with self.cond:
+            return self._latest()
+
+    def add(self, text, device, mime="text/plain"):
+        with self.cond:
+            head = self._latest()
+            if head is not None and head["text"] == text:
+                return head  # dedup: identical to current head, no new entry
+            self.db.execute(
+                "INSERT INTO clips(ts, mime, text, device) VALUES(?, ?, ?, ?)",
+                (time.time(), mime, text, device),
+            )
+            self.db.execute(
+                "DELETE FROM clips WHERE seq NOT IN"
+                " (SELECT seq FROM clips ORDER BY seq DESC LIMIT ?)",
+                (HISTORY,),
+            )
+            self.db.commit()
+            self.cond.notify_all()
+            return self._latest()
+
+    def history(self, limit):
+        with self.cond:
+            rows = self.db.execute(
+                "SELECT seq, ts, mime, text, device FROM clips"
+                " ORDER BY seq DESC LIMIT ?",
+                (limit,),
+            ).fetchall()
+            return [self._clip(r) for r in rows]
+
+    def watch(self, since, timeout):
+        """Block until a clip with seq > since exists, or timeout. Returns clip or None."""
+        deadline = time.monotonic() + timeout
+        with self.cond:
+            while True:
+                head = self._latest()
+                if head is not None and head["seq"] > since:
+                    return head
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    return None
+                self.cond.wait(remaining)
+
+
+class Handler(BaseHTTPRequestHandler):
+    protocol_version = "HTTP/1.1"
+    server_version = f"pbd/{__version__}"
+
+    @property
+    def store(self):
+        return self.server.store
+
+    def log_request(self, code="-", size="-"):
+        # Long-poll timeouts and healthchecks are routine; don't spam the log.
+        # path is unset when the request line failed to parse (e.g. a TLS hello).
+        if str(code) == "204" or getattr(self, "path", "") == "/healthz":
+            return
+        super().log_request(code, size)
+
+    def send(self, status, obj=None, text=None):
+        body = b""
+        ctype = "application/json"
+        if obj is not None:
+            body = json.dumps(obj, ensure_ascii=False).encode()
+        elif text is not None:
+            body = text.encode()
+            ctype = "text/plain; charset=utf-8"
+        self.send_response(status)
+        if body:
+            self.send_header("Content-Type", ctype)
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        if body:
+            self.wfile.write(body)
+
+    def authed(self):
+        if not TOKEN:
+            return True
+        got = self.headers.get("Authorization", "")
+        if hmac.compare_digest(got, f"Bearer {TOKEN}"):
+            return True
+        self.send(401, {"error": "unauthorized"})
+        return False
+
+    @staticmethod
+    def qint(qs, key, default, lo, hi):
+        try:
+            return max(lo, min(hi, int(qs.get(key, [default])[0])))
+        except ValueError:
+            return default
+
+    def do_GET(self):
+        url = urlparse(self.path)
+        qs = parse_qs(url.query)
+        if url.path == "/healthz":
+            return self.send(200, text="ok\n")
+        if not self.authed():
+            return
+        if url.path == "/clip":
+            clip = self.store.latest()
+            return self.send(200, clip) if clip else self.send(204)
+        if url.path == "/history":
+            limit = self.qint(qs, "limit", 50, 1, HISTORY)
+            return self.send(200, {"clips": self.store.history(limit)})
+        if url.path == "/watch":
+            since = self.qint(qs, "since", 0, 0, 2**62)
+            timeout = self.qint(qs, "timeout", 30, 1, int(WATCH_TIMEOUT_MAX))
+            clip = self.store.watch(since, float(timeout))
+            return self.send(200, clip) if clip else self.send(204)
+        self.send(404, {"error": "not found"})
+
+    def do_POST(self):
+        if not self.authed():
+            return
+        if urlparse(self.path).path != "/clip":
+            return self.send(404, {"error": "not found"})
+        length = int(self.headers.get("Content-Length", "0") or "0")
+        if length > MAX_BYTES:
+            # Drain the body (bounded) so the client reads our 413 instead of EPIPE.
+            remaining = min(length, 64 * 1024 * 1024)
+            while remaining > 0:
+                chunk = self.rfile.read(min(65536, remaining))
+                if not chunk:
+                    break
+                remaining -= len(chunk)
+            self.close_connection = True
+            return self.send(413, {"error": f"body exceeds {MAX_BYTES} bytes"})
+        try:
+            req = json.loads(self.rfile.read(length))
+            text = req["text"]
+            if not isinstance(text, str):
+                raise ValueError("text must be a string")
+        except (ValueError, KeyError, TypeError) as e:
+            return self.send(400, {"error": f"bad request: {e}"})
+        device = str(req.get("device", ""))
+        mime = str(req.get("mime", "text/plain"))
+        clip = self.store.add(text, device, mime)
+        self.send(200, {"seq": clip["seq"]})
+
+
+def main():
+    os.makedirs(DATA, exist_ok=True)
+    server = ThreadingHTTPServer(("0.0.0.0", PORT), Handler)
+    server.store = Store(os.path.join(DATA, "pb.db"))
+    print(f"pbd listening on :{PORT} (data={DATA}, history={HISTORY},"
+          f" auth={'on' if TOKEN else 'off'})", file=sys.stderr)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    main()

beamboard-0.0.1/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "beamboard"
+dynamic = ["version"]
+description = "Beam your clipboard between devices: the pbd server plus the pb client"
+readme = "README.md"
+requires-python = ">=3.8"
+authors = [{ name = "Jonas Eschmann", email = "jonas.eschmann@gmail.com" }]
+keywords = ["clipboard", "pasteboard", "sync", "pbcopy", "pbpaste", "self-hosted"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Utilities",
+]
+dependencies = []
+
+[project.scripts]
+pb = "beamboard.cli:main"
+beamboard = "beamboard.cli:main"
+pbd = "beamboard.server:main"
+
+[tool.hatch.version]
+path = "beamboard/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["beamboard"]
+
+[tool.hatch.build.targets.sdist]
+include = ["beamboard", "README.md", "pyproject.toml"]