telefi 0.3.0__tar.gz

telefi-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Huang
+
+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.

telefi-0.3.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: telefi
+Version: 0.3.0
+Summary: Telegram as a two-way control surface for scripts, CI and agents: drop a JSON envelope in a folder, get a readable message, and receive the owner's replies back as events.
+Author: Michael Huang
+License: MIT
+Project-URL: Homepage, https://github.com/sibulus13/telefi
+Project-URL: Issues, https://github.com/sibulus13/telefi/issues
+Keywords: telegram,two-way,chatops,human-in-the-loop,notifications,agents
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows :: Windows 11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest==8.4.2; extra == "dev"
+Dynamic: license-file
+
+# TeleFi
+
+> **Developed and verified on Windows 11** (build 26200, Python 3.12.4). Pure standard-library
+> Python, so other platforms should work, but only Windows 11 is tested today.
+
+**Telegram as a two-way control surface for your scripts, CI and autonomous agents.** Programs
+drop a small JSON file in a folder; TeleFi sends it to your Telegram in a readable format and
+records the delivery. You answer from your phone (a button, a typed note, a `/command`) and TeleFi
+hands your answer back to the program as a validated JSON event. Pure Python standard library:
+no runtime dependencies.
+
+```mermaid
+flowchart TD
+    P["your programs<br/>(any language)"] -->|"envelope JSON<br/>into spool/out/"| H["TeleFi hub"]
+    H --> T["your Telegram<br/>(glance-first message)"]
+    H --> L["local records<br/>outbox / inbox / conversation"]
+    T -->|"tap · reply · /command"| H
+    H -->|"inbound JSON<br/>to a queue or a command"| P
+```
+
+## Why TeleFi
+
+- **Steer autonomous code from your phone.** An agent or CI job hits a failure; you tap *Retry with
+  note*, type "use the 2016-2025 window", and the job receives that note as an event. No laptop, no
+  remote session.
+- **One way to notify, from any language.** Producers write a JSON file: no SDK, no network code, no
+  bot token in every program. A producer works even while the hub is down (the file waits).
+- **Readable at a glance.** A one-line headline, a one-line "so what", details folded away, links
+  as buttons. Every program's messages look the same.
+- **Everything is on record.** Every message, every delivery result, every reply and the whole chat
+  transcript, as JSON lines on your disk, rotated before they fill up.
+- **Contracts, not conventions.** Messages, replies, config and command lists are JSON Schemas; a
+  new program adopts TeleFi by reading `telefi schema envelope.v1`.
+
+## Features
+
+| feature | how |
+|---|---|
+| Routing | config rules by source, kind and severity -> Telegram, a local file, or a mock |
+| Dedup, holds, ack | one delivery per `dedup_key` per window; `not_before` holds a message (a grace period); Ack silences re-alerts for N days |
+| Glance-first format | headline + insight, collapsed details, URL buttons, action buttons |
+| Two-way | buttons, ForceReply prompts for notes, replies to any message, `/commands` |
+| Command registry | each program ships a manifest; `/help`, `/list` and Telegram's `/` menu are built from them |
+| Sinks | `queue` (a folder your program drains) or `command` (a program fed the event on stdin; its last output line is the reply) |
+| Log rotation | each log rotates at `rotate_at` x `max_bytes` (the safety margin), keeping `keep` old files |
+| Safe tests | a mock adapter by default; live sends only with `TELEFI_LIVE=1` |
+
+## Requirements
+
+| | |
+|---|---|
+| OS | Windows 11 (verified). Linux/macOS untested. |
+| Python | 3.12 (verified with 3.12.4) |
+| Runtime dependencies | none ([requirements.txt](requirements.txt) says so explicitly) |
+| Test dependencies | pinned in [requirements-dev.txt](requirements-dev.txt) (pytest 8.4.2 and its deps) |
+| Telegram | a bot token from @BotFather and your chat id |
+
+## Try it locally, step by step
+
+Each step is self-contained and was run end to end on 2026-10-25. Steps 1-5 need no Telegram.
+
+**1. Install and run the tests** (expect all green, one live test skipped)
+
+```bash
+git clone <this repo> telefi && cd telefi
+pip install -e . -r requirements-dev.txt
+python -m pytest
+```
+
+**2. Use a throwaway home** so nothing touches a real install
+
+```bash
+export TELEFI_HOME="$PWD/.try"          # PowerShell: $env:TELEFI_HOME = "$PWD\.try"
+```
+
+**3. See every message type exactly as Telegram shows it** (sends nothing)
+
+```bash
+python -m telefi preview
+```
+
+**4. Route the samples through the full pipeline with the mock channel**
+
+```bash
+python -m telefi samples
+# ci.failure [error] -> telegram=ok, file=ok   ... mode: mock (nothing sent)
+```
+
+**5. Publish your own message, deliver it, and read the record**
+
+```bash
+python -c "from telefi import envelope, publish; publish(envelope(source='me', kind='info', severity='info', title='hello from TeleFi'))"
+python -m telefi drain                   # info routes to the local file only
+tail -1 .try/outbox.jsonl                # the envelope and each channel's result
+```
+
+**6. Connect Telegram.** Copy `examples/.env.example` to `.env` (git-ignored) and fill it in. Create a bot with [@BotFather](https://t.me/BotFather), send it any message,
+and read your chat id from `https://api.telegram.org/bot<TOKEN>/getUpdates`.
+
+| variable | required | meaning |
+|---|---|---|
+| `TELEGRAM_BOT_TOKEN` | yes | the bot token from BotFather |
+| `TELEGRAM_CHAT_ID` | yes | the only chat TeleFi talks to; every other chat is ignored |
+| `TELEFI_HOME` | no | config and records (default `~/.telefi`) |
+| `TELEFI_SPOOL` | no | the drop folder (default `$TELEFI_HOME/spool`) |
+
+```bash
+python -m telefi samples --send          # one real message of each type
+```
+
+**7. Turn on replies.** Copy the full example config (every option, documented in
+[docs/CONFIGURATION.md](docs/CONFIGURATION.md)); it enables replies, routes `/ci` commands to
+`examples/echo_sink.py` and lists `examples/commands.example.json`:
+
+```bash
+cp examples/hub.example.json "$TELEFI_HOME/hub.json"
+python -m telefi serve                   # leave running; one hub per bot
+```
+
+In Telegram: send `/help`, then `/list`, then `/ci retry 7 try again`; the echo sink answers
+`retry received`. Tap *Retry with note* on a sample from step 6, type a note, and see it echoed.
+
+**8. Check the records**
+
+```bash
+tail -3 "$TELEFI_HOME/conversation.jsonl"   # both directions, in order
+tail -1 "$TELEFI_HOME/inbox.jsonl"          # your reply and what the sink returned
+```
+
+## Run it in the background (optional)
+
+The hub is one long-running command, `python -m telefi serve`: run it under whatever you already
+use to keep processes alive. Two ready-made examples:
+
+- Windows 11 (verified): `powershell -NoProfile -File examples/windows-service.ps1` registers a
+  scheduled task running `pythonw.exe -m telefi serve` (no console window), restarted every 5
+  minutes if it stops.
+- Linux (untested): `examples/telefi.service` (systemd user unit).
+
+Command sinks run in the hub's working directory, so give them absolute paths (or `cwd`).
+
+## Send from your program
+
+```python
+from telefi import envelope, publish
+
+publish(envelope(source="ci", kind="failure", severity="error",
+                 title="Build #43 failed", insight="Tests passed; the deploy step timed out.",
+                 body="step deploy: timeout after 600s", dedup_key="ci:build:43",
+                 actions=[{"id": "retry_note", "label": "Retry with note", "namespace": "ci",
+                           "input": {"prompt": "What should change?"}}]))
+```
+
+From any other language, write the same JSON to `$TELEFI_HOME/spool/out/<id>.json` atomically
+(write a temp file, then rename): see `examples/publish.mjs` for Node. Replies reach your program
+through a command sink (`examples/echo_sink.py`) or a queue folder (`examples/queue_drain.py`).
+
+## Examples (one per configurable part, all validated by the tests)
+
+| file | what it configures |
+|---|---|
+| `examples/.env.example` | secrets and paths |
+| `examples/hub.minimal.json` | send-only hub |
+| `examples/hub.example.json` | every hub option: routes, channels, dedup, logs, replies, sinks |
+| `examples/commands.example.json` | an app's `/commands` |
+| `examples/envelope.example.json` | every message field |
+| `examples/inbound.example.json` | what your program receives |
+| `examples/echo_sink.py`, `examples/queue_drain.py` | the two kinds of reply handler |
+| `examples/publish.mjs` | publishing from Node |
+| `examples/windows-service.ps1`, `examples/telefi.service` | running in the background (optional) |
+
+## Reference
+
+- Contracts: `python -m telefi schema envelope.v1 | inbound.v1 | hub_config.v1 | commands.v1`
+- [Configuration reference](docs/CONFIGURATION.md) · [Design](docs/DESIGN.md) · [Similar projects](docs/LANDSCAPE.md)
+
+## License
+
+MIT, see [LICENSE](LICENSE).

telefi-0.3.0/README.md

@@ -0,0 +1,179 @@
+# TeleFi
+
+> **Developed and verified on Windows 11** (build 26200, Python 3.12.4). Pure standard-library
+> Python, so other platforms should work, but only Windows 11 is tested today.
+
+**Telegram as a two-way control surface for your scripts, CI and autonomous agents.** Programs
+drop a small JSON file in a folder; TeleFi sends it to your Telegram in a readable format and
+records the delivery. You answer from your phone (a button, a typed note, a `/command`) and TeleFi
+hands your answer back to the program as a validated JSON event. Pure Python standard library:
+no runtime dependencies.
+
+```mermaid
+flowchart TD
+    P["your programs<br/>(any language)"] -->|"envelope JSON<br/>into spool/out/"| H["TeleFi hub"]
+    H --> T["your Telegram<br/>(glance-first message)"]
+    H --> L["local records<br/>outbox / inbox / conversation"]
+    T -->|"tap · reply · /command"| H
+    H -->|"inbound JSON<br/>to a queue or a command"| P
+```
+
+## Why TeleFi
+
+- **Steer autonomous code from your phone.** An agent or CI job hits a failure; you tap *Retry with
+  note*, type "use the 2016-2025 window", and the job receives that note as an event. No laptop, no
+  remote session.
+- **One way to notify, from any language.** Producers write a JSON file: no SDK, no network code, no
+  bot token in every program. A producer works even while the hub is down (the file waits).
+- **Readable at a glance.** A one-line headline, a one-line "so what", details folded away, links
+  as buttons. Every program's messages look the same.
+- **Everything is on record.** Every message, every delivery result, every reply and the whole chat
+  transcript, as JSON lines on your disk, rotated before they fill up.
+- **Contracts, not conventions.** Messages, replies, config and command lists are JSON Schemas; a
+  new program adopts TeleFi by reading `telefi schema envelope.v1`.
+
+## Features
+
+| feature | how |
+|---|---|
+| Routing | config rules by source, kind and severity -> Telegram, a local file, or a mock |
+| Dedup, holds, ack | one delivery per `dedup_key` per window; `not_before` holds a message (a grace period); Ack silences re-alerts for N days |
+| Glance-first format | headline + insight, collapsed details, URL buttons, action buttons |
+| Two-way | buttons, ForceReply prompts for notes, replies to any message, `/commands` |
+| Command registry | each program ships a manifest; `/help`, `/list` and Telegram's `/` menu are built from them |
+| Sinks | `queue` (a folder your program drains) or `command` (a program fed the event on stdin; its last output line is the reply) |
+| Log rotation | each log rotates at `rotate_at` x `max_bytes` (the safety margin), keeping `keep` old files |
+| Safe tests | a mock adapter by default; live sends only with `TELEFI_LIVE=1` |
+
+## Requirements
+
+| | |
+|---|---|
+| OS | Windows 11 (verified). Linux/macOS untested. |
+| Python | 3.12 (verified with 3.12.4) |
+| Runtime dependencies | none ([requirements.txt](requirements.txt) says so explicitly) |
+| Test dependencies | pinned in [requirements-dev.txt](requirements-dev.txt) (pytest 8.4.2 and its deps) |
+| Telegram | a bot token from @BotFather and your chat id |
+
+## Try it locally, step by step
+
+Each step is self-contained and was run end to end on 2026-10-25. Steps 1-5 need no Telegram.
+
+**1. Install and run the tests** (expect all green, one live test skipped)
+
+```bash
+git clone <this repo> telefi && cd telefi
+pip install -e . -r requirements-dev.txt
+python -m pytest
+```
+
+**2. Use a throwaway home** so nothing touches a real install
+
+```bash
+export TELEFI_HOME="$PWD/.try"          # PowerShell: $env:TELEFI_HOME = "$PWD\.try"
+```
+
+**3. See every message type exactly as Telegram shows it** (sends nothing)
+
+```bash
+python -m telefi preview
+```
+
+**4. Route the samples through the full pipeline with the mock channel**
+
+```bash
+python -m telefi samples
+# ci.failure [error] -> telegram=ok, file=ok   ... mode: mock (nothing sent)
+```
+
+**5. Publish your own message, deliver it, and read the record**
+
+```bash
+python -c "from telefi import envelope, publish; publish(envelope(source='me', kind='info', severity='info', title='hello from TeleFi'))"
+python -m telefi drain                   # info routes to the local file only
+tail -1 .try/outbox.jsonl                # the envelope and each channel's result
+```
+
+**6. Connect Telegram.** Copy `examples/.env.example` to `.env` (git-ignored) and fill it in. Create a bot with [@BotFather](https://t.me/BotFather), send it any message,
+and read your chat id from `https://api.telegram.org/bot<TOKEN>/getUpdates`.
+
+| variable | required | meaning |
+|---|---|---|
+| `TELEGRAM_BOT_TOKEN` | yes | the bot token from BotFather |
+| `TELEGRAM_CHAT_ID` | yes | the only chat TeleFi talks to; every other chat is ignored |
+| `TELEFI_HOME` | no | config and records (default `~/.telefi`) |
+| `TELEFI_SPOOL` | no | the drop folder (default `$TELEFI_HOME/spool`) |
+
+```bash
+python -m telefi samples --send          # one real message of each type
+```
+
+**7. Turn on replies.** Copy the full example config (every option, documented in
+[docs/CONFIGURATION.md](docs/CONFIGURATION.md)); it enables replies, routes `/ci` commands to
+`examples/echo_sink.py` and lists `examples/commands.example.json`:
+
+```bash
+cp examples/hub.example.json "$TELEFI_HOME/hub.json"
+python -m telefi serve                   # leave running; one hub per bot
+```
+
+In Telegram: send `/help`, then `/list`, then `/ci retry 7 try again`; the echo sink answers
+`retry received`. Tap *Retry with note* on a sample from step 6, type a note, and see it echoed.
+
+**8. Check the records**
+
+```bash
+tail -3 "$TELEFI_HOME/conversation.jsonl"   # both directions, in order
+tail -1 "$TELEFI_HOME/inbox.jsonl"          # your reply and what the sink returned
+```
+
+## Run it in the background (optional)
+
+The hub is one long-running command, `python -m telefi serve`: run it under whatever you already
+use to keep processes alive. Two ready-made examples:
+
+- Windows 11 (verified): `powershell -NoProfile -File examples/windows-service.ps1` registers a
+  scheduled task running `pythonw.exe -m telefi serve` (no console window), restarted every 5
+  minutes if it stops.
+- Linux (untested): `examples/telefi.service` (systemd user unit).
+
+Command sinks run in the hub's working directory, so give them absolute paths (or `cwd`).
+
+## Send from your program
+
+```python
+from telefi import envelope, publish
+
+publish(envelope(source="ci", kind="failure", severity="error",
+                 title="Build #43 failed", insight="Tests passed; the deploy step timed out.",
+                 body="step deploy: timeout after 600s", dedup_key="ci:build:43",
+                 actions=[{"id": "retry_note", "label": "Retry with note", "namespace": "ci",
+                           "input": {"prompt": "What should change?"}}]))
+```
+
+From any other language, write the same JSON to `$TELEFI_HOME/spool/out/<id>.json` atomically
+(write a temp file, then rename): see `examples/publish.mjs` for Node. Replies reach your program
+through a command sink (`examples/echo_sink.py`) or a queue folder (`examples/queue_drain.py`).
+
+## Examples (one per configurable part, all validated by the tests)
+
+| file | what it configures |
+|---|---|
+| `examples/.env.example` | secrets and paths |
+| `examples/hub.minimal.json` | send-only hub |
+| `examples/hub.example.json` | every hub option: routes, channels, dedup, logs, replies, sinks |
+| `examples/commands.example.json` | an app's `/commands` |
+| `examples/envelope.example.json` | every message field |
+| `examples/inbound.example.json` | what your program receives |
+| `examples/echo_sink.py`, `examples/queue_drain.py` | the two kinds of reply handler |
+| `examples/publish.mjs` | publishing from Node |
+| `examples/windows-service.ps1`, `examples/telefi.service` | running in the background (optional) |
+
+## Reference
+
+- Contracts: `python -m telefi schema envelope.v1 | inbound.v1 | hub_config.v1 | commands.v1`
+- [Configuration reference](docs/CONFIGURATION.md) · [Design](docs/DESIGN.md) · [Similar projects](docs/LANDSCAPE.md)
+
+## License
+
+MIT, see [LICENSE](LICENSE).

telefi-0.3.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "telefi"
+version = "0.3.0"
+description = "Telegram as a two-way control surface for scripts, CI and agents: drop a JSON envelope in a folder, get a readable message, and receive the owner's replies back as events."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "Michael Huang" }]
+keywords = ["telegram", "two-way", "chatops", "human-in-the-loop", "notifications", "agents"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: Microsoft :: Windows :: Windows 11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Communications :: Chat",
+]
+# Runtime is pure standard library: no third-party dependencies.
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/sibulus13/telefi"
+Issues = "https://github.com/sibulus13/telefi/issues"
+
+[project.scripts]
+telefi = "telefi.__main__:main"
+
+[project.optional-dependencies]
+dev = ["pytest==8.4.2"]
+
+[tool.setuptools.packages.find]
+include = ["telefi*"]
+
+[tool.setuptools.package-data]
+"telefi" = ["schemas/*.json"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]

telefi-0.3.0/setup.cfg

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

telefi-0.3.0/telefi/__init__.py

@@ -0,0 +1,9 @@
+"""TeleFi: a Telegram adapter layer for two-way messaging; channels and reply sinks are adapters.
+
+Producers: `from telefi import envelope, publish` (Python) or write an envelope.v1 JSON file
+into the spool's out/ directory (any language). Design: docs/HUB_DESIGN.md. Format: render.py.
+"""
+from telefi.core import drain, envelope, publish, spool_root
+from telefi.render import render_telegram
+
+__all__ = ["drain", "envelope", "publish", "render_telegram", "spool_root"]

telefi-0.3.0/telefi/__main__.py

@@ -0,0 +1,127 @@
+"""TeleFi CLI.
+
+    python -m telefi drain                 deliver everything in the spool once (the scheduled task)
+    python -m telefi serve [--interval 30] drain forever; also long-polls Telegram if inbound.enabled
+    python -m telefi preview [type ...]    print each sample exactly as the owner would see it (no send)
+    python -m telefi samples [--send]      route the samples; mock unless --send (then really delivers)
+    python -m telefi validate <file.json>  check an envelope or inbound event against its schema
+    python -m telefi schema <name>         print a published schema (envelope.v1 | inbound.v1 | hub_config.v1)
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import tempfile
+import time
+import traceback
+from pathlib import Path
+
+from telefi import core, inbound, schema
+from telefi.render import render_plain
+from telefi.samples import samples
+
+SERVE_RETRY_S = 5
+SERVE_RETRY_MAX_S = 300
+PRUNE_EVERY_S = 3600
+
+
+def _preview(names: list[str], buttons: bool) -> int:
+    for name, env in samples().items():
+        if names and name not in names:
+            continue
+        print(f"===== {name}  (routes to: {', '.join(core.route(env, core.DEFAULT_CONFIG)) or 'nothing'})")
+        print(render_plain(env, buttons=buttons))
+        print()
+    return 0
+
+
+def _samples(send: bool) -> int:
+    cfg = core.load_config()
+    if not send:
+        cfg = {**cfg, "mode": "mock"}
+    with tempfile.TemporaryDirectory() as tmp:
+        spool = Path(tmp) / "spool"
+        for env in samples().values():
+            core.publish(env, spool=spool)
+        for rec in core.drain(cfg, spool=spool):
+            env = rec["envelope"]
+            res = ", ".join(f"{d['channel']}={'ok' if d['ok'] else 'FAILED ' + str(d['error'])}" for d in rec["deliveries"])
+            print(f"{env['source']}.{env['kind']} [{env['severity']}] -> {res or 'no route'}")
+    print("mode:", "LIVE (really sent)" if send else "mock (nothing sent)")
+    return 0
+
+
+def _serve(interval: float) -> int:
+    """Drain + long-poll forever. A failing round is logged to ~/.telefi/hub.log and retried; it
+    never ends the process (the scheduled task would only restart it 5 minutes later)."""
+    cfg = core.load_config()
+    log = core.HOME / "hub.log"
+    core.append_jsonl(log, {"at": core.now_iso(), "event": "serve started", "inbound": cfg.get("inbound", {}).get("enabled")})
+    if cfg.get("inbound", {}).get("enabled"):
+        menu = inbound.register_menu(cfg)
+        core.append_jsonl(log, {"at": core.now_iso(), "event": "command menu", "ok": menu["ok"], "error": menu.get("error")})
+    failures, pruned_at = 0, 0.0
+    while True:
+        try:
+            core.drain(cfg)
+            if time.monotonic() - pruned_at > PRUNE_EVERY_S:
+                core.prune_done(core.spool_root(cfg))
+                pruned_at = time.monotonic()
+            if cfg.get("inbound", {}).get("enabled"):
+                inbound.poll_once(cfg, timeout_s=int(interval))
+            else:
+                time.sleep(interval)
+            failures = 0
+        except Exception:
+            failures += 1
+            wait = min(SERVE_RETRY_S * 2 ** (failures - 1), SERVE_RETRY_MAX_S)   # an outage never spins
+            core.append_jsonl(log, {"at": core.now_iso(), "event": "round failed", "retry_in_s": wait,
+                                    "error": traceback.format_exc()[-2000:]})
+            time.sleep(wait)
+
+
+def main(argv=None) -> int:
+    if sys.stdout is not None:                    # None under pythonw.exe (no console)
+        sys.stdout.reconfigure(encoding="utf-8")   # Windows consoles default to cp1252
+    ap = argparse.ArgumentParser(prog="python -m telefi")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("drain")
+    s = sub.add_parser("serve")
+    s.add_argument("--interval", type=float, default=30.0)
+    p = sub.add_parser("preview")
+    p.add_argument("types", nargs="*")
+    p.add_argument("--no-buttons", action="store_true", help="hide action buttons (as sent while inbound is disabled)")
+    sm = sub.add_parser("samples")
+    sm.add_argument("--send", action="store_true")
+    v = sub.add_parser("validate")
+    v.add_argument("file")
+    sc = sub.add_parser("schema")
+    sc.add_argument("name", choices=schema.SCHEMAS)
+    a = ap.parse_args(argv)
+
+    if a.cmd == "drain":
+        recs = core.drain(core.load_config())
+        failed = [r for r in recs if r.get("rejected") or any(not d["ok"] for d in r["deliveries"])]
+        print(f"[hub] delivered {len(recs) - len(failed)}/{len(recs)}", flush=True)
+        return 1 if failed else 0
+    if a.cmd == "serve":
+        return _serve(a.interval)
+    if a.cmd == "preview":
+        return _preview(a.types, buttons=not a.no_buttons)
+    if a.cmd == "samples":
+        return _samples(a.send)
+    if a.cmd == "validate":
+        obj = json.loads(Path(a.file).read_text(encoding="utf-8"))
+        name = "inbound.v1" if str(obj.get("schema", "")).endswith(".inbound.v1") else "envelope.v1"
+        bad = schema.validate(obj, name)
+        print("\n".join(bad) or f"valid {name}")
+        return 1 if bad else 0
+    if a.cmd == "schema":
+        print(json.dumps(schema.load(a.name), indent=2))
+        return 0
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())